--- name: "Geo::Line" section: "3pm" platform: "linux" package: "libgeo-point-perl" version: "0.98-1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/Geo::Line" --- # Geo::Line(3pm) a sequence of connected points ## NAME Geo::Line - a sequence of connected points ## INHERITANCE ``` Geo::Line is a Geo::Shape Geo::Line is a Math::Polygon ``` ## SYNOPSIS ``` my $line = Geo::Line->new(points => [$p1, $p2]); my $line = Geo::Line->line($p1, $p2); my $ring = Geo::Line->ring($p1, $p2, $p3, $p1); my $ring = Geo::Line->ring($p1, $p2, $p3); my $plane = Geo::Line->filled($p1, $p2, $p3, $p1); my $plane = Geo::Line->filled($p1, $p2, $p3); ``` ## DESCRIPTION A 2-dimensional sequence of connected points. The points will be forced to use the same projection. Extends "DESCRIPTION" in Math::Polygon. Extends "DESCRIPTION" in Geo::Shape. ## METHODS Extends "METHODS" in Math::Polygon. Extends "METHODS" in Geo::Shape. ### Constructors Extends "Constructors" in Math::Polygon. Extends "Constructors" in Geo::Shape. - Geo::Line-\>**bboxFromString**( $string, \[$projection\] ) Create a square from the `$string`. The coordinates can be separated by a comma (preferably), or blanks. When the coordinates end on NSEW, the order does not matter, otherwise lat-long or xy order is presumed. This routine is very smart. It understands \ PROJLABEL: \<4 coordinates in any order, but with NSEW\>\ ... example: bbox from string ``` my $x = '5n 2n 3e e12'; # coordinates in any order my $x = '5e , 2n, 3n, e12'; # coordinates in any order my $x = '2.12-23.1E, N1-4'; # stretches my $x = 'wgs84: 2-5e, 1-8n'; # starts with projection my $x = 'wgs84: e2d12' -3d, n1, n7d12'34"'; my ($xmin, $ymin, $xmax, $ymax, $proj) = Geo::Line->bboxFromString($x); my $p = Geo::Line->ringFromString($x); # When parsing user applications, you probably want: my $p = eval { Geo::Line->bboxFromString($x) }; warn $@ if $@; ``` - $obj-\>**filled**($points, %options) - Geo::Line-\>**filled**($points, %options) The `$points` form a **ring()** and the filled is part of the geometrical shape. - $obj-\>**line**($points, %options) - Geo::Line-\>**line**($points, %options) construct a line, which will probably not have the same begin and end point. The `$points` are passed as new(points), and the other `%options` are passed to **new()** as well. - $obj-\>**new**( \[%options\] ) - Geo::Line-\>**new**( \[%options\] ) When called as instance method, the projection, ring, and filled attributes are taken from the initiator, like a clone with modification. ``` -Option --Defined in --Default bbox Math::Polygon undef clockwise Math::Polygon undef filled points proj Geo::Shape see Geo::Proj::defaultProjection() ring ``` - bbox =\> \[$xmin,$ymin, $xmax,$ymax\] - clockwise =\> BOOLEAN - filled =\> BOOLEAN Implies ring. The filled of the ring is included in the geometrical shape. - points =\> ARRAY-OF-POINTS\|ARRAY-OF-COORDINATES With this option, you can specify either Geo::Point objects, or coordinate pairs which will get transformed into such objects. WARNING: in that case, the coordinates must be in xy order. - proj =\> LABEL - ring =\> BOOLEAN The first point is the last point. When specified, you have to make sure that this is the case. If **ring()** is used to create this object, that routine will check/repair it for you. example: ``` my $point = Geo::Point->xy(1, 2); my $line = Geo::Line->new ( points => [$point, [3,4], [5,6], $point] , ring => 1 ); my $clone = $line->new(filled => 1); ``` - $obj-\>**ring**($points, %options) - Geo::Line-\>**ring**($points, %options) The first and last point will be made the same: if not yet, than a reference to the first point is appended to the list. A "ring" does not cover the internal. - Geo::Line-\>**ringFromString**( $string, \[$projection\] ) Calls **bboxFromString()** and then produces a ring object from than. Don't forget the `"eval"` when you call this method. ### Attributes Extends "Attributes" in Math::Polygon. Extends "Attributes" in Geo::Shape. - $obj-\>**geopoint**( $index, \[$index, ..\] ) Returns the Geo::Point for the point with the specified `$index` or indices. - $obj-\>**geopoints**() In LIST context, this returns all points as separate scalars: each is a Geo::Point with projection information. In SCALAR context, a reference to the coordinates is returned. With **points()**, you get arrays with XY coordinates returned, but without the projection information. That will be much faster, but not sufficient for some uses. - $obj-\>**isFilled**() Returns a true value is the internals of the ring of points are declared to belong to the shape. - $obj-\>**isRing**() Returns a true value if the sequence of points are a ring or filled: the first point is the last. - $obj-\>**nrPoints**() Inherited, see "Attributes" in Math::Polygon - $obj-\>**order**() Inherited, see "Attributes" in Math::Polygon - $obj-\>**point**( $index, \[$index,...\] ) Inherited, see "Attributes" in Math::Polygon - $obj-\>**points**( \[FORMAT\] ) Inherited, see "Attributes" in Math::Polygon - $obj-\>**proj**() Inherited, see "Attributes" in Geo::Shape - $obj-\>**proj4**() Inherited, see "Attributes" in Geo::Shape ### Projections Extends "Projections" in Geo::Shape. - $obj-\>**in**( \<$label\|'utm'\> ) Inherited, see "Projections" in Geo::Shape - $obj-\>**projectOn**($nick, @points) Inherited, see "Projections" in Geo::Shape ### Geometry Extends "Geometry" in Math::Polygon. Extends "Geometry" in Geo::Shape. - $obj-\>**area**() Returns the area enclosed by the polygon. Only useful when the points are in some orthogonal projection. - $obj-\>**bbox**() The bounding box coordinates. These are more useful for rings than for open line pieces. - $obj-\>**bboxCenter**() Inherited, see "Geometry" in Geo::Shape - $obj-\>**bboxRing**( \[$xmin, $ymin, $xmax, $ymax, \[$proj\]\] ) - Geo::Line-\>**bboxRing**( \[$xmin, $ymin, $xmax, $ymax, \[$proj\]\] ) Inherited, see "Geometry" in Geo::Shape - $obj-\>**beautify**(%options) Inherited, see "Geometry" in Math::Polygon - $obj-\>**centroid**() Inherited, see "Geometry" in Math::Polygon - $obj-\>**clip**( \<$xmin,$xmax,$ymin,$ymax\>\|$object ) Clip the shape to the bounding box of `$object`, or the boxing parameters specified. A list of Geo::Line objects is returned if anything is inside the object. On the moment **Math::Polygon::lineClip()** and **Math::Polygon::fillClip1()** are used to do the job. In the future, that may change. - $obj-\>**clockwise**() Inherited, see "Geometry" in Math::Polygon - $obj-\>**contains**($point) Inherited, see "Geometry" in Math::Polygon - $obj-\>**counterClockwise**() Inherited, see "Geometry" in Math::Polygon - $obj-\>**distance**($point) Inherited, see "Geometry" in Math::Polygon - $obj-\>**distance**( $object, \[$unit\] ) Inherited, see "Geometry" in Geo::Shape - $obj-\>**equal**( \<$other \| \\@points,\[$tolerance\]\> \| $points ) Inherited, see "Geometry" in Math::Polygon - $obj-\>**isClockwise**() Inherited, see "Geometry" in Math::Polygon - $obj-\>**isClosed**() Inherited, see "Geometry" in Math::Polygon - $obj-\>**length**() The length of the line, only useful in a orthogonal coordinate system (projection). See also **perimeter()**. - $obj-\>**perimeter**() The length of the line on the ring. A check is performed that the ring is closed, but further this returns the result of **length()** - $obj-\>**same**( \<$other\_polygon \| \\@points, \[$tolerance\]\> \| @points ) Inherited, see "Geometry" in Math::Polygon - $obj-\>**startMinXY**() Inherited, see "Geometry" in Math::Polygon ### Transformations Extends "Transformations" in Math::Polygon. - $obj-\>**grid**(%options) Inherited, see "Transformations" in Math::Polygon - $obj-\>**mirror**(%options) Inherited, see "Transformations" in Math::Polygon - $obj-\>**move**(%options) Inherited, see "Transformations" in Math::Polygon - $obj-\>**resize**(%options) Inherited, see "Transformations" in Math::Polygon - $obj-\>**rotate**(%options) Inherited, see "Transformations" in Math::Polygon - $obj-\>**simplify**(%options) Inherited, see "Transformations" in Math::Polygon ### Clipping Extends "Clipping" in Math::Polygon. - $obj-\>**fillClip1**($box) Inherited, see "Clipping" in Math::Polygon - $obj-\>**lineClip**($box) Inherited, see "Clipping" in Math::Polygon ### Display Extends "Display" in Math::Polygon. Extends "Display" in Geo::Shape. - $obj-\>**deg2dm**($degrees, $pos, $neg) - Geo::Line-\>**deg2dm**($degrees, $pos, $neg) Inherited, see "Display" in Geo::Shape - $obj-\>**deg2dms**($degrees, $pos, $neg) - Geo::Line-\>**deg2dms**($degrees, $pos, $neg) Inherited, see "Display" in Geo::Shape - $obj-\>**dms2deg**($dms) - Geo::Line-\>**dms2deg**($dms) Inherited, see "Display" in Geo::Shape - $obj-\>**string**( \[FORMAT\] ) Inherited, see "Display" in Math::Polygon - $obj-\>**toString**( \[$projection\] ) Returns a string representation of the line, which is also used for stringification. The old method named `"string"` is deprecated. ## OVERLOAD Extends "OVERLOAD" in Geo::Shape. - overload: **'""' (stringification)** Inherited, see "OVERLOAD" in Geo::Shape - overload: **'bool' (truth value)** Inherited, see "OVERLOAD" in Geo::Shape ## DIAGNOSTICS - Error: area requires a ring of points If you think you have a ring of points (a polygon), than do specify that when that object is instantiated (**ring()** or new(ring)). - Error: distance calculation not implemented between a $kind and a $kind Only a subset of all objects can be used in the distance calculation. The limitation is purely caused by lack of time to implement this. - Error: **in()** not implemented for a $class - Error: perimeter requires a ring of points ## SEE ALSO This module is part of Geo-Point distribution version 0.98, built on February 01, 2019. Website: *http://perl.overmeer.net/CPAN/* ## LICENSE Copyrights 2005-2019 by \[Mark Overmeer\]. For other contributors see ChangeLog. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See *http://dev.perl.org/licenses/*