Math::...n::Calc(3pm)

✨ Math::Polygon::Calc ✨

hiii bestie 💖 this is the manual page for Math::Polygon::Calc (yeah, the 3pm one — that's just perl module page energy, iykyk). Grab a strawberry 🍓 and let's go.

---

🌸 NAME 🌸

Math::Polygon::Calc — simple polygon calculations 🦋

👑 INHERITANCE 👑

Math::Polygon::Calc
  is an Exporter

so like, it's an Exporter. it hands you functions for free. no use ceremony beyond the usual, we love a generous queen 💅

✨ 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;

(yes that MY is capitalised. that's how it's printed. we don't ask questions, we just respect the source 🙈)

🎀 DESCRIPTION 🎀

This package is a whole variaty of relatively easy polygon calculations. the slightly harder math lives in separate packages, because boundaries are healthy 💜

💅 FUNCTIONS 💅

• polygon_area(@points)

Returns the area enclosed by the polygon. ⚠️ the last point of the list must be the same as the first or your result is simply wrong, no cap.

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

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

• polygon_bbox(@points)

Returns a list with four elements: (xmin, ymin, xmax, ymax) — that's the bounding box of the polygon (all points of the polygon are within that area). literally the rectangle that wraps your whole shape like a little blanket 🫶

• 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. (it's giving "walked out there and immediately turned around" 💀)

At the moment, only pure horizontal and pure vertical spikes are removed. so don't expect it to fix your diagonal messes, bestie.

• 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. 🫠 proceed with caution.

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. ⏰ like, same points, one direction only.

• 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. 🧚 floats gonna float, fr fr.

• polygon_counter_clockwise(@points)

Be sure the polygon points are in counter-clockwise order. 🔄 the other direction, the other vibe.

• polygon_distance($point, @polygon)

[1.05] calculate the shortest distance between a point and any vertex of a closed polygon. 📏 shortest path wins, periodt.

• 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)

(no description — she's just here, serving face 💅)

• polygon_is_closed(@points)

(also no description — mysterious main character energy 🌈)

• 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. 🙃 slower but smarter, iconic.

• 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. 📍 first point? always the left-bottom-est one.

• polygon_string(@points)

(no description either — she's simply built different 🦋)

---

😭 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()

like yes, those are the actual error strings, don't @ me 💀

🔥 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. 🫶

---

okay that's the whole page bestie, you ate it 💖 this was perl v5.40.1, dated 2025-10-04, and the whole thing is the Math::...n::Calc(3pm) manual — go forth and calculate your little polygons, you gorgeous genius 👑✨