Geo::Proj(3pm)

1Geo::Proj(3)          User Contributed Perl Documentation         Geo::Proj(3)
2
3
4

NAME

6       Geo::Proj - Handling projections
7

SYNOPSIS

9        use Geo::Proj;
10
11        my $wgs84 = Geo::Proj->new   # predefined if import()
12         ( nick  => 'wgs84'
13         , proj4 => '+proj=latlong +datum=WGS84 +ellps=WGS84'
14         );
15
16        my $clrk = Geo::Proj->new
17         ( nick  => 'clark66'
18         , proj4 => [proj => "merc", ellps => "clrk66", lon_0 => -96]
19         );
20
21        my $point_wgs84= Geo::Point->latlong(56.12, 4.40, 'wgs84');
22        my $point_wgs84= Geo::Point->latlong(56.12, 4.40, $wgs84);
23
24        my $point_clrk = $point_wgs84->in($clrk);
25        my $point_clrk = Geo::Proj->to($wgs84, $clrk, $point_wgs84);
26        my $point_clrk = Geo::Proj->to($wgs84, 'clark66', $point_wgs84);
27

DESCRIPTION

29       A point on Earth's surface can be represented in many different
30       coordinate systems.  The Geo::Proj4 module wraps the popular Open
31       Source "libproj" library to convert between those coordinate systems; a
32       very complex job.
33
34       Within a program, however, you like some extra abstraction from that
35       library: to be able to simply label a point to its system, and then
36       forget about all transformations which may be necessary.  The label (or
37       "nick") hides all complicated parameters for the actual projection .
38
39       WARNING 1: this class will collect all nicks, which means that calling
40       new() with the same label twice will have the second ignored.
41
42       WARNING 2: the wgs84 nickname is predefined, but only if this module is
43       'used' with import.  So if you decide to use 'require' to dynamically
44       load this module, then don't forget to call 'import()' yourself, or
45       define the wgs84 projection yourself.
46

METHODS

48   Constructors
49       Geo::Proj->new( [$nick], %options )
50           Create a new object.
51
52            -Option--Default
53             name    <from proj4>
54             nick    <required>
55             proj4   <required>
56             srid    undef
57
58           name => STRING
59           nick => LABEL
60             The abbrevated name for this projection.
61
62           proj4 => OBJECT|ARRAY|STRING
63             The ARRAY or STRING will by used to create a Geo::Proj4 object by
64             calling Geo::Proj4::new().  You may also specify such an prepared
65             OBJECT.
66
67           srid => INTEGER
68             SRID stands for "Spatial Reference System ID", which is just an
69             index in a table of spatial descriptions as used by SQL. Only
70             INTEGER values larger than 0 are permitted.
71
72   Attributes
73       $obj->name()
74           The full, official name of the projection
75
76       $obj->nick()
77           Simple abbreviating of the projection.
78
79       $obj->proj4( [ <$nick|$proj4> ] )
80       Geo::Proj->proj4( [ <$nick|$proj4> ] )
81           Returns the projection library handle (a Geo::Proj4) to be used by
82           this component.  As class method, the $nick is specified for a
83           lookup.  In case a $proj4 is specified, that is returned.
84
85           example:
86
87            my $wgs84 = Geo::Proj->new(nick => 'wgs84', ...);
88            my $wgs84_proj4 = Geo::Proj->proj4('wgs84');
89            my $wgs84_proj4 = Geo::Proj->proj4($wgs84);
90            my $wgs84_proj4 = $wgs84->proj4;
91
92       $obj->srid()
93           The "Spatial Reference System ID" if known.
94
95   Projecting
96       Geo::Proj->defaultProjection( [ <$nick|$proj> ] )
97           The $nick must be defined with new().  Returned is the Geo::Proj
98           object for the default projection.  The default is the first name
99           created, which probably is 'wgs84' (when import() had a chance)
100
101       Geo::Proj->dumpProjections( [$fh] )
102           Print details about the defined projections to the $fh, which
103           defaults to the selected.  Especially useful for debugging.
104
105       Geo::Proj->listProjections()
106           Returns a sorted lost of projection nicks.
107
108       Geo::Proj->projection( <$nick|$proj> )
109           Returns the Geo::Proj object, defined with $nick.  In case such an
110           object is passed in as $proj, it is returned unaffected.  This
111           method is used where in other methods NICKS or $proj can be used as
112           arguments.
113
114           example:
115
116            my $wgs84 = Geo::Proj->projection('wgs84');
117            my $again = Geo::Proj->projection($wgs84);
118
119       $obj->to( [<$proj|$nick>], <$proj|$nick>, $point|ARRAY-of-$points )
120       Geo::Proj->to( [<$proj|$nick>], <$proj|$nick>, $point|ARRAY-of-$points
121       )
122           Expects an Geo::Proj to project the $point or $points to.  The work
123           is done by Geo::Proj4::transform().  As class method, you have to
124           specify two nicks or projections.
125
126           Be warned that this to() method expects POINTs which are not
127           Geo::Point objects, but which themselves are an ARRAY containing
128           X,Y and optionally a Z coordinate.
129
130           example:
131
132            my $p2 = $wgs84->to('utm31-wgs84', $p1);
133            my $p2 = $wgs84->to($utm, $p1);
134            my $p2 = Geo::Proj->to('wgs84', 'utm31-wgs84', $p1);
135
136   UTM
137       Geo::Proj->UTMprojection( <$datum|$proj|undef>, $zone )
138           The $proj is a Geo::Proj which is used to collect the datum
139           information from if no $datum was specified explicitly.  It may
140           also be a string which is the name of a datum, as known by proj4.
141           Undef will be replaced by the default projection.
142
143           example:
144
145            my $proj = Geo::Proj->UTMprojection('WGS84', 31) or die;
146            print $proj->nick;    # for instance utm31-wgs84
147
148       $obj->bestUTMprojection( $point, [$proj|$nick] )
149       Geo::Proj->bestUTMprojection( $point, [$proj|$nick] )
150           Returns the best UTM projection for some $point.  As class method,
151           you specify the nickname or the object for the point.
152
153           example:
154
155            my $point = Geo::Point->longlat(2.234, 52.12);
156            my $proj  = Geo::Proj->bestUTMprojection($point);
157            print $proj->nick;    # for instance utm31-wgs84
158
159       $obj->zoneForUTM($point)
160       Geo::Proj->zoneForUTM($point)
161           Provided some point, figure-out which zone is most optimal for
162           representing the point.  In LIST context, zone number, zone letter,
163           and meridian are returned as separate scalars.  In LIST context,
164           the zone number and letter are returned as one..
165
166           This code is stolen from Geo::Coordinates::UTM, because that module
167           immediately starts to do computations with this knowledge, which is
168           not wanted here.  Probably a lot of zones are missing.
169

OVERLOADING

171       overload: '""' (stringification)
172           Returns the nick-name for this projection.
173

LICENSE

179       Copyrights 2005-2019 by [Mark Overmeer]. For other contributors see
180       ChangeLog.
181
182       This program is free software; you can redistribute it and/or modify it
183       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
184
185
186
187perl v5.30.0                      2019-07-26                      Geo::Proj(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

OVERLOADING

SEE ALSO

LICENSE