Geo::Point(3pm)

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

NAME

6       Geo::Point - a point on the globe
7

INHERITANCE

9        Geo::Point
10          is a Geo::Shape
11

SYNOPSIS

13        use Geo::Point;
14
15        my $p = Geo::Point->latlong(1,2);
16        my $p = Geo::Point->longlat(2,1);
17
18        my $w = Geo::Proj->new(wgs84 => ...);
19        my $p = Geo::Point->latlong(1,2, 'wgs84');
20
21        my ($lat, $long) = $p->latlong;
22        my ($x, $y) = $p->xy;
23        my ($x, $y) = $p->in('utm31-wgs84');
24
25        my $p = Geo::Point->xy(1,2);
26

DESCRIPTION

28       One location on the globe, in any coordinate system.  This package
29       tries to hide the maths and the coordinate system in which the point is
30       represented.
31
32       One of the most confusing things when handling geometrical data, is
33       that sometimes latlong, sometimes xy are used: horizontal and vertical
34       organization reversed.  This package tries to hide this from your
35       program by providing abstract accessors latlong(), longlat(), xy(), and
36       yx().
37
38       Extends "DESCRIPTION" in Geo::Shape.
39

METHODS

41       Extends "METHODS" in Geo::Shape.
42
43   Constructors
44       Extends "Constructors" in Geo::Shape.
45
46       Geo::Point->fromString( $string, [$projection] )
47           Create a new point from a $string.  The coordinates can be
48           separated by a comma (preferably), or blanks.  When the coordinates
49           end on NSEW, the order does not matter, otherwise lat-long or xy
50           order is presumed.
51
52           This routine is very smart.  It understands:
53
54             PROJLABEL VALUE VALUE
55             PROJLABEL: VALUE VALUE
56             PROJLABEL, VALUE, VALUE
57             PROJLABEL: VALUE, VALUE
58             VALUE VALUE
59             VALUE, VALUE
60             utm: ZONE, VALUE, VALUE   # also without commas and ':'
61             utm: VALUE, VALUE, ZONE   # also without commas and ':'
62             utm: VALUE, VALUE         # also without commas and ':'
63             ZONE, VALUE, VALUE        # also without commas and ':'
64             VALUE, VALUE, ZONE        # also without commas and ':'
65
66           The VALUE must be suitable for projection.  If only two values are
67           provided, a "d", single or double quote, or trailing/leading "e",
68           "w", "n", "s" (either lower or upper-case) will force a latlong
69           projection.  Those coordinates must follow the rules of dms2deg().
70
71           example: point from string
72
73            my $x = 'utm 31n 12311.123 34242.12'; # utm zone 31N
74            my $x = '12311.123 34242.12 31';      # utm zone 31
75            my $x = '123.123E 12.34';             # wgs84  latlong
76            my $x = 'clrk66 123.123 12.34';       # clrk66 latlong
77            my $x = '12d34'123.1W 11.1123';       # wgs84  longlat
78
79            my $p = Geo::Point->fromString($x);
80
81            # When parsing user applications, you probably want:
82            my $p = eval { Geo::Point->fromString($x) };
83            warn $@ if $@;
84
85       $obj->latlong( [ $lat,$long,[$proj] ] | [$proj] )
86       Geo::Point->latlong( [ $lat,$long,[$proj] ] | [$proj] )
87           When called as class method, you create a new point.  Provide a
88           LATitude and LONGitude. The optional PROJection tells in which
89           coordinate system.
90
91           As instance method, the latitude and longitude are reported.  You
92           can ask it to be translated into the $proj coordinate system first.
93
94           When $proj is undefined, none is presumed. The project must be
95           specified as string, which referse to a projection defined by
96           Geo::Proj.  See also longlat(), xy(), and yx().
97
98           example: latlong as class method
99
100            my $wgs84 = Geo::Proj->new(wgs84 => ...);
101            my $gp    = Geo::Point->latlong(52.3213, 5.53, 'wgs84');
102
103           example: latlong as instance method
104
105            my ($lat, $long) = $gp->latlong('wgs84');
106
107       $obj->longlat( [ $long,$lat,[$proj] ] | [$proj] )
108       Geo::Point->longlat( [ $long,$lat,[$proj] ] | [$proj] )
109           Like latlong(), but with the coordinates reversed.  Some
110           applications prefer this.
111
112       $obj->new(%options)
113       Geo::Point->new(%options)
114            -Option   --Defined in     --Default
115             lat                         undef
116             latitude                    undef
117             long                        undef
118             longitude                   undef
119             proj       Geo::Shape       see Geo::Proj::defaultProjection()
120             x                           undef
121             y                           undef
122
123           lat => COORDINATE
124           latitude => COORDINATE
125           long => COORDINATE
126           longitude => COORDINATE
127           proj => LABEL
128           x => COORDINATE
129           y => COORDINATE
130       $obj->xy( [$x, $y, [$proj] ] | [$proj] )
131       Geo::Point->xy( [$x, $y, [$proj] ] | [$proj] )
132           Like longlat() but now for carthesian projections.  Usually, the
133           coordinate order is reversed.  See also yx().
134
135       $obj->yx( [$y, $x, [$proj] ] | [$proj] )
136       Geo::Point->yx( [$y, $x, [$proj] ] | [$proj] )
137           Like latlong() but now for carthesian projections.  Usually, the
138           coordinate order is reversed.  See also xy().
139
140   Attributes
141       Extends "Attributes" in Geo::Shape.
142
143       $obj->proj()
144           Inherited, see "Attributes" in Geo::Shape
145
146       $obj->proj4()
147           Inherited, see "Attributes" in Geo::Shape
148
149   Accessors
150       The accessors only work correctly when you are sure that the point is
151       in the right coordinate systems.
152
153       $obj->lat()
154       $obj->latitude()
155       $obj->long()
156       $obj->longitude()
157       $obj->x()
158       $obj->y()
159
160   Projections
161       Extends "Projections" in Geo::Shape.
162
163       $obj->in( <$label|'utm'> )
164           Inherited, see "Projections" in Geo::Shape
165
166       $obj->normalize()
167           Be sure the that coordinates are between -180/180 longitude, -90/90
168           lattitude.  No changes for non-latlong projections.
169
170       $obj->projectOn($nick, @points)
171           Inherited, see "Projections" in Geo::Shape
172
173   Geometry
174       Extends "Geometry" in Geo::Shape.
175
176       $obj->area()
177           Always returns zero.
178
179       $obj->bbox()
180           The bounding box of a point contains twice itself.
181
182       $obj->bboxCenter()
183           Inherited, see "Geometry" in Geo::Shape
184
185       $obj->bboxRing( [$xmin, $ymin, $xmax, $ymax, [$proj]] )
186       Geo::Point->bboxRing( [$xmin, $ymin, $xmax, $ymax, [$proj]] )
187           Inherited, see "Geometry" in Geo::Shape
188
189       $obj->distance( $object, [$unit] )
190           Inherited, see "Geometry" in Geo::Shape
191
192       $obj->distancePointPoint($geodist, $units, $point)
193           Compute the distance between the current point and some other
194           $point in $units.  The $geodist object will do the calculations.
195           See distance().
196
197       $obj->inBBox($object)
198           Returns a true value if this point is inside the bounding box of
199           the specified $object.  The borders of the bbox are included.  This
200           is relatively fast to check, even for complex objects.  When the
201           projections differ, the point is translated into the $object's
202           coordinate system, because that one must stay square.
203
204       $obj->perimeter()
205           Always returns zero.
206
207       $obj->sameAs($other, $tolerance)
208
209   Display
210       Extends "Display" in Geo::Shape.
211
212       $obj->coords()
213           Returns the coordinates in their usual order, formatted as string
214           with a joining blank;
215
216       $obj->coordsUsualOrder()
217           Returns the coordinates in the order which is usual for the
218           projection used.
219
220       $obj->deg2dm($degrees, $pos, $neg)
221       Geo::Point->deg2dm($degrees, $pos, $neg)
222           Inherited, see "Display" in Geo::Shape
223
224       $obj->deg2dms($degrees, $pos, $neg)
225       Geo::Point->deg2dms($degrees, $pos, $neg)
226           Inherited, see "Display" in Geo::Shape
227
228       $obj->dm( [$projection] )
229           Like dms(), but doesn't show seconds.
230
231       $obj->dmHTML( [$projection] )
232           Like dmsHTML(), but does not show seconds.
233
234       $obj->dms( [$projection] )
235           Show the point as DMS value-pair.  You must be sure that the
236           coordinate is a projection for which is it useful to represent the
237           values in DMS.  In SCALAR context, one string is returned.  In LIST
238           context, the values are returned separately in latlong order.
239
240           Be warned, that the returned string may contain single and double
241           quote characters, which may confuse HTML (see dmsHTML()).
242
243       $obj->dms2deg($dms)
244       Geo::Point->dms2deg($dms)
245           Inherited, see "Display" in Geo::Shape
246
247       $obj->dmsHTML( [$projection] )
248           Like dms(), but all character which are troublesome for HTML are
249           translated into character codes.
250
251       $obj->moveWest()
252           Move a point from the eastern calculations into the western
253           calculations, resulting in a value below -180.  This is useful when
254           this point is part of a larger construct, like the corners of a
255           satellite image, which are both sides of the -180 meridian.
256
257           example: moving West
258
259            my $point = Geo::Point->latlong(24, 179);
260            $point->moveWest;
261            print $point->long;   # -181;
262
263       $obj->toString( [$projection] )
264           Returns a string representation of the point, which is also used
265           for stringification.  The default projection is the one of the
266           point.
267
268           example:
269
270            print "Point: ",$gp->toString, "\n";
271            print "Point: $gp\n";   # same
272
273            print "Point: ",$gp->toString('clrk66'), "\n";
274

OVERLOAD

276       Extends "OVERLOAD" in Geo::Shape.
277
278       overload: '""' (stringification)
279           Inherited, see "OVERLOAD" in Geo::Shape
280
281       overload: 'bool' (truth value)
282           Inherited, see "OVERLOAD" in Geo::Shape
283

DIAGNOSTICS

285       Error: UTM requires 3 values: easting, northing, and zone
286       Error: can only compare a point to another Geo::Point
287       Error: distance calculation not implemented between a $kind and a $kind
288           Only a subset of all objects can be used in the distance
289           calculation.  The limitation is purely caused by lack of time to
290           implement this.
291
292       Error: dms latitude coordinate not understood: $string
293           See dms2deg() for permitted formats.
294
295       Error: dms longitude coordinate not understood: $string
296           See dms2deg() for permitted formats.
297
298       Error: illegal UTM zone in $string
299           A UTM zone can be detected at the beginning or at the end of the
300           input.  It contains a number (from 1 up to 60) and an optional
301           latitude indication (C up to X, except I and O).
302
303       Error: illegal character in x coordinate $x
304       Error: illegal character in y coordinate $y
305       Error: in() not implemented for a $class
306       Error: too few values in $string (got @parts)
307           Most projection require two parameters, but utm requires three
308           (with zone).
309
310       Error: too many values in $string (got @parts)
311           Most projection require two parameters, but utm requires three
312           (with zone).
313
314       Error: undefined projection $proj for $string
315           The projection you used (or is set as default) is not defined.  See
316           Geo::Proj::new() about how to defined them.
317

LICENSE

323       Copyrights 2005-2019 by [Mark Overmeer]. For other contributors see
324       ChangeLog.
325
326       This program is free software; you can redistribute it and/or modify it
327       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
328
329
330
331perl v5.30.0                      2019-07-26                     Geo::Point(3)