Provided by: libgeo-point-perl_0.94-1_all bug

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.

METHODS

   Constructors
       Geo::Line->bboxFromString(STRING, {PROJECTION])
           Create a square from the STRING.  The coordinates can be separated by a comma
           (preferrably), 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], [POINTS], [OPTIONS])
       Geo::Line->new([OPTIONS], [POINTS], [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                      <false>
             points                      <data>
             proj       Geo::Shape       see Geo::Proj::defaultProjection()
             ring                        <false>

           bbox => ARRAY
           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
              )'

       $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
       $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()
           See "Attributes" in Math::Polygon

       $obj->order()
           See "Attributes" in Math::Polygon

       $obj->point(INDEX, [INDEX, ...])
           See "Attributes" in Math::Polygon

       $obj->points()
           See "Attributes" in Math::Polygon

       $obj->proj()
           See "Attributes" in Geo::Shape

       $obj->proj4()
           See "Attributes" in Geo::Shape

   Projections
       $obj->in(LABEL|'utm')
           See "Projections" in Geo::Shape

       $obj->projectOn(NICK, POINTS)
           See "Projections" in Geo::Shape

   Geometry
       $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()
           See "Geometry" in Geo::Shape

       $obj->bboxRing([XMIN, YMIN, XMAX, YMAX, [PROJ]])
       Geo::Line->bboxRing([XMIN, YMIN, XMAX, YMAX, [PROJ]])
           See "Geometry" in Geo::Shape

       $obj->beautify(OPTIONS)
           See "Geometry" in Math::Polygon

       $obj->centroid()
           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()
           See "Geometry" in Math::Polygon

       $obj->contains(POINT)
           See "Geometry" in Math::Polygon

       $obj->counterClockwise()
           See "Geometry" in Math::Polygon

       $obj->distance(OBJECT, [UNIT])
           See "Geometry" in Geo::Shape

       $obj->equal((OTHER|ARRAY, [TOLERANCE])|POINTS)
           See "Geometry" in Math::Polygon

       $obj->isClockwise()
           See "Geometry" in Math::Polygon

       $obj->isClosed()
           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|ARRAY, [TOLERANCE])|POINTS)
           See "Geometry" in Math::Polygon

       $obj->startMinXY()
           See "Geometry" in Math::Polygon

   Transformations
       $obj->grid(OPTIONS)
           See "Transformations" in Math::Polygon

       $obj->mirror(OPTIONS)
           See "Transformations" in Math::Polygon

       $obj->move(OPTIONS)
           See "Transformations" in Math::Polygon

       $obj->resize(OPTIONS)
           See "Transformations" in Math::Polygon

       $obj->rotate(OPTIONS)
           See "Transformations" in Math::Polygon

       $obj->simplify(OPTIONS)
           See "Transformations" in Math::Polygon

   Clipping
       $obj->fillClip1(BOX)
           See "Clipping" in Math::Polygon

       $obj->lineClip(BOX)
           See "Clipping" in Math::Polygon

   Display
       $obj->deg2dm(DEGREES, POS, NEG)
       Geo::Line->deg2dm(DEGREES, POS, NEG)
           See "Display" in Geo::Shape

       $obj->deg2dms(DEGREES, POS, NEG)
       Geo::Line->deg2dms(DEGREES, POS, NEG)
           See "Display" in Geo::Shape

       $obj->dms2deg(DMS)
       Geo::Line->dms2deg(DMS)
           See "Display" in Geo::Shape

       $obj->string([PROJECTION])
           Returns a string representation of the line, which is also used for stringification.

           example:

OVERLOAD

       overload: '""' (stringification)()
           See "OVERLOAD" in Geo::Shape

       overload: 'bool' (truth value)()
           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.94, built on December 21, 2012.
       Website: http://perl.overmeer.net/geo/ All modules in this suite: "Geo::Point",
       "Geo::Proj4", "Geo::WKT", "Math::Polygon", "Geo::GML", "Geo::ISO19139", "Geo::EOP",
       "Geo::Format::Envisat", and "Geo::Format::Landsat".

       Please post questions or ideas to the mailinglist at http://geo-perl@list.hut.fi

LICENSE

       Copyrights 2005-2012 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://www.perl.com/perl/misc/Artistic.html