Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GEOCONVERT(1)		    GeographicLib Utilities		 GEOCONVERT(1)

       GeoConvert -- convert geographic	coordinates

       GeoConvert [ -g | -d | -: | -u |	-m | -c	] [ -z zone | -s | -t |	-S |
       -T ] [ -n ] [ -w	] [ -p prec ] [	-l | -a	] [ --comment-delimiter
       commentdelim ] [	--version | -h | --help	] [ --input-file infile	|
       --input-string instring ] [ --line-separator linesep ] [	--output-file
       outfile ]

       GeoConvert reads	from standard input interpreting each line as a
       geographic coordinate and prints	the coordinate in the format specified
       by the options on standard output.  The input is	interpreted in one of
       three different ways depending on how many space	or comma delimited
       tokens there are	on the line.  The options -g, -d, -u, and -m govern
       the format of output.  In all cases, the	WGS84 model of the earth is
       used (a = 6378137 m, f =	1/298.257223563).

	   2 tokens (output options -g,	-d, or -:) given as latitude longitude
	   using decimal degrees or degrees, minutes, and seconds.  Latitude
	   is given first (unless the -w option	is given).  See	"GEOGRAPHIC
	   COORDINATES"	for a description of the format.  For example, the
	   following are all equivalent

	       33.3 44.4
	       E44.4 N33.3
	       33d18'N 44d24'E
	       44d24 33d18N
	       33:18 +44:24

	   3 tokens (output option -u) given as	zone+hemisphere	easting
	   northing or easting northing	zone+hemisphere, where hemisphere is
	   either n (or	north) or s (or	south).	 The zone is absent for	a UPS
	   specification.  For example,

	       38n 444140.54 3684706.36
	       444140.54 3684706.36 38n
	       s 2173854.98 2985980.58
	       2173854.98 2985980.58 s

	   1 token (output option -m) is used to specify the center of an MGRS
	   grid	square.	 For example,


       -g  output latitude and longitude using decimal degrees.	 Default
	   output mode.

       -d  output latitude and longitude using degrees,	minutes, and seconds

       -:  like	-d, except use : as a separator	instead	of the d, ', and "

       -u  output UTM or UPS.

       -m  output MGRS.

       -c  output meridian convergence and scale for the corresponding UTM or
	   UPS projection.  The	meridian convergence is	the bearing of grid
	   north given as degrees clockwise from true north.

       -z zone
	   set the zone	to zone	for output.  Use either	0 < zone <= 60 for a
	   UTM zone or zone = 0	for UPS.  Alternatively	use a zone+hemisphere
	   designation,	e.g., 38n.  See	"ZONE".

       -s  use the standard UPS	and UTM	zones.

       -t  similar to -s but forces UPS	regions	to the closest UTM zone.

       -S or -T
	   behave the same as -s and -t, respectively, until the first legal
	   conversion is performed.  For subsequent points, the	zone and
	   hemisphere of that conversion are used.  This enables a sequence of
	   points to be	converted into UTM or UPS using	a consistent
	   coordinate system.

       -n  on input, MGRS coordinates refer to the south-west corner of	the
	   MGRS	square instead of the center; see "MGRS".

       -w  toggle the longitude	first flag (it starts off); if the flag	is on,
	   then	on input and output, longitude precedes	latitude (except that,
	   on input, this can be overridden by a hemisphere designator,	N, S,
	   E, W).

       -p prec
	   set the output precision to prec (default 0); prec is the precision
	   relative to 1 m.  See "PRECISION".

       -l  on output, UTM/UPS uses the long forms north	and south to designate
	   the hemisphere instead of n or s.

       -a  on output, UTM/UPS uses the abbreviations n and s to	designate the
	   hemisphere instead of north or south; this is the default

       --comment-delimiter commentdelim
	   set the comment delimiter to	commentdelim (e.g., "#"	or "//").  If
	   set,	the input lines	will be	scanned	for this delimiter and,	if
	   found, the delimiter	and the	rest of	the line will be removed prior
	   to processing and subsequently appended to the output line
	   (separated by a space).

	   print version and exit.

       -h  print usage and exit.

	   print full documentation and	exit.

       --input-file infile
	   read	input from the file infile instead of from standard input; a
	   file	name of	"-" stands for standard	input.

       --input-string instring
	   read	input from the string instring instead of from standard	input.
	   All occurrences of the line separator character (default is a
	   semicolon) in instring are converted	to newlines before the reading

       --line-separator	linesep
	   set the line	separator character to linesep.	 By default this is a

       --output-file outfile
	   write output	to the file outfile instead of to standard output; a
	   file	name of	"-" stands for standard	output.

       prec gives precision of the output with prec = 0	giving 1 m precision,
       prec = 3	giving 1 mm precision, etc.  prec is the number	of digits
       after the decimal point for UTM/UPS.  For MGRS, The number of digits
       per coordinate is 5 + prec; prec	= -6 results in	just the grid zone.
       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 (-6 for MGRS) and the maximum is 9 for
       UTM/UPS,	9 for decimal degrees, 10 for DMS, 6 for MGRS, and 8 for
       convergence and scale.

       The utility accepts geographic coordinates, latitude and	longitude, in
       a number	of common formats.  Latitude precedes longitude, unless	the -w
       option is given which switches this convention.	On input, either
       coordinate may be given first by	appending or prepending	N or S to the
       latitude	and E or W to the longitude.  These hemisphere designators
       carry an	implied	sign, positive for N and E and negative	for S and W.
       This sign multiplies any	+/- sign prefixing the coordinate.  The
       coordinates may be given	as decimal degree or as	degrees, minutes, and
       seconds.	 d, ', and " are used to denote	degrees, minutes, and seconds,
       with the	least significant designator optional.	(See "QUOTING" for how
       to quote	the characters ' and " when entering coordinates on the
       command line.)  Alternatively, :	(colon)	may be used to separate	the
       various components.  Only the final component of	coordinate can include
       a decimal point,	and the	minutes	and seconds components must be less
       than 60.

       It is also possible to carry out	addition or subtraction	operations in
       geographic coordinates.	If the coordinate includes interior signs
       (i.e., not at the beginning or immediately after	an initial hemisphere
       designator), then the coordinate	is split before	such signs; the	pieces
       are parsed separately and the results summed.  For example the point
       15" east	of 39N 70W is

	   39N 70W+0:0:15E

       WARNING:	"Exponential" notation is not recognized for geographic
       coordinates.  Thus 7.0E1	is illegal, while 7.0E+1 is parsed as (7.0E) +
       (+1), yielding the same result as 8.0E.

       Various unicode characters (encoded with	UTF-8) may also	be used	to
       denote degrees, minutes,	and seconds, e.g., the degree, prime, and
       double prime symbols; in	addition two single quotes can be used to
       represent ".

       The other GeographicLib utilities use the same rules for	interpreting
       geographic coordinates; in addition, azimuths and arc lengths are
       interpreted the same way.

       Unfortunately the characters ' and " have special meanings in many
       shells and have to be entered with care.	 However note (1) that the
       trailing	designator is optional and that	(2) you	can use	colons as a
       separator character.  Thus 10d20' can be	entered	as 10d20 or 10:20 and
       10d20'30" can be	entered	as 10:20:30.

       Unix shells (sh,	bash, tsch)
	   The characters ' and	" can be quoted	by preceding them with a \
	   (backslash);	or you can quote a string containing ' with a pair of
	   "s.	The two	alternatives are illustrated by

	      echo 10d20\'30\" "20d30'40" | GeoConvert -d -p -1
	      => 10d20'30"N 020d30'40"E

	   Quoting of command line arguments is	similar

	      GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
	      => 10d20'30"N 020d30'40"E

       Windows command shell (cmd)
	   The ' character needs no quoting; the " character can either	be
	   quoted by a ^ or can	be represented by typing ' twice.  (This
	   quoting is usually unnecessary because the trailing designator can
	   be omitted.)	 Thus

	      echo 10d20'30'' 20d30'40 | GeoConvert -d -p -1
	      => 10d20'30"N 020d30'40"E

	   Use \ to quote the "	character in a command line argument

	      GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
	      => 10d20'30"N 020d30'40"E

       Input from a file
	   No quoting need be done if the input	from a file.  Thus each	line
	   of the file "input.txt" should just contain the plain coordinates.

	     GeoConvert	-d -p -1 < input.txt

       MGRS coordinates	represent a square patch of the	earth, thus
       "38SMB4488" is in zone "38n" with 444km <= easting < 445km and 3688km
       <= northing < 3689km.  Consistent with this representation, coordinates
       are truncated (instead of rounded) to the requested precision.  When an
       MGRS coordinate is provided as input, GeoConvert	treats this as a
       representative point within the square.	By default, this
       representative point is the center of the square	("38n 444500 3688500"
       in the example above).  (This leads to a	stable conversion between MGRS
       and geographic coordinates.)  However, if the -n	option is given	then
       the south-west corner of	the square is returned instead ("38n 444000
       3688000"	in the example above).

       If the input is geographic, GeoConvert uses the standard	rules of
       selecting UTM vs	UPS and	for assigning the UTM zone (with the Norway
       and Svalbard exceptions).  If the input is UTM/UPS or MGRS, then	the
       choice between UTM and UPS and the UTM zone mirrors the input.  The -z
       zone, -s, and -t	options	allow these rules to be	overridden with	zone =
       0 being used to indicate	UPS.  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)


	  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

       Is zone is specified with a hemisphere, then this is honored when
       printing	UTM coordinates:

	  echo -1 3 | GeoConvert -u	    => 31s 500000 9889470
	  echo -1 3 | GeoConvert -u -z 31   => 31s 500000 9889470
	  echo -1 3 | GeoConvert -u -z 31s  => 31s 500000 9889470
	  echo -1 3 | GeoConvert -u -z 31n  => 31n 500000 -110530

       NOTE: the letter	in the zone specification for UTM is a hemisphere
       designator n or s and not an MGRS latitude band letter.	Convert	the
       MGRS latitude band letter to a hemisphere as follows: replace C thru M
       by s (or	south);	replace	N thru X by n (or north).

	  echo 38SMB4488 | GeoConvert	      => 33.33424 44.40363
	  echo 38SMB4488 | GeoConvert -: -p 1 => 33:20:03.25N 044:2413.06E
	  echo 38SMB4488 | GeoConvert -u      => 38n 444500 3688500
	  echo E44d24 N33d20 | GeoConvert -m -p	-3 => 38SMB4488

       GeoConvert can be used to do simple arithmetic using degree, minutes,
       and seconds.  For example, sometimes data is tiled in 15	second squares
       tagged by the DMS representation	of the SW corner.  The tags of the
       tile at 38:59:45N 077:02:00W and	its 8 neighbors	are then given by

	   for y in -$t	+0 +$t;	do
	       for x in	-$t +0 +$t; do
		   echo	38:59:45N$y 077:02:00W$x
	   done	| GeoConvert -:	-p -1 |	tr -d ': '

       An illegal line of input	will print an error message to standard	output
       beginning with "ERROR:" and causes GeoConvert to	return an exit code of
       1.  However, an error does not cause GeoConvert to terminate; following
       lines will be converted.

       UTM Universal Transverse	Mercator,

       UPS Universal Polar Stereographic,

	   Military Grid Reference System,

	   World Geodetic System 1984, <>.

       An online version of this utility is availbable at

       The algorithms for the transverse Mercator projection are described in
       C. F. F.	Karney,	Transverse Mercator with an accuracy of	a few
       nanometers, J. Geodesy 85(8), 475-485 (Aug. 2011); DOI
       <>; preprint

       GeoConvert was written by Charles Karney.

       GeoConvert was added to GeographicLib,
       <>, in 2009-01.

GeographicLib 1.50.1		  2019-12-12			 GEOCONVERT(1)


Want to link to this manual page? Use this URL:

home | help