jadedctrl/ Monkune
1
0
Disbranĉigi 0
Fontkodo Issues Tirpetoj 1 Actions Packages Projects Eldonoj Wiki Activity
Monkune/lib/windfield/mlib/README.md

891 lines
41 KiB
Markdown
Raw Permalink Normal View History

Init
2021-01-07 01:29:06 -06:00
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](../../tree/dev).
- I am currently slowing development of MLib while moving over to helping with [CPML](https://github.com/excessive/cpml). To discuss this, please comment [here](../../issues/12).
If you are looking for a library that handles updating/collision responses for you, take a look at [hxdx](https://github.com/adonaac/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](../../releases/).
You can download the latest __working__ version of MLib by downloading the latest [commit](../../commits/master/). Documentation will __only__ be updated upon releases, not upon commits.
## Implementing
To use MLib, simply place [mlib.lua](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](https://love2d.org/) installed, you can download the .zip of the demo from the [Executables](Examples/Executables) folder and extract and run the .exe that way.
You can see some examples of the code in action [here](Examples).
All examples are done using the *awesome* engine of [LÖVE](https://love2d.org/).
To run them properly, download the [.love file](Examples/LOVE) and install LÖVE to your computer.
After that, make sure you set .love files to open with "love.exe".
For more, see [here](https://love2d.org/).
## 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](test.bat)) you can simply run [test.bat](test.bat) and it will display the results, and then clean up after it's finished.
#### Default
Alternatively, you can find the tests [here](spec.lua). Keep in mind that you may need to change certain semantics to suit your OS.
You can run them via [Telescope](https://github.com/norman/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.
![Success](Reference Pictures/Success.png)
## Functions
- [mlib.line](#mlibline)
- [mlib.line.checkPoint](#mliblinecheckpoint)
- [mlib.line.getClosestPoint](#mliblinegetclosestpoint)
- [mlib.line.getYIntercept](#mliblinegetintercept)
- [mlib.line.getIntersection](#mliblinegetintersection)
- [mlib.line.getLength](#mliblinegetlength)
- [mlib.line.getMidpoint](#mliblinegetmidpoint)
- [mlib.line.getPerpendicularSlope](#mliblinegetperpendicularslope)
- [mlib.line.getSegmentIntersection](#mliblinegetsegmentintersection)
- [mlib.line.getSlope](#mliblinegetslope)
- [mlib.segment](#mlibsegment)
- [mlib.segment.checkPoint](#mlibsegmentcheckpoint)
- [mlib.segment.getPerpendicularBisector](#mlibsegmentgetperpendicularbisector)
- [mlib.segment.getIntersection](#mlibsegmentgetintersection)
- [mlib.polygon](#mlibpolygon)
- [mlib.polygon.checkPoint](#mlibpolygoncheckpoint)
- [mlib.polygon.getCentroid](#mlibpolygongetcentroid)
- [mlib.polygon.getCircleIntersection](#mlibpolygongetcircleintersection)
- [mlib.polygon.getLineIntersection](#mlibpolygongetlineintersection)
- [mlib.polygon.getPolygonArea](#mlibpolygongetpolygonarea)
- [mlib.polygon.getPolygonIntersection](#mlibpolygongetpolygonintersection)
- [mlib.polygon.getSegmentIntersection](#mlibpolygongetsegmentintersection)
- [mlib.polygon.getSignedPolygonArea](#mlibpolygongetsignedpolygonarea)
- [mlib.polygon.getTriangleHeight](#mlibpolygongettriangleheight)
- [mlib.polygon.isCircleInside](#mlibpolygoniscircleinside)
- [mlib.polygon.isCircleCompletelyInside](#mlibpolygoniscirclecompletelyinside)
- [mlib.polygon.isPolygonInside](#mlibpolygonispolygoninside)
- [mlib.polygon.isPolygonCompletelyInside](#mlibpolygonispolygoncompletelyinside)
- [mlib.polygon.isSegmentInside](#mlibpolygonissegmentinside)
- [mlib.polygon.isSegmentCompletelyInside](#mlibpolygonissegmentcompletelyinside)
- [mlib.circle](#mlibcircle)
- [mlib.circle.checkPoint](#mlibcirclecheckpoint)
- [mlib.circle.getArea](#mlibcirclegetarea)
- [mlib.circle.getCircleIntersection](#mlibcirclegetcircleintersection)
- [mlib.circle.getCircumference](#mlibcirclegetcircumference)
- [mlib.circle.getLineIntersection](#mlibcirclegetlineintersection)
- [mlib.circle.getSegmentIntersection](#mlibcirclegetsegmentintersection)
- [mlib.circle.isCircleCompletelyInside](#mlibcircleiscirclecompletelyinside)
- [mlib.circle.isCircleCompletelyInsidePolygon](#mlibcircleiscirclecompletelyinsidepolygon)
- [mlib.circle.isPointOnCircle](#mlibcircleispointoncircle)
- [mlib.circle.isPolygonCompletelyInside](#mlibcircleispolygoncompletelyinside)
- [mlib.statistics](#mlibstatistics)
- [mlib.statistics.getCentralTendency](#mlibstatisticsgetcentraltendency)
- [mlib.statistics.getDispersion](#mlibstatisticsgetdispersion)
- [mlib.statistics.getMean](#mlibstatisticsgetmean)
- [mlib.statistics.getMedian](#mlibstatisticsgetmedian)
- [mlib.statistics.getMode](#mlibstatisticsgetmode)
- [mlib.statistics.getRange](#mlibstatisticsgetrange)
- [mlib.statistics.getStandardDeviation](#mlibstatisticsgetstandarddeviation)
- [mlib.statistics.getVariance](#mlibstatisticsgetvariance)
- [mlib.statistics.getVariationRatio](#mlibstatisticsgetvariationratio)
- [mlib.math](#mlibmath)
- [mlib.math.getAngle](#mlibmathgetangle)
- [mlib.math.getPercentage](#mlibmathgetpercentage)
- [mlib.math.getPercentOfChange](#mlibmathgetpercentofchange)
- [mlib.math.getQuadraticRoots](#mlibmathgetquadraticroots)
- [mlib.math.getRoot](#mlibmathgetroot)
- [mlib.math.getSummation](#mlibmathgetsummation)
- [mlib.math.isPrime](#mlibmathisprime)
- [mlib.math.round](#mlibmathround)
- [Aliases](#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:
```lua
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](#mlibcirclegetsegmentintersection) 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](#mlibpolygongetpolygonintersection) 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](#mlibstatisticsgetmode).
- `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 `percent`age 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 `n`th 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 `root`th root of `number`.
- Example:
```lua
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](#mliblinegetlength) |
| mlib.line.getCircleIntersection | [mlib.circle.getLineIntersection](#mlibcirclegetlineintersection) |
| milb.line.getPolygonIntersection | [mlib.polygon.getLineIntersection](#mlibpolygongetlineintersection) |
| mlib.line.getLineIntersection | [mlib.line.getIntersection](#mliblinegetintersection) |
| mlib.segment.getCircleIntersection | [mlib.circle.getSegmentIntersection](#mlibcirclegetsegmentintersection) |
| milb.segment.getPolygonIntersection | [mlib.pollygon.getSegmentIntersection](#mlibpollygongetsegmentintersection) |
| mlib.segment.getLineIntersection | [mlib.line.getSegmentIntersection](#mliblinegetsegmentintersection) |
| mlib.segment.getSegmentIntersection | [mlib.segment.getIntersection](#mlibsegmentgetintersection) |
| milb.segment.isSegmentCompletelyInsideCircle | [mlib.circle.isSegmentCompletelyInside](#mlibcircleissegmentcompletelyinside) |
| mlib.segment.isSegmentCompletelyInsidePolygon | [mlib.polygon.isSegmentCompletelyInside](#mlibpolygonissegmentcompletelyinside) |
| mlib.circle.getPolygonIntersection | [mlib.polygon.getCircleIntersection](#mlibpolygongetcircleintersection) |
| mlib.circle.isCircleInsidePolygon | [mlib.polygon.isCircleInside](#mlibpolygoniscircleinside) |
| mlib.circle.isCircleCompletelyInsidePolygon | [mlib.polygon.isCircleCompletelyInside](#mlibpolygoniscirclecompletelyinside) |
| mlib.polygon.isCircleCompletelyOver | [mlib.circleisPolygonCompletelyInside](#mlibcircleispolygoncompletelyinside) |
## 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