.TH m.u2ll
.nh
.SH NAME 
\fIm.u2ll\fR \- Converts Universal Transverse Mercator (UTM) coordinates
to geographic (latitude/longitude) coordinates.
.br
\fI(GRASS Data Import/Processing Program) \fR
.SH SYNOPSIS
\fBm.u2ll \fR
.br
\fBm.u2ll help \fR
.br
\fBm.u2ll \fR[\fB-srwod\fR] \fBspheroid\*=\fIname \fR[\fBzone\*=\fIvalue\fR] [\fBinput\*=\fIname\fR] [\fBoutput\*=\fIname\fR]
.SH DESCRIPTION
.I m.u2ll
converts Universal Transverse Mercator (UTM) northings and eastings
to geographic coordinates (i.e., latitudes and longitudes).
The user must specify the UTM coordinates to be converted and the spheroid on
which the geographic coordinates will be based.
The program also needs to know the UTM zone in which the input coordinates are located.
However, if the user is running GRASS from a UTM data base LOCATION,
\fIm.u2ll\fR will use this data base's UTM zone designation,
if no zone is specified by the user.

The GRASS program \fIm.ll2u\fR performs the reverse operation,
converting geographic coordinates to UTM coordinates.

The list of spheroids available is somewhat dynamic.
At the time of this release, available spheroids included:
airy, australian, bessel, clark66, everest, grs80, hayford,
international, krasovsky, wgs66, wgs72, and wgs84 (see table below).

This command can be run either non-interactively or interactively.
The user can run the program non-interactively by entering desired flag settings
and parameter values on the command line using the following format:
.LP
.RS
\fBm.u2ll \fR[\fB-srwod\fR] \fBspheroid\*=\fIname \fR[\fBzone\*=\fIvalue\fR] [\fBinput\*=\fIname\fR] [\fBoutput\*=\fIname\fR]
.RE
.LP

Alternately, the user can simply type:
.LP
.RS
\fBm.u2ll\fR
.RE
.LP
on the command line.  In this case, the user will be prompted for
parameter values and flag settings through the standard interface described
in the manual entry for \fIparser\fR.

Input can be entered from the keyboard or from an input file.
In either case, input should be entered with one UTM easting and northing
pair per line, in the format shown below:
.nf
.LP
.RS
easting northing
easting northing
easting northing
easting northing
  .
  .
end
.RE
.LP
.fi
If the user sets the -r flag, \fIm.u2ll\fR will expect the order of the
coordinates to be reversed, and stated as northing, easting pairs,
rather than as easting, northing pairs.  This is useful for passing
ASCII GRASS vector (\fI/dig\fR) files, whose coordinates are stated as
northing, easting pairs, directly through \fIm.u2ll\fR.

Similarly, the user can elect to send output to an output file or (by default)
to standard output (the user's terminal screen).
Example input and output are shown below (see EXAMPLE).

Program flag settings and parameters have the following meanings.
.LP
\fBFlags:\fR
.IP \fB-s\fR 18
Specified UTM zone is in the southern hemisphere.
.IP \fB-r\fR 18
The order of coordinates is reversed in the input, and entered as:  \fInorth east\fR.
This option allows the user to pass an ascii vector file through \fIm.u2ll\fR.
.IP \fB-w\fR 18
Do not flag invalid east, north input lines as errors.
.IP \fB-o\fR 18
Flag other invalid input lines as errors.
.IP \fB-d\fR 18
Output latitude/longitude values in decimal degrees,
rather than in the form \fIdd:mm:ss\fR.
.LP
\fBParameters:\fR
.IP \fBspheroid\*=\fIname\fR 18
Reference spheroid (ellipsoid).
.br
Options:  airy, australian, bessel, clark66, everest, grs80, hayford,
international, krasovsky, wgs66, wgs72, wgs84
.IP \fBzone\*=\fIvalue\fR 18
UTM zone in which UTM coordinates are located.
.br
Options:  1-60
.IP \fBinput\*=\fIname\fR 18
Name of input file containing UTM values to be converted.
.IP \fBoutput\*=\fIname\fR 18
Name to be assigned to output file containing longitude and latitude values.
.LP

AVAILABLE SPHEROIDS
.br
(The on-line listing includes only the spheroid names.)
.sp .25
.TS
tab(;);
l|c|l|l
l|c|l|l
l|c|l|l
l|l|l|l.
Spheroid:;Semi-major axis;Eccentricity sqrd (e),;Commonly used for:
;(Equatorial Radius);Flattening (f),
;(a):;or Polar Radius (b):
_
airy;a\*=6377563.396;e\*=.006670540
australian;a\*=6378160;f\*=1/298.25;Australia
bessel;a\*=6377397.155;e\*=.006674372;Japan
clark66;a\*=6378206.4;b\*=6356583.8;N. America
everest;a\*=6377276.345;e\*=.0066378466;India, Burma
grs80;a\*=6378137;f\*=1/298.257
hayford;a\*=6378388;f\*=1/297
international;a\*=6378388;f\*=1/297;Europe
krasovsky;a\*=6378245;f\*=1/298.3
wgs66;a\*=6378145;f\*=1/298.25;worldwide coverage
wgs72;a\*=6378135;f\*=1/298.26;worldwide coverage
wgs84;a\*=6378137;f\*=1/298.257223563;worldwide coverage
.TE
.SH EXAMPLE
Assume the user has input the command:
.LP
.RS
\fBm.u2ll  -s  spheroid\*=wgs72  zone\*=4  input\*=utm.infile  output\*=ll.outfile \fR
.RE
.LP
where the input file \fIutm.infile\fR contains the following easting and northing 
UTM coordinate values and zone designations:
.nf
.LP
.RS
237740.85 2167292.10
238740.00 2167000.00
239000.00 2167100.00
237100.00 2166000.00
end
.RE
.LP
.fi
Output would then be sent to the output file \fIll.outfile\fR,
containing the below longitude and latitude coordinate values:
.nf
.LP
.RS
166:02:25.645137W 70:27:46.615528S
166:00:53.237056W 70:27:59.692673S
166:00:27.23258W 70:27:57.454281S
166:03:41.428895W 70:28:25.61617S
end
.RE
.LP
.fi
.SH NOTES
Users can add information to the ellipsoid parameter definition file on their
systems (located in $GISBASE/etc/ellipse.table) to add spheroids not now
among those supported by GRASS.

See \fIm.ll2u\fR for a brief discussion of spheroids.

The UTM zone designation determines on what area of the earth
a point is found.  The same UTM coordinates will be found
in each different UTM zone.  Look at the marginalia of your source map
to determine into which UTM zone your UTM coordinates fall.
Although the user can permissibly omit specification of a UTM zone
when running this program under a UTM data base LOCATION,
it is safer to specify it (see DESCRIPTION, above).

\fIm.u2ll\fR converts the first pair of coordinates on each line of input
and leaves anything else on the line alone.
If a line begins:
.LP
.RS
xxxxxx.xx xxxxxxx.xx
.RE
.LP
then the xxxxxx.xx xxxxxxx.xx UTM coordinate pair is converted to a longitude,
latitude pair.  Any other information appearing on the line is left alone.
If the line doesn't begin with a pair of coordinates in the above format,
then the line is left as it is.
.SH FILES
See ellipsoid parameter definition file in $GISBASE/etc/ellipse.table.
.SH "SEE ALSO"
For australian, clark66, grs80, hayford, international, krasovsky, and wgs72
ellipsoid parameters, see:
.br
John P. Snyder, \fIMap Projections - A  Working  Manual\fR,
U.S. Government Printing Office, Washington DC, 1989.
U.S. Geological Survey Professional Paper 1395;  from Table 1, p.12.
.LP
For bessel, airy, everest, and wgs66 ellipsoid parameter values, see:
.br
Thomas O. Seppelin, \fIThe  Department  of Defense World
Geodetic System 1972\fR, presented at the International
Symposium on Problems Related to the Redefinition of
North American Geodetic Networks, Fredericton, New 
Brunswick, Canada in May, 1974;  see Table 9, p.35.
.LP
For wgs84 parameter values, see:
.br
U.S. Naval Oceanographic Labs.
.LP
Also read GRASS User's Reference Manual entries for:
.br
.I d.labels,
.I d.points,
.I d.sites,
.I d.where,
.I m.datum.shift,
.I m.gc2ll,
.I m.ll2gc,
.I m.ll2u,
and
.I parser
.SH AUTHOR
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory