NAME

       Math::Polygon::Calc - Simple polygon calculations

INHERITANCE

        Math::Polygon::Calc
          is an Exporter

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;

DESCRIPTION

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

FUNCTIONS

       polygon_area(@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 <https://mathworld.wolfram.com/PolygonArea.html>, and sounds:

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

       polygon_bbox(@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.

       polygon_beautify( [\%options], @points )
           Polygons,  certainly  after some computations, can have a lot of horrible artifacts: points which are
           double, spikes, etc.  The optional HASH contains the %options.

            -Option       --Default
             remove_spikes  <C<false>>

           remove_spikes => BOOLEAN
             Spikes contain of three successive points, where the first is on the line between  the  second  and
             the third.  The line goes from first to second, but then back to get to the third point.

             At the moment, only pure horizontal and pure vertical spikes are removed.

       polygon_centroid( [%options|\%options], @points )
           Returns the centroid location of the polygon.

           The  last  point  of  the  list must be the same as the first (must be 'closed') to produce a correct
           result.

           warning: When the polygon is very flat, it will not produce a stable result: minor changes in  single
           coordinates will move the centroid too far.

           The algorithm was found at <https://en.wikipedia.org/wiki/Centroid#Of_a_polygon>

            -Option  --Default
             is_large  false

           is_large => BOOLEAN
             When  the  polygon  is  small and far from the origin "(0,0)" (as often happens when processing geo
             coordinates), then rounding errors will have a large impact on result of the algorithm.   To  avoid
             this, we will move the poly first close to the origin, and move the calculated center point back.

             This   transform,   which  cost  modest  performance,  can  be  disabled  with  this  option.   The
             transformation  will  also  not  happen  when  the  first  "x"  coordinate  is  an   object,   like
             Math::BigFloat.

       polygon_clockwise(@points)
           Be sure the polygon points are in clockwise order.

       polygon_contains_point($point, @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.

       polygon_counter_clockwise(@points)
           Be sure the polygon points are in counter-clockwise order.

       polygon_distance($point, @polygon)
           [1.05] calculate the shortest distance between a point and any vertex of a closed polygon.

       polygon_equal( \@points1, \@points2, [$tolerance] )
           Compare two polygons, on the level of points. When the polygons are the same but rotated,  this  will
           return "false". See polygon_same().

       polygon_format($format, @points)
           [1.07]  Map  the $format over all @points, both the X and Y coordinate.  This is especially useful to
           reduce the number of digits in the stringification.  For instance, when you want reproducible results
           in regression scripts.

           The format is anything supported by printf(),  for  instance  "%5.2f".   Or,  you  can  pass  a  code
           reference which accepts a single value.

       polygon_is_clockwise(@points)

       polygon_is_closed(@points)

       polygon_perimeter(@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) + ...

       polygon_same( \@points1, \@points2, [$tolerance] )
           [1.12] Compare two polygons, where the polygons may be rotated or mirrored wrt each  other.  This  is
           (much)  slower  than polygon_equal(), but some algorithms will cause un unpredictable rotation in the
           result.

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

       polygon_string(@points)

DIAGNOSTICS

       Error: empty polygon is neither closed nor open
           Cast by polygon_is_closed()

       Error: polygon points on a line, so no centroid
           Cast by polygon_centroid()

SEE ALSO

       This   module   is   part   of   Math-Polygon  version  2.00,  built  on  September  04,  2025.  Website:
       http://perl.overmeer.net/CPAN/

LICENSE

       For contributors see file ChangeLog.

       This software is copyright (c) 2004-2025 by Mark Overmeer.

       This is free software; you can redistribute it and/or modify it under  the  same  terms  as  the  Perl  5
       programming language system itself.

perl v5.40.1                                       2025-10-04                           Math::Polygon::Calc(3pm)