Geom Class Reference

Library of various geometric transforms.

Member Functions
	centroid(geom)
	Find the centroid (center) of geom
	coordsToPoints(coordList)
	Convert a table of coordinates into a table of points. [details]
	flip(geom, horizontal)
	Flip geom along the x- or y-axis in regards to the origin. [details]
	rotate(geom, angle)
	Rotate geom about its centroid. [details]
	scale(geom, sx, sy)
	Scale geom by sx, sy, in reference to the x- and y-axes. [details]
	transform(geom, tx, ty, sx, sy, angle)
	Transform geom by scaling, rotating, and translating. [details]
	translate(geom, tx, ty)
	Translate (offset) geom by tx, ty. [details]

Static Member Functions
	clipPolygons(op, subject, clip, mergeAfterTriangulating=false)
	Perform a clipping operation on sets of polygons. [details]
	clipPolygonsAsTree(op, subject, clip)
	Perform a clipping operation on sets of polygons, keeping holes. [details]
	offsetPolygons(offset, polygons)
	Offset polygons by the given offset. [details]
	polyganize(triangles)
	Merge triangles into convex polygons. [details]
	segmentsIntersect(a1, a2, b1, b2)
	Finds intersection of the linesegments (a1, a2) and (b1, b2) [details]
	triangulate(polygons)
	Break up polygons into triangles. [details]

Detailed Description

Library of various geometric transforms.

The Geom class provides a collection of useful geometric operations. Since point objects are immutable, all the Geom functions return either a new point or a new table of new points. All follow the same usage pattern.

local p1 = point.new(0, 10)
local p2 = point.new(10, 10)
local p3 = point.new(10, 0)
 
local geom = {p1, p2, p3, p1}   -- Use a table
 
local triangle = LineItem.new()
triangle:setGeom(Geom.rotate(geom, 45))
 
bf:addItem(triangle)

In all cases below, geom refers to either a single point or a table of points.

Member Function Documentation

centroid(geom)

Arg types: geom: Geom  |  returns point

Find the centroid (center) of geom

Parameters

geom	The geometry to find the centroid of

Returns

The centroid, the average of all the points in geometry. This point has the property of minimizing the sum square distance to all points in geom

Geom.clipPolygons(op, subject, clip, mergeAfterTriangulating = false)

Arg types: op: ClipType, subject: mixed, clip: mixed, mergeAfterTriangulating = false: bool  |  returns table

static

Perform a clipping operation on sets of polygons.

This function uses Bitfighter's polygon manipulation utilities to perform boolean operations on sets of polygons. While these utilities are generally robust, there are a few caveats and some inputs may cause failure.

In particular, Bitfighter's engine does not support "holes" in polygons. Because of this, if the result of the requested operation would have holes, the entire solution is triangulated to remove them. The triangles may then be optionally merged into convex polygons. This way, the client code (or level designer) can select and manually join the result into the desired shape, rather than making Bitfighter guess (probably incorrectly) how it should look. When no holes are created in the output, this function produces the least number of polygons which represent it.

Note

This function is highly experimental, and potentially very resource intensive. If the output must be triangulated (because you made a hole), then there is a possibility that the program will crash abruptly. Please use this function with great care, and make sure to constrain the inputs tightly so that users can not induce crashes.

Parameters

op	ClipType The polygon boolean operation to execute.
subject	A table of polygons or a single polygon to use as the subject.
clip	A table of polygons or a single polygon to use as the clip.
mergeAfterTriangulating	Merge triangles into convex polygons when forced to triangulate the result.

Returns

A table of the solution polygons, or nil on failure.

Geom.clipPolygonsAsTree(op, subject, clip)

Arg types: op: ClipType, subject: mixed, clip: mixed  |  returns table

static

Perform a clipping operation on sets of polygons, keeping holes.

This function uses Bitfighter's polygon manipulation utilities to perform boolean operations on sets of polygons, keeping holes, and returning the result as a tree of polygons and holes. This is useful when performing repeated operations on the results of a clipping operation, or when you need to know which polygon is contained in which hole or vice versa.

Note

This function is highly experimental, and potentially very resource intensive. The algorithm runs in O(n) = n*log(n) time, with respect to the number of vertices.

Parameters

op	ClipType The polygon boolean operation to execute.
subject	A table of polygons or a single polygon to use as the subject.
clip	A table of polygons or a single polygon to use as the clip.

Returns

A tree representing the solution, in the following format:

{
  points = { p1, p2, ...},
  children = { child1, child2, ... }
  hole = false -- True if this is a hole.
}

Where each child is a another table with the same structure, representing the holes or polygons contained by this node. Note that all of a polygon's children will be holes, and vice versa.

coordsToPoints(coordList)

Arg types: coordList: table  |  returns nothing

Convert a table of coordinates into a table of points.

Parse a list of coordinates and generate points for every pair. An even number of coordinates should be provided. If an odd number is supplied, 0 will be used for the missing coordinate.

Example: pts = Geom.coordsToPoints({ 0,0, 100,0, 100,100, 0,100 })

Parameters

coordList

- The list of coordinates to be used for creating points

Returns

A table of points that can be used as input for other functions requring a multi-point geometry

flip(geom, horizontal)

Arg types: geom: Geom, horizontal: bool  |  returns geom

Flip geom along the x- or y-axis in regards to the origin.

Parameters

geom	- The geometry to modify. Geom can either be a point or a table of points.
horizontal	- Pass true to flip along the x-axis, false to flip along the y-axis.

Returns

A geometry of the same type that was passed in.

Geom.offsetPolygons(offset, polygons)

Arg types: offset: num, polygons: mixed  |  returns table

static

Offset polygons by the given offset.

This offsets polygons using a 'miter' join type.

If the input offset generates polygons that overlap, the output can have fewer total polygons than the input.

If the input polygon has 'isthmus' pieces, then the output cat have more polygons than the input.

Parameters

offset	Amount to offset the polygons.
polygons	A table of polygons.

Returns

A table of the solution polygons, or nil on failure.

Geom.polyganize(triangles)

Arg types: triangles: mixed  |  returns table

static

Merge triangles into convex polygons.

Merges triangles into convex polygons using the Recast library. This function is meant for use as a best-effort to clean up triangles output by geometric operations.

Note

Any non-triangle polygons in the input will be discarded.

This function is highly experimental, and potentially very resource intensive. There is a possibility that the program will crash abruptly. Please use this function with great care, and make sure to constrain the inputs tightly so that users can not induce crashes.

Parameters

triangles

Either a single triangle or a table of triangles.

Returns

A table of convex polygons or nil on failure.

rotate(geom, angle)

Arg types: geom: Geom, angle: int  |  returns nothing

Rotate geom about its centroid.

Parameters

geom	- The geometry to modify. Geom can either be a point or a table of points.
angle	- The angle (clockwise, in degrees) to rotate geom.

Returns

A geometry of the same type that was passed in.

local p1 = point.new(0, 10)
local p2 = point.new(10, 10)
local p3 = point.new(10, 0)
 
local geom = {p1, p2, p3, p1}
 
local triangle = LineItem.new()
triangle:setGeom(Geom.rotate(geom, 45))
 
bf:addItem(triangle)

scale(geom, sx, sy)

Arg types: geom: Geom, sx: int, sy: int  |  returns nothing

Scale geom by sx, sy, in reference to the x- and y-axes.

If sy is omitted, geom will be scaled evenly horizontally and vertically without distortion.

Parameters

geom	- The geometry to modify. Geom can either be a point or a table of points.
sx	- The amount to scale each point in geom horizontally.
sy	- (Optional) The amount to scale each point in geom vertically. Defaults to sx.

Returns

A geometry of the same type that was passed in.

Geom.segmentsIntersect(a1, a2, b1, b2)

Arg types: a1: point, a2: point, b1: point, b2: point  |  returns bool, num

static

Finds intersection of the linesegments (a1, a2) and (b1, b2)

Determines if and "when" the line segments a and b intersect. The boolean return value is true if the segments intersect. The number return value is a "time" t along the line a corresponding to where they intersect. If the segments intersect, the first return value will true and the second return value will be in the range [0, 1]. If they do not intersect, the first return value will be false, and the second value should be discarded.

To find the actual point of intersection, just use

local ok, t = Geom.segmentsIntersect(a1, a2, b1, b2)
if ok == true then
  local intersection = a1 + (a2 - a1) * t
end

Returns

ok,t Returns true if the segments intersect, and a time t along a when the intersect.

transform(geom, tx, ty, sx, sy, angle)

Arg types: geom: Geom, tx: int, ty: int, sx: int, sy: int, angle: int  |  returns nothing

Transform geom by scaling, rotating, and translating.

Apply a full transformation to the points in geom, doing a combination of the above in a single operation. Scales, rotates, then translates. Performing these operations together is more effient than applying them individually.

Note that sy can be omitted for uniform scaling horizontally and vertically.

Parameters

geom	- The geometry to modify. Geom can either be a point or a table of points.
tx	- The amount to add to the x-coord of each point in geom.
ty	- The amount to add to the y-coord of each point in geom.
sx	- The amount to scale each point in geom horizontally.
sy	- (Optional) The amount to scale each point in geom vertically. Defaults to sx.
angle	- The angle (clockwise, in degrees) to rotate geom.

Returns

A geometry of the same type that was passed in.

translate(geom, tx, ty)

Arg types: geom: Geom, tx: int, ty: int  |  returns nothing

Translate (offset) geom by tx, ty.

Parameters

geom	- The geometry to modify. Geom can either be a point or a table of points.
tx	- The amount to add to the x-coord of each point in geom.
ty	- The amount to add to the y-coord of each point in geom.

Returns

A geometry of the same type that was passed in.

Geom.triangulate(polygons)

Arg types: polygons: mixed  |  returns table

static

Break up polygons into triangles.

Performs a Constrained Delauney Triangulation on the input. This function is meant to be used for breaking complex polygons into pieces which can then be manipulated either in the editor or through more processing.

Parameters

polygons

Either a single polygon or a table of polygons.

Returns

A table of triangles or nil on failure.