The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MARKOV / Geo-Point-0.94 / lib / Geo / Line.pod 
=head1 NAME

Geo::Line - a sequence of connected points

=head1 INHERITANCE

 Geo::Line
   is a Geo::Shape

 Geo::Line
   is a Math::Polygon

=head1 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);

=head1 DESCRIPTION

A 2-dimensional sequence of connected points.  The points will be forced
to use the same projection.

=head1 METHODS

=head2 Constructors

=over 4

=item Geo::Line-E<gt>B<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 $@;

=item $obj-E<gt>B<filled>(POINTS, OPTIONS)

=item Geo::Line-E<gt>B<filled>(POINTS, OPTIONS)

The POINTS form a L<ring()|Geo::Line/"Constructors"> and the filled is part of the geometrical
shape.

=item $obj-E<gt>B<line>(POINTS, OPTIONS)

=item Geo::Line-E<gt>B<line>(POINTS, OPTIONS)

construct a line, which will probably not have the same begin and end
point.  The POINTS are passed as L<new(points)|Geo::Line/"Constructors">, and the other OPTIONS
are passed to L<new()|Geo::Line/"Constructors"> as well.

=item $obj-E<gt>B<new>([OPTIONS], [POINTS], [OPTIONS])

=item Geo::Line-E<gt>B<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>

=over 2

=item bbox => ARRAY

=item clockwise => BOOLEAN

=item filled => BOOLEAN

Implies ring.  The filled of the ring is included in the geometrical
shape.

=item points => ARRAY-OF-POINTS|ARRAY-OF-COORDINATES

With this option, you can specify either L<Geo::Point|Geo::Point> objects, or
coordinate pairs which will get transformed into such objects.  WARNING:
in that case, the coordinates must be in xy order.

=item proj => LABEL

=item ring => BOOLEAN

The first point is the last point.  When specified, you have to make
sure that this is the case.  If L<ring()|Geo::Line/"Constructors"> is used to create this object,
that routine will check/repair it for you.

=back

example: 

 my $point = Geo::Point->xy(1, 2);
 my $line  = Geo::Line->new
   ( points => [$point, [3,4], [5,6], $point]
   , ring   => 1
   )'

=item $obj-E<gt>B<ring>(POINTS, OPTIONS)

=item Geo::Line-E<gt>B<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.

=item Geo::Line-E<gt>B<ringFromString>(STRING, [PROJECTION])

Calls L<bboxFromString()|Geo::Line/"Constructors"> and then produces a ring object from than.
Don't forget the C<eval> when you call this method.

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<geopoint>(INDEX, [INDEX, ..])

Returns the L<Geo::Point|Geo::Point> for the point with the specified INDEX or
indices.

=item $obj-E<gt>B<geopoints>()

In LIST context, this returns all points as separate scalars: each is a
L<Geo::Point|Geo::Point> with projection information.  In SCALAR context, a
reference to the coordinates is returned.

With L<points()|Math::Polygon/"Attributes">, you get arrays with XY coordinates returned, but
without the projection information.  That will be much faster, but
not sufficient for some uses.

=item $obj-E<gt>B<isFilled>()

Returns a true value is the internals of the ring of points are declared
to belong to the shape.

=item $obj-E<gt>B<isRing>()

Returns a true value if the sequence of points are a ring or filled: the
first point is the last.

=item $obj-E<gt>B<nrPoints>()

See L<Math::Polygon/"Attributes">

=item $obj-E<gt>B<order>()

See L<Math::Polygon/"Attributes">

=item $obj-E<gt>B<point>(INDEX, [INDEX, ...])

See L<Math::Polygon/"Attributes">

=item $obj-E<gt>B<points>()

See L<Math::Polygon/"Attributes">

=item $obj-E<gt>B<proj>()

See L<Geo::Shape/"Attributes">

=item $obj-E<gt>B<proj4>()

See L<Geo::Shape/"Attributes">

=back

=head2 Projections

=over 4

=item $obj-E<gt>B<in>(LABEL|'utm')

See L<Geo::Shape/"Projections">

=item $obj-E<gt>B<projectOn>(NICK, POINTS)

See L<Geo::Shape/"Projections">

=back

=head2 Geometry

=over 4

=item $obj-E<gt>B<area>()

Returns the area enclosed by the polygon.  Only useful when the points
are in some orthogonal projection.

=item $obj-E<gt>B<bbox>()

The bounding box coordinates.  These are more useful for rings than for
open line pieces.

=item $obj-E<gt>B<bboxCenter>()

See L<Geo::Shape/"Geometry">

=item $obj-E<gt>B<bboxRing>([XMIN, YMIN, XMAX, YMAX, [PROJ]])

=item Geo::Line-E<gt>B<bboxRing>([XMIN, YMIN, XMAX, YMAX, [PROJ]])

See L<Geo::Shape/"Geometry">

=item $obj-E<gt>B<beautify>(OPTIONS)

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<centroid>()

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<clip>((XMIN,XMAX,YMIN,YMAX)|OBJECT)

Clip the shape to the bounding box of OBJECT, or the boxing parameters
specified.  A list of L<Geo::Line|Geo::Line> objects is returned if anything is
inside the object.

On the moment L<Math::Polygon::lineClip()|Math::Polygon/"Clipping"> and
L<Math::Polygon::fillClip1()|Math::Polygon/"Clipping"> are used to do the job.  In the future,
that may change.

=item $obj-E<gt>B<clockwise>()

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<contains>(POINT)

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<counterClockwise>()

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<distance>(OBJECT, [UNIT])

See L<Geo::Shape/"Geometry">

=item $obj-E<gt>B<equal>((OTHER|ARRAY, [TOLERANCE])|POINTS)

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<isClockwise>()

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<isClosed>()

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<length>()

The length of the line, only useful in a orthogonal coordinate system
(projection).  See also L<perimeter()|Geo::Line/"Geometry">.

=item $obj-E<gt>B<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 L<length()|Geo::Line/"Geometry">

=item $obj-E<gt>B<same>((OTHER|ARRAY, [TOLERANCE])|POINTS)

See L<Math::Polygon/"Geometry">

=item $obj-E<gt>B<startMinXY>()

See L<Math::Polygon/"Geometry">

=back

=head2 Transformations

=over 4

=item $obj-E<gt>B<grid>(OPTIONS)

See L<Math::Polygon/"Transformations">

=item $obj-E<gt>B<mirror>(OPTIONS)

See L<Math::Polygon/"Transformations">

=item $obj-E<gt>B<move>(OPTIONS)

See L<Math::Polygon/"Transformations">

=item $obj-E<gt>B<resize>(OPTIONS)

See L<Math::Polygon/"Transformations">

=item $obj-E<gt>B<rotate>(OPTIONS)

See L<Math::Polygon/"Transformations">

=item $obj-E<gt>B<simplify>(OPTIONS)

See L<Math::Polygon/"Transformations">

=back

=head2 Clipping

=over 4

=item $obj-E<gt>B<fillClip1>(BOX)

See L<Math::Polygon/"Clipping">

=item $obj-E<gt>B<lineClip>(BOX)

See L<Math::Polygon/"Clipping">

=back

=head2 Display

=over 4

=item $obj-E<gt>B<deg2dm>(DEGREES, POS, NEG)

=item Geo::Line-E<gt>B<deg2dm>(DEGREES, POS, NEG)

See L<Geo::Shape/"Display">

=item $obj-E<gt>B<deg2dms>(DEGREES, POS, NEG)

=item Geo::Line-E<gt>B<deg2dms>(DEGREES, POS, NEG)

See L<Geo::Shape/"Display">

=item $obj-E<gt>B<dms2deg>(DMS)

=item Geo::Line-E<gt>B<dms2deg>(DMS)

See L<Geo::Shape/"Display">

=item $obj-E<gt>B<string>([PROJECTION])

Returns a string representation of the line, which is also used for
stringification.

example: 

=back

=head1 OVERLOAD

=over 4

=item overload: B<'""' (stringification)>()

See L<Geo::Shape/"OVERLOAD">

=item overload: B<'bool' (truth value)>()

See L<Geo::Shape/"OVERLOAD">

=back

=head1 DIAGNOSTICS

=over 4

=item 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 (L<ring()|Geo::Line/"Constructors"> or L<new(ring)|Geo::Line/"Constructors">).

=item 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.

=item Error: in() not implemented for a $class

=item Error: perimeter requires a ring of points

=back

=head1 SEE ALSO

This module is part of Geo-Point distribution version 0.94,
built on December 21, 2012. Website: F<http://perl.overmeer.net/geo/>
All modules in this suite:
L</Geo::Point>,
L</Geo::Proj4>,
L</Geo::WKT>,
L</Math::Polygon>,
L</Geo::GML>,
L</Geo::ISO19139>,
L</Geo::EOP>,
L</Geo::Format::Envisat>, and
L</Geo::Format::Landsat>.

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

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>