# modeling/primitives

Primitives provide the building blocks for complex parts. Each primitive is a geometrical object that can be described mathematically, and therefore precise. Primitives can be logically combined, transformed, extruded, etc.

Source:
##### Example
``const { cube, ellipse, star } = require('@jscad/modeling').primitives``

### Methods

#### (static) arc(optionsopt) → {path2}

Source:

Construct an arc in two dimensional space where all points are at the same distance from the center.

##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of arc

`radius` Number <optional>
`1`

`startAngle` Number <optional>
`0`

starting angle of the arc, in radians

`endAngle` Number <optional>
`TAU`

ending angle of the arc, in radians

`segments` Number <optional>
`32`

number of segments to create per full rotation

`makeTangent` Boolean <optional>
`false`

adds line segments at both ends of the arc to ensure that the gradients at the edges are tangent

new 2D path

Type
path2

#### (static) circle(optionsopt) → {geom2}

Source:
See:

Construct a circle in two dimensional space where all points are at the same distance from the center.

##### Example
``let myshape = circle({radius: 10})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of circle

`radius` Number <optional>
`1`

`startAngle` Number <optional>
`0`

start angle of circle, in radians

`endAngle` Number <optional>
`TAU`

end angle of circle, in radians

`segments` Number <optional>
`32`

number of segments to create per full rotation

new 2D geometry

Type
geom2

#### (static) cube(optionsopt) → {geom3}

Source:
See:

Construct an axis-aligned solid cube in three dimensional space with six square faces.

##### Example
``let myshape = cube({size: 10})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of cube

`size` Number <optional>
`2`

dimension of cube

new 3D geometry

Type
geom3

#### (static) cuboid(optionsopt) → {geom3}

Source:

Construct an axis-aligned solid cuboid in three dimensional space.

##### Example
``let myshape = cuboid({size: [5, 10, 5]})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of cuboid

`size` Array <optional>
`[2,2,2]`

dimensions of cuboid; width, depth, height

new 3D geometry

Type
geom3

#### (static) cylinder(optionsopt) → {geom3}

Source:
See:

Construct a Z axis-aligned cylinder in three dimensional space.

##### Example
``let myshape = cylinder({height: 2, radius: 10})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of cylinder

`height` Number <optional>
`2`

height of cylinder

`radius` Number <optional>
`1`

radius of cylinder (at both start and end)

`segments` Number <optional>
`32`

number of segments to create per full rotation

new geometry

Type
geom3

#### (static) cylinderElliptic(optionsopt) → {geom3}

Source:

Construct a Z axis-aligned elliptic cylinder in three dimensional space.

##### Example
``let myshape = cylinderElliptic({height: 2, startRadius: [10,5], endRadius: [8,3]})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of cylinder

`height` Number <optional>
`2`

height of cylinder

`startRadius` Array <optional>
`[1,1]`

radius of rounded start, must be two dimensional array

`startAngle` Number <optional>
`0`

start angle of cylinder, in radians

`endRadius` Array <optional>
`[1,1]`

radius of rounded end, must be two dimensional array

`endAngle` Number <optional>
`TAU`

end angle of cylinder, in radians

`segments` Number <optional>
`32`

number of segments to create per full rotation

new geometry

Type
geom3

#### (static) ellipse(optionsopt) → {geom2}

Source:
See:

Construct an axis-aligned ellipse in two dimensional space.

##### Example
``let myshape = ellipse({radius: [5,10]})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of ellipse

`radius` Array <optional>
`[1,1]`

radius of ellipse, along X and Y

`startAngle` Number <optional>
`0`

start angle of ellipse, in radians

`endAngle` Number <optional>
`TAU`

end angle of ellipse, in radians

`segments` Number <optional>
`32`

number of segments to create per full rotation

new 2D geometry

Type
geom2

#### (static) ellipsoid(optionsopt) → {geom3}

Source:

Construct an axis-aligned ellipsoid in three dimensional space.

##### Example
``let myshape = ellipsoid({radius: [5, 10, 20]})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of ellipsoid

`radius` Array <optional>
`[1,1,1]`

radius of ellipsoid, along X, Y and Z

`segments` Number <optional>
`32`

number of segments to create per full rotation

`axes` Array <optional>

an array with three vectors for the x, y and z base vectors

new 3D geometry

Type
geom3

#### (static) geodesicSphere(optionsopt) → {geom3}

Source:

Construct a geodesic sphere based on icosahedron symmetry.

##### Example
``let myshape = geodesicSphere({radius: 15, frequency: 18})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`radius` Number <optional>
`1`

`frequency` Number <optional>
`6`

subdivision frequency per face, multiples of 6

new 3D geometry

Type
geom3

#### (static) line(points) → {path2}

Source:

Construct a new line in two dimensional space from the given points. The points must be provided as an array, where each element is a 2D point.

##### Example
``let myshape = line([[10, 10], [-10, 10]])``
##### Parameters:
Name Type Description
`points` Array

array of points from which to create the path

new 2D path

Type
path2

#### (static) polygon(options) → {geom2}

Source:

Construct a polygon in two dimensional space from a list of points, or a list of points and paths.

NOTE: The ordering of points is important, and must define a counter clockwise rotation of points.

##### Example
``````let roof = [[10,11], [0,11], [5,20]]
let wall = [[0,0], [10,0], [10,10], [0,10]]

let poly = polygon({ points: roof })
or
let poly = polygon({ points: [roof, wall] })
or
let poly = polygon({ points: roof, paths: [0, 1, 2] })
or
let poly = polygon({ points: [roof, wall], paths: [[0, 1, 2], [3, 4, 5, 6]] })``````
##### Parameters:
Name Type Description
`options` Object

options for construction

###### Properties
Name Type Attributes Default Description
`points` Array

points of the polygon : either flat or nested array of 2D points

`paths` Array <optional>

paths of the polygon : either flat or nested array of point indexes

`orientation` String <optional>
`'counterclockwise'`

orientation of points

new 2D geometry

Type
geom2

#### (static) polyhedron(options) → {geom3}

Source:

Construct a polyhedron in three dimensional space from the given set of 3D points and faces. The faces can define outward or inward facing polygons (orientation). However, each face must define a counter clockwise rotation of points which follows the right hand rule.

##### Example
``````let mypoints = [ [10, 10, 0], [10, -10, 0], [-10, -10, 0], [-10, 10, 0], [0, 0, 10] ]
let myfaces = [ [0, 1, 4], [1, 2, 4], [2, 3, 4], [3, 0, 4], [1, 0, 3], [2, 1, 3] ]
let myshape = polyhedron({points: mypoint, faces: myfaces, orientation: 'inward'})``````
##### Parameters:
Name Type Description
`options` Object

options for construction

###### Properties
Name Type Attributes Default Description
`points` Array

list of points in 3D space

`faces` Array

list of faces, where each face is a set of indexes into the points

`colors` Array <optional>

list of RGBA colors to apply to each face

`orientation` String <optional>
`'outward'`

orientation of faces

new 3D geometry

Type
geom3

#### (static) rectangle(optionsopt) → {geom2}

Source:

Construct an axis-aligned rectangle in two dimensional space with four sides at right angles.

##### Example
``let myshape = rectangle({size: [10, 20]})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of rectangle

`size` Array <optional>
`[2,2]`

dimension of rectangle, width and length

new 2D geometry

Type
geom2

#### (static) roundedCuboid(optionsopt) → {geom3}

Source:

Construct an axis-aligned solid cuboid in three dimensional space with rounded corners.

##### Example
``let mycube = roundedCuboid({size: [10, 20, 10], roundRadius: 2, segments: 16})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of rounded cube

`size` Array <optional>
`[2,2,2]`

dimension of rounded cube; width, depth, height

`roundRadius` Number <optional>
`0.2`

`segments` Number <optional>
`32`

number of segments to create per full rotation

new 3D geometry

Type
geom3

#### (static) roundedCylinder(optionsopt) → {geom3}

Source:

Construct a Z axis-aligned solid cylinder in three dimensional space with rounded ends.

##### Example
``let myshape = roundedCylinder({ height: 10, radius: 2, roundRadius: 0.5 })``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of cylinder

`height` Number <optional>
`2`

height of cylinder

`radius` Number <optional>
`1`

`roundRadius` Number <optional>
`0.2`

`segments` Number <optional>
`32`

number of segments to create per full rotation

new 3D geometry

Type
geom3

#### (static) roundedRectangle(optionsopt) → {geom2}

Source:

Construct an axis-aligned rectangle in two dimensional space with rounded corners.

##### Example
``let myshape = roundedRectangle({size: [10, 20], roundRadius: 2})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of rounded rectangle

`size` Array <optional>
`[2,2]`

dimension of rounded rectangle; width and length

`roundRadius` Number <optional>
`0.2`

`segments` Number <optional>
`32`

number of segments to create per full rotation

new 2D geometry

Type
geom2

#### (static) sphere(optionsopt) → {geom3}

Source:
See:

Construct a sphere in three dimensional space where all points are at the same distance from the center.

##### Example
``let myshape = sphere({radius: 5})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0,0]`

center of sphere

`radius` Number <optional>
`1`

`segments` Number <optional>
`32`

number of segments to create per full rotation

`axes` Array <optional>

an array with three vectors for the x, y and z base vectors

new 3D geometry

Type
geom3

#### (static) square(optionsopt) → {geom2}

Source:
See:

Construct an axis-aligned square in two dimensional space with four equal sides at right angles.

##### Example
``let myshape = square({size: 10})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of square

`size` Number <optional>
`2`

dimension of square

new 2D geometry

Type
geom2

#### (static) star(optionsopt) → {geom2}

Source:
See:

Construct a star in two dimensional space.

##### Example
``````let star1 = star({vertices: 8, outerRadius: 10}) // star with 8/2 density
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`center` Array <optional>
`[0,0]`

center of star

`vertices` Number <optional>
`5`

number of vertices (P) on the star

`density` Number <optional>
`2`

density (Q) of star

`outerRadius` Number <optional>
`1`

`innerRadius` Number <optional>
`0`

inner radius of vertices, or zero to calculate

`startAngle` Number <optional>
`0`

starting angle for first vertice, in radians

new 2D geometry

Type
geom2

#### (static) torus(optionsopt) → {geom3}

Source:

Construct a torus by revolving a small circle (inner) about the circumference of a large (outer) circle.

##### Example
``let myshape = torus({ innerRadius: 10, outerRadius: 100 })``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`innerRadius` Number <optional>
`1`

`outerRadius` Number <optional>
`4`

`innerSegments` Integer <optional>
`32`

number of segments to create per rotation

`outerSegments` Integer <optional>
`32`

number of segments to create per rotation

`innerRotation` Integer <optional>
`0`

rotation of small (inner) circle in radians

`outerRotation` Number <optional>
`TAU`

rotation (outer) of the torus (RADIANS)

`startAngle` Number <optional>
`0`

start angle of the torus (RADIANS)

new 3D geometry

Type
geom3

#### (static) triangle(optionsopt) → {geom2}

Source:
See:

Construct a triangle in two dimensional space from the given options. The triangle is always constructed CCW from the origin, [0, 0, 0].

##### Example
``let myshape = triangle({type: 'AAS', values: [degToRad(62), degToRad(35), 7]})``
##### Parameters:
Name Type Attributes Description
`options` Object <optional>

options for construction

###### Properties
Name Type Attributes Default Description
`type` String <optional>
`'SSS'`

type of triangle to construct; A ~ angle, S ~ side

`values` Array <optional>
`[1,1,1]`

angle (radians) of corners or length of sides

new 2D geometry

Type
geom2