Grid Reference Utilities - API documentation

API Documentation

The API generally follows the normal conventions of the relevant language. As a result, classes and methods in PHP are generally in the format name_of_method, while the JavaScript equivalent will be in the format nameOfMethod. In both languages, pseudo-constants are in the format NAME_OF_CONSTANT.

Using the different types of return value
The Grid Reference Utilities toolbox
Methods of the Grid Reference Utilities toolbox
Methods for conversion between different NGR formats

get_UK_grid_ref

Convert grid coordinates to a UK grid reference.

get_Irish_grid_ref

Convert grid coordinates to an Irish grid reference.

get_UK_grid_nums

Convert a UK grid reference to grid coordinates.

get_Irish_grid_nums

Convert an Irish grid reference to grid coordinates.

add_grid_units

Convert grid coordinates to ITM format.

parse_grid_nums

Interpret ITM format or generic coordinates as grid coordinates.
Methods for representing ellipsoid earth models

get_ellipsoid

Get a predefined Earth model.

create_ellipsoid

Create a custom Earth model.
Methods for conversion between grid coordinates and latitude/longitude

grid_to_lat_long

Convert grid coordinates to latitude/longitude.

lat_long_to_grid

Convert latitude/longitude to grid coordinates.

utm_to_lat_long

Convert a UTM grid reference to latitude/longitude.

lat_long_to_utm

Convert latitude/longitude to a UTM grid reference.

get_datum

Get a predefined datum.

create_datum

Create a custom datum.
Methods for conversion between polar grid coordinates and latitude/longitude

polar_to_lat_long

Convert polar stereographic grid coordinates to latitude/longitude.

lat_long_to_polar

Convert latitude/longitude to polar stereographic grid coordinates.

ups_to_lat_long

Convert a UPS grid grid reference to latitude/longitude.

lat_long_to_ups

Convert latitude/longitude to a UPS grid grid reference.
Methods for conversion between different latitude/longitude formats

dd_to_dms

Convert latitude/longitude degrees to degrees-minutes or degrees-minutes-seconds.

dd_format

Add degree symbol and optional hemisphere units to latitude/longitude.

dms_to_dd

Interpret several latitude/longitude formats as latitude/longitude coordinates.
Shifting grid coordinates between earth models using bilinear interpolation

shift_grid

Move coordinates horizontally or vertically using bilinear interpolation.

reverse_shift_grid

Move coordinates in reverse horizontally or vertically using bilinear interpolation.

get_shift_set

Get a predefined shift set for bilinear interpolation.

create_shift_set

Create a custom shift set for bilinear interpolation.

create_shift_record

Create a bilinear interpolation shift record, containing database data.

cache_shift_records

Cache bilinear interpolation shift records, to avoid repeated database calls.

delete_shift_cache

Clear bilinear interpolation shift record cache, to free up memory.
Methods for conversion between different latitude/longitude Earth models using Helmert transformation

Helmert_transform

Convert latitude/longitude from one Earth model to another using Helmert transformation.

get_transformation

Get a predefined transformation set for Helmert transformation.

create_transformation

Create a custom transformation set for Helmert transformation.
Methods for conversion between different latitude/longitude Earth models using polynomial transformation

polynomial_transform

Convert latitude/longitude from one Earth model to another using polynomial transformation.

reverse_polynomial_transform

Convert latitude/longitude from one Earth model to another in reverse using a polynomial transformation.

get_polynomial_coefficients

Get predefined transformation coefficients for polynomial transformation.

create_polynomial_coefficients

Create custom transformation coefficients for polynomial transformation.
Methods for conversion between Earth model heights and geoid heights using bilinear interpolation

apply_geoid

Move coordinates vertically using bilinear interpolation.

get_geoid_grd

Get a predefined geoid data specification for bilinear interpolation.

create_geoid_grd

Create a custom geoid data specification for bilinear interpolation.

create_geoid_record

Create a geoid shift record, containing database data.

cache_geoid_records

Cache geoid shift records, to avoid repeated database calls.

delete_geoid_cache

Clear geoid shift record cache, to free up memory.
Methods for geodesics - measuring distances between latitude,longitude points

get_geodesic_destination

Add a geodetic vector to a latitude,longitude point, and get the resulting coordinates.

get_geodesic

Calculate the distance and azimuths between two latitude,longitude points.
Methods for conversion between latitude,longitude and Cartesian X,Y,Z coordinates

xyz_to_lat_long

Convert Cartesian X,Y,Z coordinates to latitude/longitude.

lat_long_to_xyz

Convert latitude/longitude to Cartesian X,Y,Z coordinates.
More information; details and demos

To download the script(s), and see the script license, use the links on the navigation panel at the top of this page.

Using the different types of return value

Most methods can return a data array of converted values, a basic string of text that may contain characters that are not HTML-safe, or a HTML string that can be put directly into HTML. The data arrays are designed to be fed directly as input into other methods, so where relevant, methods will always accept input as an array that matches the output from corresponding methods. When choosing HTML as a return value, most return values are just a string that may contain HTML entities. However, get_*_grid_ref/get*GridRef also returns some markup, that can be styled with the following CSS to produce visual gaps, while allowing copy/paste to copy without gaps:

var.grid + var, var.grid + var + var { margin-left: 0.3em; }

If constructing your own strings from the values returned in an array, note that very large or very small numbers (ones returned by the scripts as a float) may be written by default by PHP or JavaScript using scientific notation, resulting in examples like 1.234E-20. To avoid this, you can obtain a nicely formatted string using the appropriate code below:

PHP

sprintf('%F',$foo)

JavaScript

foo.toFixed(6)

Be warned though that it will round up numbers that are >= 59.9999995 to 60, and that could result in displaying an unexpected number of minutes or seconds. This could be avoided by using the following code when displaying minutes or seconds:

PHP

sprintf( '%F', ( $foo >= 59.9999995 ) ? 59.999999 : $foo )

JavaScript

( ( foo >= 59.9999995 ) ? 59.999999 : foo ).toFixed(6)

Note that the numbers will then be presented to an accuracy of 6 decimal places, even if the numbers themselves are less accurate than that. To use lower accuracy, use '%.2F' in PHP to give 2 decimal places, and toFixed(2) in JavaScript to achieve the same result. To remove trailing zeros, which may be considered more aesthetically pleasing (but can also give unbalanced number pairs), you can use the following code:

PHP

preg_replace( "/((\.\d*[1-9])0+|\.0+)$/", '$2', $numberstring )

JavaScript

numberstring.replace(/((\.\d*[1-9])0+|\.0+)$/,'$2')

With the PHP version of the script, when choosing to return a text string, you need to choose what encoding your page will be served as, to ensure that characters are returned in that encoding. This mainly affects the 'degrees' character, which has different values in different encodings. The following pseudo-constants are available for their respective encodings (see PHP's documentation of html_entity_decode for details of these encodings):

TEXT_EUROPEAN: (\xB0) ISO-8859-1, ISO-8859-15, [CP|WINDOWS-]1251, [CP|WINDOWS-]1252
TEXT_UNICODE: (\xC2\xB0) UTF-8
TEXT_ASIAN: (\x26\x64\x65\x67\x3B) [cp|ibm]866, KOI8-R, [BIG5|950], [GB2312|936], BIG5-HKSCS, [Shift_JIS|932], EUC-JP
TEXT_DEFAULT: Your PHP server's default_charset (not recommended). Your PHP environment may operate in a different encoding than it sends to browsers, so this can cause problems on some servers. On most current servers, it uses UTF-8.

If you do not know which of these you want, you probably want TEXT_EUROPEAN or TEXT_UNICODE - try something like this, and ensure that browsers display a 'degrees' character (°):

print $grutoolbox->TEXT_EUROPEAN;

Alternatively, if none of these works with your encoding, you can supply a text string containing the 'degrees' character in your page's own encoding.

This problem does not affect the JavaScript version of the script, which does not need you to specify the encoding. The JavaScript version of the script therefore just offers a single TEXT pseudo-constant.

The Grid Reference Utilities toolbox

The Grid Reference Utilities toolbox is the object whose methods provide all of the functionality of the script. This is currently implemented as a singleton, but this may change in future. Do not rely on it remaining as a singleton. Firstly you need to include a copy of the script on your page:

PHP

include('PATH TO SCRIPT/gridrefutils.php');

HTML (for use from JavaScript)

<script src="PATH TO SCRIPT/gridrefutils.js" type="text/javascript"></script>

Your script can then get a reference to the Grid Reference Utilities toolbox as follows:

PHP

$grutoolbox = Grid_Ref_Utils::toolbox();

JavaScript

var grutoolbox = gridRefUtilsToolbox();

Methods of the Grid Reference Utilities toolbox

Methods for conversion between different NGR formats

NGR formats work for any valid UK or Ireland reference in the standard grid letters. Numbers are rounded (205369 becomes n0537) not truncated. (The NGR systems normally use truncation, but rounding gets you closer to an actual point.)

get_UK_grid_ref (PHP) or getUKGridRef (JS): Returns a UK grid reference equivalent to the supplied coordinates.
get_Irish_grid_ref (PHP) or getIrishGridRef (JS): Returns an Irish grid reference equivalent to the supplied coordinates.
get_UK_grid_nums (PHP) or getUKGridNums (JS): Returns coordinates equivalent to the UK grid reference.
get_Irish_grid_nums (PHP) or getIrishGridNums (JS): Returns coordinates equivalent to the Irish grid reference.
add_grid_units (PHP) or addGridUnits (JS): Returns coordinates formatted with leading E/W and N/S units, and trailing m unit. Most commonly used with ITM grid references, but will work with any generic grid coordinate numbers.
parse_grid_nums (PHP) or parseGridNums (JS): Returns numeric coordinates equivalent to the supplied coordinates string. Used to parse a string version of the coordinates into an array, or to test for their validity.

get_UK_grid_ref, getUKGridRef, get_Irish_grid_ref, getIrishGridRef

Returns a UK/Irish grid reference equivalent to the supplied coordinates. Produces 2-10 figure grid references, or grid references with floating point precision.

method( easting, northing[, figures[, return_type[, deny_bad_reference[, use_rounding]]]] )

method( Array( easting, northing )[, figures[, return_type[, deny_bad_reference[, use_rounding]]]] )

easting

Float: easting relative to origin (SV00 UK or V00 Ireland).

northing

Float: northing relative to origin (SV00 UK or V00 Ireland).

figures

Integer 1-25: number of figures to use for each of the easting and northing (eg. use 3 for a 6 figure grid reference). Defaults to 4 (8 figure grid reference). For a value of 1-5, it will return a 2-10 figure grid reference. For values greater than 5, the returned grid reference will use floating point precision. Although values as high as 25 are permitted, this goes far beyond the accuracy of the conversion routines. Suggested maximum value is 8.

null: use the default value (4).

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

grid_letters grid_easting grid_northing

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

<var class="grid">grid_letters</var><var>grid_easting</var><var>grid_northing</var>

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((string)grid_letters,(string)grid_easting,(string)grid_northing)

Returned strings will always use integer values for coordinates.

deny_bad_reference

Boolean: true to return false if the coordinates are outside the available grid letters. False (default) to return 'OUT_OF_GRID' as the grid letters if the coordinates are outside the available grid letters.

use_rounding

Boolean: true to round grid references to the specified number of significant figures. False (default) to truncate grid references to the specified number of significant figures.

get_UK_grid_nums, getUKGridNums, get_Irish_grid_nums, getIrishGridNums

Returns coordinates equivalent to the UK/Irish grid reference. Supports 2-10 figure grid references, or grid references with floating point precision. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( grid_reference[, return_type[, deny_bad_reference[, use_rounding[, precise]]]] )

method( grid_letters, grid_easting, grid_northing[, return_type[, deny_bad_reference[, use_rounding[, precise]]]] )

method( Array( grid_letters, grid_easting, grid_northing )[, return_type[, deny_bad_reference[, use_rounding[, precise]]]] )

grid_reference

String: grid reference in the format 'XY12345678' or 'XY 1234 5678' (UK) or 'X12345678' or 'X 1234 5678' (Ireland). Floating point numbers are also accepted but must be given in 10 figure grid references, and must be separated by whitespace.

grid_letters

String: 'XY' (UK) or 'X' (Ireland).

grid_easting

String: easting relative to grid square.

grid_northing

String: northing relative to grid square.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

easting,northing

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

easting,northing

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)easting,(float)northing)

deny_bad_reference

Boolean: true to return false if the grid_reference, grid_letters, grid_easting or grid_northing cannot be recognised as a valid format. False (default) to treat the coordinates as 0 for any of those parameters that cannot be recognised as a valid format.

use_rounding

Boolean: true to use the exact value of the grid reference as the coordinate to transform (the southwest corner of the area covered by the grid reference), assuming that the grid reference has been rounded to the nearest value, and is therefore already the average of all possible coordinates. False (default) to translate the mid-point of the grid reference's square (so for a 6 figure grid reference, which refers to a 100 m square, it will translate the point in the centre of that 100 m square), assuming the average of all points it could have referred to if standard truncation were used.

precise

Boolean: true to return floating point coordinates when returning text or HTML strings. False (default) to return integer coordinates when returning text or HTML strings. This parameter is ignored when returning data arrays.

add_grid_units, addGridUnits

Returns coordinates formatted with leading E/W and N/S units, and trailing m unit. Most commonly used with ITM grid references, but will work with any generic grid coordinate numbers. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( easting, northing[, return_type[, precise]] )

method( Array( easting, northing )[, return_type[, precise]] )

easting

Float: easting coordinate of the grid reference.

northing

Float: northing coordinate of the grid reference.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

E eastingm, N northingm

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

E eastingm, N northingm

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)easting,(int)easting_multiplier,(float)northing,(int)northing_multiplier)

easting_multiplier will be 1 for points to the east of the grid's origin and -1 for points to the west of it. northing_multiplier will be 1 for points to the north of the grid's origin and -1 for points to the south of it.

precise

parse_grid_nums, parseGridNums

Returns numeric coordinates equivalent to the supplied coordinates string. Used to parse a string version of the coordinates into an array, or to test for their validity. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( coordinates[, return_type[, deny_bad_coords[, strict_nums[, precise]]]] )

method( Array( easting, easting_multiplier, northing, northing_multiplier )[, return_type[, precise]] )

coordinates

String: numeric grid reference coordinates. Depends on the strict_nums parameter to determine whether to recognise only the generic coordinate format used by all grid reference types, or the wider range of formats typically used only with ITM grid references - examples:

'12345,67890'
'123m, 456m'
'E 12345m, N 67890m'

The actual formats supported when strict_nums is true include anything matching this pattern - whitespace is ignored between all tokens except the [-] and <float>:

[-]<float>,[-]<float>

The actual formats supported when strict_nums is false include anything matching this pattern - whitespace is ignored between all tokens except the [-] and <float>:

[EW][-]<float>[m][, ][NS][-]<float>[m]

easting

Positive float: easting component of the coordinate.

easting_multiplier

Integer: 1 for points to the east of the grid's origin and -1 for points to the west of it.

northing

Positive float: northing component of the coordinate.

northing_multiplier

Integer: 1 for points to the north of the grid's origin and -1 for points to the south of it.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

easting,northing

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

easting,northing

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)easting,(float)northing)

deny_bad_coords

Boolean: true to return false if the coordinates cannot be recognised as a valid format. False (default) to treat the coordinates as 0,0 if the coordinates cannot be recognised as a valid format.

strict_nums

Boolean: true to recognise only float,float as a valid format. False (default) to recognise a wide range of possible formats, such as those used by ITM.

precise

Methods for representing ellipsoid earth models

Ellipsoids are the usual way to represent a relatively simplistic oblate or prolate spheroid.

get_ellipsoid (PHP) or getEllipsoid (JS): Returns a predefined Earth model ellipsoid parameter set that can be used as the ellipsoid_from or ellipsoid_to parameters with Helmert_transform/HelmertTransform, or as the ellipsoid parameter with create_datum/createDatum, or as the ellipsoid parameter with utm_to_lat_long/utmToLatLong and lat_long_to_utm/latLongToUtm, or as the ellipsoid parameter with get_geodesic_destination/getGeodesicDestination and get_geodesic/getGeodesic, or as the ellipsoid parameter with xyz_to_lat_long/xyzToLatLong and lat_long_to_xyz/latLongToXyz.
create_ellipsoid (PHP) or createEllipsoid (JS): Returns a custom Earth model ellipsoid parameter set that can be used as the ellipsoid_from or ellipsoid_to parameters with Helmert_transform/HelmertTransform, or as the ellipsoid parameter with create_datum/createDatum, or as the ellipsoid parameter with utm_to_lat_long/utmToLatLong and lat_long_to_utm/latLongToUtm, or as the ellipsoid parameter with get_geodesic_destination/getGeodesicDestination and get_geodesic/getGeodesic, or as the ellipsoid parameter with xyz_to_lat_long/xyzToLatLong and lat_long_to_xyz/latLongToXyz.

get_ellipsoid, getEllipsoid

Returns a predefined Earth model ellipsoid parameter set that can be used as the ellipsoid_from or ellipsoid_to parameters with Helmert_transform/HelmertTransform, or as the ellipsoid parameter with create_datum/createDatum, or as the ellipsoid parameter with utm_to_lat_long/utmToLatLong and lat_long_to_utm/latLongToUtm, or as the ellipsoid parameter with get_geodesic_destination/getGeodesicDestination and get_geodesic/getGeodesic, or as the ellipsoid parameter with xyz_to_lat_long/xyzToLatLong and lat_long_to_xyz/latLongToXyz.

Note that GRS80 is not exactly the same as WGS84's ellipsoid. Originally, WGS84 used GRS80, but now uses a slightly more refined version (which confusingly is normally also called GRS80), with only a 0.25 mm difference between them at the poles. In most cases, the results will be the same. The GRS80 ellipsoid is normally used only for special cases such as high accuracy transformation of differential GPS coordinates within Europe. In most other cases involving GPS, WGS84 is the correct ellipsoid.

method( name )

name

String: one of the predefined names:

'Airy_1830': Ellipsoid used by OS Airy 1830, covering the British National Grid.
'Airy_1830_mod': Ellipsoid used by OSI modified Airy 1830, covering the Irish National Grid.
'WGS84': Ellipsoid used by WGS84 (most GPS software), covering the entire Earth.
'GRS80': Ellipsoid used by ETRS89 (European differential GPS), covering the entire Earth.

Invalid names will cause the method to return false.

create_ellipsoid, createEllipsoid

Returns a custom Earth model ellipsoid parameter set that can be used as the ellipsoid_from or ellipsoid_to parameters with Helmert_transform/HelmertTransform, or as the ellipsoid parameter with create_datum/createDatum, or as the ellipsoid parameter with utm_to_lat_long/utmToLatLong and lat_long_to_utm/latLongToUtm, or as the ellipsoid parameter with get_geodesic_destination/getGeodesicDestination and get_geodesic/getGeodesic, or as the ellipsoid parameter with xyz_to_lat_long/xyzToLatLong and lat_long_to_xyz/latLongToXyz.

method( major_axis, minor_axis )

major_axis: Float: semi-major axis a (in metres).
minor_axis: Float: semi-minor axis b (in metres).

Methods for conversion between grid coordinates and latitude/longitude

Some precision will be lost during conversion, by truncation and floating point errors, as well as by limitations of the conversion algorithms. When selecting the GPS model, there may be upto 5 metres of error due to limitations of the Earth model used by GPS systems, and the conversion algorithms. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 10 decimal places.

grid_to_lat_long (PHP) or gridToLatLong (JS): Returns the latitude/longitude coordinates for the given grid coordinates, according to the selected Earth model/datum.
lat_long_to_grid (PHP) or latLongToGrid (JS): Returns the grid coordinates for the given longitude/latitude coordinates, according to the selected Earth model/datum.
utm_to_lat_long (PHP) or utmToLatLong (JS): Returns the latitude/longitude coordinates for the given UTM grid reference.
lat_long_to_utm (PHP) or latLongToUtm (JS): Returns a UTM grid reference for the given latitude/longitude coordinates. Picks the most appropriate UTM zone (and takes account of the abnormally shaped zones 31-37). Returns either longhand or shorthand formats.
get_datum (PHP) or getDatum (JS): Returns a predefined datum parameter set that can be used as the type parameter with grid_to_lat_long/gridToLatLong and lat_long_to_grid/latLongToGrid, or the datum parameter with polar_to_lat_long/polarToLatLong and lat_long_to_polar/latLongToPolar.
create_datum (PHP) or createDatum (JS): Returns a custom datum parameter set that can be used as the type parameter with grid_to_lat_long/gridToLatLong and lat_long_to_grid/latLongToGrid, or the datum parameter with polar_to_lat_long/polarToLatLong and lat_long_to_polar/latLongToPolar.

grid_to_lat_long, gridToLatLong

Returns the latitude/longitude coordinates for the given grid coordinates, according to the selected Earth model/datum, using transverse mercator projection.

method( easting, northing, type[, return_type] )

method( Array( easting, northing ), type[, return_type] )

easting

Float: easting coordinate of the grid reference.

northing

Float: northing coordinate of the grid reference.

type

If you do not know which of the following options you want, you probably want COORDS_GPS_UK.

PHP: $grutoolbox->COORDS_GPS_UK
JS: grutoolbox.COORDS_GPS_UK: Convert from UK grid coordinates to the WGS84/GRS80 coordinates used by most GPS software. Uses Helmert transformation to convert to WGS84/GRS80.
PHP: $grutoolbox->COORDS_GPS_IRISH
JS: grutoolbox.COORDS_GPS_IRISH: Convert from Irish grid coordinates to the WGS84/GRS80 coordinates used by most GPS software. Uses polynomial transformation to convert to WGS84/GRS80 (recommended).
PHP: $grutoolbox->COORDS_GPS_IRISH_HELMERT
JS: grutoolbox.COORDS_GPS_IRISH_HELMERT: Convert from Irish grid coordinates to the WGS84/GRS80 coordinates used by most GPS software. Uses Helmert transformation to convert to WGS84/GRS80 (less accurate).
PHP: $grutoolbox->COORDS_OS_UK
JS: grutoolbox.COORDS_OS_UK: Convert from UK grid coordinates to the Airy 1830 coordinates used by Ordnance Survey.
PHP: $grutoolbox->COORDS_OSI
JS: grutoolbox.COORDS_OSI: Convert from Irish grid coordinates to the modified Airy 1830 coordinates used by Ordnance Survey Ireland.
PHP: $grutoolbox->COORDS_GPS_ITM
JS: grutoolbox.COORDS_GPS_ITM: Convert from Irish Transverse Mercator coordinates to the WGS84/GRS80 coordinates used by most GPS software.
PHP and JS: datum parameter set: Datum parameter set for the grid.

Invalid types will cause the method to return false.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude)

lat_long_to_grid, latLongToGrid

Returns the grid coordinates for the given longitude/latitude coordinates, according to the selected Earth model/datum, using transverse mercator projection. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( latitude, longitude, type[, return_type[, precise]] )

method( Array( latitude, longitude ), type[, return_type[, precise]] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

type

If you do not know which of the following options you want, you probably want COORDS_GPS_UK.

PHP: $grutoolbox->COORDS_GPS_UK
JS: grutoolbox.COORDS_GPS_UK: Convert from the WGS84/GRS80 coordinates used by most GPS software to UK grid coordinates. Uses Helmert transformation to convert from WGS84/GRS80.
PHP: $grutoolbox->COORDS_GPS_IRISH
JS: grutoolbox.COORDS_GPS_IRISH: Convert from the WGS84/GRS80 coordinates used by most GPS software to Irish grid coordinates. Uses polynomial transformation to convert from WGS84/GRS80 (recommended).
PHP: $grutoolbox->COORDS_GPS_IRISH_HELMERT
JS: grutoolbox.COORDS_GPS_IRISH_HELMERT: Convert from the WGS84/GRS80 coordinates used by most GPS software to Irish grid coordinates. Uses Helmert transformation to convert from WGS84/GRS80 (less accurate).
PHP: $grutoolbox->COORDS_OS_UK
JS: grutoolbox.COORDS_OS_UK: Convert from the Airy 1830 coordinates used by Ordnance Survey to UK grid coordinates.
PHP: $grutoolbox->COORDS_OSI
JS: grutoolbox.COORDS_OSI: Convert from the modified Airy 1830 coordinates used by Ordnance Survey Ireland to Irish grid coordinates.
PHP: $grutoolbox->COORDS_GPS_ITM
JS: grutoolbox.COORDS_GPS_ITM: Convert from the WGS84/GRS80 coordinates used by most GPS software to Irish Transverse Mercator coordinates.
PHP and JS: datum parameter set: Datum parameter set for the grid.

Invalid types will cause the method to return false.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

easting,northing

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

easting,northing

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)easting,(float)northing)

precise

utm_to_lat_long, utmToLatLong

Returns the latitude/longitude coordinates for the given UTM grid reference.

method( utm_reference[, ellipsoid[, return_type[, deny_bad_reference]]] )

method( zone, hemisphere, easting, northing[, ellipsoid[, return_type[, deny_bad_reference]]] )

method( Array( zone, hemisphere, easting, northing )[, ellipsoid[, return_type[, deny_bad_reference]]] )

utm_reference

String: UTM grid reference in longhand or shorthand format - examples:

'12345 67890 zone 17 n'
'12345mE, 67890mN, zone 17, northern hemisphere'
'17S 12345 67890'
'17 North, 12345, 67890'

The actual formats supported include anything matching these patterns:

[01-60](<letter>|north|south)<float>[, ]<float>
<float>[letters][, ]<float>[letters][, ]zone[01-60][,][NS]...

Whitespace is ignored between tokens. When encountering the ambiguous 'S' in '17S 12345 67890', it will be treated as latitude band 'S', not shorthand for Southern Hemisphere. To refer to the Southern Hemisphere, use latitude bands within that hemisphere, the full word 'south', or the longhand format.

zone

Integer 1-60: UTM zone of the grid reference.

hemisphere

Integer: 1 for the Northern Hemisphere, -1 for the Southern Hemisphere.

easting

Float: easting coordinate of the grid reference.

northing

Float: northing coordinate of the grid reference.

ellipsoid

Ellipsoid parameter set for the source Earth model. Invalid ellipsoids will cause the method to return false. (If using anything except the default Earth model, you will need to use a Helmert transformation to convert the results to GPS coordinates.)

null (default): use the default Earth Model; WGS84.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude)

deny_bad_reference

Boolean: true to return false if the utm_reference, zone, hemisphere, easting or northing cannot be recognised as a valid format. False (default) to return 90,0 latitude/longitude (coordinates that cannot be legitimately represented in UTM) if any of those parameters that cannot be recognised as a valid format.

lat_long_to_utm, latLongToUtm

Returns a UTM grid reference for the given latitude/longitude coordinates. Picks the most appropriate UTM zone (and takes account of the abnormally shaped zones 31-37). Returns either longhand or shorthand formats. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( latitude, longitude[, ellipsoid[, format[, return_type[, deny_bad_coords[, precise]]]]] )

method( Array( latitude, longitude )[, ellipsoid[, format[, return_type[, deny_bad_coords[, precise]]]]] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

ellipsoid

Ellipsoid parameter set for the source Earth model. Invalid ellipsoids will cause the method to return false.

null (default): use the default Earth Model; WGS84.

format

Boolean: true to return the longhand format:

12345mE, 67890mN, Zone 17, Northern Hemisphere

false (default) to return the shorthand format:

17T 12345 67890

To avoid the confusion between the ambiguous latitude band letters and hemisphere notation, the scripts will always use only the latitude band letters in the shorthand format (a very popular way of writing UTM grid references), and the hemisphere name in the longhand format (this is a format suggested by the American military, who created UTM). If you want to produce another format, you will need to make the method return a data array, and construct it yourself.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return one of the following strings (depending on whether the format parameter was false or true):

zoneband_letter easting northing
eastingmE, northingmN, Zone zone, [North|South]ern Hemisphere

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return one of the following strings (depending on whether the format parameter was false or true):

zoneband_letter easting northing
eastingmE, northingmN, Zone zone, [North|South]ern Hemisphere

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return one of the following arrays (depending on whether the format parameter was false or true):

Array((int)zone,(int)hemisphere,(float)easting,(float)northing,(string)band_letter)
Array((int)zone,(int)hemisphere,(float)easting,(float)northing,(string)hemisphere_identifier)

hemisphere will be 1 for points to the north of the equator and -1 for points to the south of it. hemisphere_identifier will be 'North' for points to the north of the equator and 'South' for points to the south of it.

deny_bad_coords

Boolean: true to return false if the latitude is greater than 84 or less than -80, or if latitude or longitude cannot be recognised as numbers. False to return the zone, easting and northing as 0, and the hemisphere identifier as North or South or zone letter as A/B/Y/Z (depending on which part of the polar regions it appears to refer to), if the latitude is greater than 84 or less than -80, or if latitude or longitude cannot be recognised as numbers.

precise

get_datum, getDatum

Returns a predefined datum parameter set that can be used as the type parameter with grid_to_lat_long/gridToLatLong and lat_long_to_grid/latLongToGrid, or the datum parameter with polar_to_lat_long/polarToLatLong and lat_long_to_polar/latLongToPolar.

method( name )

name

String: one of the predefined names:

'OSGB36': Datum set used by the British National Grid.
'OSTN15': Datum set used by the British National Grid as part of the OSTN15 high accuracy grid shift transformation.
'Ireland_1965': Datum used by the Irish National Grid.
'IRENET95': Datum used by the Irish Transverse Mercator.
'UPS_North': Datum used by the Universal Polar Stereographic at the North Pole.
'UPS_South': Datum used by the Universal Polar Stereographic at the South Pole.

Invalid names will cause the method to return false.

create_datum, createDatum

Returns a custom datum parameter set that can be used as the type parameter with grid_to_lat_long/gridToLatLong and lat_long_to_grid/latLongToGrid, or the datum parameter with polar_to_lat_long/polarToLatLong and lat_long_to_polar/latLongToPolar.

method( ellipsoid, scale, map_origin_easting, map_origin_northing, origin_lat, origin_long )

ellipsoid: Ellipsoid parameter set for the Earth model used by the datum. Invalid ellipsoids will cause the method to return false.
scale: Float: F₀ scale factor on central meridian. For a polar stereographic datum, this is the scale factor at the natural origin (North or South Pole).
map_origin_easting: Float: E₀ map easting of true origin (in metres).
map_origin_northing: Float: N₀ map northing of true origin (in metres).
origin_lat: Float: φ₀ true origin latitude (in degrees). For a polar stereographic datum, the only permitted values are 90 (for North Pole) or -90 (for South Pole).
origin_long: Float: λ₀ true origin longitude (in degrees). For a polar stereographic datum, this will be the 'up' direction on the map for South Pole, and 'down' direction on the map for North Pole.

Methods for conversion between polar grid coordinates and latitude/longitude

These methods are designed to work only with basic polar stereographic projections, where the origin is at either the North or South Pole, and the scale factor is provided at the origin. The intended use is to couple the UPS methods with the UTM methods, to allow any point on the Earth to be located using one of these systems. Some precision will be lost during conversion, by truncation and floating point errors, as well as by limitations of the conversion algorithms. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 10 decimal places.

Clarification note; these methods do not relate to mathematical polar coordinates. They relate to map grid systems that use a polar stereographic projection.

polar_to_lat_long (PHP) or polarToLatLong (JS): Returns the latitude/longitude coordinates for the given polar stereographic grid coordinates, according to the selected datum.
lat_long_to_polar (PHP) or latLongToPolar (JS): Returns the polar stereographic grid coordinates for the given longitude/latitude coordinates, according to the selected datum.
ups_to_lat_long (PHP) or upsToLatLong (JS): Returns the latitude/longitude coordinates for the given UPS grid reference.
lat_long_to_ups (PHP) or latLongToUps (JS): Returns a UPS grid reference for the given latitude/longitude coordinates. Picks the appropriate pole. Returns a grid reference using either latitude band or hemisphere identifier notation.

polar_to_lat_long, polarToLatLong

Returns the latitude/longitude coordinates for the given polar stereographic grid coordinates, according to the selected datum. Only basic stereographic projections and datums are supported, where the natural origin is at either the North or South Pole, and the scale factor is provided at the natural origin.

method( easting, northing, datum[, return_type] )

method( Array( easting, northing ), datum[, return_type] )

easting

Float: easting coordinate of the grid reference.

northing

Float: northing coordinate of the grid reference.

datum

Datum parameter set for the grid.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude)

lat_long_to_polar, latLongToPolar

Returns the polar stereographic grid coordinates for the given longitude/latitude coordinates, according to the selected datum. Only basic stereographic projections and datums are supported, where the natural origin is at either the North or South Pole, and the scale factor is provided at the natural origin. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( latitude, longitude, datum[, return_type[, precise]] )

method( Array( latitude, longitude ), datum[, return_type[, precise]] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

datum

Datum parameter set for the grid.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

easting,northing

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

easting,northing

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)easting,(float)northing)

precise

ups_to_lat_long, upsToLatLong

Returns the latitude/longitude coordinates for the given UPS grid reference.

method( ups_reference[, return_type[, deny_bad_reference[, min_length]]] )

method( hemisphere, easting, northing[, return_type[, deny_bad_reference[, min_length]]] )

method( Array( hemisphere, easting, northing )[, return_type[, deny_bad_reference[, min_length]]] )

ups_reference

String: UPS grid reference using either a latitude band or hemishphere identifier - examples:

'Y 12345.123 67890.456'
'North 12345 67890'
'S 12345 67890'

The actual formats supported include anything matching this pattern:

(A|B|Y|Z|N|S|north|south)[,]<float>[, ]<float>

Whitespace or a comma is required between the numbers.

hemisphere

Integer: 1 for the Northern Hemisphere, -1 for the Southern Hemisphere.

String: 'N', 'Y', 'Z' or 'North' for the Northern Hemisphere, 'S', 'A', 'B' or 'South' for the Southern Hemisphere.

easting

Float: easting coordinate of the grid reference.

northing

Float: northing coordinate of the grid reference.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude)

deny_bad_reference

Boolean: true to return false if the ups_reference, hemisphere, easting or northing cannot be recognised as a valid format. False (default) to return 0,0 latitude/longitude (coordinates that cannot be legitimately represented in UPS) if any of those parameters that cannot be recognised as a valid format.

min_length

Boolean: true to treat easting and northing values as an invalid format if they are less than 800000. False (default) to allow any number for those parameters. This is most useful when combined with deny_bad_reference to distinguish between Irish grid references and UPS.

lat_long_to_ups, latLongToUps

Returns a UPS grid reference for the given latitude/longitude coordinates. Picks the appropriate pole. Returns a grid reference using either latitude band or hemisphere identifier notation. When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places.

method( latitude, longitude[, format[, return_type[, deny_bad_coords[, precise]]]] )

method( Array( latitude, longitude )[, format[, return_type[, deny_bad_coords[, precise]]]] )

latitude

Float: the latitude of the point in the WGS84 (GPS) Earth model.

longitude

Float: the longitude of the point in the WGS84 (GPS) Earth model.

format

Boolean: true to return the grid reference with a hemisphere identifier:

N 12345 67890

false (default) to return the grid reference with a zone identifier (the same letters as the latitude bands in UTM):

Y 12345 67890

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return one of the following strings (depending on whether the format parameter was false or true):

zone_letter easting northing
hemisphere_identifier easting northing

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return one of the following strings (depending on whether the format parameter was false or true):

zone_letter easting northing
hemisphere_identifier easting northing

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return one of the following arrays (depending on whether the format parameter was false or true):

Array((int)hemisphere,(float)easting,(float)northing,(string)zone_letter)
Array((int)hemisphere,(float)easting,(float)northing,(string)hemisphere_identifier)

hemisphere will be 1 for points to the north of the equator and -1 for points to the south of it. hemisphere_identifier will be 'N' for points to the north of the equator and 'S' for points to the south of it.

deny_bad_coords

Boolean: true to return false if the latitude is less than 83.5 and greater than -79.5, or if latitude or longitude cannot be recognised as numbers. False to return the easting and northing as 2000000, and the hemisphere identifier or zone letter as 'OUT_OF_GRID', if the latitude is less than 83.5 and greater than -79.5, or if latitude or longitude cannot be recognised as numbers.

precise

Methods for conversion between different latitude/longitude formats

Some precision will be lost during conversion, by truncation and floating point errors, as well as by limitations of the conversion algorithms. When returning text or HTML string versions of latitude/longitude decimal degrees, values will be given to a precision of 10 decimal places. These methods are provided to allow production or recognition of several different formats, to match user expectations or to match the formats used by various GPS software.

dd_to_dms (PHP) or ddToDms (JS): Converts decimal degrees (49.5,-123.5) to either the decimal minutes format (49°30'N, 123°30'W) or the more common degrees-minutes-seconds format (49°30'0"N, 123°30'0"W) for latitude,longitude.
dd_format (PHP) or ddFormat (JS): Converts decimal degrees (49.5,-123.5) to either the format using hemisphere units (49.5°N, 123.5°W) or the simple format without hemisphere units (49.5°, -123.5°) for latitude,longitude.
dms_to_dd (PHP) or dmsToDd (JS): Converts degrees-minutes-seconds format (49°30'0"N, 123°30'0"W) and a variety of other latitude/longitude formats to decimal degrees (49.5,-123.5) for latitude,longitude.

dd_to_dms, ddToDms

Converts decimal degrees (49.5,-123.5) to either the decimal minutes format (49°30'N, 123°30'W) or the more common degrees-minutes-seconds format (49°30'0"N, 123°30'0"W) for latitude,longitude. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 6 decimal places for degrees-minutes-seconds, or 8 decimal places for decimal minutes.

method( latitude, longitude[, only_dm[, return_type]] )

method( Array( latitude, longitude )[, only_dm[, return_type]] )

latitude

Float: latitude of the point in decimal degrees.

longitude

Float: longitude of the point in decimal degrees.

only_dm

Boolean: true to return decimal minutes (49°30.7'N, 123°30.7645'W). False (default) to return the more normal degrees-minutes-seconds.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return one of the following strings (depending on whether the only_dm parameter was false or true):

deg°min'sec"N, deg°min'sec"E
deg°min'N, deg°min'E

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return one of the following strings (depending on whether the only_dm parameter was false or true):

deg<string>min'sec"N, deg<string>min'sec"E
deg<string>min'N, deg<string>min'E

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return one of the following strings (depending on whether the only_dm parameter was false or true):

deg&deg;min'sec&quot;N, deg&deg;min'sec&quot;E
deg&deg;min'N, deg&deg;min'E

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return one of the following arrays (depending on whether the only_dm parameter was false or true):

Array((int)lat_degrees,(int)lat_minutes,(float)lat_seconds,(int)lat_multiplier,(int)long_degrees,(int)long_minutes,(float)long_seconds,(int)long_multiplier)
Array((int)lat_degrees,(float)lat_minutes,0,(int)lat_multiplier,(int)long_degrees,(float)long_minutes,0,(int)long_multiplier)

lat_multiplier will be 1 for points to the north of the equator and -1 for points to the south of it. long_multiplier will be 1 for points to the east of the meridian and -1 for points to the west of it.

dd_format, ddFormat

Converts decimal degrees (49.5,-123.5) to either the format using hemisphere units (49.5°N, 123.5°W) or the simple format without hemisphere units (49.5°, -123.5°) for latitude,longitude.

method( latitude, longitude[, no_units[, return_type]] )

method( Array( latitude, longitude )[, no_units[, return_type]] )

latitude

Float: latitude of the point in decimal degrees.

longitude

Float: longitude of the point in decimal degrees.

no_units

Boolean: true to return the number of degrees without hemisphere units (49.5°, -123.5°). False (default) to return the number of degrees with hemisphere units (49.5°N, 123.5°W).

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return one of the following strings (depending on whether the no_units parameter was false or true):

deg°N, deg°E
deg°, deg°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return one of the following strings (depending on whether the no_units parameter was false or true):

deg<string>N, deg<string>E
deg<string>, deg<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return one of the following strings (depending on whether the no_units parameter was false or true):

deg&deg;N, deg&deg;E
deg&deg;, deg&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return one of the following arrays (depending on whether the no_units parameter was false or true):

Array((float)lat_degrees,0,0,(int)lat_multiplier,(float)long_degrees,0,0,(int)long_multiplier)
Array((float)lat_degrees,0,0,1,(float)long_degrees,0,0,1)

dms_to_dd, dmsToDd

Converts degrees-minutes-seconds format (49°30'0"N, 123°30'0"W) and a variety of other latitude/longitude formats to decimal degrees (49.5,-123.5) for latitude,longitude.

method( coordinates[, return_type[, deny_bad_coords[, allow_unitless]]] )

method( Array( lat_degrees, lat_minutes, lat_seconds, lat_multiplier, long_degrees, long_minutes, long_seconds, long_multiplier )[, return_type] )

coordinates

String: representation of coordinates in degrees-minutes-seconds, degrees-minutes or degrees format - examples:

'49°30'0"N, 123°30'0"W'
'17.20°S 123.54°E'
'-17.20°, 123.54°'
'-49d30m0.5s, -123d30m0.5s'
'17.20S, 123.54E'
'-17.20N 123.54W'

The actual formats supported include anything matching this pattern, where <separator> is any non-numeric character - leading and trailing whitespace is ignored, as well as whitespace after separators, and before/after the comma:

[-]<float><separator>[<float><separator>[<float><separator>]]([NS][,]|,)[-]<float><separator>[<float><separator>[<float><separator>]][EW]
[-]<float>[NS][,][-]<float>[EW]

lat_degrees

Positive integer or float: degrees component of latitude.

lat_minutes

Positive integer or float: minutes component of latitude.

lat_seconds

Positive float: seconds component of latitude.

lat_multiplier

Integer: 1 for points to the north of the equator and -1 for points to the south of it.

long_degrees

Positive integer or float: degrees component of longitude.

long_minutes

Positive integer or float: minutes component of longitude.

long_seconds

Positive float: seconds component of longitude.

long_multiplier

Integer: 1 for points to the east of the meridian and -1 for points to the west of it.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude)

deny_bad_coords

Boolean: true to return false if the coordinates cannot be recognised as a possible latitude/longitude format. False (default) to treat the coordinates as 0,0 if the coordinates cannot be recognised as a possible latitude/longitude format.

allow_unitless

Boolean: true to also recognise the following input format:

[-]<float>,[-]<float>

False (default) to treat that format as invalid.

Shifting grid coordinates between earth models using bilinear interpolation

Grid shifting using bilinear interpolation currently offers the highest accuracy method of transforming coordinates from a grid based on idealised Earth models, into grid coordinates used by local mapping, that most closely represents the real measurements that would be taken with land-based mapping techniques. This can take all of the local distortions of gravity into account, applying horizontal and vertical geoid shifts at the same time, to convert from GPS based grid coordinates into high accuracy local mapping grids such as the British National Grid. Those new grid coordinates can be based on a local Earth model rather than the original Earth model, but will now be a more realistic representation of the Earth at that particular location. Unlike most other methods defined here, grid shifting relies on potentially extensive databases of sample points, and an external data source is therefore required.

The methods here expect data to be provided by an external database of some kind, and the method of communicating with that database and loading the data is left up to the implementation. The data is expected to be provided in a regular easting-northing grid of points, supplied in whichever format the local mapping agency offers (such as CSV with the British Ordnance Survey). The methods here will request data, providing the coordinates of the sample points, and the record index of the sample points within the data grid. Because the files are generally too large to transmit in full as Web page data, it is expected that JavaScript will need to use dynamic requests to a server, and as such, it will probably need to operate asynchronously. The JavaScript version of the script therefore offers a callback feature that can be used to run the code asynchronously if needed.

When returning coordinates as high precision text or HTML strings, values will be given to a precision of 6 decimal places. When returning text or HTML string versions of heights, values will be given to a precision of 6 decimal places.

Examples of grid shifting transformations that may be used with this feature include OSTN15 and OSGM15 for Great Britain.

shift_grid (PHP) or shiftGrid (JS): Returns the coordinates and optionally also height of a point with its coordinates shifted into the new datum using bilinear interpolation, and its geoid undulation (the difference between an ellipsoid and a geoid) subtracted from it.
reverse_shift_grid (PHP) or reverseShiftGrid (JS): Returns the coordinates and optionally also height of a point with its coordinates shifted in reverse from one datum into another using bilinear interpolation, and its geoid undulation (the difference between an ellipsoid and a geoid) added to it.
get_shift_set (PHP) or getShiftSet (JS): Returns a predefined shift set that can be used as the shiftset parameter with shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid.
create_shift_set (PHP) or createShiftSet (JS): Returns a custom shift set that can be used as the shiftset parameter with shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid.
create_shift_record (PHP) or createShiftRecord (JS): Returns a custom bilinear interpolation shift record that can be returned to a request for shift data, or cached using cache_shift_records/cacheShiftRecords.
cache_shift_records (PHP) or cacheShiftRecords (JS): Caches bilinear interpolation shift records so that they do not need to be requested dynamically. This can be done in advance of making a request to shift_grid/shiftGrid or reverse_shift_grid/reverseShiftGrid, to reduce the need for loading data dynamically.
delete_shift_cache (PHP) or deleteShiftCache (JS): Deletes the cached bilinear interpolation shift records for a particular shift set, or for all shift sets at once, to reduce memory usage.

shift_grid, shiftGrid, reverse_shift_grid, reverseShiftGrid

Returns the coordinates and optionally also height of a point with its coordinates shifted either forward or in reverse into the new datum using bilinear interpolation, and its geoid undulation (the difference between an ellipsoid and a geoid) subtracted from it (shift_grd/shiftGrd) or added to it (reverse_shift_grd/reverseShiftGrd). Returns false if shiftset or return_type are not valid. Returns false if return_callback has been specified with an invalid value.

If the grid reference sits exactly on a line of data points, the methods will use the same data points for both sides of the bilinear interpolation. This is slightly different from the algorithm given by Ordnance Survey, but will return the same results in all cases. The benefit of this approach is that it can return values even when the grid reference is on the final line of data points in the shift grid, where the Ordnance Survey algorithm cannot. When returning data arrays, the methods can also return datum information, if it is provided. This allows the returned data to be checked to see if two or more different datums were used, since this means that the geoid undulation cannot be properly related to any datum.

PHP

method( easting, northing[, height], shiftset, fetch_records[, return_type[, deny_bad_coords[, precise]]] )

method( array( easting, northing ), height, shiftset, fetch_records[, return_type[, deny_bad_coords[, precise]]] )

method( array( easting, northing[, height] ), shiftset, fetch_records[, return_type[, deny_bad_coords[, precise]]] )

JS

method( easting, northing[, height], shiftset, fetch_records[, return_type[, deny_bad_coords[, precise[, return_callback]]]] )

method( array( easting, northing ), height, shiftset, fetch_records[, return_type[, deny_bad_coords[, precise[, return_callback]]]] )

method( array( easting, northing[, height] ), shiftset, fetch_records[, return_type[, deny_bad_coords[, precise[, return_callback]]]] )

easting

Float: easting coordinate of the grid reference.

northing

Float: northing coordinate of the grid reference.

height

Float: the height of the point in metres - if this parameter is provided, the return value will also include height.

shiftset

shift set. Invalid values will cause the method to treat all values as if they were out of the transformation area.

fetch_records

PHP: String: callback function that will be called with call_user_func to retrieve data. Further details below.

JS: Function: callback function that will be called to retrieve data. Further details below.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return one of the following strings (depending on whether the height parameter was provided):

easting,northing
easting,northing,height

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return one of the following strings (depending on whether the height parameter was provided):

easting,northing
easting,northing,height

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return one of the following arrays (depending on whether the height parameter and datum information was provided):

Array((float)easting,(float)northing)
Array((float)easting,(float)northing,(float)height)
Array((float)easting,(float)northing,(array)datum_information)
Array((float)easting,(float)northing,(float)height,(array)datum_information)

datum_information will be provided if any of the data points had additional datum information supplied. The array will contain 4 cells, representing the four corners of the shift grid square; bottom_left, bottom_right, top_right, top_left. The cells will contain the datum information that was returned for their respective data points.

deny_bad_coords

Boolean: true to return false if the coordinates are outside the available shift grid, or if fetch_records fails to return any useful values. False (default) to return 'OUT_OF_GRID' with strings or NAN/NaN with data arrays for all values if the coordinates are outside the available shift grid, or if fetch_records fails to return any useful values.

precise

Boolean: true to return floating point easting and northing when returning strings. False (default) to return integers for easting and northing when returning strings.

return_callback

JS: Function: callback function that will be passed the results instead of returning them directly. If supplied, asynchronous operation is enabled. Further details below.

JS: null (default): results are returned directly, and synchronous operation is enabled.

When needed, fetch_records will be called, and passed two or three parameters:

name: String: the name of the shift set.
records: Array: array listing all uncached records needed for the current point.
data_callback: Function: only supplied when asynchronous operation is enabled in JavaScript. With PHP, or when synchronous operation is enabled in JavaScript, this parameter is not provided.

The records parameter will be an array of arrays (PHP) or objects (JS) with the folllowing keys/properties:

easting: Integer: the easting of the data point in the shift grid. (This can be a floating point number if your shift set uses floating point spacing or offsets, but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
northing: Integer: the northing of the data point in the shift grid. (This can be a floating point number if your shift set uses floating point spacing or offsets, but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
record: Optional integer: the record index of the data point in the shift grid. This will only be supplied if your shift set has a non-zero recordcols value.

Record index is calculated from: easting record index + ( northing record index * recordcols ) + recordstart, where the easting record index is ( easting - x_starts_at ) / x_spacing, and the northing record index is ( northing - y_starts_at ) / x_spacing. Since a shift set may choose not to specify the number of columns that it covers (the number can actually be variable at different points in the grid), and it may also choose not to supply record indexing, the record index is not used for caching. Instead, the easting and northing are used to recognise cached values. Floating point offsets and spacing can probably work, but it is possible for a floating point number to get different rounding or precision errors when returned from different systems, and this can cause databases not to recognise which easting and northing records are being requested. Implementations are therefore strongly encouraged to use integer-based offsets and spacing.

With PHP, or when synchronous mode is enabled in JavaScript, fetch_records must return an array of bilinear interpolation shift records. There is no need to cache the records in advance, as they will be automatically cached immediately after they are returned. Note that this means that simply supplying reponses to a fetch_records callback call, will result in an increase in memory usage, until the PHP script ends, or the page containing the JavaScript is unloaded, or until the cache is deleted. This will speed up future calls to shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid within the same shift grid cell, as it removes the need to use the fetch_records callback next time. If fetch_records cannot locate the requested records, it must respond with an empty array or null. This will then cause shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid to return false.

When asynchronous operation is enabled in JavaScript, fetch_records must not return its results directly. Instead, it must call the data_callback, passing it the array of results as a parameter. The same caching and data format rules apply as for synchronous mode. The only difference is that the results must be passed to the callback function instead of being returned directly. This allows an asynchronous database call to take place, and use the callback when records have been obtained. When asynchronous operation is enabled in JavaScript, shiftGrid and reverseShiftGrid will always use the return_callback to pass back responses, instead of returning values, even if an error occurs (except of course an invalid return_callback value). These calls will always be asynchronous when asynchronous operation is enabled. If fetch_records calls the data_callback in the same thread, the response will be forced to become asynchronous, to ensure that the code that calls applyGeoid always gets a consistent execution sequence.

get_shift_set, getShiftSet

Returns a predefined shift set that can be used as the shiftset parameter with shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid. Returned shift sets will have a name that matches the name used to request them, will be passed by shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid to the fetch_records callback function as the name parameter when fetching records.

method( name )

name

String: one of the predefined names:

'OSTN15': OSTN15 transformation used by British Ordnance Survey to convert between ETRS89 GPS coordinates and British National Grid grid references and heights, the OSTN15_OSGM15_DataFile.txt file.

Invalid names will cause the method to return false.

create_shift_set, createShiftSet

Returns a custom shift set that can be used as the shiftset parameter with shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid. Missing name or a spacing of 0 will cause it to return false.

method( name, x_spacing, y_spacing[, x_starts_at[, y_starts_at[, record_columns[, recort_start]]]] )

name: String: identifier name for the grid set. This will be passed by shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid to the fetch_records callback function as the name parameter when fetching records.
x_spacing: Integer: the East-West spacing between data points in the shift grid. (This can be a floating point number but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
y_spacing: Integer: the North-South spacing between data points in the shift grid. (This can be a floating point number but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
x_starts_at: Integer: the easting at which the data points will start. Only needed if using record index to search for records. Default 0. (This can be a floating point number but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
y_starts_at: Integer: the northing at which the data points will start. Only needed if using record index to search for records. Default 0. (This can be a floating point number but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
record_columns: Integer: the number of columns of data records in the grid. Only needed if using record index to search for records. Default 0 (meaning that record indexes will not be used).
record_start: Integer: the record index for the first data point. Default 0.

create_shift_record, createShiftRecord

Returns a bilinear interpolation shift record that can be returned by a fetch_records callback function when called from shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid, or which can be cached using cache_shift_records/cacheShiftRecords.

method( easting, northing, east_shift, north_shift, geoid_undulation[, datum] )

easting: Integer: the easting of the data point in the shift grid. (This can be a floating point number if your shift set uses floating point spacing or offsets, but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
northing: Integer: the northing of the data point in the shift grid. (This can be a floating point number if your shift set uses floating point spacing or offsets, but floating point numbers may have matching issues, and are very strongly discouraged. Shift sets should use integers.)
east_shift: Float: the shift East. Positive numbers move the point further East with shift_grid/shiftGrid or West with reverse_shift_grid/reverseShiftGrid.
north_shift: Float: the shift North. Positive numbers move the point further North with shift_grid/shiftGrid or South with reverse_shift_grid/reverseShiftGrid.
geoid_undulation: Float: the geoid undulation of the data point (the difference between the ellipsoid height and the geoid, or the value needed to shift the point from one Earth model to another). Positive numbers decrease the height with shift_grid/shiftGrid and increase the height with reverse_shift_grid/reverseShiftGrid.
datum: Mixed: any value which will help you identify the datum that is used for a data point.

cache_shift_records, cacheShiftRecords

Caches bilinear interpolation shift records, so that further calls to shift_grid/shiftGrid and reverse_shift_grid/reverseShiftGrid do not need to use the fetch_records callback function to retrieve those data records. This can be used in advance to speed up operations, avoiding the need to make multiple dynamic requests to a database. Invalid names or records will cause the method to return false and abort caching. Returns true otherwise.

This method is called automatically when returning values from a fetch_records callback function, so returned values will be automatically cached. Repeated calls to this method with the same easting and northing will cause it to cache the most recent shift values.

method( name, record )

method( name, array( record[, record[, ...]] ) )

name: String: identifier name for the shift set that the record applies to.
record: Bilinear interpolation shift record.; null: causes nothing to be cached, returns true.

delete_shift_cache, deleteShiftCache

Deletes all cached bilinear interpolation shift records for a particular shift set, or for all shift sets at once, to reduce memory usage.

method()

method( name )

name: String: identifier name for the shift set whose records should be deleted from the cache.; null (default): delete all cached records for all shift sets.

Methods for conversion between different latitude/longitude Earth models using Helmert transformation

Some precision will be lost during conversion, by truncation and floating point errors, as well as by limitations of the conversion algorithms. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 10 decimal places. When returning text or HTML string versions of heights, values will be given to a precision of 6 decimal places.

Helmert_transform (PHP) or HelmertTransform (JS): Returns the longitude/latitude[/height] coordinates of the given point, transformed from one Earth model to another. As an example, this can be used to convert coordinates from the Airy 1830 Earth model used by the British Ordnance Survey, to the WGS84/GRS80 Earth model used by GPS.
get_transformation (PHP) or getTransformation (JS): Returns a predefined Helmert transformation parameter set that can be used as the transform_via parameter with Helmert_transform/HelmertTransform.
create_transformation (PHP) or createTransformation (JS): Returns a custom Helmert transformation parameter set that can be used as the transform_via parameter with Helmert_transform/HelmertTransform.

Helmert_transform, HelmertTransform

Returns the longitude/latitude[/height] coordinates of the given point, transformed from one Earth model to another. As an example, this can be used to convert coordinates from the Airy 1830 Earth model used by the British Ordnance Survey, to the WGS84/GRS80 Earth model used by GPS. Invalid ellipsoids or transform parameter sets will cause the method to return false.

When heights are omitted (which is a common approach), a height of 0 will be assumed during the transformation. This has a very small effect on the horizontal results, around 15 cm displacement per 1 km of elevation, in real cases. This is completely overshadowed by the imperfections of Helmert transformation parameter sets at representing the real World, which are typically up to a few metres in real cases. Therefore the displacement caused by omiting the height can normally be safely ignored.

method( latitude, longitude[, height], ellipsoid_from, transform_via, ellipsoid_to[, return_type] )

method( Array( latitude, longitude ), height, ellipsoid_from, transform_via, ellipsoid_to[, return_type] )

method( Array( latitude, longitude[, height] ), ellipsoid_from, transform_via, ellipsoid_to[, return_type] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

height

Float: height of the point in metres (not normally used) - if this parameter is provided, the return value will also include height.

ellipsoid_from

Ellipsoid parameter set for the source Earth model.

transform_via

Helmert transformation parameter set to use when converting from the source model to the destination.

ellipsoid_to

Ellipsoid parameter set for the destination Earth model.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return one of the following strings (depending on whether the height parameter was provided):

latitude°, longitude°
latitude°, longitude°, height

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return one of the following strings (depending on whether the height parameter was provided):

latitude<string>, longitude<string>
latitude<string>, longitude<string>, height

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return one of the following strings (depending on whether the height parameter was provided):

latitude&deg;, longitude&deg;,
latitude&deg;, longitude&deg;, height

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return one of the following arrays (depending on whether the height parameter was provided):

Array((float)latitude,(float)longitude)
Array((float)latitude,(float)longitude,(float)height)

get_transformation, getTransformation

Returns a predefined Helmert transformation parameter set that can be used as the transform_via parameter with Helmert_transform/HelmertTransform.

method( name )

name

String: one of the predefined names:

'OSGB36_to_WGS84': Used to transform from OS Airy 1830 coordinates to WGS84/GRS80 coordinates.
'WGS84_to_OSGB36': Used to transform from WGS84/GRS80 coordinates to OS Airy 1830 coordinates.
'Ireland65_to_WGS84': Used to transform from OSI modified Airy 1830 coordinates to WGS84/GRS80 coordinates.
'WGS84_to_Ireland65': Used to transform from WGS84/GRS80 coordinates to OSI modified Airy 1830 coordinates.

Invalid names will cause the method to return false.

create_transformation, createTransformation

Returns a custom Helmert transformation parameter set that can be used as the transform_via parameter with Helmert_transform/HelmertTransform. Make sure you use valid values, as invalid values can cause some loops to run for a long time, and produce poor performance.

method( translation_x, translation_y, translation_z, scale_factor, rotation_x, rotation_y, rotation_z )

translation_x: Float: translation vector x axis component in metres.
translation_y: Float: translation vector y axis component in metres.
translation_z: Float: translation vector z axis component in metres.
scale_factor: Float: scale factor in ppm.
rotation_x: Float: rotation matrix x axis component in arcseconds.
rotation_y: Float: rotation matrix y axis component in arcseconds.
rotation_z: Float: rotation matrix z axis component in arcseconds.

Methods for conversion between different latitude/longitude Earth models using polynomial transformation

When available, this can provide much more accurate transformations than Helmert transformations, taking localised distortions into account. Rather than transforming to an idealised earth model (such as an ellipsoid), it transforms to or from a more realistic representation of the Earth at a particular location, with coordinates that can then be projected into mapping grids that reflect real distortions in the shape of the World and its gravity. While not as perfect as approaches like grid shifting, it allows large areas to be well represented with very small amounts of correction data. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 10 decimal places.

polynomial_transform (PHP) or polynomialTransform (JS): Returns the longitude/latitude coordinates of the given point, transformed from one Earth model to another. As an example, this can be used to convert coordinates from the Modified Airy 1830 Earth model used by the Ordnance Survey Ireland, to the GRS80 Earth model used by ETRS89.
reverse_polynomial_transform (PHP) or reversePolynomialTransform (JS): Returns the longitude/latitude coordinates of the given point, transformed in reverse from one Earth model to another. As an example, this can be used to convert coordinates from the GRS80 Earth model used by ETRS89 to the Modified Airy 1830 Earth model used by the Ordnance Survey Ireland.
get_polynomial_coefficients (PHP) or getPolynomialCoefficients (JS): Returns predefined transformation coefficients that can be used as the coefficients parameter with polynomial_transform/polynomialTransform.
create_polynomial_coefficients (PHP) or createPolynomialCoefficients (JS): Returns custom transformation coefficients that can be used as the coefficients parameter with polynomial_transform/polynomialTransform.

polynomial_transform, polynomialTransform, reverse_polynomial_transform, reversePolynomialTransform

Returns the longitude/latitude coordinates of the given point, transformed forwards or in reverse from one Earth model to another. As an example, polynomial_transform/polynomialTransform can be used to convert coordinates from the Modified Airy 1830 Earth model used by the Ordnance Survey Ireland, to the GRS80 Earth model used by ETRS89, and reverse_polynomial_transform/reversePolynomialTransform can be used to convert coordinates from the GRS80 Earth model used by ETRS89 to the Modified Airy 1830 Earth model used by the Ordnance Survey Ireland. They can also be used to apply localised distortions without transforming to a new Earth model, if coefficients are available for that purpose. Invalid coefficients will cause the method to return false.

method( latitude, longitude, coefficients[, return_type] )

method( Array( latitude, longitude ), coefficients[, return_type] )

latitude

Float: the latitude of the point in the source Earth model.

longitude

Float: the longitude of the point in the source Earth model.

coefficients

transformation coefficients to use when converting from the source model to the destination.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude)

get_polynomial_coefficients, getPolynomialCoefficients

Returns predefined transformation coefficients that can be used as the coefficients parameter with polynomial_transform/polynomialTransform and reverse_polynomial_transform/reversePolynomialTransform.

method( name )

name

String: one of the predefined names:

'OSiLPS': Used to transform from OSI modified Airy 1830 coordinates to WGS84/GRS80 coordinates, with 95% of the results having an accuracy of 0.4 m.

Invalid names will cause the method to return false.

create_polynomial_coefficients, createPolynomialCoefficients

Returns custom transformation coefficients that can be used as the coefficients parameter with polynomial_transform/polynomialTransform and reverse_polynomial_transform/reversePolynomialTransform.

method( order, positive, latitude_m, longitude_m, k0, latitude_coefficients, longitude_coefficients )

order: Integer: the order of the polynomial, eg. 3 for a third order polynomial. Currently only third order polynomials are supported, so 3 is the only valid value.
positive: Boolean: true to add polynomial transformation shift to the original coordinates with forward transformation, and subtract it from them in reverse transformation (like the 'OSiLPS' transformation). False to subtract polynomial transformation shift from the original coordinates with forward transformation, and add it to them in reverse transformation.
latitude_m: Float: latitude in the middle of the region, which may also be known as φ_m.
longitude_m: Float: longitude in the middle of the region, which may also be known as λ_m.
k0: Float: multiplication factor, which may be known as a variation of k₀ or K_o.
latitude_coefficients: Array: A_ij coefficients. A 3*3 two-dimensional array of A[i][j] = float value, where i is 0 to 3, and j is 0 to 3. Minimal checking is done to verify that the array is multi-dimensional. Invalid arrays will cause the method to return false. Array lengths and values are not checked.
longitude_coefficients: Array: B_ij coefficients. A 3*3 two-dimensional array of B[i][j] = float value, where i is 0 to 3, and j is 0 to 3. Minimal checking is done to verify that the array is multi-dimensional. Invalid arrays will cause the method to return false. Array lengths and values are not checked.

Methods for conversion between Earth model heights and geoid heights using bilinear interpolation

Geoids are a way of representing the uneven effects gravity across a planet, and the approximate relationship between ellipsoid height and local mean sea level at that point. In general, geoids do not take ocean currents and tidal channels into account (except in the cases of local mapping geoids like OSGM15), but they are much better at approximating local heights than an ellipsoid height. Unlike most other methods defined here, geoids rely on potentially extensive databases of sample points, and an external data source is therefore required.

The methods here expect data to be provided by an external database of some kind, and the method of communicating with that database and loading the data is left up to the implementation. The data is expected to be provided in a regular latitude-longitude grid of points, typically supplied by the .grd file format. The methods here will request data, providing the coordinates of the sample points, and the latitude and longitude index and overall index of the sample points within the data grid. Because the files are generally too large to transmit in full as Web page data, it is expected that JavaScript will need to use dynamic requests to a server, and as such, it will probably need to operate asynchronously. The JavaScript version of the script therefore offers a callback feature that can be used to run the code asynchronously if needed.

Examples of grids that may be used with this feature include the OSGM15_Belfast.gri and OSGM15_Malin.gri for Ireland (Northern and Republic), and the global EGM96 ww15mgh.grd.

When returning text or HTML string versions of heights, values will be given to a precision of 6 decimal places.

apply_geoid (PHP) or applyGeoid (JS): Returns the height of a point with its geoid undulation (the difference between an ellipsoid and a geoid) added or subtracted from it.
get_geoid_grd (PHP) or getGeoidGrd (JS): Returns a predefined geoid grd specification that can be used as the geoid_grd parameter with apply_geoid/applyGeoid.
create_geoid_grd (PHP) or createGeoidGrd (JS): Returns a custom geoid grd specification that can be used as the geoid_grd parameter with apply_geoid/applyGeoid.
create_geoid_record (PHP) or createGeoidRecord (JS): Returns a custom geoid grd data point record that can be returned to a request for geoid data, or cached using cache_geoid_records/cacheGeoidRecords.
cache_geoid_records (PHP) or cacheGeoidRecords (JS): Caches geoid grd data point records so that they do not need to be requested dynamically. This can be done in advance of making a request to apply_geoid/applyGeoid, to reduce the need for loading data dynamically.
delete_geoid_cache (PHP) or deleteGeoidCache (JS): Deletes the cached geoid grd data point records for a particular geoid grd specification, or for all geoid grd specifications at once, to reduce memory usage.

apply_geoid, applyGeoid

Returns the height of a point with its geoid undulation (the difference between an ellipsoid and a geoid) added or subtracted from it. Returns false if the point is not within the area covered by the geoid grd specification. Returns false if shiftset or return_type are not valid. Returns false if return_callback has been specified with an invalid value.

In cases where the geoide grd specification has latitude spacing or longitude spacing that has been truncated or rounded to a value that does not perfectly divide into the latitude or longitude ranges, the values will be corrected to the nearest value which does divide correctly. This should preserve the intent of the files, rather than the actual values supplied. This, for example, allows the OSGM15 files to use 0.013333 degrees to represent 0.0133-recurring degrees, or 0.8 minutes, or 48 seconds. Be aware that the fetch_records callback functions will be passed latitude and longitude indexes, latitudes and longitudes that are based on this corrected value.

PHP

method( latitude, longitude, height, direction, geoid_grd, fetch_records[, return_type[, deny_bad_coords]] )

method( array( latitude, longitude ), height, direction, geoid_grd, fetch_records[, return_type[, deny_bad_coords]] )

method( array( latitude, longitude, height ), direction, geoid_grd, fetch_records[, return_type[, deny_bad_coords]] )

JS

method( latitude, longitude, height, direction, geoid_grd, fetch_records[, return_type[, deny_bad_coords[, return_callback]]] )

method( array( latitude, longitude ), height, direction, geoid_grd, fetch_records[, return_type[, deny_bad_coords[, return_callback]]] )

method( array( latitude, longitude, height ), direction, geoid_grd, fetch_records[, return_type[, deny_bad_coords[, return_callback]]] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

height

Float: the height of the point (either ellipsoid or geoid height) in metres.

direction

Boolean: true to subtract the geoid undulation (typically the direction that data is supplied to convert from ellipsoid height to geoid height), false to add it (typically the direction that data is supplied to convert from geoid height to ellipsoid height).

geoid_grd

Geoid grd specification. Invalid values will normally cause the method to return false.

fetch_records

PHP: String: callback function that will be called with call_user_func to retrieve data. Further details below.

JS: Function: callback function that will be called to retrieve data. Further details below.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

height

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

height

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following value (note that this is a single value, not an array):

(float)height

deny_bad_coords

Boolean: true to return false if the coordinates are outside the available geoid grd, or if fetch_records fails to return any useful values. False (default) to return NAN/NaN if the coordinates are outside the available geoid grd, or if fetch_records fails to return any useful values.

return_callback

JS: Function: callback function that will be passed the results instead of returning them directly. If supplied, asynchronous operation is enabled. Further details below.

JS: null (default): results are returned directly, and synchronous operation is enabled.

When needed, fetch_records will be called, and passed two or three parameters:

name: String: the name of the geoid grd specification.
records: Array: array listing all uncached records needed for the current point.
data_callback: Function: only supplied when asynchronous operation is enabled in JavaScript. With PHP, or when synchronous operation is enabled in JavaScript, this parameter is not provided.

The records parameter will be an array of arrays (PHP) or objects (JS) with the folllowing keys/properties:

latitude: Float: the latitude of the data point in the geoid grd. This will be rounded to the number of decimal places specified by the geoid grd specification's latitude_spacing_decimal_places parameter (which should be the number of decimal places given for the latitude spacing or the minimum latitude value, whichever is longer).
longitude: Float: the longitude of the data point in the geoid grd. This will be rounded to the number of decimal places specified by the geoid grd specification's longitude_spacing_decimal_places parameter (which should be the number of decimal places given for the longitude spacing or the minimum longitude value, whichever is longer).
latindex: Integer: the 0-based latitude index of the data point in the geoid grd, starting from the northern-most value.
longindex: Integer: the 0-based longitude index of the data point in the geoid grd, starting from the western-most value.
recordindex: Integer: the 0-based record index of the data point in the geoid grd.

Latitude and longitude index will be the 0-based index of the data point within the geoid grd. For example, the second point from the north-most latitude and third point from the west-most longitude will have a latitude index of 1 and longitude index of 2. The overall record index is also available in case the data is not organised any better than the original grd file (since grd files are basically a long list of values). Latitude and longitude will be rounded to the number of significant figures given for the geoid grd specification (applying any corrections needed to match the intended positions of the points), and longitude will be supplied within the same range as the geoid grd specification (so anywhere within -180 to 360 inclusive).

With PHP, or when synchronous mode is enabled in JavaScript, fetch_records must return an array of geoid grd data point records. There is no need to cache the records in advance, as they will be automatically cached immediately after they are returned. Note that this means that simply supplying reponses to a fetch_records callback call, will result in an increase in memory usage, until the PHP script ends, or the page containing the JavaScript is unloaded, or until the cache is deleted. This will speed up future calls to apply_geoid/applyGeoid within the same geoid grd cell, as it removes the need to use the fetch_records callback next time. If fetch_records cannot locate the requested records, it must respond with an empty array or null. This will then cause apply_geoid/applyGeoid to return false.

When asynchronous operation is enabled in JavaScript, fetch_records must not return its results directly. Instead, it must call the data_callback, passing it the array of results as a parameter. The same caching and data format rules apply as for synchronous mode. The only difference is that the results must be passed to the callback function instead of being returned directly. This allows an asynchronous database call to take place, and use the callback when records have been obtained. When asynchronous operation is enabled in JavaScript, applyGeoid will always use the return_callback to pass back responses, instead of returning values, even if an error occurs (except of course an invalid return_callback value). These calls will always be asynchronous when asynchronous operation is enabled. If fetch_records calls the data_callback in the same thread, the response will be forced to become asynchronous, to ensure that the code that calls applyGeoid always gets a consistent execution sequence.

get_geoid_grd, getGeoidGrd

Returns a predefined geoid grd specification that can be used as the geoid_grd parameter with apply_geoid/applyGeoid. Returned specifications will have a name that matches the name used to request them, will be passed by apply_geoid/applyGeoid to the fetch_records callback function as the name parameter when fetching records.

method( name )

name

String: one of the predefined names:

'OSGM15_Belfast': OSGM15 geoid configuration used by Land & Property Services to convert between ETRS89 GPS elevations and local mapping heights for the Irish Grid and Irish Transverse Mercator within Northern Ireland, the OSGM15_Belfast.gri file.
'OSGM15_Malin': OSGM15 geoid configuration used by Ordnance Survey Ireland to convert between ETRS89 GPS elevations and local mapping heights for the Irish Grid and Irish Transverse Mercator within the Republic of Ireland, the OSGM15_Malin.gri file.
'EGM96_ww15mgh': EGM96 global geoid configuration for the worldwide 15 minute gridded geoid heights, the ww15mgh.grd file.

Invalid names will cause the method to return false.

create_geoid_grd, createGeoidGrd

Returns a custom geoid grd specification that can be used as the geoid_grd parameter with apply_geoid/applyGeoid. Most of the values can be found in the header line of the relevant .grd file. Missing name, reversed max/min values, or a spacing of 0 will cause it to return false.

Longitude ranges can be a complete circle including the values at both ends, and can also use negative longitudes or an entire circle of values above 0, such as -180 degrees to 180 degrees, or 0 degrees to 360 degrees, which allows the data to cover the entire ellipsoid in whichever format the grd file supplies. In cases where the full range of longitudes is supplied, identical data points must exist at both ends of the range, such as 0 and 360 degrees.

The range of longitudes must be continuous, with the max value larger than the min value. In cases where the latitude range covers a partial circle which crosses the 180° line, the values beyond that line should use positive numbers. It is, for example, possible to have a range of 90° to 270°, or even -10° to 270°. It is not possible to have a range of 90° to -90° via 180°.

method( name, latitude_min, latitude_max, longitude_min, longitude_max, latitude_spacing, longitude_spacing, latitude_spacing_decimal_places, longitude_spacing_decimal_places )

name: String: identifier name for the specification. This will be passed by apply_geoid/applyGeoid to the fetch_records callback function as the name parameter when fetching records.
latitude_min: Float: the minimum latitude of the geoid grd. This is usually the first value in a .grd file's header.
latitude_max: Float: the maximum latitude of the geoid grd. This is usually the second value in a .grd file's header.
longitude_min: Float: the minimum longitude of the geoid grd. This is usually the third value in a .grd file's header.
longitude_max: Float: the maximum longitude of the geoid grd. This is usually the fourth value in a .grd file's header.
latitude_spacing: Float: the latitude spacings between data points in the geoid grd. This is usually the fifth value in a .grd file's header.
longitude_spacing: Float: the longitude spacings between data points in the geoid grd. This is usually the sixth value in a .grd file's header.
latitude_spacing_decimal_places: Integer: the number of decimal places given by the latitude spacing in the geoid grd, or the latitude_min, whichever is longer.
longitude_spacing_decimal_places: Integer: the number of decimal places given by the longitude spacing in the geoid grd, or the longitude_min, whichever is longer.

create_geoid_record, createGeoidRecord

Returns a geoid grd data point record that can be returned by a fetch_records callback function when called from apply_geoid/applyGeoid, or which can be cached using cache_geoid_records/cacheGeoidRecords.

method( recordindex, geoid_undulation )

recordindex: Integer: the 0-based record index of the data point in the geoid grd (eg. the third data point record within a .grd file would have an index of 2).
geoid_undulation: Float: the geoid undulation of the data point (the difference between the ellipsoid height and the geoid; the value given for that data point within the .grd file).

cache_geoid_records, cacheGeoidRecords

Caches geoid grd data point records, so that further calls to apply_geoid/applyGeoid do not need to use the fetch_records callback function to retrieve those data records. This can be used in advance to speed up operations, avoiding the need to make multiple dynamic requests to a database. Invalid names or records will cause the method to return false and abort caching. Returns true otherwise.

This method is called automatically when returning values from a fetch_records callback function, so returned values will be automatically cached. Repeated calls to this method with the same record indexes will cause it to cache the most recent geoid_undulation value.

method( name, record )

method( name, array( record[, record[, ...]] ) )

name: String: identifier name for the geoid grd specification that the record applies to.
record: Geoid grd data point record.; null: causes nothing to be cached, returns true.

delete_geoid_cache, deleteGeoidCache

Deletes all cached geoid grd data point records for a particular geoid grd specification, or for all geoid grd specifications at once, to reduce memory usage.

method()

method( name )

name: String: identifier name for the geoid grd specification whose records should be deleted from the cache.; null (default): delete all cached records for all geoid grds.

Methods for geodesics - measuring distances between latitude,longitude points

The current implementation uses the relatively minimal Vincenty formulae for the so-called "direct" and "inverse" problems, selected for high speed and low complexity. get_geodesic includes error handling for the few cases where Vincenty's formulae can fail to resolve, and can normally return useful values. An example of usage is to calculate the length of a GPS track. The formulas are based on lengths around the surface of an ellipsoid; height and slopes are ignored. Geodetic azimuth relates to the direction up the longitudinal meridian. This means that at the poles, the azimuth is still relevant, and relates to the longitude supplied. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 10 decimal places. When returning text or HTML string versions of azimuths, values will be given to a precision of 6 decimal places.

get_geodesic_destination (PHP) or getGeodesicDestination (JS): Add a geodetic vector to a latitude,longitude point, and get the resulting coordinates, according to the selected Earth model.
get_geodesic (PHP) or getGeodesic (JS): Calculate the distance and azimuths between two latitude,longitude points, according to the selected Earth model.

get_geodesic_destination, getGeodesicDestination

Returns the latitude,longitude and final azimuth, after following a geodetic vector (distance and direction) from a point, according to the selected Earth model. Also known as the direct problem. Returned azimuth will be in the range of 0 ≤ azimuth < 360.

method( latitude, longitude, distance, azimuth, ellipsoid[, return_type] )

method( array( latitude, longitude ), distance, azimuth, ellipsoid[, return_type] )

method( latitude, longitude, array( distance, azimuth ), ellipsoid[, return_type] )

method( array( latitude, longitude), array( distance, azimuth ), ellipsoid[, return_type] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

distance

Float: the geodetic distance of the geodesic (length around the curve of the ellipsoid) in metres.

azimuth

Float: the azimuth of the geodesic, in degrees (either 0-360° or -180-180° approach can be used).

ellipsoid

Ellipsoid parameter set for the source Earth model. Invalid ellipsoids will cause the method to return false.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude° @ azimuth°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string> @ azimuth<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg; @ azimuth&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude,(float)azimuth)

get_geodesic, getGeodesic

Returns the geodetic distance, initial azimuth and final azimuth of a geodetic vector between two points - the distance and direction of the shortest route between two points. Also known as the inverse problem. Returned azimuth will be in the range of 0 ≤ azimuth < 360. In cases where the start and end points are extremely close to each other (approximately zero), or directly opposite each other on the ellipsoid (antipodal), the formulas cannot return a useful value. In these cases, error handling takes over, and tries to return useful values with varing amounts of approximation. In almost all cases, the returned values are perfectly usable, but it will return details of what approximation it had to use, and how reliable that answer is, when returning data arrays. These details may be used to estimate the reliability of the answer. When returning strings, error handling is signified by the presence of an approximation symbol (~) at the start of the string.

method( latitude_from, longitude_from, latitude_to, longitude_to, ellipsoid[, return_type] )

method( array( latitude_from, longitude_from ), latitude_to, longitude_to, ellipsoid[, return_type] )

method( latitude_from, longitude_from, array( latitude_to, longitude_to ), ellipsoid[, return_type] )

method( array( latitude_from, longitude_from), array( latitude_to, longitude_to ), ellipsoid[, return_type] )

latitude_from

Float: the latitude of the start point in the selected Earth model.

longitude_from

Float: the longitude of the start point in the selected Earth model.

latitude_to

Float: the latitude of the end point in the selected Earth model.

longitude_to

Float: the longitude of the end point in the selected Earth model.

ellipsoid

Ellipsoid parameter set for the source Earth model. Invalid ellipsoids will cause the method to return false.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

[~]distance m, start_azimuth° => end_azimuth°

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

[~]distance m, start_azimuth<string> => end_azimuth<string>

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

[~]distance m, start_azimuth&deg; =&gt; end_azimuth&deg;

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

PHP:

Array((float)distance,(float)start_azimuth,(float)end_azimuth[,array(problem_data)])

JS:

Array((float)distance,(float)start_azimuth,(float)end_azimuth[,{Object problem_data}])

problem_data Only provided if error handling was used. Array or Object containing the following keys/properties:

detectiontype

String:

'BELOW_RESOLUTION': The angles were too small for the trigonometry functions, so the error handling was used early. Distances were therefore estimated as either 0 for points close together, or the distance over the poles for approximately antipodal points.
'DID_NOT_CONVERGE': The iterative formula was allowed to run several hundred times, but still failed to converge. The distance is as calculated using Vincenty formulae, but since it did not converge, the distance may have small errors.

separation

String:

'ANTIPODAL': Points are directly opposite each other on the spheroid.
'NEARLY_ANTIPODAL': Points are very close to being opposite each other on the spheroid.
'NEARLY_IDENTICAL': Points are very close to being the same position.
'IDENTICAL': Points are the same, according to the available number precision.

distanceconfidence

Float: confidence, between 0 and 1 inclusive. In many cases, the distance can be calculated perfectly, so the value will be 1. 0.99 will be points almost exactly opposite each other at the poles. 0.98 will be points almost exactly opposite each other elsewhere which were detected early, or points so close together that numerically the distance is approximately 0. 0.6 will be points almost opposite each other which did not converge (such as on a prolate spheroid); the distances can be wildly wrong and different in different scripting engines, but are normally within the same order of magnitude.

azimuthconfidence

Float: confidence, between 0 and 1 inclusive. In many cases, the azimuth can be calculated perfectly, so the value will be 1. 0.9 will be points almost exactly opposite each other, not at the poles, or on a prolate spheroid. 0.5 or below will be points so close together that the angle between them could not be calculated; an approximate was given instead within ±45°, which becomes increasingly meaningless approaching the poles, where the confidence value is lowest.

Methods for conversion between latitude,longitude and Cartesian X,Y,Z coordinates

Cartesian X,Y,Z coordinates are the native coordinates of the GPS/GNSS systems, and are normally converted into latitude,longitude coordinates (known as spherical coordinates, even when applied to an ellipsoid) to aid human understanding. They offer more useful increments at the poles, and all measurements are in metres (assuming that the dimensions of the ellipsoid/Earth model are in metres). They are, however, relative to the centre of the ellipsoid, and cannot be directly related to distances in one apparent dimension on the surface. When returning text or HTML string versions of latitude/longitude, values will be given to a precision of 10 decimal places. When returning text or HTML string versions of Cartesian coordinates, values will be given to a precision of 6 decimal places.

xyz_to_lat_long (PHP) or xyzToLatLong (JS): Returns the latitude,longitude equivalent to the supplied X,Y,Z coordinates, according to the selected Earth model.
lat_long_to_xyz (PHP) or latLongToXyz (JS): Returns the X,Y,Z coordinates equivalent to the supplied coordinates, according to the selected Earth model.

xyz_to_lat_long, xyzToLatLong

Returns the latitude,longitude equivalent to the supplied X,Y,Z coordinates, according to the selected Earth model.

method( X, Y, Z, ellipsoid[, return_type] )

method( Array( X, Y, Z ), ellipsoid[, return_type] )

X

Float: Cartesian X coordinate (distance towards the prime meridian.

Y

Float: Cartesian Y coordinate (distance towards the 90° meridian).

Z

Float: Cartesian X coordinate (distance towards the North Pole).

ellipsoid

Ellipsoid parameter set for the source Earth model. Invalid ellipsoids will cause the method to return false.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

latitude°, longitude°, height

PHP: String; text to use as the 'degrees' unit (must not be an empty string)

Return the following string:

latitude<string>, longitude<string>, height

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

latitude&deg;, longitude&deg;, height

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)latitude,(float)longitude,(float)height)

lat_long_to_xyz, latLongToXyz

Returns the X,Y,Z coordinates equivalent to the supplied latitude,longitude, according to the selected Earth model. Height is required to calculate the correct position, so if one is not supplied, height is assumed to be 0.

method( latitude, longitude[, height], ellipsoid[, return_type] )

method( Array( latitude, longitude ), height, ellipsoid[, return_type] )

method( Array( latitude, longitude[, height] ), ellipsoid[, return_type] )

latitude

Float: the latitude of the point in the selected Earth model.

longitude

Float: the longitude of the point in the selected Earth model.

height

Float: height of the point in metres, relative to the ellipsoid (default 0).

ellipsoid

Ellipsoid parameter set for the source Earth model. Invalid ellipsoids will cause the method to return false.

return_type

PHP: $grutoolbox->TEXT_EUROPEAN

PHP: $grutoolbox->TEXT_UNICODE

PHP: $grutoolbox->TEXT_ASIAN

PHP: $grutoolbox->TEXT_DEFAULT

JS: grutoolbox.TEXT

Return the following string:

X Y Z

PHP: $grutoolbox->HTML

JS: grutoolbox.HTML

PHP and JS: Boolean true

Return the following string:

X Y Z

PHP: $grutoolbox->DATA_ARRAY

JS: grutoolbox.DATA_ARRAY

PHP and JS: Boolean false (default)

Return the following array:

Array((float)X,(float)Y,(float)Z)

More information

For demos, and examples of how to use the API to perform common tasks, see the details and demos page.

Grid Reference Utilities - API documentation

Navigation

Site search

Site navigation

Details and download

API Documentation

Using the different types of return value

The Grid Reference Utilities toolbox

Methods of the Grid Reference Utilities toolbox

Methods for conversion between different NGR formats

get_UK_grid_ref, getUKGridRef, get_Irish_grid_ref, getIrishGridRef

get_UK_grid_nums, getUKGridNums, get_Irish_grid_nums, getIrishGridNums

add_grid_units, addGridUnits

parse_grid_nums, parseGridNums

Methods for representing ellipsoid earth models

get_ellipsoid, getEllipsoid

create_ellipsoid, createEllipsoid

Methods for conversion between grid coordinates and latitude/longitude

grid_to_lat_long, gridToLatLong

lat_long_to_grid, latLongToGrid

utm_to_lat_long, utmToLatLong

lat_long_to_utm, latLongToUtm

get_datum, getDatum

create_datum, createDatum

Methods for conversion between polar grid coordinates and latitude/longitude

polar_to_lat_long, polarToLatLong

lat_long_to_polar, latLongToPolar

ups_to_lat_long, upsToLatLong

lat_long_to_ups, latLongToUps

Methods for conversion between different latitude/longitude formats

dd_to_dms, ddToDms

dd_format, ddFormat

dms_to_dd, dmsToDd

Shifting grid coordinates between earth models using bilinear interpolation

shift_grid, shiftGrid, reverse_shift_grid, reverseShiftGrid

get_shift_set, getShiftSet

create_shift_set, createShiftSet

create_shift_record, createShiftRecord

cache_shift_records, cacheShiftRecords

delete_shift_cache, deleteShiftCache

Methods for conversion between different latitude/longitude Earth models using Helmert transformation

Helmert_transform, HelmertTransform

get_transformation, getTransformation

create_transformation, createTransformation

Methods for conversion between different latitude/longitude Earth models using polynomial transformation

polynomial_transform, polynomialTransform, reverse_polynomial_transform, reversePolynomialTransform

get_polynomial_coefficients, getPolynomialCoefficients

create_polynomial_coefficients, createPolynomialCoefficients

Methods for conversion between Earth model heights and geoid heights using bilinear interpolation

apply_geoid, applyGeoid

get_geoid_grd, getGeoidGrd

create_geoid_grd, createGeoidGrd

create_geoid_record, createGeoidRecord

cache_geoid_records, cacheGeoidRecords

delete_geoid_cache, deleteGeoidCache

Methods for geodesics - measuring distances between latitude,longitude points

get_geodesic_destination, getGeodesicDestination

get_geodesic, getGeodesic

Methods for conversion between latitude,longitude and Cartesian X,Y,Z coordinates

xyz_to_lat_long, xyzToLatLong

lat_long_to_xyz, latLongToXyz

More information