=encoding utf8

=head1 NAME

Math::Polygon::Calc - Simple polygon calculations

=head1 INHERITANCE

 Math::Polygon::Calc
   is a Exporter

=head1 SYNOPSIS

 my @poly = ( [1,2], [2,4], [5,7], [1, 2] );

 my ($xmin, $ymin, $xmax, $ymax) = polygon_bbox @poly;

 my $area = polygon_area @poly;
 MY $L    = polygon_perimeter @poly;
 if(polygon_is_clockwise @poly) { ... };
 
 my @rot  = polygon_start_minxy @poly;

=head1 DESCRIPTION

This package contains a wide variaty of relatively easy polygon
calculations.  More complex calculations are put in separate
packages.

=head1 FUNCTIONS

=over 4

=item B<polygon_area>(LIST-of-$points)

Returns the area enclosed by the polygon.  The last point of the list
must be the same as the first to produce a correct result.

The algorithm was found at L<http://mathworld.wolfram.com/PolygonArea.html>,
and sounds:

 A = abs( 1/2 * (x1y2-x2y1 + x2y3-x3y2 ...)

=item B<polygon_bbox>(LIST-of-$points)

Returns a list with four elements: (xmin, ymin, xmax, ymax), which describe
the bounding box of the polygon (all points of the polygon are within that
area.

=item B<polygon_beautify>( [$options], LIST-of-$points )

Polygons, certainly after some computations, can have a lot of
horrible artifacts: points which are double, spikes, etc.  This
functions provided by this module beautify
The optional HASH contains the $options:

 -Option        --Default
  remove_between  <false>
  remove_spikes   <false>

=over 2

=item remove_between => BOOLEAN

Simple points in-between are always removed, but more complex
points are not: when the line is not parallel to one of the axes,
more intensive calculations must take place.  This will only be
done when this flags is set.
NOT IMPLEMENTED YET

=item remove_spikes => BOOLEAN

=back

=item B<polygon_centroid>(LIST-of-$points)

Returns the centroid location of the polygon.  The last point of the list
must be the same as the first to produce a correct result.

The algorithm was found at
F<http://en.wikipedia.org/wiki/Centroid#Centroid_of_polygon>

=item B<polygon_clockwise>(LIST-of-$points)

Be sure the polygon points are in clockwise order.

=item B<polygon_contains_point>($point, LIST-of-$points)

Returns true if the point is inside the closed polygon.  On an edge will
be flagged as 'inside'.  But be warned of rounding issues, caused by
the floating-point calculations used by this algorithm.

=item B<polygon_counter_clockwise>(LIST-of-$points)

Be sure the polygon points are in counter-clockwise order.

=item B<polygon_distance>($point, @polygon)

[1.05] calculate the shortest distance between a point and any vertex of
a closed polygon.

=item B<polygon_equal>( ARRAY-of-$points, ARRAY-of-$points, [$tolerance] )

Compare two polygons, on the level of points. When the polygons are
the same but rotated, this will return false. See L<polygon_same()|Math::Polygon::Calc/"FUNCTIONS">.

=item B<polygon_is_clockwise>(LIST-of-$points)

=item B<polygon_is_closed>($points)

=item B<polygon_perimeter>(LIST-of-$points)

The length of the line of the polygon.  This can also be used to compute
the length of any line: of the last point is not equal to the first, then
a line is presumed; for a polygon they must match.

This is simply Pythagoras.

 $l = sqrt((x1-x0)^2 + (y1-y0)^2) + sqrt((x2-x1)^2+(y2-y1)^2) + ...

=item B<polygon_same>( ARRAY-of-$points, ARRAY-of-$points, [$tolerance] )

Compare two polygons, where the polygons may be rotated wrt each
other. This is (much) slower than L<polygon_equal()|Math::Polygon::Calc/"FUNCTIONS">, but some algorithms
will cause un unpredictable rotation in the result.

=item B<polygon_start_minxy>(LIST-of-$points)

Returns the polygon, where the point which is closest to the left-bottom
corner of the bounding box is made first.

=item B<polygon_string>(LIST-of-$points)

=back

=head1 SEE ALSO

This module is part of Math-Polygon distribution version 1.05,
built on December 28, 2016. Website: F<http://perl.overmeer.net/geo/>

=head1 LICENSE

Copyrights 2004,2006-2016 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>