.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "UTM 3pm"
.TH UTM 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Geo::Coordinates::UTM \- Perl extension for Latitiude Longitude conversions.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Geo::Coordinates::UTM;
.PP
my ($zone,$easting,$northing)=latlon_to_utm($ellipsoid,$latitude,$longitude);
.PP
my ($latitude,$longitude)=utm_to_latlon($ellipsoid,$zone,$easting,$northing);
.PP
my ($zone,$easting,$northing)=mgrs_to_utm($mgrs);
.PP
my ($latitude,$longitude)=mgrs_to_latlon($ellipsoid,$mgrs);
.PP
my ($mgrs)=utm_to_mgrs($zone,$easting,$northing);
.PP
my ($mgrs)=latlon_to_mgrs($ellipsoid,$latitude,$longitude);
.PP
my \f(CW@ellipsoids\fR=ellipsoid_names;
.PP
my($name, \f(CW$r\fR, \f(CW$sqecc\fR) = ellipsoid_info '\s-1WGS\-84\s0';
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module will translate latitude longitude coordinates to Universal Transverse Mercator(\s-1UTM\s0) coordinates and vice versa.
.SS "Mercator Projection"
.IX Subsection "Mercator Projection"
The Mercator projection was first invented to help mariners. They needed to be able to take a course and know the distance traveled, and draw a line on the map which showed the day's journey. In order to do this, Mercator invented a projection which preserved length, by projecting the earth's surface onto a cylinder, sharing the same axis as the earth itself.
This caused all Latitude and Longitude lines to intersect at a 90 degree angle, thereby negating the problem that longitude lines get closer together at the poles.
.SS "Transverse Mercator Projection"
.IX Subsection "Transverse Mercator Projection"
A Transverse Mercator projection takes the cylinder and turns it on its side. Now the cylinder's axis passes through the equator, and it can be rotated to line up with the area of interest. Many countries use Transverse Mercator for their grid systems.
.SS "Universal Transverse Mercator"
.IX Subsection "Universal Transverse Mercator"
The Universal Transverse Mercator(\s-1UTM\s0) system sets up a universal world wide system for mapping. The Transverse Mercator projection is used, with the cylinder in 60 positions. This creates 60 zones around the world.
Positions are measured using Eastings and Northings, measured in meters, instead of Latitude and Longitude. Eastings start at 500,000 on the centre line of each zone.
In the Northern Hemisphere, Northings are zero at the equator and increase northward. In the Southern Hemisphere, Northings start at 10 million at the equator, and decrease southward. You must know which hemisphere and zone you are in to interpret your location globally. 
Distortion of scale, distance, direction and area increase away from the central meridian.
.PP
\&\s-1UTM\s0 projection is used to define horizontal positions world-wide by dividing the surface of the Earth into 6 degree zones, each mapped by the Transverse Mercator projection with a central meridian in the center of the zone. 
\&\s-1UTM\s0 zone numbers designate 6 degree longitudinal strips extending from 80 degrees South latitude to 84 degrees North latitude. \s-1UTM\s0 zone characters designate 8 degree zones extending north and south from the equator. Eastings are measured from the central meridian (with a 500 km false easting to insure positive coordinates). Northings are measured from the equator (with a 10,000 km false northing for positions south of the equator).
.PP
\&\s-1UTM\s0 is applied separately to the Northern and Southern Hemisphere, thus within a single \s-1UTM\s0 zone, a single X / Y pair of values will occur in both the Northern and Southern Hemisphere. 
To eliminate this confusion, and to speed location of points, a \s-1UTM\s0 zone is sometimes subdivided into 20 zones of Latitude. These grids can be further subdivided into 100,000 meter grid squares with double-letter designations. This subdivision by Latitude and further division into grid squares is generally referred to as the Military Grid Reference System (\s-1MGRS\s0).
The unit of measurement of \s-1UTM\s0 is always meters and the zones are numbered from 1 to 60 eastward, beginning at the 180th meridian.
The scale distortion in a north-south direction parallel to the central meridian (\s-1CM\s0) is constant However, the scale distortion increases either direction away from the \s-1CM.\s0 To equalize the distortion of the map across the \s-1UTM\s0 zone, a scale factor of 0.9996 is applied to all distance measurements within the zone. The distortion at the zone boundary, 3 degrees away from the \s-1CM\s0 is approximately 1%.
.SS "Datums and Ellipsoids"
.IX Subsection "Datums and Ellipsoids"
Unlike local surveys, which treat the Earth as a plane, the precise determination of the latitude and longitude of points over a broad area must take into account the actual shape of the Earth. To achieve the precision necessary for accurate location, the Earth cannot be assumed to be a sphere. Rather, the Earth's shape more closely approximates an ellipsoid (oblate spheroid): flattened at the poles and bulging at the Equator. Thus the Earth's shape, when cut through its polar axis, approximates an ellipse.
A \*(L"Datum\*(R" is a standard representation of shape and offset for coordinates, which includes an ellipsoid and an origin. You must consider the Datum when working with geospatial data, since data with two different Datum will not line up. The difference can be as much as a kilometer!
.SH "EXAMPLES"
.IX Header "EXAMPLES"
A description of the available ellipsoids and sample usage of the conversion routines follows
.SS "Ellipsoids"
.IX Subsection "Ellipsoids"
The Ellipsoids available are as follows:
.IP "1 Airy" 6
.IX Item "1 Airy"
.PD 0
.IP "2 Australian National" 6
.IX Item "2 Australian National"
.IP "3 Bessel 1841" 6
.IX Item "3 Bessel 1841"
.IP "4 Bessel 1841 (Nambia)" 6
.IX Item "4 Bessel 1841 (Nambia)"
.IP "5 Clarke 1866" 6
.IX Item "5 Clarke 1866"
.IP "6 Clarke 1880" 6
.IX Item "6 Clarke 1880"
.IP "7 Everest 1830 (India)" 6
.IX Item "7 Everest 1830 (India)"
.IP "8 Fischer 1960 (Mercury)" 6
.IX Item "8 Fischer 1960 (Mercury)"
.IP "9 Fischer 1968" 6
.IX Item "9 Fischer 1968"
.IP "10 \s-1GRS 1967\s0" 6
.IX Item "10 GRS 1967"
.IP "11 \s-1GRS 1980\s0" 6
.IX Item "11 GRS 1980"
.IP "12 Helmert 1906" 6
.IX Item "12 Helmert 1906"
.IP "13 Hough" 6
.IX Item "13 Hough"
.IP "14 International" 6
.IX Item "14 International"
.IP "15 Krassovsky" 6
.IX Item "15 Krassovsky"
.IP "16 Modified Airy" 6
.IX Item "16 Modified Airy"
.IP "17 Modified Everest" 6
.IX Item "17 Modified Everest"
.IP "18 Modified Fischer 1960" 6
.IX Item "18 Modified Fischer 1960"
.IP "19 South American 1969" 6
.IX Item "19 South American 1969"
.IP "20 \s-1WGS 60\s0" 6
.IX Item "20 WGS 60"
.IP "21 \s-1WGS 66\s0" 6
.IX Item "21 WGS 66"
.IP "22 \s-1WGS\-72\s0" 6
.IX Item "22 WGS-72"
.IP "23 \s-1WGS\-84\s0" 6
.IX Item "23 WGS-84"
.IP "24 Everest 1830 (Malaysia)" 6
.IX Item "24 Everest 1830 (Malaysia)"
.IP "25 Everest 1956 (India)" 6
.IX Item "25 Everest 1956 (India)"
.IP "26 Everest 1964 (Malaysia and Singapore)" 6
.IX Item "26 Everest 1964 (Malaysia and Singapore)"
.IP "27 Everest 1969 (Malaysia)" 6
.IX Item "27 Everest 1969 (Malaysia)"
.IP "28 Everest (Pakistan)" 6
.IX Item "28 Everest (Pakistan)"
.IP "29 Indonesian 1974" 6
.IX Item "29 Indonesian 1974"
.IP "30 Arc 1950" 6
.IX Item "30 Arc 1950"
.IP "30 \s-1NAD 27\s0" 6
.IX Item "30 NAD 27"
.IP "30 \s-1NAD 83\s0" 6
.IX Item "30 NAD 83"
.PD
.SS "ellipsoid_names"
.IX Subsection "ellipsoid_names"
The ellipsoids can be accessed using  ellipsoid_names. To store thes into an array you could use
.PP
.Vb 1
\&     my @names = ellipsoid_names;
.Ve
.SS "ellipsoid_info"
.IX Subsection "ellipsoid_info"
Ellipsoids may be called either by name, or number. To return the ellipsoid information, ( \*(L"official\*(R" name, equator radius and square eccentricity) you can use ellipsoid_info and specify a name. The specified name can be numeric (for compatibility reasons) or a more-or-less exact name. Any text between parentheses will be ignored.
.PP
.Vb 5
\&     my($name, $r, $sqecc) = ellipsoid_info \*(Aqwgs84\*(Aq;
\&     my($name, $r, $sqecc) = ellipsoid_info \*(AqWGS 84\*(Aq;
\&     my($name, $r, $sqecc) = ellipsoid_info \*(AqWGS\-84\*(Aq;
\&     my($name, $r, $sqecc) = ellipsoid_info \*(AqWGS\-84 (new specs)\*(Aq;
\&     my($name, $r, $sqecc) = ellipsoid_info 23;
.Ve
.SS "latlon_to_utm"
.IX Subsection "latlon_to_utm"
Latitude values in the southern hemisphere should be supplied as negative values (e.g. 30 deg South will be \-30). Similarly Longitude values West of the meridian should also be supplied as negative values. Both latitude and longitude should not be entered as deg,min,sec but as their decimal equivalent, e.g. 30 deg 12 min 22.432 sec should be entered as 30.2062311
.PP
The ellipsoid value should correspond to one of the numbers above, e.g. to use \s-1WGS\-84,\s0 the ellipsoid value should be 23
.PP
For latitude  57deg 49min 59.000sec North
    longitude 02deg 47min 20.226sec West
.PP
using Clarke 1866 (Ellipsoid 5)
.PP
.Vb 1
\&     ($zone,$east,$north)=latlon_to_utm(\*(Aqclarke 1866\*(Aq,57.803055556,\-2.788951667)
.Ve
.PP
returns
.PP
.Vb 3
\&     $zone  = 30V
\&     $east  = 512543.777159849
\&     $north = 6406592.20049111
.Ve
.SS "latlon_to_utm_force_zone"
.IX Subsection "latlon_to_utm_force_zone"
On occasions, it is necessary to map a pair of (latitude, longitude)
coordinates to a predefined zone. This function allows to select the
projection zone as follows:
.PP
.Vb 2
\&     ($zone, $east, $north)=latlon_to_utm(\*(Aqinternational\*(Aq, $zone_number,
\&                                          $latitude, $longitude)
.Ve
.PP
For instance, Spain territory goes over zones 29, 30 and 31 but
sometimes it is convenient to use the projection corresponding to zone
30 for all the country.
.PP
Santiago de Compostela is at 42deg 52min 57.06sec North, 8deg 32min 28.70sec West
.PP
.Vb 1
\&    ($zone, $east, $norh)=latlon_to_utm(\*(Aqinternational\*(Aq,  42.882517, \-8.541306)
.Ve
.PP
returns
.PP
.Vb 3
\&     $zone = 29T
\&     $east = 537460.331
\&     $north = 4747955.991
.Ve
.PP
but forcing the conversion to zone 30:
.PP
.Vb 2
\&    ($zone, $east, $norh)=latlon_to_utm_force_zone(\*(Aqinternational\*(Aq,
\&                                                   30, 42.882517, \-8.541306)
.Ve
.PP
returns
.PP
.Vb 3
\&    $zone = 30T
\&    $east = 47404.442
\&    $north = 4762771.704
.Ve
.SS "utm_to_latlon"
.IX Subsection "utm_to_latlon"
Reversing the above example,
.PP
.Vb 1
\&     ($latitude,$longitude)=utm_to_latlon(5,\*(Aq30V\*(Aq,512543.777159849,6406592.20049111)
.Ve
.PP
returns
.PP
.Vb 2
\&     $latitude  = 57.8030555601332
\&     $longitude = \-2.7889516669741
\&
\&     which equates to
\&
\&     latitude  57deg 49min 59.000sec North
\&     longitude 02deg 47min 20.226sec West
.Ve
.SS "latlon_to_mgrs"
.IX Subsection "latlon_to_mgrs"
Latitude values in the southern hemisphere should be supplied as negative values (e.g. 30 deg South will be \-30). Similarly Longitude values West of the meridian should also be supplied as negative values. Both latitude and longitude should not be entered as deg,min,sec but as their decimal equivalent, e.g. 30 deg 12 min 22.432 sec should be entered as 30.2062311
.PP
The ellipsoid value should correspond to one of the numbers above, e.g. to use \s-1WGS\-84,\s0 the ellipsoid value should be 23
.PP
For latitude  57deg 49min 59.000sec North
    longitude 02deg 47min 20.226sec West
.PP
using \s-1WGS84\s0 (Ellipsoid 23)
.PP
.Vb 1
\&     ($mgrs)=latlon_to_mgrs(23,57.8030590197684,\-2.788956799)
.Ve
.PP
returns
.PP
.Vb 1
\&     $mgrs  = 30VWK1254306804
.Ve
.SS "mgrs_to_latlon"
.IX Subsection "mgrs_to_latlon"
Reversing the above example,
.PP
.Vb 1
\&     ($latitude,$longitude)=mgrs_to_latlon(23,\*(Aq30VWK1254306804\*(Aq)
.Ve
.PP
returns
.PP
.Vb 2
\&     $latitude  = 57.8030590197684
\&     $longitude = \-2.788956799645
.Ve
.SS "mgrs_to_utm"
.IX Subsection "mgrs_to_utm"
.Vb 1
\&    Similarly it is possible to convert MGRS directly to UTM
\&
\&        ($zone,$easting,$northing)=mgrs_to_utm(\*(Aq30VWK1254306804\*(Aq)
\&
\&    returns
\&
\&        $zone = 30V
\&        $easting = 512543
\&        $northing = 6406804
.Ve
.SS "utm_to_mgrs"
.IX Subsection "utm_to_mgrs"
.Vb 1
\&    and the inverse converting from UTM yo MGRS is done as follows
\&
\&       ($mgrs)=utm_to_mgrs(\*(Aq30V\*(Aq,512543,6406804);
\&
\&    returns
\&        $mgrs = 30VWK1254306804
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Crookham, grahamc@cpan.org
.SH "THANKS"
.IX Header "THANKS"
Thanks go to the following:
.PP
Felipe Mendonca Pimenta for helping out with the Southern hemisphere testing.
.PP
Michael Slater for discovering the Escape \eQ bug.
.PP
Mark Overmeer for the ellipsoid_info routines and code review.
.PP
Lok Yan for the >72deg. N bug.
.PP
Salvador Fandino for the forced zone \s-1UTM\s0 and additional tests
.PP
Matthias Lendholt for modifications to \s-1MGRS\s0 calculations
.PP
Peder Stray for the short \s-1MGRS\s0 patch
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000,2002,2004,2007,2010,2013 by Graham Crookham.  All rights reserved.
.PP
This package is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.