NAME
Math::Geometry::Planar - A collection of planar geometry functions
SYNOPSIS
use Math::Geometry::Planar;
$polygon = Math::Geometry::Planar->new; creates a new polygon object;
$contour = Math::Geometry::Planar->new; creates a new contour object;Formats
A point is a reference to an array holding the x and y coordinates of the point.
$point = [$x_coord,$y_coord];A polygon is a reference to an (ordered) array of points. The first point is the begin and end point of the polygon. The points can be given in any direction (clockwise or counter clockwise).
A contour is a reference to an array of polygons. By convention, the first polygon is the outer shape, all other polygons represent holes in the outer shape. The outer shape must enclose all holes ! Using this convention, the points can be given in any direction, however, keep in mind that some functions (e.g. triangulation) require that the outer polygons are entered in counter clockwise order and the inner polygons (holes) in clock wise order. The points, polygons, add_polygons methods will automatically set the right order of points. No points can be assigned to an object that already has polygons assigned to and vice versa.
$points = [[$x1,$y1],[$x2,$y2], ... ];
$polygon->points($points); # assign points to polygon object
$points1 = [[$x1,$y1],[$x2,$y2], ... ];
$points2 = [[ax1,by1],[ax2,by2], ... ];
$contour->polygons([$points1,$points2, ...]); # assign polgyons to contour objectMETHODS
The available methods are:
$polygon->points(arg);
Returns the polygon points if no argument is entered. If the argument is a refence to a points array, sets the points for a polygon object.
$contour->polygons(arg);
Returns the contour polygons if no argument is entered. If the argument is a refence to a polygons array, sets the polygons for a contour object.
$contour->num_polygons;
Returns the total number of polygons in the contour.
$contour->add_polygons(arg);
Adds a list of polygons to a contour object (if the contour object doesn't have any polygons yet, the very first polygon reference from the list is used as the outer shape). Returns the total number of polygons in the contour.
$contour->get_polygons(arg_1,arg_2, ... );
Returns a list of polygons where each element of the list corresponds to the polygon at index arg_x - starting at 0, the outer shape. If the index arg_x is out of range, the corresponding value in the result list wil be undefined. If no argument is entered, a full list of all polygons is returned. Please note that this method returns a list rather then a reference.
$polygon->cleanup;
Remove colinear points from the polygon/contour.
$polygon->isconvex;
Returns true if the polygon/contour is convex. A contour is considered to be convex if the outer shape is convex.
$polygon->issimple;
Returns true if the polygon/contour is simple. A contour is considered to be simple if all it's polygons are simple.
$polygon->perimeter;
Returns the perimeter of the polygon/contour. The perimeter of a contour is the perimeter of the outer shape.
$polygon->area;
Returns the signed area of the polygon/contour (positive if the points are in counter clockwise order). The area of a contour is the area of the outer shape minus the sum of the area of the holes.
$polygon->centroid;
Returns the centroid (center of gravity) of the polygon/contour.
$polygon->isinside($point);
Returns true if point is inside the polygon/contour (a point is inside a contour if it is inside the outer polygon and not inside a hole).
$polygon->rotate($angle,$center);
Returns polygon/contour rotated $angle (in radians) around $center. If no center is entered, rotates around the origin.
$polygon->move($dx,$dy);
Returns polygon/contour moved $dx in x direction and $dy in y direction.
$polygon->mirrorx($center);
Returns polygon/contour mirrored in x direction with (vertical) axis of reflection through point $center. If no center is entered, axis is the Y-axis.
$polygon->mirrory($center);
Returns polygon/contour mirrored in y direction with (horizontal) axis of reflection through point $center. If no center is entered, axis is the X-axis.
$polygon->mirror($axos);
Returns polygon mirrored/contour along axis $axis (= array with 2 points defining axis of reflection).
$polygon->scale($csale,$center);
Returns polygon/contour scaled by a factor $scale, center of scaling is $scale. If no center is entered, center of scaling is the origin.
$polygon->bbox;
Returns the polygon's/contour's bounding box.
$polygon->minrectangle;
Returns the polygon's/contour's minimal (area) enclosing rectangle.
$polygon->convexhull;
Returns a polygon representing the convex hull of the polygon/contour.
$polygon->convexhull2;
Returns a polygon representing the convex hull of an arbitrary set of points (works also on a contour, however a contour is a set of polygons and polygons are ordered sets of points so the method above will be faster)
$polygon->triangulate;
Triangulates a polygon/contour based on Raimund Seidel's algorithm: 'A simple and fast incremental randomized algorithm for computing trapezoidal decompositions and for triangulating polygons' Returns a list of polygons (= the triangles)
$polygon->offset_polygon($distance);
Returns reference to an array of polygons representing the original polygon offsetted by $distance
$polygon->convert2gpc;
Converts a polygon/contour to a gpc structure and returns the resulting gpc structure
EXPORTS
SegmentLength[$p1,$p2];
Returns the length of the segment (vector) p1p2
Determinant(x1,y1,x2,y2);
Returns the determinant of the matrix with rows x1,y1 and x2,y2 which is x1*y2 - y1*x2
DotProduct($p1,$p2,$p3,$p4);
Returns the vector dot product of vectors p1p2 and p3p4 or the dot product of p1p2 and p2p3 if $p4 is ommited from the argument list
CrossProduct($p1,$p2,$p3);
Returns the vector cross product of vectors p1p2 and p1p3
TriangleArea($p1,$p2,$p3);
Returns the signed area of the triangle p1p2p3
Colinear($p1,$p2,$p3);
Returns true if p1,p2 and p3 are colinear
SegmentIntersection($p1,$p2,$p3,$p4);
Returns the intersection point of segments p1p2 and p3p4, false if segments don't intersect
LineIntersection($p1,$p2,$p3,$p4);
Returns the intersection point of lines p1p2 and p3p4, false if lines don't intersect (parallel lines)
RayIntersection($p1,$p2,$p3,$p4);
Returns the intersection point of rays p1p2 and p3p4, false if lines don't intersect (parallel rays) p1 (p3) is the startpoint of the ray and p2 (p4) is a point on the ray.
RayLineIntersection($p1,$p2,$p3,$p4);
Returns the intersection point of ray p1p2 and line p3p4, false if lines don't intersect (parallel rays) p1 is the startpoint of the ray and p2 is a point on the ray.
SegmentLineIntersection($p1,$p2,$p3,$p4);
Returns the intersection point of segment p1p2 and line p3p4, false if lines don't intersect (parallel rays)
SegmentRayIntersection($p1,$p2,$p3,$p4);
Returns the intersection point of segment p1p2 and ray p3p4, false if lines don't intersect (parallel rays) p3 is the startpoint of the ray and p4 is a point on the ray.
Perpendicular($p1,$p2,$p3,$p4);
Returns true if lines (segments) p1p2 and p3p4 are perpendicular
PerpendicularFoot($p1,$p2,$p3);
Returns the perpendicular foot of p3 on line p1p2
DistanceToLine($p1,$p2,$p3);
Returns the perpendicular distance of p3 to line p1p2
DistanceToSegment($p1,$p2,$p3);
Returns the distance of p3 to segment p1p2. Depending on the point's position, this is the distance to one of the endpoints or the perpendicular distance to the segment.
Gpc2Polygons($gpc_contour);
Converts a gpc contour structure to an array of contours and returns the array
GpcClip($operation,$gpc_contour_1,$gpc_contour_2);
$operation is DIFFERENCE, INTERSECTION, XOR or UNION
$gpc_polygon_1 is the source polygon
$gpc_polygon_2 is the clip polygonReturns a gpc polygon structure which is the result of the gpc clipping operation
CircleToPoly($i,$p1,$p2,$p3);
Converts the circle through points p1p2p3 to a polygon with i segments
CircleToPoly($i,$center,$p1);
Converts the circle with center through point p1 to a polygon with i segments
CircleToPoly($i,$center,$radius);
Converts the circle with center and radius to a polygon with i segments
ArcToPoly($i,$p1,$p2,$p3);
Converts the arc with begin point p1, intermediate point p2 and end point p3 to a (non-closed !) polygon with i segments
ArcToPoly($i,$center,$p1,$p2,$direction);
Converts the arc with center, begin point p1 and end point p2 to a (non-closed !) polygon with i segments. If direction is 0, the arc is traversed counter clockwise from p1 to p2, clockwise if direction is 1