1Geo::Proj4(3) User Contributed Perl Documentation Geo::Proj4(3)
2
6 Geo::Proj4 - PROJ.4 cartographic projections library
7
9 Geo::Proj4
10 is a DynaLoader
11
13 use Geo::Proj4;
14 my $proj = Geo::Proj4->new(proj => "merc",
16 ellps => "clrk66", lon_0 => -96)
17 or die "parameter error: ".Geo::Proj4->error. "\n";
18 my $proj = Geo::Proj4->new("+proj=merc +ellps=clrk66 +lon_0=-96")
20 or die "parameter error: ".Geo::Proj4->error. "\n";
21 my $proj = Geo::Proj4->new(init => "epsg:28992");
23 my ($x, $y) = $proj->forward($lat, $lon);
25 if($proj->hasInverse)
27 { my ($lat, $lon) = $proj->inverse($x, $y);
28 ...
29 }
30 my $proj = Geo::Proj4->new(init => "epsg:26985") or die;
32 my ($lat, $lon) = $proj->inverse(401717.80, 130013.88);
33 my $point = [ 123.12, -5.4 ];
35 my $projected_point = $from->transform($to, $point);
36 my $projected_multi = $from->transform($to, \@points);
37
39 The Open Source PROJ.4 library converts between geographic coordinate
40 systems. It is able to convert between geodetic latitude and longitude
41 (LL, most commonly the WGS84 projection), into an enormous variety of
42 other cartographic projections (XY, usually UTM).
43 WARNING: It is not always clear what the source projection is when
45 forward() or inverse() are used, i.e. in what projection system the
46 source data is expected to be in. Therefore, you can better be
47 specific on both source and destination projection and use transform().
48
50 Instantiation
51 Geo::Proj4->new($string|%options)
52 The object defines the target projection, but that's easier said
53 than done: projections have different parameter needs. The
54 parameters which can (or need to) be used are listed with "cs2cs
55 -lP". The manual page of "cs2cs" explains how the configuration
56 works.
57 Two ways are provided to define the projection. Either, use a list
59 of %options, which are pairs of parameters, or pass one string
60 which contains all parameters at once. You must supply a "proj"
61 parameter.
62 In case of an OPTION list: WARNING: Specify boolean parameters
64 (e.g. the south parameter to the UTM projection) with a matching
65 value of undef.
66 example:
68 my $proj = Geo::Proj4->new(proj => "merc",
70 ellps => "clrk66", lon_0 => -96 )
71 or die Geo::Proj4->error;
72 my $proj = Geo::Proj4->new("+proj=merc +ellps=clrk66 +lon_0=096")
74 or die Geo::Proj4->error;
75 my $proj = Geo::Proj4->new(init => "epsg:$epsg");
77 Accessors
79 $obj->datum()
80 Tries to return a datum name for this projection.
81 $obj->dump()
83 Write the definition in extended form to stdout. This output
84 cannot be caught, because it is done on stdio level, below the
85 reach of PerlIO.
86 Geo::Proj4->error()
88 Returns a dualvar (see Scalar::Util) containing the error number
89 and error string of the last reported error.
90 example:
92 my $proj = Geo::Proj4->new(...);
94 unless(defined $proj)
95 { my $error = Geo::Proj4->error;
96 warn "error-code: ".$error+0;
97 warn "error-string: $error\n";
98 }
99 $obj->hasInverse()
101 Returns whether the reverse function for the projection exists.
102 Some projections are one-way.
103 $obj->isGeocentric()
105 Returns true when the source projection is using a geocentric
106 coordinate system; i.e. uses x-y coordinates.
107 $obj->isGeodesic()
109 Returns true when the source projection is using a geodetic
110 coordinate system; i.e. uses lat long coordinates. Same as
111 isLatlong()
112 $obj->isLatlong()
114 Returns true when the source projection is using a geodetic
115 coordinate system; i.e. uses lat long coordinates. Same as
116 isGeodesic().
117 $obj->normalized()
119 Returns a string which is produced by the library based on the data
120 extracted from the initiation parameters. This string may be more
121 explicit than the passed values, and could be used for debugging.
122 $obj->projection()
124 Returns the projection type.
125 Converters
127 $obj->forward($latitude, $longitude)
128 Perform a forward projection from $latitude and $longitude (LL) to
129 the cartographic projection (XY) represented by the Geo::Proj4
130 instance.
131 WARNING: for historic reasons, latitude and longitude are assumed
133 to be in (floating point) degrees, although the library expects
134 rads. See forwardRad(). A latitude south of the Equator and
135 longitude west of the Prime Meridian given with negative values.
136 Returned are two values, usually X and Y in meters, or whatever
138 units are relevant to the given projection. When the destination
139 projection also than the order of parameters will be returned as
140 LONG,LAT (not lat,long!)
141 On error, "forward" will return undef for both values.
143 example:
145 my ($x, $y) = $proj->forward($lat, $lon);
147 my ($long2, $lat2) = $proj->forward($lat, $lon);
148 $obj->forwardRad($latitude, $longitude)
150 Perform a forward projection from $latitude and $longitude (LL) to
151 the cartographic projection (XY) represented by the Geo::Proj4
152 instance. This function reflects to library function "forward()",
153 expecting radians, not degrees.
154 $obj->inverse(($x,$y) | ($lat,$long))
156 Perform an inverse projection from the (cartographic) projection
157 represented by this Geo::Proj4 object, back into latitude and
158 longitude values.
159 WARNING: for historic reasons, latitude and longitude are assumed
161 to be in (floating point) degrees, although the library expects
162 rads. See inverseRad().
163 On error, "inverse" will return undef for both values.
165 example:
167 if($proj->hasInverse)
169 { my ($lat, $lon) = $proj->inverse($x, $y);
170 ...
171 }
172 $obj->inverseRad(($x,$y) | ($lat|$long))
174 Perform an inverse projection from the (cartographic) projection
175 represented by this Geo::Proj4 object, back into latitude and
176 longitude values. Latitude and longitude are assumed to be in
177 radians. See inverse().
178 $obj->transform($to, $point|ARRAY-of-$points)
180 Translate the $points into the projecten of $to. Each point is
181 specified as two or three values in an ARRAY. In case of latlong
182 source or destination projections, coordinates are translated into
183 radians and/or back. Both input and output values are always in
184 X-Y/LongLat order. See transformRad()
185 example:
187 my $from = Geo::Proj4->new("+proj=latlong +datum=NAD83");
189 my $to = Geo::Proj4->new("+proj=utm +zone=10 +datum=WGS84");
190 my $point = [ 1.12, 3.25 ]; # See Geo::Point
192 my $pr_point = $from->transform($to, $point);
193 my $pr = $from->transform($to, [ $point1, $point2 ]);
195 my $pr_point1 = $pr->[0];
196 my $pr_point2 = $pr->[1];
197 $obj->transformRad($to, $point|ARRAY-of-$points)
199 Translate the $points into the projecten of $to. Each point is
200 specified as two or three values in an ARRAY. In case of latlong
201 source or destination projections, coordinates are expected to be
202 in radians. Both input and output values are always in X-Y/LongLat
203 order. See transform()
204 Library introspection
206 Geo::Proj4->datumInfo($label)
207 Returns a hash with information about the specified datum. With
208 listDatums(), all defined LABELS can be found.
209 Geo::Proj4->ellipsoidInfo($label)
211 Returns a hash with information about the specified ellipsis. With
212 listEllipsoids(), all defined LABELS can be found.
213 $obj->libVersion()
215 Geo::Proj4->libVersion()
216 Returns the version of the proj4 library
217 Geo::Proj4->listDatums()
219 Returns a list with all defined datum labels.
220 example:
222 foreach my $id (Geo::Proj4->listDatums)
224 { my $def = Geo::Proj4->datum($id);
225 print "$id = $def->{ellips_id}\n";
226 }
227 Geo::Proj4->listEllipsoids()
229 Returns a list with all defined ellips labels.
230 example:
232 foreach my $id (Geo::Proj4->listEllipsoids)
234 { my $def = Geo::Proj4->ellipsoid($id);
235 print "$id = $def->{name}\n";
236 }
237 Geo::Proj4->listTypes()
239 Returns a list with all defined projection types.
240 example:
242 foreach my $id (Geo::Proj4->listTypes)
244 { my $def = Geo::Proj4->type($id);
245 print "$id = $def->{description}\n";
246 }
247 Geo::Proj4->listUnits()
249 Returns a list with all defined unit labels.
250 example:
252 foreach my $id (Geo::Proj4->listUnits)
254 { my $def = Geo::Proj4->unit($id);
255 print "$id = $def->{name}\n";
256 }
257 Geo::Proj4->typeInfo($label)
259 Returns a hash with information about the specified projection
260 type. With listTypes(), all defined LABELS can be found.
261 Geo::Proj4->unitInfo($label)
263 Returns a hash with information about the specified unit. With
264 listUnits(), all defined LABELS can be found.
265
267 Install
268 Geo::Proj4 uses XS to wrap the PROJ.4 cartographic projections library.
269 You will need to have the PROJ.4 library installed in order to build
270 and use this module. You can get source code and binaries for the
271 PROJ.4 library from its home page at
272 <http://www.remotesensing.org/proj/>.
273 Projections
275 Covering all the possible projections and their arguments in PROJ.4 is
276 well beyond the scope of this document. However, the cs2cs(1) utility
277 that ships with PROJ.4 will list the projections it knows about by
278 running cs2cs -lp, the ellipsoid models it knows with the -le
279 parameter, the units it knows about with -lu, and the geodetic datums
280 it knows with -ld. Read cs2cs(1) for more details.
281 Alternately, you can read the PROJ.4 documentation, which can be found
283 on the project's homepage. There are links to PDFs, text documentation,
284 a FAQ, and more.
285 Bugs
287 One common source of errors is that latitude and longitude are swapped:
288 some projection systems use lat-long, other use x-y which is a swapped
289 order. Especially the forward() and inverse() cause this problem,
290 always flipping the coordinate order. The transform() method is much
291 easier: input and output in x-y/long-lat order.
292 Also be warned that the values must have the right sign. Make sure you
294 give negative values for south latitude and west longitude. For
295 calculating projections, this is more important than on maps.
296
298 Error: transform() expects array of points
299 Error: transformRad() expects array of points
300
302 See the Geo::Point website at <http://perl.overmeer.net/geo/> for an
303 html version of this and related modules;
304 Effusive thanks to Frank Warmerdam (maintainer of PROJ.4) and Gerald
306 Evenden (main contributor of PROJ.4). Their PROJ.4 library home page:
307 <http://www.remotesensing.org/proj/>
308 proj(1), cs2cs(1), pj_init(3).
310
312 Developed and maintained by Mark Overmeer <markov@cpan.org>. Copyright
313 (c) 2004-2018 by the authors. All rights reserved.
314 Originally Written by Schuyler Erle <schuyler@nocat.net> and Rich
316 Gibson <rich@nocat.net>. Their site: Mapping Hacks home page:
317 <http://www.mappinghacks.com>
318
320 This library is free software; you can redistribute it and/or modify it
321 under the same terms as Perl itself.
322perl v5.30.0 2019-07-26 Geo::Proj4(3)