1Math::Polygon(3) User Contributed Perl Documentation Math::Polygon(3)
2
6 Math::Polygon - Class for maintaining polygon data
7
9 my $poly = Math::Polygon->new( [1,2], [2,4], [5,7], [1,2] );
10 print $poly->nrPoints;
11 my @p = $poly->points;
12 my ($xmin, $ymin, $xmax, $ymax) = $poly->bbox;
14 my $area = $poly->area;
16 my $l = $poly->perimeter;
17 if($poly->isClockwise) { ... };
18 my $rot = $poly->startMinXY;
20 my $center = $poly->centroid;
21 if($poly->contains($point)) { ... };
22 my $boxed = $poly->lineClip($xmin, $xmax, $ymin, $ymax);
24
26 This class provides an Object Oriented interface around
27 Math::Polygon::Calc, Math::Polygon::Clip, and other. Together, these
28 modules provide basic transformations on 2D polygons in pure perl.
29 WARNING: these computations may show platform dependent ronding
31 differences. These may also originate from compilation options of the
32 Perl version you installed.
33
35 Constructors
36 $obj->new(%options, [@points], %options)
37 Math::Polygon->new(%options, [@points], %options)
38 You may add %options before and/or after the @points. You may also
39 use the "points" option to set the points. Each point in @points
40 is (a references) to an ARRAY with two elements: an X and a Y
41 coordinate.
42 When new() is called as instance method, it is believed that the
44 new polygon is derived from the callee, and therefore some facts
45 (like clockwise or anti-clockwise direction) will get copied unless
46 overruled.
47 -Option --Default
49 bbox undef
50 clockwise undef
51 points undef
52 bbox => [$xmin,$ymin, $xmax,$ymax]
54 Usually computed from the shape automatically, but can also be
55 overruled. See bbox().
56 clockwise => BOOLEAN
58 Is not specified, it will be computed by the isClockwise() method
59 on demand.
60 points => \@points
62 See points() and nrPoints().
63 example: creation of new polygon
65 my $p = Math::Polygon->new([1,0],[1,1],[0,1],[0,0],[1,0]);
67 my @p = ([1,0],[1,1],[0,1],[0,0],[1,0]);
69 my $p = Math::Polygon->new(points => \@p);
70 Attributes
72 $obj->nrPoints()
73 Returns the number of points,
74 $obj->order()
76 Returns the number of (unique?) points: one less than nrPoints().
77 $obj->point( $index, [$index,...] )
79 Returns the point with the specified $index or INDEXES. In SCALAR
80 context, only the first $index is used.
81 example:
83 my $point = $poly->point(2);
85 my ($first, $last) = $poly->point(0, -1);
86 $obj->points( [FORMAT] )
88 In LIST context, the points are returned as list, otherwise as
89 reference to an ARRAY of points.
90 [1.09] When a FORMAT is given, each coordinate will get processed.
92 This may be useful to hide platform specific rounding errors.
93 FORMAT may be a CODE reference or a printf() alike string. See
94 Math::Polygon::Calc::polygon_format().
95 example:
97 my @points = $poly->points;
99 my $first = $points[0];
100 my $x0 = $points[0][0]; # == $first->[0] --> X
101 my $y0 = $points[0][1]; # == $first->[1] --> Y
102 my @points = $poly->points("%.2f");
104 Geometry
106 $obj->area()
107 Returns the area enclosed by the polygon. The last point of the
108 list must be the same as the first to produce a correct result.
109 The computed result is cached. Function
110 Math::Polygon::Calc::polygon_area().
111 example:
113 my $area = $poly->area;
115 print "$area $poly_units ^2\n";
116 $obj->bbox()
118 Returns a list with four elements: (xmin, ymin, xmax, ymax), which
119 describe the bounding box of the polygon (all points of the polygon
120 are inside that area). The computation is expensive, and
121 therefore, the results are cached. Function
122 Math::Polygon::Calc::polygon_bbox().
123 example:
125 my ($xmin, $ymin, $xmax, $ymax) = $poly->bbox;
127 $obj->beautify(%options)
129 Returns a new, beautified version of this polygon. Function
130 Math::Polygon::Calc::polygon_beautify().
131 Polygons, certainly after some computations, can have a lot of
133 horrible artifacts: points which are double, spikes, etc. This
134 functions provided by this module beautify them. A new polygon is
135 returned.
136 -Option --Default
138 remove_spikes <false>
139 remove_spikes => BOOLEAN
141 $obj->centroid()
142 Returns the centroid location of the polygon. The last point of
143 the list must be the same as the first to produce a correct result.
144 The computed result is cached. Function
145 Math::Polygon::Calc::polygon_centroid().
146 example:
148 my $center = $poly->centroid;
150 my ($cx, $cy) = @$center;
151 $obj->clockwise()
153 Make sure the points are in clockwise order.
154 example:
156 $poly->clockwise;
158 $obj->contains($point)
160 Returns a truth value indicating whether the point is inside the
161 polygon or not. On the edge is inside.
162 $obj->counterClockwise()
164 Make sure the points are in counter-clockwise order.
165 example:
167 $poly->counterClockwise
169 $obj->distance($point)
171 [1.05] Returns the distance of the point to the closest point on
172 the border of the polygon, zero if the point is on an edge.
173 $obj->equal( <$other | \@points,[$tolerance]> | $points )
175 Compare two polygons, on the level of points. When the polygons are
176 the same but rotated, this will return false. See same(). Function
177 Math::Polygon::Calc::polygon_equal().
178 example:
180 if($poly->equal($other_poly, 0.1)) ...
182 if($poly->equal(\@points, 0.1)) ...
183 if($poly->equal(@points)) ...
184 $obj->isClockwise()
186 The points are (in majority) orded in the direction of the hands of
187 the clock. This calculation is quite expensive (same effort as
188 calculating the area of the polygon), and the result is therefore
189 cached.
190 example:
192 if($poly->isClockwise) ...
194 $obj->isClosed()
196 Returns true if the first point of the poly definition is the same
197 as the last point.
198 $obj->perimeter()
200 The length of the line of the polygon. This can also be used to
201 compute the length of any line: of the last point is not equal to
202 the first, then a line is presumed; for a polygon they must match.
203 Function Math::Polygon::Calc::polygon_perimeter().
204 example:
206 my $fence = $poly->perimeter;
208 print "fence length: $fence $poly_units\n"
209 $obj->same( <$other_polygon | \@points, [$tolerance]> | @points )
211 Compare two polygons, where the polygons may be rotated wrt each
212 other. This is (much) slower than equal(), but some algorithms will
213 cause un unpredictable rotation in the result. Function
214 Math::Polygon::Calc::polygon_same().
215 example:
217 if($poly->same($other_poly, 0.1)) ...
219 if($poly->same(\@points, 0.1)) ...
220 if($poly->same(@points)) ...
221 $obj->startMinXY()
223 Returns a new polygon object, where the points are rotated in such
224 a way that the point which is losest to the left-bottom point of
225 the bounding box has become the first.
226 Function Math::Polygon::Calc::polygon_start_minxy().
228 Transformations
230 Implemented in Math::Polygon::Transform: changes on the structure of
231 the polygon except clipping. All functions return a new polygon object
232 or undef.
233 $obj->grid(%options)
235 Returns a polygon object with the points snapped to grid points.
236 See Math::Polygon::Transform::polygon_grid().
237 -Option--Default
239 raster 1.0
240 raster => FLOAT
242 The raster size, which determines the points to round to. The
243 origin "[0,0]" is always on a grid-point. When the raster value
244 is zero, no transformation will take place.
245 $obj->mirror(%options)
247 Mirror the polygon in a line. Only one of the options can be
248 provided. Some programs call this "flip" or "flop".
249 -Option--Default
251 b 0
252 line <undef>
253 rc undef
254 x undef
255 y undef
256 b => FLOAT
258 Only used in combination with option "rc" to describe a line.
259 line => [POINT, POINT]
261 Alternative way to specify the mirror line. The "rc" and "b" are
262 computed from the two points of the line.
263 rc => FLOAT
265 Description of the line which is used to mirror in. The line is
266 "y= rc*x+b". The "rc" equals "-dy/dx", the firing angle. If
267 "undef" is explicitly specified then "b" is used as constant x:
268 it's a vertical mirror.
269 x => FLOAT
271 Mirror in the line "x=value", which means that "y" stays
272 unchanged.
273 y => FLOAT
275 Mirror in the line "y=value", which means that "x" stays
276 unchanged.
277 $obj->move(%options)
279 Returns a moved polygon object: all point are moved over the
280 indicated distance. See Math::Polygon::Transform::polygon_move().
281 -Option--Default
283 dx 0
284 dy 0
285 dx => FLOAT
287 Displacement in the horizontal direction.
288 dy => FLOAT
290 Displacement in the vertical direction.
291 $obj->resize(%options)
293 Returns a resized polygon object. See
294 Math::Polygon::Transform::polygon_resize().
295 -Option--Default
297 center [0,0]
298 scale 1.0
299 xscale <scale>
300 yscale <scale>
301 center => $point
303 scale => FLOAT
304 Resize the polygon with the indicated factor. When the factor is
305 larger than 1, the resulting polygon with grow, when small it
306 will be reduced in size. The scale will be respective from the
307 center.
308 xscale => FLOAT
310 Specific scaling factor in the horizontal direction.
311 yscale => FLOAT
313 Specific scaling factor in the vertical direction.
314 $obj->rotate(%options)
316 Returns a rotated polygon object: all point are moved over the
317 indicated distance. See
318 Math::Polygon::Transform::polygon_rotate().
319 -Option --Default
321 center [0,0]
322 degrees 0
323 radians 0
324 center => POINT
326 degrees => FLOAT
327 specify rotation angle in degrees (between -180 and 360).
328 radians => FLOAT
330 specify rotation angle in rads (between -pi and 2*pi)
331 $obj->simplify(%options)
333 Returns a polygon object where points are removed. See
334 Math::Polygon::Transform::polygon_simplify().
335 -Option --Default
337 max_points undef
338 same 0.0001
339 slope undef
340 max_points => INTEGER
342 First, "same" and "slope" reduce the number of points. Then, if
343 there are still more than the specified number of points left,
344 the points with the widest angles will be removed until the
345 specified maximum number is reached.
346 same => FLOAT
348 The distance between two points to be considered "the same"
349 point. The value is used as radius of the circle.
350 slope => FLOAT
352 With three points X(n),X(n+1),X(n+2), the point X(n+1) will be
353 removed if the length of the path over all three points is less
354 than "slope" longer than the direct path between X(n) and X(n+2).
355 The slope will not be removed around the starting point of the
357 polygon. Removing points will change the area of the polygon.
358 Clipping
360 $obj->fillClip1($box)
361 Clipping a polygon into rectangles can be done in various ways.
362 With this algorithm, the parts of the polygon which are outside the
363 $box are mapped on the borders. The polygon stays in one piece,
364 but may have vertices which are followed in two directions.
365 Returned is one polygon, which is cleaned from double points,
367 spikes and superfluous intermediate points, or "undef" when no
368 polygon is outside the $box. Function
369 Math::Polygon::Clip::polygon_fill_clip1().
370 $obj->lineClip($box)
372 Returned is a list of ARRAYS-OF-POINTS containing line pieces from
373 the input polygon. Function
374 Math::Polygon::Clip::polygon_line_clip().
375 Display
377 $obj->string( [FORMAT] )
378 Print the polygon.
379 [1.09] When a FORMAT is specified, all coordinates will get
381 formatted first. This may hide platform dependent rounding
382 differences.
383
385 This module is part of Math-Polygon distribution version 1.10, built on
386 January 03, 2018. Website: http://perl.overmeer.net/CPAN/
387
389 Copyrights 2004-2018 by [Mark Overmeer]. For other contributors see
390 ChangeLog.
391 This program is free software; you can redistribute it and/or modify it
393 under the same terms as Perl itself. See http://dev.perl.org/licenses/
394perl v5.36.0 2023-01-20 Math::Polygon(3)