Math::...urface(3pm)

💖 Math::Polygon::Surface 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section, manual page Math::...urface(3pm) — yes the name is truncated like that, it's giving mystery, iykyk ✨

🌸 NAME 🌸

Math::Polygon::Surface — Polygon with exclusions 🫶

---

✨ SYNOPSIS ✨

  my $outer   = Math::Polygon->new( [1,2], [2,4], [5,7], [1,2] );
  my $surface = Math::Polygon::Surface->new($outer);

---

🦋 DESCRIPTION 🦋

So like, a surface is one polygon that's the outer bounds of an array — the main character 👑 — plus, optionally, a whole list of polygons that represent exclusions from that outer polygon. Think of it as the polygon but with little cutouts, and honestly? Obsessed. 💅

---

🎀 METHODS 🎀

🧚 Constructors

• $any->new( [%options], [@polygons], %options ) — the vibe is: you may merge %options right in with @polygons, nbg. You can also use the "outer" and "inner" options.

Okay so each polygon is a reference to an ARRAY of points, and each point is an ARRAY of X and Y. But fr fr, just pass Math::Polygon objects instead, it's way better. 💜

Here's the option tea:

• inner — default: []
  • inner => \@polygons — the inner @polygons, zero or more Math::Polygon objects.
• outer — default: undef
  • outer => $polygon — the outer $polygon, a Math::Polygon.

💅 Attributes

• $obj->inner() — hands you a list (often empty, and that's fine, it's valid 🥺) of inner polygons.
• $obj->outer() — hands you the outer polygon. Periodt.

🌈 Simple calculations

• area() — gives you the area enclosed by the outer polygon, minus the areas of all the inner polygons. Peep method Math::Polygon::area() for the deets.
• $obj->bbox() — returns a list of four elements: (xmin, ymin, xmax, ymax), which describe the bounding box of the surface, and that bbox is literally the bbox of the outer polygon. Peep method Math::Polygon::bbox().
• $obj->perimeter() — the length of the border, which is the sum of the outer and inner perimeters. Peep method Math::Polygon::perimeter().

⭐ Clipping

• $obj->fillClip1($box) — so clipping a polygon into rectangles can be done in various ways (many paths, many vibes). With this algorithm, the parts of the polygon that sit outside the $box get mapped onto the borders. Every polygon is treated separately, no grouping up. 🙈
• $obj->lineClip($box) — what you get back is a list of ARRAYS-OF-POINTS containing line pieces from the input surface. Lines coming from outer polygons and inner polygons are undistinguishable from each other. Peep method Math::Polygon::lineClip().
• $obj->string() — translates the surface structure into some string. If you need a standardized format, use Geo::WKT instead, bestie. What you get back is a single string that possibly contains multiple lines: the first line is the outer, and the other lines represent the inner polygons. 🍓

---

💀 DIAGNOSTICS 💀

• Error: surface requires outer polygon — cast by new(). Yeah, no outer polygon, no surface. It said what it said. 😭

---

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

---

and that's a wrap, babe ✨ this whole thing shipped with perl v5.40.1 on 2025-10-04, and it lives in the Math::...urface(3pm) page — slay, go clip some polygons 💖