Monkune/lib/windfield/mlib

MLib

MLib is a math and shape-intersection detection library written in Lua. It's aim is to be robust and easy to use.

NOTE:

• I am (slowly) working on completely rewriting this in order to be easier to use and less bug-prone. You can check out the progress here.
• I am currently slowing development of MLib while moving over to helping with CPML. To discuss this, please comment here.

If you are looking for a library that handles updating/collision responses for you, take a look at hxdx. It uses MLib functions as well as Box2d to handle physics calculations.

Downloading

You can download the latest stable version of MLib by downloading the latest release. You can download the latest working version of MLib by downloading the latest commit. Documentation will only be updated upon releases, not upon commits.

Implementing

To use MLib, simply place mlib.lua inside the desired folder in your project. Then use the require 'path.to.mlib' to use any of the functions.

Examples

If you don't have LÖVE installed, you can download the .zip of the demo from the Executables folder and extract and run the .exe that way. You can see some examples of the code in action here. All examples are done using the awesome engine of LÖVE. To run them properly, download the .love file and install LÖVE to your computer. After that, make sure you set .love files to open with "love.exe". For more, see here.

When should I use MLib?

• If you need to know exactly where two objects intersect.
• If you need general mathematical equations to be done.
• If you need very precise details about point intersections.

When should I not use MLib?

• All of the objects in a platformer, or other game, for instance, should not be registered with MLib. Only ones that need very specific information.
• When you don't need precise information/odd shapes.

Specs

For Windows

If you run Windows and have Telescope in %USERPROFILE%\Documents\GitHub (you can also manually change the path in test.bat) you can simply run test.bat and it will display the results, and then clean up after it's finished.

Default

Alternatively, you can find the tests here. Keep in mind that you may need to change certain semantics to suit your OS. You can run them via Telescope and type the following command in the command-line of the root folder:

tsc -f specs.lua

If that does not work, you made need to put a link to Lua inside of the folder for telescope and run the following command:

lua tsc -f specs.lua

If you encounter further errors, try to run the command line as an administrator (usually located in C:\Windows\System32\), then right-click on cmd.exe and select Run as administrator, then do

cd C:\Path\to\telescope\

And then run one of the above commands. If none of those work, just take my word for it that all the tests pass and look at this picture. 

Functions

• mlib.line
  • mlib.line.checkPoint
  • mlib.line.getClosestPoint
  • mlib.line.getYIntercept
  • mlib.line.getIntersection
  • mlib.line.getLength
  • mlib.line.getMidpoint
  • mlib.line.getPerpendicularSlope
  • mlib.line.getSegmentIntersection
  • mlib.line.getSlope
• mlib.segment
  • mlib.segment.checkPoint
  • mlib.segment.getPerpendicularBisector
  • mlib.segment.getIntersection
• mlib.polygon
  • mlib.polygon.checkPoint
  • mlib.polygon.getCentroid
  • mlib.polygon.getCircleIntersection
  • mlib.polygon.getLineIntersection
  • mlib.polygon.getPolygonArea
  • mlib.polygon.getPolygonIntersection
  • mlib.polygon.getSegmentIntersection
  • mlib.polygon.getSignedPolygonArea
  • mlib.polygon.getTriangleHeight
  • mlib.polygon.isCircleInside
  • mlib.polygon.isCircleCompletelyInside
  • mlib.polygon.isPolygonInside
  • mlib.polygon.isPolygonCompletelyInside
  • mlib.polygon.isSegmentInside
  • mlib.polygon.isSegmentCompletelyInside
• mlib.circle
  • mlib.circle.checkPoint
  • mlib.circle.getArea
  • mlib.circle.getCircleIntersection
  • mlib.circle.getCircumference
  • mlib.circle.getLineIntersection
  • mlib.circle.getSegmentIntersection
  • mlib.circle.isCircleCompletelyInside
  • mlib.circle.isCircleCompletelyInsidePolygon
  • mlib.circle.isPointOnCircle
  • mlib.circle.isPolygonCompletelyInside
• mlib.statistics
  • mlib.statistics.getCentralTendency
  • mlib.statistics.getDispersion
  • mlib.statistics.getMean
  • mlib.statistics.getMedian
  • mlib.statistics.getMode
  • mlib.statistics.getRange
  • mlib.statistics.getStandardDeviation
  • mlib.statistics.getVariance
  • mlib.statistics.getVariationRatio
• mlib.math
  • mlib.math.getAngle
  • mlib.math.getPercentage
  • mlib.math.getPercentOfChange
  • mlib.math.getQuadraticRoots
  • mlib.math.getRoot
  • mlib.math.getSummation
  • mlib.math.isPrime
  • mlib.math.round
• Aliases

mlib.line

• Deals with linear aspects, such as slope and length.

mlib.line.checkPoint

• Checks if a point lies on a line.
• Synopsis:
  • onPoint = mlib.line.checkPoint( px, px, x1, y1, x2, y2 )
• Arguments:
  • px, py: Numbers. The x and y coordinates of the point being tested.
  • x1, y1, x2, y2: Numbers. Two x and y coordinates of the line being tested.
• Returns:
  • onPoint: Boolean.
    • true if the point is on the line.
    • false if it does not.
• Notes:
  • You cannot use the format mlib.line.checkPoint( px, px, slope, intercept ) because this would lead to errors on vertical lines.

mlib.line.getClosestPoint

• Gives the closest point to a line.
• Synopses:
  • cx, cy = mlib.line.getClosestPoint( px, py, x1, y1, x2, y2 )
  • cx, cy = mlib.line.getClosestPoint( px, py, slope, intercept )
• Arguments:
  • x, y: Numbers. The x and y coordinates of the point.
  • x1, y1, x2, y2: Numbers. Two x and y coordinates on the line.
  • slope, intercept:
    • Numbers. The slope and y-intercept of the line.
    • Booleans (false). The slope and y-intercept of a vertical line.
• Returns:
  • cx, cy: Numbers. The closest points that lie on the line to the point.

mlib.line.getYIntercept

• Gives y-intercept of the line.
• Synopses:
  • intercept, isVertical = mlib.line.getYIntercept( x1, y1, x2, y2 )
  • intercept, isVertical = mlib.line.getYIntercept( x1, y1, slope )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates that lie on the line.
  • slope:
    • Number. The slope of the line.
• Returns:
  • intercept:
    • Number. The y-intercept of the line.
    • Number. The x1 coordinate of the line if the line is vertical.
  • isVertical:
    • Boolean. true if the line is vertical, false if the line is not vertical.

mlib.line.getIntersection

• Gives the intersection of two lines.
• Synopses:
  • x, y = mlib.line.getIntersection( x1, y1, x2, y2, x3, y3, x4, y4 )
  • x, y = mlib.line.getIntersection( slope1, intercept1, x3, y3, x4, y4 )
  • x, y = mlib.line.getIntersection( slope1, intercept1, slope2, intercept2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates that lie on the first line.
  • x3, y3, x4, y4: Numbers. Two x and y coordinates that lie on the second line.
  • slope1, intercept1:
    • Numbers. The slope and y-intercept of the first line.
    • Booleans (false). The slope and y-intercept of the first line (if the first line is vertical).
  • slope2, intercept2:
    • Numbers. The slope and y-intercept of the second line.
    • Booleans (false). The slope and y-intercept of the second line (if the second line is vertical).
• Returns:
  • x, y:
    • Numbers. The x and y coordinate where the lines intersect.
    • Boolean:
      • true, nil: The lines are collinear.
      • false, nil: The lines are parallel and not collinear.

mlib.line.getLength

• Gives the distance between two points.
• Synopsis:
  • `length = mlib.line.getLength( x1, y1, x2, y2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
• Returns:
  • length: Number. The distance between the two points.

mlib.line.getMidpoint

• Gives the midpoint of two points.
• Synopsis:
  • x, y = mlib.line.getMidpoint( x1, y1, x2, y2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
• Returns:
  • x, y: Numbers. The midpoint x and y coordinates.

mlib.line.getPerpendicularSlope

• Gives the perpendicular slope of a line.
• Synopses:
  • perpSlope = mlib.line.getPerpendicularSlope( x1, y1, x2, y2 )
  • perpSlope = mlib.line.getPerpendicularSlope( slope )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
  • slope: Number. The slope of the line.
• Returns:
  • perpSlope:
    • Number. The perpendicular slope of the line.
    • Boolean (false). The perpendicular slope of the line (if the original line was horizontal).

mlib.line.getSegmentIntersection

• Gives the intersection of a line segment and a line.
• Synopses:
  • x1, y1, x2, y2 = mlib.line.getSegmentIntersection( x1, y1, x2, y2, x3, y3, x4, y4 )
  • x1, y1, x2, y2 = mlib.line.getSegmentIntersection( x1, y1, x2, y2, slope, intercept )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates that lie on the line segment.
  • x3, y3, x4, y4: Numbers. Two x and y coordinates that lie on the line.
  • slope, intercept:
    • Numbers. The slope and y-intercept of the the line.
    • Booleans (false). The slope and y-intercept of the line (if the line is vertical).
• Returns:
  • x1, y1, x2, y2:
    • Number, Number, Number, Number.
      • The points of the line segment if the line and segment are collinear.
    • Number, Number, Boolean (nil), Boolean (nil).
      • The coordinate of intersection if the line and segment intersect and are not collinear.
    • Boolean (false), Boolean (nil), Boolean (nil),
      • Boolean (nil). If the line and segment don't intersect.

mlib.line.getSlope

• Gives the slope of a line.
• Synopsis:
  • `slope = mlib.line.getSlope( x1, y1, x2, y2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
• Returns:
  • slope:
    • Number. The slope of the line.
    • Boolean (false). The slope of the line (if the line is vertical).

mlib.segment

• Deals with line segments.

mlib.segment.checkPoint

• Checks if a point lies on a line segment.
• Synopsis:
  • onSegment = mlib.segment.checkPoint( px, py, x1 y1, x2, y2 )
• Arguments:
  • px, py: Numbers. The x and y coordinates of the point being checked.
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
• Returns:
  • onSegment: Boolean.
    • true if the point lies on the line segment.
    • false if the point does not lie on the line segment.

mlib.segment.getPerpendicularBisector

• Gives the perpendicular bisector of a line.
• Synopsis:
  • x, y, slope = mlib.segment.getPerpendicularBisector( x1, y1, x2, y2 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
• Returns:
  • x, y: Numbers. The midpoint of the line.
  • slope:
    • Number. The perpendicular slope of the line.
    • Boolean (false). The perpendicular slope of the line (if the original line was horizontal).

mlib.segment.getIntersection

• Checks if two line segments intersect.
• Synopsis:
  • cx1, cy1, cx2, cy2 = mlib.segment.getIntersection( x1, y1, x2, y2, x3, y3 x4, y4 )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates of the first line segment.
  • x3, y3, x4, y4: Numbers. Two x and y coordinates of the second line segment.
• Returns:
  • cx1, cy1, cx2, cy2:
    • Number, Number, Number, Number.
      • The points of the resulting intersection if the line segments are collinear.
    • Number, Number, Boolean (nil), Boolean (nil).
      • The point of the resulting intersection if the line segments are not collinear.
    • Boolean (false), Boolean (nil), Boolean (nil) , Boolean (nil).
      • If the line segments don't intersect.

mlib.polygon

• Handles aspects involving polygons.

mlib.polygon.checkPoint

• Checks if a point is inside of a polygon.
• Synopses:
  • inPolygon = mlib.polygon.checkPoint( px, py, vertices )
  • inPolygon = mlib.polygon.checkPoint( px, py, ... )
• Arguments:
  • px, py: Numbers. The x and y coordinate of the point being checked.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • inPolygon: Boolean.
    • true if the point is inside the polygon.
    • false if the point is not inside the polygon.

mlib.polygon.getCentroid

• Returns the centroid of the polygon.
• Synopses:
  • cx, cy = mlib.polygon.getCentroid( vertices )
  • cx, cy = mlib.polygon.getCentroid( ... )
• Arguments:
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • cx, cy: Numbers. The x and y coordinates of the centroid.

mlib.polygon.getCircleIntersection

• Returns the coordinates of where a circle intersects a polygon.
• Synopses:
  • intersections = mlib.polygon.getCircleIntersection( cx, cy, radius, vertices )
  • `intersections = mlib.polygon.getCircleIntersection( cx, cy, radius, ... )
• Arguments:
  • cx, cy: Number. The coordinates of the center of the circle.
  • radius: Number. The radius of the circle.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • intersections: Table. Contains the intersections and type.
• Example:

local tab = _.polygon.getCircleIntersection( 5, 5, 1, 4, 4, 6, 4, 6, 6, 4, 6 )
for i = 1, # tab do
	print( i .. ':', unpack( tab[i] ) )
end
-- 1: 	tangent		5		4
-- 2: 	tangent		6 		5
-- 3: 	tangent 	5		6
-- 4: 	tagnent 	4		5

• For more see mlib.circle.getSegmentIntersection or the [specs](spec.lua# L676)

mlib.polygon.getLineIntersection

• Returns the coordinates of where a line intersects a polygon.
• Synopses:
  • intersections = mlib.polygon.getLineIntersection( x1, y1, x2, y2, vertices )
  • `intersections = mlib.polygon.getLineIntersection( x1, y1, x2, y2, ... )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • intersections: Table. Contains the intersections.
• Notes:
  • With collinear lines, they are actually broken up. i.e. { 0, 4, 0, 0 } would become { 0, 4 }, { 0, 0 }.

mlib.polygon.getPolygonArea

• Gives the area of a polygon.
• Synopses:
  • area = mlib.polygon.getArea( vertices )
  • `area = mlib.polygon.getArea( ... )
• Arguments:
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • area: Number. The area of the polygon.

mlib.polygon.getPolygonIntersection

• Gives the intersection of two polygons.
• Synopsis:
  • intersections = mlib.polygon.getPolygonIntersections( polygon1, polygon2 )
• Arguments:
  • polygon1: Table. The vertices of the first polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • polygon2: Table. The vertices of the second polygon in the format { x1, y1, x2, y2, x3, y3, ... }
• Returns:
  • intersections: Table. A table of the points of intersection.

mlib.polygon.getSegmentIntersection

• Returns the coordinates of where a line segmeing intersects a polygon.
• Synopses:
  • intersections = mlib.polygon.getSegmentIntersection( x1, y1, x2, y2, vertices )
  • `intersections = mlib.polygon.getSegmentIntersection( x1, y1, x2, y2, ... )
• Arguments:
  • x1, y1, x2, y2: Numbers. Two x and y coordinates.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • intersections: Table. Contains the intersections.
• Notes:
  • With collinear line segments, they are not broken up. See the [specs](spec.lua# L508) for more.

mlib.polygon.getSignedPolygonArea

• Gets the signed area of the polygon. If the points are ordered counter-clockwise the area is positive. If the points are ordered clockwise the number is negative.
• Synopses:
  • area = mlib.polygon.getLineIntersection( vertices )
  • `area = mlib.polygon.getLineIntersection( ... )
• Arguments:
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • area: Number. The signed area of the polygon. If the points are ordered counter-clockwise the area is positive. If the points are ordered clockwise the number is negative.

mlib.polygon.getTriangleHeight

• Gives the height of a triangle.
• Synopses:
  • height = mlib.polygon.getTriangleHeigh( base, x1, y1, x2, y2, x3, y3 )
  • height = mlib.polygon.getTriangleHeight( base, area )
• Arguments:
  • base: Number. The length of the base of the triangle.
  • x1, y1, x2, y2, x3, y3: Numbers. The x and y coordinates of the triangle.
  • area: Number. The regular area of the triangle. Not the signed area.
• Returns:
  • height: Number. The height of the triangle.

mlib.polygon.isCircleInside

• Checks if a circle is inside the polygon.
• Synopses:
  • inPolygon = mlib.polygon.isCircleInside( cx, cy, radius, vertices )
  • inPolygon = mlib.polygon.isCircleInside( cx, cy, radius, ... )
• Arguments:
  • cx, cy: Numbers. The x and y coordinates for the center of the circle.
  • radius: Number. The radius of the circle.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • inPolygon: Boolean.
    • true if the circle is inside the polygon.
    • false if the circle is not inside the polygon.
• Notes:
  • Only returns true if the center of the circle is inside the circle.

mlib.polygon.isCircleCompletelyInside

• Checks if a circle is completely inside the polygon.
• Synopses:
  • inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, vertices )
  • inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, ... )
• Arguments:
  • cx, cy: Numbers. The x and y coordinates for the center of the circle.
  • radius: Number. The radius of the circle.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • inPolygon: Boolean.
    • true if the circle is completely inside the polygon.
    • false if the circle is not inside the polygon.

mlib.polygon.isPolygonInside

• Checks if a polygon is inside a polygon.
• Synopsis:
  • inPolygon = mlib.polygon.isPolygonInside( polygon1, polygon2 )
• Arguments:
  • polygon1: Table. The vertices of the first polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • polygon2: Table. The vertices of the second polygon in the format { x1, y1, x2, y2, x3, y3, ... }
• Returns:
  • inPolygon: Boolean.
    • true if the polygon2 is inside of polygon1.
    • false if polygon2 is not inside of polygon2.
• Notes:
  • Returns true as long as any of the line segments of polygon2 are inside of the polygon1.

mlib.polygon.isPolygonCompletelyInside

• Checks if a polygon is completely inside a polygon.
• Synopsis:
  • inPolygon = mlib.polygon.isPolygonCompletelyInside( polygon1, polygon2 )
• Arguments:
  • polygon1: Table. The vertices of the first polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • polygon2: Table. The vertices of the second polygon in the format { x1, y1, x2, y2, x3, y3, ... }
• Returns:
  • inPolygon: Boolean.
    • true if the polygon2 is completely inside of polygon1.
    • false if polygon2 is not inside of polygon2.

mlib.polygon.isSegmentInside

• Checks if a line segment is inside a polygon.
• Synopses:
  • inPolygon = mlib.polygon.isSegmentInside( x1, y1, x2, y2, vertices )
  • inPolygon = mlib.polygon.isSegmentInside( x1, y1, x2, y2, ... )
• Arguments:
  • x1, y1, x2, y2: Numbers. The x and y coordinates of the line segment.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • inPolygon: Boolean.
    • true if the line segment is inside the polygon.
    • false if the line segment is not inside the polygon.
• Note:
  • Only one of the points has to be in the polygon to be considered 'inside' of the polygon.
  • This is really just a faster version of mlib.polygon.getPolygonIntersection that does not give the points of intersection.

mlib.polygon.isSegmentCompletelyInside

• Checks if a line segment is completely inside a polygon.
• Synopses:
  • inPolygon = mlib.polygon.isSegmentCompletelyInside( x1, y1, x2, y2, vertices )
  • inPolygon = mlib.polygon.isSegmentCompletelyInside( x1, y1, x2, y2, ... )
• Arguments:
  • x1, y1, x2, y2: Numbers. The x and y coordinates of the line segment.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • inPolygon: Boolean.
    • true if the line segment is completely inside the polygon.
    • false if the line segment is not inside the polygon.

mlib.circle

• Handles aspects involving circles.

mlib.circle.checkPoint

• Checks if a point is on the inside or on the edge the circle.
• Synopsis:
  • inCircle = mlib.circle.checkPoint( px, px, cx, cy, radius )
• Arguments:
  • px, py: Numbers. The x and y coordinates of the point being tested.
  • cx, cy: Numbers. The x and y coordinates of the center of the circle.
  • radius: Number. The radius of the circle.
• Returns:
  • inCircle: Boolean.
    • true if the point is inside or on the circle.
    • false if the point is outside of the circle.

mlib.circle.getArea

• Gives the area of a circle.
• Synopsis:
  • area = mlib.circle.getArea( radius )
• Arguments:
  • radius: Number. The radius of the circle.
• Returns:
  • area: Number. The area of the circle.

mlib.circle.getCircleIntersection

• Gives the intersections of two circles.
• Synopsis:
  • `intersections = mlib.circle.getCircleIntersection( c1x, c1y, radius1, c2x, c2y, radius2 )
• Arguments:
  • c1x, c1y: Numbers. The x and y coordinate of the first circle.
  • radius1: Number. The radius of the first circle.
  • c2x, c2y: Numbers. The x and y coordinate of the second circle.
  • radius2: Number. The radius of the second circle.
• Returns:
  • intersections: Table. A table that contains the type and where the circle collides. See the [specs](spec.lua# L698) for more.

mlib.circle.getCircumference

• Returns the circumference of a circle.
• Synopsis:
  • circumference = mlib.circle.getCircumference( radius )
• Arguments:
  • radius: Number. The radius of the circle.
• Returns:
  • circumference: Number. The circumference of a circle.

mlib.circle.getLineIntersection

• Returns the intersections of a circle and a line.
• Synopsis:
  • intersections = mlib.circle.getLineIntersections( cx, cy, radius, x1, y1, x2, y2 )
• Arguments:
  • cx, cy: Numbers. The x and y coordinates for the center of the circle.
  • radius: Number. The radius of the circle.
  • x1, y1, x2, y2: Numbers. Two x and y coordinates the lie on the line.
• Returns:
  • intersections: Table. A table with the type and where the intersections happened. Table is formatted:
    • type, x1, y1, x2, y2
      • String ('secant'), Number, Number, Number, Number
        • The numbers are the x and y coordinates where the line intersects the circle.
      • String ('tangent'), Number, Number, Boolean (nil), Boolean (nil)
        • x1 and x2 represent where the line intersects the circle.
      • Boolean (false), Boolean (nil), Boolean (nil), Boolean (nil), Boolean (nil)
        • No intersection.
    • For more see the [specs](spec.lua# L660).

mlib.circle.getSegmentIntersection

• Returns the intersections of a circle and a line segment.
• Synopsis:
  • intersections = mlib.circle.getSegmentIntersections( cx, cy, radius, x1, y1, x2, y2 )
• Arguments:
  • cx, cy: Numbers. The x and y coordinates for the center of the circle.
  • radius: Number. The radius of the circle.
  • x1, y1, x2, y2: Numbers. The two x and y coordinates of the line segment.
• Returns:
  • intersections: Table. A table with the type and where the intersections happened. Table is formatted:
    • type, x1, y1, x2, y2
      • String ('chord'), Number, Number, Number, Number
        • The numbers are the x and y coordinates where the line segment is on both edges of the circle.
      • String ('enclosed'), Number, Number, Number, Number
        • The numbers are the x and y coordinates of the line segment if it is fully inside of the circle.
      • String ('secant'), Number, Number, Number, Number
        • The numbers are the x and y coordinates where the line segment intersects the circle.
      • String ('tangent'), Number, Number, Boolean (nil), Boolean (nil)
        • x1 and x2 represent where the line segment intersects the circle.
      • Boolean (false), Boolean (nil), Boolean (nil), Boolean (nil), Boolean (nil)
        • No intersection.
    • For more see the [specs](spec.lua# L676).

mlib.circle.isCircleCompletelyInside

• Checks if one circle is completely inside of another circle.
• Synopsis:
  • completelyInside = mlib.circle.isCircleCompletelyInside( c1x, c1y, c1radius, c2x, c2y, c2radius )
• Arguments:
  • c1x, c1y: Numbers. The x and y coordinates of the first circle.
  • c1radius: Number. The radius of the first circle.
  • c2x, c2y: Numbers. The x and y coordinates of the second circle.
  • c2radius: Number. The radius of the second circle.
• Returns:
  • completelyInside: Boolean.
    • true if circle1 is inside of circle2.
    • false if circle1 is not completely inside of circle2.

mlib.circle.isCircleCompletelyInsidePolygon

• Checks if a circle is completely inside the polygon.
• Synopses:
  • inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, vertices )
  • inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, ... )
• Arguments:
  • cx, cy: Numbers. The x and y coordinates for the center of the circle.
  • radius: Number. The radius of the circle.
  • vertices: Table. The vertices of the polygon in the format { x1, y1, x2, y2, x3, y3, ... }
  • ...: Numbers. The x and y coordinates of the polygon. (Same as using unpack( vertices ))
• Returns:
  • inPolygon: Boolean.
    • true if the circle is completely inside the polygon.
    • false if the circle is not inside the polygon.

mlib.circle.isPointOnCircle

• Checks if a point is exactly on the edge of the circle.
• Synopsis:
  • onCircle = mlib.circle.checkPoint( px, px, cx, cy, radius )
• Arguments:
  • px, py: Numbers. The x and y coordinates of the point being tested.
  • cx, cy: Numbers. The x and y coordinates of the center of the circle.
  • radius: Number. The radius of the circle.
• Returns:
  • onCircle: Boolean.
    • true if the point is on the circle.
    • false if the point is on the inside or outside of the circle.
• Notes:
  • Will return false if the point is inside or outside of the circle.

mlib.circle.isPolygonCompletelyInside

• Checks if a polygon is completely inside of a circle.
• Synopsis:
  • completelyInside = mlib.circle.isPolygonCompletelyInside( circleX, circleY, circleRadius, vertices )
  • completelyInside = mlib.circle.isPolygonCompletelyInside( circleX, circleY, circleRadius, ... )
• Arguments:
  • circleX, circleY: Numbers. The x and y coordinates of the circle.
  • circleRadius: Number. The radius of the circle.
  • vertices: Table. A table containing all of the vertices of the polygon.
  • ...: Numbers. All of the points of the polygon.
• Returns:
  • completelyInside: Boolean.
    • true if the polygon is inside of the circle.
    • false if the polygon is not completely inside of the circle.

mlib.statistics

• Handles statistical aspects of math.

mlib.statistics.getCentralTendency

• Gets the central tendency of the data.
• Synopses:
  • modes, occurrences, median, mean = mlib.statistics.getCentralTendency( data )
  • modes, occurrences, median, mean = mlib.statistics.getCentralTendency( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • modes, occurrences: Table, Number. The modes of the data and the number of times it occurs. See mlib.statistics.getMode.
  • median: Number. The median of the data set.
  • mean: Number. The mean of the data set.

mlib.statistics.getDispersion

• Gets the dispersion of the data.
• Synopses:
  • variationRatio, range, standardDeviation = mlib.statistics.getDispersion( data )
  • variationRatio, range, standardDeviation = mlib.statistics.getDispersion( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • variationRatio: Number. The variation ratio of the data set.
  • range: Number. The range of the data set.
  • standardDeviation: Number. The standard deviation of the data set.

mlib.statistics.getMean

• Gets the arithmetic mean of the data.
• Synopses:
  • mean = mlib.statistics.getMean( data )
  • mean = mlib.statistics.getMean( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • mean: Number. The arithmetic mean of the data set.

mlib.statistics.getMedian

• Gets the median of the data set.
• Synopses:
  • median = mlib.statistics.getMedian( data )
  • median = mlib.statistics.getMedian( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • median: Number. The median of the data.

mlib.statistics.getMode

• Gets the mode of the data set.
• Synopses:
  • mode, occurrences = mlib.statistics.getMode( data )
  • mode, occurrences = mlib.statistics.getMode( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • mode: Table. The mode(s) of the data.
  • occurrences: Number. The number of time the mode(s) occur.

mlib.statistics.getRange

• Gets the range of the data set.
• Synopses:
  • range = mlib.statistics.getRange( data )
  • range = mlib.statistics.getRange( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • range: Number. The range of the data.

mlib.statistics.getStandardDeviation

• Gets the standard deviation of the data.
• Synopses:
  • standardDeviation = mlib.statistics.getStandardDeviation( data )
  • standardDeviation = mlib.statistics.getStandardDeviation( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • standardDeviation: Number. The standard deviation of the data set.

mlib.statistics.getVariance

• Gets the variation of the data.
• Synopses:
  • variance = mlib.statistics.getVariance( data )
  • variance = mlib.statistics.getVariance( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • variance: Number. The variation of the data set.

mlib.statistics.getVariationRatio

• Gets the variation ratio of the data.
• Synopses:
  • variationRatio = mlib.statistics.getVariationRatio( data )
  • variationRatio = mlib.statistics.getVariationRatio( ... )
• Arguments:
  • data: Table. A table containing the values of data.
  • ...: Numbers. All of the numbers in the data set.
• Returns:
  • variationRatio: Number. The variation ratio of the data set.

mlib.math

• Miscellaneous functions that have no home.

mlib.math.getAngle

• Gets the angle between three points.
• Synopsis:
  • angle = mlib.math.getAngle( x1, y1, x2, y2, x3, y3 )
• Arguments:
  • x1, y1: Numbers. The x and y coordinates of the first point.
  • x2, y2: Numbers. The x and y coordinates of the vertex of the two points.
  • x3, y3: Numbers. The x and y coordinates of the second point.

mlib.math.getPercentage

• Gets the percentage of a number.
• Synopsis:
  • percentage = mlib.math.getPercentage( percent, number )
• Arguments:
  • percent: Number. The decimal value of the percent (i.e. 100% is 1, 50% is .5).
  • number: Number. The number to get the percentage of.
• Returns:
  • percentage: Number. The percentage or number.

mlib.math.getPercentOfChange

• Gets the percent of change from one to another.
• Synopsis:
  • change = mlib.math.getPercentOfChange( old, new )
• Arguments:
  • old: Number. The original number.
  • new: Number. The new number.
• Returns:
  • change: Number. The percent of change from old to new.

mlib.math.getQuadraticRoots

• Gets the quadratic roots of the the equation.
• Synopsis:
  • root1, root2 = mlib.math.getQuadraticRoots( a, b, c )
• Arguments:
  • a, b, c: Numbers. The a, b, and c values of the equation a * x ^ 2 + b * x ^ 2 + c.
• Returns:
  • root1, root2: Numbers. The roots of the equation (where a * x ^ 2 + b * x ^ 2 + c = 0).

mlib.math.getRoot

• Gets the nth root of a number.
• Synopsis:
  • x = mlib.math.getRoot( number, root )
• Arguments:
  • number: Number. The number to get the root of.
  • root: Number. The root.
• Returns:
  • x: The rootth root of number.
• Example:

local a = mlib.math.getRoot( 4, 2 ) -- Same as saying 'math.pow( 4, .5 )' or 'math.sqrt( 4 )' in this case.
local b = mlib.math.getRoot( 27, 3 )

print( a, b ) --> 2, 3

• For more, see the [specs](spec.lua# L860).

mlib.math.getSummation

• Gets the summation of numbers.
• Synopsis:
  • summation = mlib.math.getSummation( start, stop, func )
• Arguments:
  • start: Number. The number at which to start the summation.
  • stop: Number. The number at which to stop the summation.
  • func: Function. The method to add the numbers.
    • Arguments:
      • i: Number. Index.
      • previous: Table. The previous values used.
• Returns:
  • Summation: Number. The summation of the numbers.
  • For more, see the [specs](spec.lua# L897).

mlib.math.isPrime

• Checks if a number is prime.
• Synopsis:
  • isPrime = mlib.math.isPrime( x )
• Arguments:
  • x: Number. The number to check if it's prime.
• Returns:
  • isPrime: Boolean.
    • true if the number is prime.
    • false if the number is not prime.

mlib.math.round

• Rounds a number to the given decimal place.
• Synopsis:
  • `rounded = mlib.math.round( number, [place] )
• Arguments:
  • number: Number. The number to round.
  • place (1): Number. The decimal place to round to. Defaults to 1.
• Returns:
  • The rounded number.
  • For more, see the [specs](spec.lua# L881).

Aliases

Alias	Corresponding Function
milb.line.getDistance	mlib.line.getLength
mlib.line.getCircleIntersection	mlib.circle.getLineIntersection
milb.line.getPolygonIntersection	mlib.polygon.getLineIntersection
mlib.line.getLineIntersection	mlib.line.getIntersection
mlib.segment.getCircleIntersection	mlib.circle.getSegmentIntersection
milb.segment.getPolygonIntersection	mlib.pollygon.getSegmentIntersection
mlib.segment.getLineIntersection	mlib.line.getSegmentIntersection
mlib.segment.getSegmentIntersection	mlib.segment.getIntersection
milb.segment.isSegmentCompletelyInsideCircle	mlib.circle.isSegmentCompletelyInside
mlib.segment.isSegmentCompletelyInsidePolygon	mlib.polygon.isSegmentCompletelyInside
mlib.circle.getPolygonIntersection	mlib.polygon.getCircleIntersection
mlib.circle.isCircleInsidePolygon	mlib.polygon.isCircleInside
mlib.circle.isCircleCompletelyInsidePolygon	mlib.polygon.isCircleCompletelyInside
mlib.polygon.isCircleCompletelyOver	mlib.circleisPolygonCompletelyInside

License

A math library made in Lua copyright (C) 2014 Davis Claiborne This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Contact me at davisclaib at gmail.com