File: README

package info (click to toggle)
libgeo-coordinates-utm-perl 0.11-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 204 kB
  • ctags: 14
  • sloc: perl: 1,410; makefile: 2
file content (300 lines) | stat: -rw-r--r-- 10,862 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
NAME
    Geo::Coordinates::UTM - Perl extension for Latitiude Longitude
    conversions.

SYNOPSIS
    use Geo::Coordinates::UTM;

my ($zone,$easting,$northing)=latlon_to_utm($ellipsoid,$latitude,$longitude);

my ($latitude,$longitude)=utm_to_latlon($ellipsoid,$zone,$easting,$northing);

my ($zone,$easting,$northing)=mgrs_to_utm($mgrs);

my ($latitude,$longitude)=mgrs_to_latlon($ellipsoid,$mgrs);

my ($mgrs)=utm_to_mgrs($zone,$easting,$northing);

my ($mgrs)=latlon_to_mgrs($ellipsoid,$latitude,$longitude);

my @ellipsoids=ellipsoid_names;

my($name, $r, $sqecc) = ellipsoid_info 'WGS-84';

DESCRIPTION
    This module will translate latitude longitude coordinates to Universal
    Transverse Mercator(UTM) coordinates and vice versa.

  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.

  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.

  Universal Transverse Mercator

    The Universal Transverse Mercator(UTM) 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.

    UTM 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. UTM zone numbers designate 6 degree longitudinal strips
    extending from 80 degrees South latitude to 84 degrees North latitude.
    UTM 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).

    UTM is applied separately to the Northern and Southern Hemisphere, thus
    within a single UTM 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 UTM 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 (MGRS). The unit of measurement of
    UTM 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 (CM) is constant However, the
    scale distortion increases either direction away from the CM. To
    equalize the distortion of the map across the UTM 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 CM is
    approximately 1%.

  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 "Datum" 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!

EXAMPLES
    A description of the available ellipsoids and sample usage of the
    conversion routines follows

  Ellipsoids

    The Ellipsoids available are as follows:

    1 Airy
    2 Australian National
    3 Bessel 1841
    4 Bessel 1841 Nambia
    5 Clarke 1866
    6 Clarke 1880
    7 Everest
    8 Fischer 1960 Mercury
    9 Fischer 1968
    10 GRS 1967
    11 GRS 1980
    12 Helmert 1906
    13 Hough
    14 International
    15 Krassovsky
    16 Modified Airy
    17 Modified Everest
    18 Modified Fischer 1960
    19 South American 1969
    20 WGS 60
    21 WGS 66
    22 WGS-72
    23 WGS-84
    24 Everest 1830 Malaysia
    25 Everest 1956 India
    26 Everest 1964 Malaysia and Singapore
    27 Everest 1969 Malaysia
    28 Everest Pakistan
    29 Indonesian 1974
	30 Arc 1950
	31 NAD 27
	32 NAD 83

  ellipsoid_names

    The ellipsoids can be accessed using ellipsoid_names. To store thes into
    an array you could use

         my @names = ellipsoid_names;

  ellipsoid_info

    Ellipsoids may be called either by name, or number. To return the
    ellipsoid information, ( "official" 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.

         my($name, $r, $sqecc) = ellipsoid_info 'wgs84';
         my($name, $r, $sqecc) = ellipsoid_info 'WGS 84';
         my($name, $r, $sqecc) = ellipsoid_info 'WGS-84';
         my($name, $r, $sqecc) = ellipsoid_info 'WGS-84 (new specs)';
         my($name, $r, $sqecc) = ellipsoid_info 23;

  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

    The ellipsoid value should correspond to one of the numbers above, e.g.
    to use WGS-84, the ellipsoid value should be 23

    For latitude 57deg 49min 59.000sec North longitude 02deg 47min 20.226sec
    West

    using Clarke 1866 (Ellipsoid 5)

         ($zone,$east,$north)=latlon_to_utm('clarke 1866',57.803055556,-2.788951667)

    returns

         $zone  = 30V
         $east  = 512533.364651484
         $north = 6409932.13416127

  utm_to_latlon

    Reversing the above example,

         ($latitude,$longitude)=utm_to_latlon(5,30V,512533.364651484,6409932.13416127)

    returns

         $latitude  = 57.8330555601433
         $longitude = -2.788951666974

         which equates to

         latitude  57deg 49min 59.000sec North
         longitude 02deg 47min 20.226sec West

  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:

         ($zone, $east, $north)=latlon_to_utm('international', $zone_number,
                                          $latitude, $longitude)

    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.

    Santiago de Compostela is at 42deg 52min 57.06sec North, 8deg 32min 28.70sec West

        ($zone, $east, $norh)=latlon_to_utm('international',  42.882517, -8.541306)

    returns

        $zone = 29T
        $east = 537460.331
        $north = 4747955.991

    but forcing the conversion to zone 30:

        ($zone, $east, $norh)=latlon_to_utm_force_zone('international',
                                                   30, 42.882517, -8.541306)

    returns

        $zone = 30T
        $east = 47404.442
        $north = 4762771.704

    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

    The ellipsoid value should correspond to one of the numbers above, e.g. to use WGS-84, the ellipsoid value should be 23

    For latitude  57deg 49min 59.000sec North
        longitude 02deg 47min 20.226sec West

    using WGS84 (Ellipsoid 23)

         ($mgrs)=latlon_to_mgrs(23,57.8030590197684,-2.788956799)

    returns 

         $mgrs  = 30VWK1254306804

    mgrs_to_latlon

    Reversing the above example,

         ($latitude,$longitude)=mgrs_to_latlon(23,'30VWK1254306804')

    returns

         $latitude  = 57.8030590197684
         $longitude = -2.788956799645

    mgrs_to_utm

    Similarly it is possible to convert MGRS directly to UTM


AUTHOR
    Graham Crookham, grahamc@cpan.org

THANKS
    Thanks go to the following:

    Felipe Mendonca Pimenta for helping out with the Southern hemisphere
    testing.

    Michael Slater for discovering the Escape \Q bug.

    Mark Overmeer for the ellipsoid_info routines and code review.

    Lok Yan for the >72deg. N bug.

    Salvador Fandino for the forced zone UTM and additional tests

    Matthias Lendholt for modifications to MGRS calculations

    Peder Stray for the short MGRS patch

COPYRIGHT
    Copyright (c) 2000,2002,2004,2007,2010,2013 by Graham Crookham. All rights reserved.

    This package is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.