mightyscape-1.1-deprecated/api.md at 7c536aa80bbfd6bc21145c49c1154858cbda2bdb

Archived

This repository has been archived on 2023-03-25. You can view files and clone it, but cannot push or open issues or pull requests.

38 KiB

Raw Blame History

Classes

CAG
CSG
Path2D
Polygon
Vector2D
Vector3D

Constants

defaultResolution2D: Number of polygons per 360 degree revolution for 2D objects.
defaultResolution3D: Number of polygons per 360 degree revolution for 3D objects.
EPS: Epsilon used during determination of near zero distances.
angleEPS: Epsilon used during determination of near zero areas.
areaEPS: Epsilon used during determination of near zero areas. This is the minimal area of a minimal polygon.

Functions

fromObject(obj) ⇒ CAG: Reconstruct a CAG from an object with identical property names.
fromPointsNoCheck(points) ⇒ CAG: Construct a CAG from a list of points (a polygon). Like fromPoints() but does not check if the result is a valid polygon. The points MUST rotate counter clockwise. The points can define a convex or a concave polygon. The polygon must not self intersect.
fromPath2(Path2) ⇒ CAG: Construct a CAG from a 2d-path (a closed sequence of points). Like fromPoints() but does not check if the result is a valid polygon.
fromSlices(options) ⇒ CSG: Construct a CSG solid from a list of pre-generated slices. See Polygon.prototype.solidFromSlices() for details.
fromObject(obj) ⇒ CSG: Reconstruct a CSG solid from an object with identical property names.
fromCompactBinary(bin) ⇒ CSG: Reconstruct a CSG from the output of toCompactBinary().
Line2D(normal) ⇒ Line2D: class Line2D Represents a directional line in 2D space A line is parametrized by its normal vector (perpendicular to the line, rotated 90 degrees counter clockwise) and w. The line passes through the point .times(w). Equation: p is on line if normal.dot(p)==w
circle([options]) ⇒ CAG: Construct a circle.
ellipse([options]) ⇒ CAG: Construct an ellispe.
rectangle([options]) ⇒ CAG: Construct a rectangle.
roundedRectangle([options]) ⇒ CAG: Construct a rounded rectangle.
cube([options]) ⇒ CSG: Construct an axis-aligned solid cuboid.
sphere([options]) ⇒ CSG: Construct a solid sphere
cylinder([options]) ⇒ CSG: Construct a solid cylinder.
roundedCylinder([options]) ⇒ CSG: Construct a cylinder with rounded ends.
cylinderElliptic([options]) ⇒ CSG: Construct an elliptic cylinder.
roundedCube([options]) ⇒ CSG: Construct an axis-aligned solid rounded cuboid.
polyhedron([options]) ⇒ CSG: Create a polyhedron using Openscad style arguments. Define face vertices clockwise looking from outside.

CAG

Kind: global class

CAG
- new CAG()
- instance
  - .toPoints() ⇒ Array.<points>
  - .rotateExtrude(options) ⇒ CSG
  - .toCompactBinary() ⇒ CompactBinary
- static
  - .fromSides(sides) ⇒ CAG
  - .fromPoints(points) ⇒ CAG
  - .fromCompactBinary(bin) ⇒ CAG

new CAG()

Class CAG Holds a solid area geometry like CSG but 2D. Each area consists of a number of sides. Each side is a line between 2 points.

caG.toPoints() ⇒ `Array.<points>`

Convert to a list of points.

Kind: instance method of CAG
Returns: Array.<points> - list of points in 2D space

caG.rotateExtrude(options) ⇒ `CSG`

Extrude to into a 3D solid by rotating the origin around the Y axis. (and turning everything into XY plane)

Kind: instance method of CAG
Returns: CSG - new 3D solid

Param	Type	Default	Description
options	`Object`		options for construction
[options.angle]	`Number`	`360`	angle of rotation
[options.resolution]	`Number`	`defaultResolution3D`	number of polygons per 360 degree revolution

caG.toCompactBinary() ⇒ `CompactBinary`

Convert to compact binary form. See CAG.fromCompactBinary.

Kind: instance method of CAG

CAG.fromSides(sides) ⇒ `CAG`

Construct a CAG from a list of Side instances.

Kind: static method of CAG
Returns: CAG - new CAG object

Param	Type	Description
sides	`Array.<Side>`	list of sides

CAG.fromPoints(points) ⇒ `CAG`

Construct a CAG from a list of points (a polygon). The rotation direction of the points is not relevant. The points can define a convex or a concave polygon. The polygon must not self intersect.

Kind: static method of CAG
Returns: CAG - new CAG object

Param	Type	Description
points	`Array.<points>`	list of points in 2D space

CAG.fromCompactBinary(bin) ⇒ `CAG`

Reconstruct a CAG from the output of toCompactBinary().

Kind: static method of CAG
Returns: CAG - new CAG object

Param	Type	Description
bin	`CompactBinary`	see toCompactBinary()

CSG

Kind: global class

CSG
- new CSG()
- instance
  - .toPolygons() ⇒ Array.<Polygon>
  - .union(csg) ⇒ CSG
  - .subtract(csg) ⇒ CSG
  - .intersect(csg) ⇒ CSG
  - .invert() ⇒ CSG
  - .transform(matrix4x4) ⇒ CSG
  - .getBounds() ⇒ Array.<Vector3D>
  - .getFeatures(features) ⇒ Array.<Float>
- static
  - .fromPolygons(polygons) ⇒ CSG

new CSG()

Class CSG Holds a binary space partition tree representing a 3D solid. Two solids can be combined using the union(), subtract(), and intersect() methods.

csG.toPolygons() ⇒ `Array.<Polygon>`

Kind: instance method of CSG
Returns: Array.<Polygon> - The list of polygons.

csG.union(csg) ⇒ `CSG`

Return a new CSG solid representing the space in either this solid or in the given solids. Neither this solid nor the given solids are modified.

Kind: instance method of CSG
Returns: CSG - new CSG object

Param	Type	Description
csg	`Array.<CSG>`	list of CSG objects

Example

let C = A.union(B)

Example

+-------+            +-------+
|       |            |       |
|   A   |            |       |
|    +--+----+   =   |       +----+
+----+--+    |       +----+       |
     |   B   |            |       |
     |       |            |       |
     +-------+            +-------+

csG.subtract(csg) ⇒ `CSG`

Return a new CSG solid representing space in this solid but not in the given solids. Neither this solid nor the given solids are modified.

Kind: instance method of CSG
Returns: CSG - new CSG object

Param	Type	Description
csg	`Array.<CSG>`	list of CSG objects

Example

let C = A.subtract(B)

Example

+-------+            +-------+
|       |            |       |
|   A   |            |       |
|    +--+----+   =   |    +--+
+----+--+    |       +----+
     |   B   |
     |       |
     +-------+

csG.intersect(csg) ⇒ `CSG`

Return a new CSG solid representing space in both this solid and in the given solids. Neither this solid nor the given solids are modified.

Kind: instance method of CSG
Returns: CSG - new CSG object

Param	Type	Description
csg	`Array.<CSG>`	list of CSG objects

Example

let C = A.intersect(B)

Example

+-------+
|       |
|   A   |
|    +--+----+   =   +--+
+----+--+    |       +--+
     |   B   |
     |       |
     +-------+

csG.invert() ⇒ `CSG`

Return a new CSG solid with solid and empty space switched. This solid is not modified.

Kind: instance method of CSG
Returns: CSG - new CSG object
Example

let B = A.invert()

csG.transform(matrix4x4) ⇒ `CSG`

Return a new CSG solid that is transformed using the given Matrix. Several matrix transformations can be combined before transforming this solid.

Kind: instance method of CSG
Returns: CSG - new CSG object

Param	Type	Description
matrix4x4	`CSG.Matrix4x4`	matrix to be applied

Example

var m = new CSG.Matrix4x4()
m = m.multiply(CSG.Matrix4x4.rotationX(40))
m = m.multiply(CSG.Matrix4x4.translation([-.5, 0, 0]))
let B = A.transform(m)

csG.getBounds() ⇒ `Array.<Vector3D>`

Returns an array of Vector3D, providing minimum coordinates and maximum coordinates of this solid.

Kind: instance method of CSG
Example

let bounds = A.getBounds()
let minX = bounds[0].x

csG.getFeatures(features) ⇒ `Array.<Float>`

Returns an array of values for the requested features of this solid. Supported Features: 'volume', 'area'

Kind: instance method of CSG
Returns: Array.<Float> - values

Param	Type	Description
features	`Array.<String>`	list of features to calculate

Example

let volume = A.getFeatures('volume')
let values = A.getFeatures('area','volume')

CSG.fromPolygons(polygons) ⇒ `CSG`

Construct a CSG solid from a list of Polygon instances.

Kind: static method of CSG
Returns: CSG - new CSG object

Param	Type	Description
polygons	`Array.<Polygon>`	list of polygons

Path2D

Kind: global class

Path2D
- new Path2D([points], [closed])
- instance
  - .getPoints() ⇒ Array.<Vector2>
  - .appendPoint(point) ⇒ Path2D
  - .appendPoints(points) ⇒ Path2D
  - .isClosed() ⇒ Boolean
  - .appendBezier(controlpoints, [options]) ⇒ Path2D
  - .appendArc(endpoint, [options]) ⇒ Path2D
- static
  - .arc([options]) ⇒ Path2D

new Path2D([points], [closed])

Class Path2D Represents a series of points, connected by infinitely thin lines. A path can be open or closed, i.e. additional line between first and last points. The difference between Path2D and CAG is that a path is a 'thin' line, whereas a CAG is an enclosed area.

Param	Type	Default	Description
[points]	`Array.<Vector2D>`	`[]`	list of points
[closed]	`boolean`	`false`	closer of path

Example

new CSG.Path2D()
new CSG.Path2D([[10,10], [-10,10], [-10,-10], [10,-10]], true) // closed

path2D.getPoints() ⇒ `Array.<Vector2>`

Get the points that make up the path. note that this is current internal list of points, not an immutable copy.

Kind: instance method of Path2D
Returns: Array.<Vector2> - array of points the make up the path

path2D.appendPoint(point) ⇒ `Path2D`

Append an point to the end of the path.

Kind: instance method of Path2D
Returns: Path2D - new Path2D object (not closed)

Param	Type	Description
point	`Vector2D`	point to append

path2D.appendPoints(points) ⇒ `Path2D`

Append a list of points to the end of the path.

Kind: instance method of Path2D
Returns: Path2D - new Path2D object (not closed)

Param	Type	Description
points	`Array.<Vector2D>`	points to append

path2D.isClosed() ⇒ `Boolean`

Determine if the path is a closed or not.

Kind: instance method of Path2D
Returns: Boolean - true when the path is closed, otherwise false

path2D.appendBezier(controlpoints, [options]) ⇒ `Path2D`

Append a Bezier curve to the end of the path, using the control points to transition the curve through start and end points.
The Bézier curve starts at the last point in the path, and ends at the last given control point. Other control points are intermediate control points.
The first control point may be null to ensure a smooth transition occurs. In this case,
the second to last control point of the path is mirrored into the control points of the Bezier curve. In other words, the trailing gradient of the path matches the new gradient of the curve.

Kind: instance method of Path2D
Returns: Path2D - new Path2D object (not closed)

Param	Type	Default	Description
controlpoints	`Array.<Vector2D>`		list of control points
[options]	`Object`		options for construction
[options.resolution]	`Number`	`defaultResolution2D`	number of sides per 360 rotation

Example

let p5 = new CSG.Path2D([[10,-20]],false);
p5 = p5.appendBezier([[10,-10],[25,-10],[25,-20]]);
p5 = p5.appendBezier([[25,-30],[40,-30],[40,-20]]);

path2D.appendArc(endpoint, [options]) ⇒ `Path2D`

Append an arc to the end of the path. This implementation follows the SVG arc specs. For the details see http://www.w3.org/TR/SVG/paths.html#PathDataEllipticalArcCommands

Kind: instance method of Path2D
Returns: Path2D - new Path2D object (not closed)

Param	Type	Default	Description
endpoint	`Vector2D`		end point of arc
[options]	`Object`		options for construction
[options.radius]	`Number`	`0`	radius of arc (X and Y), see also xradius and yradius
[options.xradius]	`Number`	`0`	X radius of arc, see also radius
[options.yradius]	`Number`	`0`	Y radius of arc, see also radius
[options.xaxisrotation]	`Number`	`0`	rotation (in degrees) of the X axis of the arc with respect to the X axis of the coordinate system
[options.resolution]	`Number`	`defaultResolution2D`	number of sides per 360 rotation
[options.clockwise]	`Boolean`	`false`	draw an arc clockwise with respect to the center point
[options.large]	`Boolean`	`false`	draw an arc longer than 180 degrees

Example

let p1 = new CSG.Path2D([[27.5,-22.96875]],false);
p1 = p1.appendPoint([27.5,-3.28125]);
p1 = p1.appendArc([12.5,-22.96875],{xradius: 15,yradius: -19.6875,xaxisrotation: 0,clockwise: false,large: false});
p1 = p1.close();

Path2D.arc([options]) ⇒ `Path2D`

Construct an arc.

Kind: static method of Path2D
Returns: Path2D - new Path2D object (not closed)

Param	Type	Default	Description
[options]	`Object`		options for construction
[options.center]	`Vector2D`	`[0,0]`	center of circle
[options.radius]	`Number`	`1`	radius of circle
[options.startangle]	`Number`	`0`	starting angle of the arc, in degrees
[options.endangle]	`Number`	`360`	ending angle of the arc, in degrees
[options.resolution]	`Number`	`defaultResolution2D`	number of sides per 360 rotation
[options.maketangent]	`Boolean`	`false`	adds line segments at both ends of the arc to ensure that the gradients at the edges are tangent

Example

let path = CSG.Path2D.arc({
  center: [5, 5],
  radius: 10,
  startangle: 90,
  endangle: 180,
  resolution: 36,
  maketangent: true
});

Polygon

Kind: global class

Polygon
- new Polygon(vertices, [shared], [plane])
- instance
  - .checkIfConvex() ⇒ boolean
  - .solidFromSlices(options)
  - ._addWalls(walls, bottom, top)
- static
  - .Shared
    - new Polygon.Shared(color)
    - .fromColor(r, g, b, [a], [color])
  - .createFromPoints(points, [shared], [plane])

new Polygon(vertices, [shared], [plane])

Class Polygon Represents a convex polygon. The vertices used to initialize a polygon must be coplanar and form a convex loop. They do not have to be Vertex instances but they must behave similarly (duck typing can be used for customization).
Each convex polygon has a shared property, which is shared between all polygons that are clones of each other or were split from the same polygon. This can be used to define per-polygon properties (such as surface color).
The plane of the polygon is calculated from the vertex coordinates if not provided. The plane can alternatively be passed as the third argument to avoid calculations.

Param	Type	Default	Description
vertices	`Array.<Vertex>`		list of vertices
[shared]	`Shared`	`defaultShared`	shared property to apply
[plane]	`Plane`		plane of the polygon

Example

const vertices = [
  new CSG.Vertex(new CSG.Vector3D([0, 0, 0])),
  new CSG.Vertex(new CSG.Vector3D([0, 10, 0])),
  new CSG.Vertex(new CSG.Vector3D([0, 10, 10]))
]
let observed = new Polygon(vertices)

polygon.checkIfConvex() ⇒ `boolean`

Check whether the polygon is convex. (it should be, otherwise we will get unexpected results)

Kind: instance method of Polygon

polygon.solidFromSlices(options)

Creates solid from slices (Polygon) by generating walls

Kind: instance method of Polygon

Param	Type	Description
options	`Object`	Solid generating options - numslices {Number} Number of slices to be generated - callback(t, slice) {Function} Callback function generating slices. arguments: t = [0..1], slice = [0..numslices - 1] return: Polygon or null to skip - loop {Boolean} no flats, only walls, it's used to generate solids like a tor

polygon._addWalls(walls, bottom, top)

Kind: instance method of Polygon

Param	Description
walls	Array of wall polygons
bottom	Bottom polygon
top	Top polygon

Polygon.Shared

Kind: static class of Polygon

.Shared
- new Polygon.Shared(color)
- .fromColor(r, g, b, [a], [color])

new Polygon.Shared(color)

Class Polygon.Shared Holds the shared properties for each polygon (Currently only color).

Param	Type	Description
color	`Array.<Array>`	array containing RGBA values, or null

Example

let shared = new CSG.Polygon.Shared([0, 0, 0, 1])

Shared.fromColor(r, g, b, [a], [color])

Create Polygon.Shared from color values.

Kind: static method of Shared

Param	Type	Description
r	`number`	value of RED component
g	`number`	value of GREEN component
b	`number`	value of BLUE component
[a]	`number`	value of ALPHA component
[color]	`Array.<Array>`	OR array containing RGB values (optional Alpha)

Example

let s1 = Polygon.Shared.fromColor(0,0,0)
let s2 = Polygon.Shared.fromColor([0,0,0,1])

Polygon.createFromPoints(points, [shared], [plane])

Create a polygon from the given points.

Kind: static method of Polygon

Param	Type	Default	Description
points	`Array.<Array>`		list of points
[shared]	`Shared`	`defaultShared`	shared property to apply
[plane]	`Plane`		plane of the polygon

Example

const points = [
  [0,  0, 0],
  [0, 10, 0],
  [0, 10, 10]
]
let observed = CSG.Polygon.createFromPoints(points)

Vector2D

Kind: global class

new Vector2D()

Class Vector2D Represents a 2D vector with X, Y coordinates

Example

new CSG.Vector2D(1, 2);
new CSG.Vector3D([1, 2]);
new CSG.Vector3D({ x: 1, y: 2});

Vector3D

Kind: global class

new Vector3D()

Class Vector3D Represents a 3D vector with X, Y, Z coordinates.

Example

new CSG.Vector3D(1, 2, 3);
new CSG.Vector3D([1, 2, 3]);
new CSG.Vector3D({ x: 1, y: 2, z: 3 });
new CSG.Vector3D(1, 2); // assumes z=0
new CSG.Vector3D([1, 2]); // assumes z=0

defaultResolution2D

Number of polygons per 360 degree revolution for 2D objects.

Kind: global constant
Default: 32

defaultResolution3D

Number of polygons per 360 degree revolution for 3D objects.

Kind: global constant
Default: 12

EPS

Epsilon used during determination of near zero distances.

Kind: global constant
Default: 0.00001

angleEPS

Epsilon used during determination of near zero areas.

Kind: global constant
Default: 0.1

areaEPS

Epsilon used during determination of near zero areas. This is the minimal area of a minimal polygon.

Kind: global constant

fromObject(obj) ⇒ `CAG`

Reconstruct a CAG from an object with identical property names.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Description
obj	`Object`	anonymous object, typically from JSON

fromPointsNoCheck(points) ⇒ `CAG`

Construct a CAG from a list of points (a polygon). Like fromPoints() but does not check if the result is a valid polygon. The points MUST rotate counter clockwise. The points can define a convex or a concave polygon. The polygon must not self intersect.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Description
points	`Array.<points>`	list of points in 2D space

fromPath2(Path2) ⇒ `CAG`

Construct a CAG from a 2d-path (a closed sequence of points). Like fromPoints() but does not check if the result is a valid polygon.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Description
Path2	`path`	a Path2 path

fromSlices(options) ⇒ `CSG`

Construct a CSG solid from a list of pre-generated slices. See Polygon.prototype.solidFromSlices() for details.

Kind: global function
Returns: CSG - new CSG object

Param	Type	Description
options	`Object`	options passed to solidFromSlices()

fromObject(obj) ⇒ `CSG`

Reconstruct a CSG solid from an object with identical property names.

Kind: global function
Returns: CSG - new CSG object

Param	Type	Description
obj	`Object`	anonymous object, typically from JSON

fromCompactBinary(bin) ⇒ `CSG`

Reconstruct a CSG from the output of toCompactBinary().

Kind: global function
Returns: CSG - new CSG object

Param	Type	Description
bin	`CompactBinary`	see toCompactBinary().

Line2D(normal) ⇒ `Line2D`

class Line2D Represents a directional line in 2D space A line is parametrized by its normal vector (perpendicular to the line, rotated 90 degrees counter clockwise) and w. The line passes through the point .times(w). Equation: p is on line if normal.dot(p)==w

Kind: global function

Param	Type	Description
normal	`Vector2D`	normal must be a unit vector!

circle([options]) ⇒ `CAG`

Construct a circle.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Default	Description
[options]	`Object`		options for construction
[options.center]	`Vector2D`	`[0,0]`	center of circle
[options.radius]	`Number`	`1`	radius of circle
[options.resolution]	`Number`	`defaultResolution2D`	number of sides per 360 rotation

ellipse([options]) ⇒ `CAG`

Construct an ellispe.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Default	Description
[options]	`Object`		options for construction
[options.center]	`Vector2D`	`[0,0]`	center of ellipse
[options.radius]	`Vector2D`	`[1,1]`	radius of ellipse, width and height
[options.resolution]	`Number`	`defaultResolution2D`	number of sides per 360 rotation

rectangle([options]) ⇒ `CAG`

Construct a rectangle.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Default	Description
[options]	`Object`		options for construction
[options.center]	`Vector2D`	`[0,0]`	center of rectangle
[options.radius]	`Vector2D`	`[1,1]`	radius of rectangle, width and height
[options.corner1]	`Vector2D`	`[0,0]`	bottom left corner of rectangle (alternate)
[options.corner2]	`Vector2D`	`[0,0]`	upper right corner of rectangle (alternate)

roundedRectangle([options]) ⇒ `CAG`

Construct a rounded rectangle.

Kind: global function
Returns: CAG - new CAG object

Param	Type	Default	Description
[options]	`Object`		options for construction
[options.center]	`Vector2D`	`[0,0]`	center of rounded rectangle
[options.radius]	`Vector2D`	`[1,1]`	radius of rounded rectangle, width and height
[options.corner1]	`Vector2D`	`[0,0]`	bottom left corner of rounded rectangle (alternate)
[options.corner2]	`Vector2D`	`[0,0]`	upper right corner of rounded rectangle (alternate)
[options.roundradius]	`Number`	`0.2`	round radius of corners
[options.resolution]	`Number`	`defaultResolution2D`	number of sides per 360 rotation

Example

let r = roundedRectangle({
  center: [0, 0],
  radius: [5, 10],
  roundradius: 2,
  resolution: 36,
});