The examples of utility use here assume that the utilities have been built and put in a directory in your PATH.
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 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 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 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 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
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.