1Math::Polygon(3)      User Contributed Perl Documentation     Math::Polygon(3)
2
3
4

NAME

6       Math::Polygon - Class for maintaining polygon data
7

SYNOPSIS

9        my $poly = Math::Polygon->new( [1,2], [2,4], [5,7], [1,2] );
10        print $poly->nrPoints;
11        my @p    = $poly->points;
12
13        my ($xmin, $ymin, $xmax, $ymax) = $poly->bbox;
14
15        my $area   = $poly->area;
16        my $l      = $poly->perimeter;
17        if($poly->isClockwise) { ... };
18
19        my $rot    = $poly->startMinXY;
20        my $center = $poly->centroid;
21        if($poly->contains($point)) { ... };
22
23        my $boxed  = $poly->lineClip($xmin, $xmax, $ymin, $ymax);
24

DESCRIPTION

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
30       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

METHODS

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
43           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
48            -Option   --Default
49             bbox       undef
50             clockwise  undef
51             points     undef
52
53           bbox => [$xmin,$ymin, $xmax,$ymax]
54             Usually computed from the shape automatically, but can also be
55             overruled. See bbox().
56
57           clockwise => BOOLEAN
58             Is not specified, it will be computed by the isClockwise() method
59             on demand.
60
61           points => \@points
62             See points() and nrPoints().
63
64           example: creation of new polygon
65
66            my $p = Math::Polygon->new([1,0],[1,1],[0,1],[0,0],[1,0]);
67
68            my @p = ([1,0],[1,1],[0,1],[0,0],[1,0]);
69            my $p = Math::Polygon->new(points => \@p);
70
71   Attributes
72       $obj->nrPoints()
73           Returns the number of points,
74
75       $obj->order()
76           Returns the number of (unique?) points: one less than nrPoints().
77
78       $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
82           example:
83
84             my $point = $poly->point(2);
85             my ($first, $last) = $poly->point(0, -1);
86
87       $obj->points( [FORMAT] )
88           In LIST context, the points are returned as list, otherwise as
89           reference to an ARRAY of points.
90
91           [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
96           example:
97
98             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
103             my @points = $poly->points("%.2f");
104
105   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
112           example:
113
114             my $area = $poly->area;
115             print "$area $poly_units ^2\n";
116
117       $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
124           example:
125
126             my ($xmin, $ymin, $xmax, $ymax) = $poly->bbox;
127
128       $obj->beautify(%options)
129           Returns a new, beautified version of this polygon.  Function
130           Math::Polygon::Calc::polygon_beautify().
131
132           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
137            -Option       --Default
138             remove_spikes  <false>
139
140           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
147           example:
148
149             my $center = $poly->centroid;
150             my ($cx, $cy) = @$center;
151
152       $obj->clockwise()
153           Make sure the points are in clockwise order.
154
155           example:
156
157             $poly->clockwise;
158
159       $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
163       $obj->counterClockwise()
164           Make sure the points are in counter-clockwise order.
165
166           example:
167
168             $poly->counterClockwise
169
170       $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
174       $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
179           example:
180
181             if($poly->equal($other_poly, 0.1)) ...
182             if($poly->equal(\@points, 0.1)) ...
183             if($poly->equal(@points)) ...
184
185       $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
191           example:
192
193             if($poly->isClockwise) ...
194
195       $obj->isClosed()
196           Returns true if the first point of the poly definition is the same
197           as the last point.
198
199       $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
205           example:
206
207            my $fence = $poly->perimeter;
208            print "fence length: $fence $poly_units\n"
209
210       $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
216           example:
217
218             if($poly->same($other_poly, 0.1)) ...
219             if($poly->same(\@points, 0.1)) ...
220             if($poly->same(@points)) ...
221
222       $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
227           Function Math::Polygon::Calc::polygon_start_minxy().
228
229   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
234       $obj->grid(%options)
235           Returns a polygon object with the points snapped to grid points.
236           See Math::Polygon::Transform::polygon_grid().
237
238            -Option--Default
239             raster  1.0
240
241           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
246       $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
250            -Option--Default
251             b       0
252             line    <undef>
253             rc      undef
254             x       undef
255             y       undef
256
257           b => FLOAT
258             Only used in combination with option "rc" to describe a line.
259
260           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
264           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
270           x => FLOAT
271             Mirror in the line "x=value", which means that "y" stays
272             unchanged.
273
274           y => FLOAT
275             Mirror in the line "y=value", which means that "x" stays
276             unchanged.
277
278       $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
282            -Option--Default
283             dx      0
284             dy      0
285
286           dx => FLOAT
287             Displacement in the horizontal direction.
288
289           dy => FLOAT
290             Displacement in the vertical direction.
291
292       $obj->resize(%options)
293           Returns a resized polygon object.  See
294           Math::Polygon::Transform::polygon_resize().
295
296            -Option--Default
297             center  [0,0]
298             scale   1.0
299             xscale  <scale>
300             yscale  <scale>
301
302           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
309           xscale => FLOAT
310             Specific scaling factor in the horizontal direction.
311
312           yscale => FLOAT
313             Specific scaling factor in the vertical direction.
314
315       $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
320            -Option --Default
321             center   [0,0]
322             degrees  0
323             radians  0
324
325           center => POINT
326           degrees => FLOAT
327             specify rotation angle in degrees (between -180 and 360).
328
329           radians => FLOAT
330             specify rotation angle in rads (between -pi and 2*pi)
331
332       $obj->simplify(%options)
333           Returns a polygon object where points are removed.  See
334           Math::Polygon::Transform::polygon_simplify().
335
336            -Option    --Default
337             max_points  undef
338             same        0.0001
339             slope       undef
340
341           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
347           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
351           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
356             The slope will not be removed around the starting point of the
357             polygon.  Removing points will change the area of the polygon.
358
359   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
366           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
371       $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
376   Display
377       $obj->string( [FORMAT] )
378           Print the polygon.
379
380           [1.09] When a FORMAT is specified, all coordinates will get
381           formatted first.  This may hide platform dependent rounding
382           differences.
383

SEE ALSO

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

LICENSE

389       Copyrights 2004-2018 by [Mark Overmeer]. For other contributors see
390       ChangeLog.
391
392       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/
394
395
396
397perl v5.36.0                      2023-01-20                  Math::Polygon(3)
Impressum