Utility Programs

Back to Geocentric coordinates. Forward to Old Versions. Up to Contents.

The examples of utility use here assume that the utilities have been built and put in a directory in your PATH.

GeoConvert

GeoConvert is a command line utility for geographic coordinate conversions via GeographicLib::GeoCoords. There is an online interface to this utility at http://geographiclib.sourceforge.net/cgi-bin/GeoConvert

Examples:

Here is the usage (obtained from "GeoConvert -h")

Usage: GeoConvert [-g|-d|-u|-m|-c] [-p prec] [-z zone] [-s] [-n] [-h]

Convert geographic coordinates to

    -g latitude and longitude (decimal degrees), default output
    -d latitude and longitude (degrees mins secs)
    -u UTM or UPS
    -m MGRS
    -c meridian convergence and scale

The WGS84 model of the earth is used.  Geographic coordinates are given on
standard input as:

Latitude and longitude (decimal degrees or degrees minutes seconds).  d,
', and " are used to denote degrees, minutes, and seconds, with the least
significant designator optional.  Latitude is given first unless a
hemisphere is specified, e.g., the following are all equivalent

    33.3 44.4
    E44.4 N33.3
    33d18'N 44d24'E
    44d24 33d18N

UTM or UPS given as zone+hemisphere easting northing or easting northing
zone+hemisphere.  The zone is absent for a UPS specification.  E.g.,

    38N 444140.54 3684706.36
    444140.54 3684706.36 38N
    S 2173854.98 2985980.58
    2173854.98 2985980.58 S

MRGS is used to specify the center of a grid square, e.g.,

    38SMB4484
    38SMB44140847064

-p prec (default 0) sets the precision relative to 1m.  This gives the
number of digits after the decimal point for UTM/UPS.  The number of digits
per coordinate for MGRS is 5 + prec.  For decimal degrees, the number of
digits after the decimal point is 5 + prec.  For DMS (degree, minute,
seconds) output, the number of digits after the decimal point in the
seconds components is 1 + prec; if this is negative then use minutes (prec
= -2 or -3) or degrees (prec <= -4) as the least significant component.
Print convergence, resp. scale, with 5 + prec, resp. 7 + prec, digits after
the decimal point.  The minimum value of prec is -5 and the maximum is 9
for UTM/UPS, 9 for decimal degrees, 10 for DMS, 6 for MGRS, and 8 for
convergence and scale.

MGRS coordinates are given by truncating (instead of rounding) the
coordinates to the requested precision.  For example is prec = -3, the
result is the 1km square enclosing the position, for example,

    echo 38N 444800 3684700 | GeoConvert -m -p -3   ==> 38SMB4484

If the -n option is given, then, on input, an MSGS coordinate refers to
the south-west corner of the MGRS square instead of the center.  Thus:

    echo 38SMB4484 | GeoConvert -u         ==> 38N 444500 3684500
    echo 38SMB4484 | GeoConvert -u -n      ==> 38N 444000 3684000

Convergence is the bearing of grid north given as degrees clockwise from
true north.

UTM/UPS and MGRS are given in zone of the input if applicable, otherwise in
the standard zone.

-z zone sets the zone for output.  Use either a positive number for a UTM
zone or zone = 0 to specify UPS.  Alternatively use a zone+hemisphere
designation (and the hemisphere is ignored).

-s uses the standard zone.

For example, the point

    79.9S 6.1E

corresponds to possible MGRS coordinates

    32CMS4324728161 (standard UTM zone = 32)
    31CEM6066227959 (neighboring UTM zone = 31)
      BBZ1945517770 (neighboring UPS zone)

then
    echo 79.9S 6.1E      | GeoConvert -p -3 -m       ==> 32CMS4328
    echo 31CEM6066227959 | GeoConvert -p -3 -m       ==> 31CEM6027
    echo 31CEM6066227959 | GeoConvert -p -3 -m -s    ==> 32CMS4328
    echo 31CEM6066227959 | GeoConvert -p -3 -m -z 0  ==>   BBZ1917

-h prints this help.

Geod

Geod is a command line utility for geodesic calculations via GeographicLib::Geodesic. There is an online interface to this utility at http://geographiclib.sourceforge.net/cgi-bin/Geod

Example (route from JFK Airport to Singapore Changi Airport)

Here is the usage (obtained from "Geod -h")

Usage: Geod [-l lat1 lon1 azi1 | -i] [-a] [-n | -e a r]
            [-d] [-b] [-f] [-p prec] [-h]

Perform geodesic calculations.

The shortest path between two points on the ellipsoid at (lat1, lon1) and
(lat2, lon2) is called the geodesic.  Its length is s12 and the geodesic
from point 1 to point 2 has azimuths azi1 and azi2 at the two end
points.  The reduced length of the geodesic, m12, is defined such that
if the initial azimuth is perturbed by dazi1 (radians) then the second
point is displaced by m12*dazi1 in the direction perpendicular to the
geodesic.  On a flat surface, we have m12 = s12.

Geod operates in one of three modes:

(1) It accepts lines on the standard input containing "lat1 lon1 azi1
    s12" and prints "lat2 lon2 azi2 m12" on standard output.  This is
    the direct geodesic calculation.

(2) Command line arguments "-l lat1 lon1 azi1" specify a geodesic line.
    Geod then accepts a sequence of s12 values (one per line) on
    standard input and prints "lat2 lon2 azi2 m12" for each.  This
    generates a sequence of points on a single geodesic.

(3) With the -i command line argument, Geod performs the inverse
    geodesic calculation.  It reads lines containing "lat1 lon1 lat2
    lon2" and prints the corresponding values of "azi1 azi2 s12 m12".

By default, the WGS84 ellipsoid is used.  Specifying "-e a r" sets the
equatorial radius of the ellipsoid to "a" and the reciprocal flattening
to r.  Setting r = 0 results in a sphere.  Specify r < 0 for a prolate
ellipsoid.  The -n option uses the international ellipsoid (equivalent to
"-e 6378388 297").

Output of angles is as decimal degrees.  If -d is specified the output
is as degrees, minutes, seconds.  Input can be in either style.  d, ',
and " are used to denote degrees, minutes, and seconds, with the least
significant designator optional.  By default, latitude precedes
longitude for each point; however on input either may be given first by
appending N or S to the latitude and E or W to the longitude.  Azimuths
(measured clockwise from north) give the heading of the geodesic.  The
azimuth azi2 is the forward azimuth (the heading beyond point 2).  If
the -b flag is given, azi2 is converted to a back azimuth (the direction
back to point 1) for output.

s12 is given in meters, unless the -a flag is given.  In that case, s12
(on both input and output) are given as the arc length on the auxiliary
sphere a12 (measured in degrees).  In these terms, 180 degrees is the
distance from one equator crossing to the next or from the minimum
latitude to the maximum latitude.  Distances greater than 180 degrees do
not correspond to shortest paths.  m12 is always given in meters.

The output lines consist of the four quantities needed to complete the
specification of the geodesic.  With the -f option, each line of output
is a complete geodesic specification consisting of nine quantities

    lat1 lon1 azi1 lat2 lon2 azi2 s12 a12 m12

where here s12 is the distance and a12 the arc length.

-p prec (default 3) gives the precision of the output relative to 1m.
The minimum value of prec is 0 (1 m accuracy) and the maximum value is
10 (0.1 nm accuracy, but then the last digits are unreliable).

-h prints this help.

TransverseMercatorTest

TransverseMercatorTest is a command line utility for testing GeographicLib::TransverseMercatorExact and GeographicLib::TransverseMercator.

Examples:

Note that, unlike GeoConvert, TransverseMercatorTest has no no ability to change the precision of the output.

Here is the usage (obtained from "TranverseMercatorTest -h")

TransverseMercatorTest [-r] [-t|-s]

Convert between geographic coordinates and transverse Mercator coordinates.

Read lines with latitude and longitude (or easting and northing if -r is
specified) from standard input and print latitude, longitude, easting,
northing, convergence, and scale.  Units are degrees (or DMS) and meters.

By default, the WGS84 is ellipsoid is used, central meridian = 0, UTM
central scale (0.9996), and false easting and false northing are zero.

If -r is given, the reverse projection is performed (the inputs are easting
and northing).

If -s is given, the sixth-order Krueger series approximation to the
transverse Mercator projection is used instead of the exact projection.

If -t is specified, an ellipsoid of eccentricity 0.1 is used, central scale
= 1, 1/4 meridian distance = 1.  In addition, the cut in the exact
transverse Mercator projection at northing = 0 is removed.  The domain of
latitude (lat) and longitude (lon) is the union of
    lat in [0, 90]  and lon in [0, 90]
    lat in (-90, 0] and lon in [81, 90]
The domain of easting (x) and northing (x) is the union of
    x in [0, inf)       and y in [0, 1]
    x in [1.71..., inf) and y in (-inf, 0]

-s and -t are mutually exclusive (the last flag specified is the operative
one).

-h prints this help.

CartConvert

CartConvert is a command line utility for geodetic to cartesian coordinate conversions via GeographicLib::Geocentric and GeographicLib::LocalCartesian.

Examples:

Note that, unlike GeoConvert, CartConvert has no no ability to change the precision of the output.

Here is the usage (obtained from "CartConvert -h")

Usage: CartConvert [-r] [-l lat0 lon0 h0] [-h]

Convert geodetic coordinates to either geocentric or local cartesian
coordinates.  Geocentric coordinates have the origin at the center of the
earth, with the z axis going thru the north pole, and the x axis thru lat =
0, lon = 0.  By default, the conversion is to geocentric coordinates.
Specifying -l lat0 lon0 h0 causes a local coordinate system to be used with
the origin at latitude = lat0, longitude = lon0, height = h0, z normal to
the ellipsoid and y due north.

By default, the WGS84 ellipsoid is used.  Specifying "-e a r" sets the
equatorial radius of the ellipsoid to "a" and the reciprocal flattening
to r.  Setting r = 0 results in a sphere.  Specify r < 0 for a prolate
ellipsoid.

Geodetic coordinates are provided on standard input as a set of lines
containing (blank separated) latitude, longitude (degrees or DMS), and
height (meters).  For each set of geodetic coordinates, the corresponding
cartesian coordinates x, y, z (meters) are printed on standard output.

If -r is given the reverse transformation is performed.

-h prints this help

EquidistantTest

EquidistantTest is a command line utility for performing azimuthal equidistant and Cassini-Soldner projections using GeographicLib::AzimuthalEquidistant and GeographicLib::CassiniSoldner. These projections are both defined in terms of geodesics.

Examples (position of Caen in the Cassini-Soldner projection with origin at the Paris Observatory)

Note that, unlike GeoConvert, EquidistantTest has no no ability to change the precision of the output.

Here is the usage (obtained from "EquidistantTest -h")

Usage: EquidistantTest [-c lat0 lon0] [-z lat0 lon0] [-r] [-h]

Convert geodetic coordinates to either azimuthal equidistant or
Cassini-Soldner coordinates.  The center of the projection (lat0, lon0)
is specified by either the -c option (for Cassini-Soldner) or -z option
(for azimuthal equidistant).  At least one of these options must be
given (the last one given is used).  The WGS84 model of the earth is
used.

Geodetic coordinates are provided on standard input as a set of lines
containing (blank separated) latitude and longitude (degrees or DMS).
For each set of geodetic coordinates, the corresponding projected
coordinates x, y (meters) are printed on standard output together with
the azimuth azi (degrees) and reciprocal scale rk.  For Cassini-Soldner,
azi is the bearing of the easting direction and the scale in the
northing direction is 1/rk.  For azimuthal equidistant, azi is the
bearing of the radial direction and the scale in the azimuthal direction
is 1/rk

If -r is given the reverse transformation is performed.  x and y are
given on standard input and each line of the standard output gives
latitude, longitude, azi, and rk.

-h prints this help

GeoidEval

Evaluate the height of the geoid by interpolating into a grid via GeographicLib::Geoid. There is an online interface to this utility at http://geographiclib.sourceforge.net/cgi-bin/Geoid

Example: the height of the EGM96 geoid at Timbuktu

The first number is the height of the geoid and the 2nd and 3rd are its slopes in the northerly and easterly direction.

In addition, this utility requires the installation of the geoid data files; see Installing the datasets for details

Here is the usage (obtained from "GeoidEval -h")

Usage:
  GeoidEval [-n name] [-d dir] [-l] [-a] [-c south west north east] [-v] [-h]

Read in positions on standard input and print out the corresponding
geoid heights on standard output.  In addition print the northly and
easterly gradients of the geoid height (i.e., the rate at which the
geoid height changes per unit distance along the WGS84 ellipsoid in
the specified directions).

Positions are given as latitude and longitude, UTM/UPS, or MGRS, in
any of the formats accepted by GeoConvert.

By default the EGM96 geoid is used with a 5' grid.  This may be
overriden with the -n option.  The name specified should be one of

                                  bilinear error    cubic error
   name         geoid    grid     max     rms       max     rms
   egm84-30     EGM84    30'      1.546m  70mm      0.274m  14mm
   egm84-15     EGM84    15'      0.413m  18mm      0.020m   1mm
   egm96-15     EGM96    15'      1.152m  40mm      0.169m   7mm
   egm96-5      EGM96     5'      0.140m   5mm      0.003m   1mm
   egm2008-5    EGM2008   5'      0.478m  12mm      0.294m   5mm
   egm2008-2_5  EGM2008   2.5'    0.135m   3mm      0.031m   1mm
   egm2008-1    EGM2008   1'      0.025m   1mm      0.003m   1mm

(Some of the geoids may not be available.)  The errors listed here
are estimates of the quantization and interpolation errors in the
reported heights compared to the specified geoid.

Cubic interpolation is used to compute the geoid height unless
-l is specified in which case bilinear interpolation is used.
Cubic interpolation is more accurate; however it results in
small discontinuities in the returned height on cell boundaries.
The gradients are computed by differentiating the interpolated
results.

GeoidEval will load the geoid data from the directory specified by
the -d option.  If this is not provided, it will look up the value of
GEOID_PATH (currently UNDEFINED) in the environment.
If this is not defined, it will use the compile-time value of
/usr/local/share/GeographicLib/geoids.

By default, the data file is randomly read to compute the geoid
heights at the input positions.  Usually this is sufficient for
interactive use.  If many heights are to be computed, GeoidEval
allows a block of data to be read into memory and heights within the
corresponding rectangle can then be computed without any disk acces.
If -a is specified all the geoid data is read; in the case of
egm2008-1, this requires about 0.5 GB of RAM.  The -c option allows
a rectangle of data to be cached.  The evaluation of heights
outside the cached rectangle causes the necessary data to be read
from disk.

Regardless of whether any cache is requested (with the -a or -c
options), the data for the last grid cell in cached.  This allows
the geoid height along a continuous path to be returned with little
disk overhead.

The -v option causes the data about the current geoid to be printed
to standard error.

-h prints this help.
Back to Geocentric coordinates. Forward to Old Versions. Up to Contents.

Generated on 21 May 2010 for GeographicLib by  doxygen 1.6.1