/ 
Math-Geometry-Planar-1.01
River stage one • 2 direct dependents • 8 total dependents
/ Math::Geometry::Planar

NAME

Math::Geometry::Planar - Module with 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 refenece 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).

$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 object

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.

$contour = [$poly1,$poly2], ... ];

METHODS

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.  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 will be 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 tota
area the holes)

$polygon->centroid;

Returns the centroid 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

$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

$polygon->mirrory($center);

Returns polygon/contour mirrored in y direction
with (horizontal) axis of reflection through point $center

$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

$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 reference to a list of triangles

$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 | x1 y1 | which is x1*y2 - y1*x2
        | x2 y2 |

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 false if segments don't intersect
Returns the intersection point of segments p1p2 and p3p4

LineIntersection($p1,$p2,$p3,$p4);

Returns false if lines don't intersect (parallel lines)
Returns the intersection point of lines p1p2 and p3p4

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 dostance of p3 to line p1p2

DistanceToSegment($p1,$p2,$p3);

Returns the perpendicular distance of p3 to segment p1p2

Gpc2Polygons($gpc_contour);

Comverts 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 polygon
Returns 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 points p1 to a polygon with i segments

CircleToPoly($i,$center,$radius);

Converts the circle with center and radius to a polygon with i segments

ArcleToPoly($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

ArcleToPoly($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