libgeo-point-perl 0.96-1 / usr / share / perl5 / Geo / Line.pod

=encoding utf8

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

Extends L<"DESCRIPTION" in Math::Polygon|Math::Polygon/"DESCRIPTION">.
 
Extends L<"DESCRIPTION" in Geo::Shape|Geo::Shape/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in Math::Polygon|Math::Polygon/"METHODS">.
 
Extends L<"METHODS" in Geo::Shape|Geo::Shape/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in Math::Polygon|Math::Polygon/"Constructors">.
 
Extends L<"Constructors" in Geo::Shape|Geo::Shape/"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])

=item Geo::Line-E<gt>B<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                      <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
   );
 my $clone = $line->new(filled => 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

Extends L<"Attributes" in Math::Polygon|Math::Polygon/"Attributes">.
 
Extends L<"Attributes" in Geo::Shape|Geo::Shape/"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>()

Inherited, see L<Math::Polygon/"Attributes">

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

Inherited, see L<Math::Polygon/"Attributes">

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

Inherited, see L<Math::Polygon/"Attributes">

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

Inherited, see L<Math::Polygon/"Attributes">

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

Inherited, see L<Geo::Shape/"Attributes">

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

Inherited, see L<Geo::Shape/"Attributes">

=back

=head2 Projections

Extends L<"Projections" in Geo::Shape|Geo::Shape/"Projections">.
 
=over 4

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

Inherited, see L<Geo::Shape/"Projections">

=item $obj-E<gt>B<projectOn>($nick, @points)

Inherited, see L<Geo::Shape/"Projections">

=back

=head2 Geometry

Extends L<"Geometry" in Math::Polygon|Math::Polygon/"Geometry">.
 
Extends L<"Geometry" in Geo::Shape|Geo::Shape/"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>()

Inherited, 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]])

Inherited, see L<Geo::Shape/"Geometry">

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

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, 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>()

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, see L<Geo::Shape/"Geometry">

=item $obj-E<gt>B<equal>(<$other | ARRAY,[$tolerance]> | $points)

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, 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)

Inherited, see L<Math::Polygon/"Geometry">

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

Inherited, see L<Math::Polygon/"Geometry">

=back

=head2 Transformations

Extends L<"Transformations" in Math::Polygon|Math::Polygon/"Transformations">.
 
=over 4

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

Inherited, see L<Math::Polygon/"Transformations">

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

Inherited, see L<Math::Polygon/"Transformations">

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

Inherited, see L<Math::Polygon/"Transformations">

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

Inherited, see L<Math::Polygon/"Transformations">

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

Inherited, see L<Math::Polygon/"Transformations">

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

Inherited, see L<Math::Polygon/"Transformations">

=back

=head2 Clipping

Extends L<"Clipping" in Math::Polygon|Math::Polygon/"Clipping">.
 
=over 4

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

Inherited, see L<Math::Polygon/"Clipping">

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

Inherited, see L<Math::Polygon/"Clipping">

=back

=head2 Display

Extends L<"Display" in Math::Polygon|Math::Polygon/"Display">.
 
Extends L<"Display" in Geo::Shape|Geo::Shape/"Display">.
 
=over 4

=item $obj-E<gt>B<deg2dm>($degrees, $pos, $neg)

=item Geo::Line-E<gt>B<deg2dm>($degrees, $pos, $neg)

Inherited, see L<Geo::Shape/"Display">

=item $obj-E<gt>B<deg2dms>($degrees, $pos, $neg)

=item Geo::Line-E<gt>B<deg2dms>($degrees, $pos, $neg)

Inherited, see L<Geo::Shape/"Display">

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

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

Inherited, see L<Geo::Shape/"Display">

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

Inherited, see L<Math::Polygon/"Display">

=item $obj-E<gt>B<toString>([$projection])

Returns a string representation of the line, which is also used for
stringification.  The old method named C<string> is deprecated.

=back

=head1 OVERLOAD

Extends L<"OVERLOAD" in Geo::Shape|Geo::Shape/"OVERLOAD">.
 
=over 4

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

Inherited, see L<Geo::Shape/"OVERLOAD">

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

Inherited, 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.96,
built on January 21, 2014. 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-2014 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>