Geo::Line(3pm)

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

NAME

6       Geo::Line - a sequence of connected points
7

INHERITANCE

9        Geo::Line
10          is a Geo::Shape
11
12        Geo::Line
13          is a Math::Polygon
14

SYNOPSIS

16        my $line  = Geo::Line->new(points => [$p1, $p2]);
17        my $line  = Geo::Line->line($p1, $p2);
18
19        my $ring  = Geo::Line->ring($p1, $p2, $p3, $p1);
20        my $ring  = Geo::Line->ring($p1, $p2, $p3);
21
22        my $plane = Geo::Line->filled($p1, $p2, $p3, $p1);
23        my $plane = Geo::Line->filled($p1, $p2, $p3);
24

DESCRIPTION

26       A 2-dimensional sequence of connected points.  The points will be
27       forced to use the same projection.
28
29       Extends "DESCRIPTION" in Math::Polygon.
30
31       Extends "DESCRIPTION" in Geo::Shape.
32

METHODS

34       Extends "METHODS" in Math::Polygon.
35
36       Extends "METHODS" in Geo::Shape.
37
38   Constructors
39       Extends "Constructors" in Math::Polygon.
40
41       Extends "Constructors" in Geo::Shape.
42
43       Geo::Line->bboxFromString( $string, [$projection] )
44           Create a square from the $string.  The coordinates can be separated
45           by a comma (preferably), or blanks.  When the coordinates end on
46           NSEW, the order does not matter, otherwise lat-long or xy order is
47           presumed.
48
49           This routine is very smart.  It understands
50            PROJLABEL: <4 coordinates in any order, but with NSEW>
51            ...
52
53           example: bbox from string
54
55            my $x = '5n 2n 3e e12';       # coordinates in any order
56            my $x = '5e , 2n, 3n, e12';   # coordinates in any order
57            my $x = '2.12-23.1E, N1-4';   # stretches
58            my $x = 'wgs84: 2-5e, 1-8n';  # starts with projection
59            my $x = 'wgs84: e2d12' -3d, n1, n7d12'34"';
60
61            my ($xmin, $ymin, $xmax, $ymax, $proj)
62               = Geo::Line->bboxFromString($x);
63
64            my $p = Geo::Line->ringFromString($x);
65
66            # When parsing user applications, you probably want:
67            my $p = eval { Geo::Line->bboxFromString($x) };
68            warn $@ if $@;
69
70       $obj->filled($points, %options)
71       Geo::Line->filled($points, %options)
72           The $points form a ring() and the filled is part of the geometrical
73           shape.
74
75       $obj->line($points, %options)
76       Geo::Line->line($points, %options)
77           construct a line, which will probably not have the same begin and
78           end point.  The $points are passed as new(points), and the other
79           %options are passed to new() as well.
80
81       $obj->new( [%options] )
82       Geo::Line->new( [%options] )
83           When called as instance method, the projection, ring, and filled
84           attributes are taken from the initiator, like a clone with
85           modification.
86
87            -Option   --Defined in     --Default
88             bbox       Math::Polygon    undef
89             clockwise  Math::Polygon    undef
90             filled                      <false>
91             points                      <data>
92             proj       Geo::Shape       see Geo::Proj::defaultProjection()
93             ring                        <false>
94
95           bbox => [$xmin,$ymin, $xmax,$ymax]
96           clockwise => BOOLEAN
97           filled => BOOLEAN
98             Implies ring.  The filled of the ring is included in the
99             geometrical shape.
100
101           points => ARRAY-OF-POINTS|ARRAY-OF-COORDINATES
102             With this option, you can specify either Geo::Point objects, or
103             coordinate pairs which will get transformed into such objects.
104             WARNING: in that case, the coordinates must be in xy order.
105
106           proj => LABEL
107           ring => BOOLEAN
108             The first point is the last point.  When specified, you have to
109             make sure that this is the case.  If ring() is used to create
110             this object, that routine will check/repair it for you.
111
112           example:
113
114            my $point = Geo::Point->xy(1, 2);
115            my $line  = Geo::Line->new
116              ( points => [$point, [3,4], [5,6], $point]
117              , ring   => 1
118              );
119            my $clone = $line->new(filled => 1);
120
121       $obj->ring($points, %options)
122       Geo::Line->ring($points, %options)
123           The first and last point will be made the same: if not yet, than a
124           reference to the first point is appended to the list.  A "ring"
125           does not cover the internal.
126
127       Geo::Line->ringFromString( $string, [$projection] )
128           Calls bboxFromString() and then produces a ring object from than.
129           Don't forget the "eval" when you call this method.
130
131   Attributes
132       Extends "Attributes" in Math::Polygon.
133
134       Extends "Attributes" in Geo::Shape.
135
136       $obj->geopoint( $index, [$index, ..] )
137           Returns the Geo::Point for the point with the specified $index or
138           indices.
139
140       $obj->geopoints()
141           In LIST context, this returns all points as separate scalars: each
142           is a Geo::Point with projection information.  In SCALAR context, a
143           reference to the coordinates is returned.
144
145           With points(), you get arrays with XY coordinates returned, but
146           without the projection information.  That will be much faster, but
147           not sufficient for some uses.
148
149       $obj->isFilled()
150           Returns a true value is the internals of the ring of points are
151           declared to belong to the shape.
152
153       $obj->isRing()
154           Returns a true value if the sequence of points are a ring or
155           filled: the first point is the last.
156
157       $obj->nrPoints()
158           Inherited, see "Attributes" in Math::Polygon
159
160       $obj->order()
161           Inherited, see "Attributes" in Math::Polygon
162
163       $obj->point( $index, [$index,...] )
164           Inherited, see "Attributes" in Math::Polygon
165
166       $obj->points( [FORMAT] )
167           Inherited, see "Attributes" in Math::Polygon
168
169       $obj->proj()
170           Inherited, see "Attributes" in Geo::Shape
171
172       $obj->proj4()
173           Inherited, see "Attributes" in Geo::Shape
174
175   Projections
176       Extends "Projections" in Geo::Shape.
177
178       $obj->in( <$label|'utm'> )
179           Inherited, see "Projections" in Geo::Shape
180
181       $obj->projectOn($nick, @points)
182           Inherited, see "Projections" in Geo::Shape
183
184   Geometry
185       Extends "Geometry" in Math::Polygon.
186
187       Extends "Geometry" in Geo::Shape.
188
189       $obj->area()
190           Returns the area enclosed by the polygon.  Only useful when the
191           points are in some orthogonal projection.
192
193       $obj->bbox()
194           The bounding box coordinates.  These are more useful for rings than
195           for open line pieces.
196
197       $obj->bboxCenter()
198           Inherited, see "Geometry" in Geo::Shape
199
200       $obj->bboxRing( [$xmin, $ymin, $xmax, $ymax, [$proj]] )
201       Geo::Line->bboxRing( [$xmin, $ymin, $xmax, $ymax, [$proj]] )
202           Inherited, see "Geometry" in Geo::Shape
203
204       $obj->beautify(%options)
205           Inherited, see "Geometry" in Math::Polygon
206
207       $obj->centroid()
208           Inherited, see "Geometry" in Math::Polygon
209
210       $obj->clip( <$xmin,$xmax,$ymin,$ymax>|$object )
211           Clip the shape to the bounding box of $object, or the boxing
212           parameters specified.  A list of Geo::Line objects is returned if
213           anything is inside the object.
214
215           On the moment Math::Polygon::lineClip() and
216           Math::Polygon::fillClip1() are used to do the job.  In the future,
217           that may change.
218
219       $obj->clockwise()
220           Inherited, see "Geometry" in Math::Polygon
221
222       $obj->contains($point)
223           Inherited, see "Geometry" in Math::Polygon
224
225       $obj->counterClockwise()
226           Inherited, see "Geometry" in Math::Polygon
227
228       $obj->distance($point)
229           Inherited, see "Geometry" in Math::Polygon
230
231       $obj->distance( $object, [$unit] )
232           Inherited, see "Geometry" in Geo::Shape
233
234       $obj->equal( <$other | \@points,[$tolerance]> | $points )
235           Inherited, see "Geometry" in Math::Polygon
236
237       $obj->isClockwise()
238           Inherited, see "Geometry" in Math::Polygon
239
240       $obj->isClosed()
241           Inherited, see "Geometry" in Math::Polygon
242
243       $obj->length()
244           The length of the line, only useful in a orthogonal coordinate
245           system (projection).  See also perimeter().
246
247       $obj->perimeter()
248           The length of the line on the ring.  A check is performed that the
249           ring is closed, but further this returns the result of length()
250
251       $obj->same( <$other_polygon | \@points, [$tolerance]> | @points )
252           Inherited, see "Geometry" in Math::Polygon
253
254       $obj->startMinXY()
255           Inherited, see "Geometry" in Math::Polygon
256
257   Transformations
258       Extends "Transformations" in Math::Polygon.
259
260       $obj->grid(%options)
261           Inherited, see "Transformations" in Math::Polygon
262
263       $obj->mirror(%options)
264           Inherited, see "Transformations" in Math::Polygon
265
266       $obj->move(%options)
267           Inherited, see "Transformations" in Math::Polygon
268
269       $obj->resize(%options)
270           Inherited, see "Transformations" in Math::Polygon
271
272       $obj->rotate(%options)
273           Inherited, see "Transformations" in Math::Polygon
274
275       $obj->simplify(%options)
276           Inherited, see "Transformations" in Math::Polygon
277
278   Clipping
279       Extends "Clipping" in Math::Polygon.
280
281       $obj->fillClip1($box)
282           Inherited, see "Clipping" in Math::Polygon
283
284       $obj->lineClip($box)
285           Inherited, see "Clipping" in Math::Polygon
286
287   Display
288       Extends "Display" in Math::Polygon.
289
290       Extends "Display" in Geo::Shape.
291
292       $obj->deg2dm($degrees, $pos, $neg)
293       Geo::Line->deg2dm($degrees, $pos, $neg)
294           Inherited, see "Display" in Geo::Shape
295
296       $obj->deg2dms($degrees, $pos, $neg)
297       Geo::Line->deg2dms($degrees, $pos, $neg)
298           Inherited, see "Display" in Geo::Shape
299
300       $obj->dms2deg($dms)
301       Geo::Line->dms2deg($dms)
302           Inherited, see "Display" in Geo::Shape
303
304       $obj->string( [FORMAT] )
305           Inherited, see "Display" in Math::Polygon
306
307       $obj->toString( [$projection] )
308           Returns a string representation of the line, which is also used for
309           stringification.  The old method named "string" is deprecated.
310

OVERLOAD

312       Extends "OVERLOAD" in Geo::Shape.
313
314       overload: '""' (stringification)
315           Inherited, see "OVERLOAD" in Geo::Shape
316
317       overload: 'bool' (truth value)
318           Inherited, see "OVERLOAD" in Geo::Shape
319

DIAGNOSTICS

321       Error: area requires a ring of points
322           If you think you have a ring of points (a polygon), than do specify
323           that when that object is instantiated (ring() or new(ring)).
324
325       Error: distance calculation not implemented between a $kind and a $kind
326           Only a subset of all objects can be used in the distance
327           calculation.  The limitation is purely caused by lack of time to
328           implement this.
329
330       Error: in() not implemented for a $class
331       Error: perimeter requires a ring of points
332

LICENSE

338       Copyrights 2005-2019 by [Mark Overmeer]. For other contributors see
339       ChangeLog.
340
341       This program is free software; you can redistribute it and/or modify it
342       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
343
344
345
346perl v5.30.0                      2019-07-26                      Geo::Line(3)