# primitive-geometry

2.10.0 • Public • Published

# primitive-geometry

Geometries for 3D rendering, including normals, UVs and cell indices (faces). Perfect if you want to supercharge your dependency folder... with 30KB of geometries.

## Installation

`npm install primitive-geometry`

## Features

• Common API: options object in, simplicial complex out
• Outputs TypedArray (`Float32Array` for geometry data and `Uint8Array|Uint16Array|Uint32Array` for cells)
• Zero dependency
• Same parameters naming: radius (or rx/ry/rz), scale (or height/sx/sy/sz), segments (or nx/ny/nz) and a few specific parameters for icosphere/cylinder/cone/torus.
• Different Elliptical mappings: see the comparison images and the demo.

See difference with v1 here.

## Usage

See the example and its source.

```import Primitives from "primitive-geometry";

scale: 0.5,
});
// {
//   positions: Float32Array [x, y, z, x, y, z,  ...],
//   normals: Float32Array [x, y, z, x, y, z, ...]
//   uvs: Float32Array [u, v, u, v, ...],
//   cells: Uint8/16/32/Array [a, b, c, a, b, c, ...],
// }
const planeGeometry = Primitives.plane({
sx: 1,
sy: 1,
nx: 1,
ny: 1,
direction: "z",
});
const roundedRectangleGeometry = Primitives.roundedRectangle({
sx: 1,
sy: 1,
nx: 1,
ny: 1,
roundSegments: 8,
edgeSegments: 1,
});
sx: 1,
sy: 0.5,
nx: 1,
ny: 1,
roundSegments: 8,
edgeSegments: 1,
});

const ellipseGeometry = Primitives.ellipse({
sx: 1,
sy: 0.5,
segments: 32,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mapping: mappings.elliptical,
});
const disc = Primitives.disc({
segments: 32,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mapping: mappings.concentric,
});
const superellipse = Primitives.superellipse({
sx: 1,
sy: 0.5,
segments: 32,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mapping: mappings.lamé,
m: 2,
n: 2,
});
const squircle = Primitives.squircle({
sx: 1,
sy: 1,
segments: 128,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mapping: mappings.fgSquircular,
squareness: 0.95,
});
const annulus = Primitives.annulus({
segments: 32,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mapping: mappings.concentric,
});
const reuleux = Primitives.reuleux({
segments: 32,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mapping: mappings.concentric,
n: 3,
});

const cubeGeometry = Primitives.cube({
sx: 1,
sy: 1,
sz: 1,
nx: 1,
ny: 1,
nz: 1,
});
const roundedCubeGeometry = Primitives.roundedCube({
sx: 1,
sy: 1,
sz: 1,
nx: 1,
ny: 1,
nz: 1,
roundSegments: 8,
edgeSegments: 1,
});

const sphereGeometry = Primitives.sphere({
nx: 32,
ny: 16,
theta: Math.PI,
thetaOffset: 0,
phi: Math.PI * 2,
phiOffset: 0,
});
const icosphereGeometry = Primitives.icosphere({
subdivisions: 2,
});
const ellipsoidGeometry = Primitives.ellipsoid({
nx: 32,
ny: 16,
rx: 0.5,
ry: 0.25,
rz: 0.25,
theta: Math.PI,
thetaOffset: 0,
phi: Math.PI * 2,
phiOffset: 0,
});

const cylinderGeometry = Primitives.cylinder({
height: 1,
nx: 16,
ny: 1,
capSegments: 1,
capApex: true,
capBase: true,
capBaseSegments: 1,
phi: Math.PI * 2,
});
const coneGeometry = Primitives.cone({
height: 1,
nx: 16,
ny: 1,
capSegments: 1,
capBase: true,
theta: Math.PI * 2,
});
const capsuleGeometry = Primitives.capsule({
height: 0.5,
nx: 16,
ny: 1,
roundSegments: 16,
theta: Math.PI * 2,
});
const torusGeometry = Primitives.torus({
segments: 64,
minorSegments: 32,
theta: Math.PI * 2,
thetaOffset: 0,
phi: Math.PI * 2,
phiOffset: 0,
});

const tetrahedron = Primitives.tetrahedron({
});
const icosahedron = Primitives.icosahedron({
});

// without normals/uvs
const boxGeometry = Primitives.box({
sx: 1,
sy: 1,
sz: 1,
});
const circleGeometry = Primitives.circle({
segments: 32,
closed: false,
theta: Math.PI * 2,
thetaOffset: 0,
});```

## Modules

index

Re-export all geometries, UV mappings functions and utils.

annulus
box
capsule
circle
cone
cube
cylinder
disc
ellipse
ellipsoid
icosahedron
icosphere
mappings
plane
reuleux
roundedCube
roundedRectangle
sphere
squircle
superellipse
tetrahedron
torus
utils

## Typedefs

BasicSimplicialComplex : `object`

Geometry definition without normals and UVs.

SimplicialComplex : `object`

Geometry definition.

## index

Re-export all geometries, UV mappings functions and utils.

## annulus

### annulus([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `AnnulusOptions` `{}`

#### annulus~AnnulusOptions : `object`

Kind: inner typedef of `annulus` Properties

Name Type Default
[radius] `number` `0.5`
[segments] `number` `32`
[innerSegments] `number` `16`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[innerRadius] `number` `radius * 0.5`
[mapping] `function` `mappings.concentric`

## box

### box([options]) ⇒ `BasicSimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `BoxOptions` `{}`

#### box~BoxOptions : `object`

Kind: inner typedef of `box` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `sx`
[sz] `number` `sx`

## capsule

### capsule([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `CapsuleOptions` `{}`

#### capsule~CapsuleOptions : `object`

Kind: inner typedef of `capsule` Properties

Name Type Default
[height] `number` `0.5`
[radius] `number` `0.25`
[nx] `number` `16`
[ny] `number` `1`
[roundSegments] `number` `32`
[phi] `number` `TAU`

## circle

### circle([options]) ⇒ `BasicSimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `CircleOptions` `{}`

#### circle~CircleOptions : `object`

Kind: inner typedef of `circle` Properties

Name Type Default
[radius] `number` `0.5`
[segments] `number` `32`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[closed] `boolean` `false`

## cone

### cone([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `ConeOptions` `{}`

#### cone~ConeOptions : `object`

Kind: inner typedef of `cone` Properties

Name Type Default
[height] `number` `1`
[radius] `number` `0.25`
[nx] `number` `16`
[ny] `number` `1`
[capSegments] `number` `1`
[capBase] `boolean` `true`
[phi] `number` `TAU`

## cube

### cube([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `CubeOptions` `{}`

#### cube~CubeOptions : `object`

Kind: inner typedef of `cube` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `sx`
[sz] `number` `sx`
[nx] `number` `1`
[ny] `number` `nx`
[nz] `number` `nx`

## cylinder

### cylinder([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `CylinderOptions` `{}`

#### cylinder~CylinderOptions : `object`

Kind: inner typedef of `cylinder` Properties

Name Type Default
[height] `number` `1`
[radius] `number` `0.25`
[nx] `number` `16`
[ny] `number` `1`
[radiusApex] `number` `radius`
[capSegments] `number` `1`
[capApex] `boolean` `true`
[capBase] `boolean` `true`
[phi] `number` `TAU`

## disc

### disc([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `DiscOptions` `{}`

#### disc~DiscOptions : `object`

Kind: inner typedef of `disc` Properties

Name Type Default
[radius] `number` `0.5`
[segments] `number` `32`
[innerSegments] `number` `16`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[mapping] `function` `mappings.concentric`

## ellipse

### ellipse([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `EllipseOptions` `{}`

#### ellipse~EllipseOptions : `object`

Kind: inner typedef of `ellipse` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `0.5`
[radius] `number` `0.5`
[segments] `number` `32`
[innerSegments] `number` `16`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[mapping] `function` `mappings.elliptical`

## ellipsoid

### ellipsoid([options]) ⇒ `SimplicialComplex` ⏏

Default to an oblate spheroid.

Kind: Exported function

Param Type Default
[options] `EllipsoidOptions` `{}`

#### ellipsoid~EllipsoidOptions : `object`

Kind: inner typedef of `ellipsoid` Properties

Name Type Default
[radius] `number` `0.5`
[nx] `number` `32`
[ny] `number` `16`
[rx] `number` `1`
[ry] `number` `0.5`
[rz] `number` `ry`
[theta] `number` `Math.PI`
[thetaOffset] `number` `0`
[phi] `number` `TAU`
[phiOffset] `number` `0`

## icosahedron

### icosahedron([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `IcosahedronOptions` `{}`

#### icosahedron~IcosahedronOptions : `object`

Kind: inner typedef of `icosahedron` Properties

Name Type Default
[radius] `number` `0.5`

## icosphere

### icosphere([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `IcosphereOptions` `{}`

#### icosphere~IcosphereOptions : `object`

Kind: inner typedef of `icosphere` Properties

Name Type Default
[radius] `number` `0.5`
[subdivisions] `number` `2`

## plane

### plane([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `PlaneOptions` `{}`

#### plane~PlaneOptions : `object`

Kind: inner typedef of `plane` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `sx`
[nx] `number` `1`
[ny] `number` `nx`
[direction] `PlaneDirection` `"z"`
[quads] `boolean` `false`

#### plane~PlaneDirection : `"x"` | `"-x"` | `"y"` | `"-y"` | `"z"` | `"-z"`

Kind: inner typedef of `plane`

### quad([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `QuadOptions` `{}`

#### quad~QuadOptions : `object`

Kind: inner typedef of `quad` Properties

Name Type Default
[scale] `number` `0.5`

## reuleux

### reuleux([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function See: Parametric equations for regular and Reuleaux polygons

Param Type Default
[options] `ReuleuxOptions` `{}`

#### reuleux~ReuleuxOptions : `object`

Kind: inner typedef of `reuleux` Properties

Name Type Default
[radius] `number` `0.5`
[segments] `number` `32`
[innerSegments] `number` `16`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[mapping] `function` `mappings.concentric`
[n] `number` `3`

## roundedCube

### roundedCube([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `RoundedCubeOptions` `{}`

#### roundedCube~RoundedCubeOptions : `object`

Kind: inner typedef of `roundedCube` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `sx`
[sz] `number` `sx`
[nx] `number` `1`
[ny] `number` `nx`
[nz] `number` `nx`
[radius] `number` `sx * 0.25`
[roundSegments] `number` `8`
[edgeSegments] `number` `1`

## roundedRectangle

### roundedRectangle([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `RoundedCubeOptions` `{}`

#### roundedRectangle~RoundedCubeOptions : `object`

Kind: inner typedef of `roundedRectangle` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `sx`
[nx] `number` `1`
[ny] `number` `nx`
[radius] `number` `sx * 0.25`
[roundSegments] `number` `8`
[edgeSegments] `number` `1`

## sphere

### sphere([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `SphereOptions` `{}`

#### sphere~SphereOptions : `object`

Kind: inner typedef of `sphere` Properties

Name Type Default
[radius] `number` `0.5`
[nx] `number` `32`
[ny] `number` `16`
[theta] `number` `Math.PI`
[thetaOffset] `number` `0`
[phi] `number` `TAU`
[phiOffset] `number` `0`

## squircle

### squircle([options]) ⇒ `SimplicialComplex` ⏏

Fernández-Guasti squircle

Kind: Exported function See: Squircular Calculations – Chamberlain Fong

Param Type Default
[options] `SquircleOptions` `{}`

#### squircle~SquircleOptions : `object`

Kind: inner typedef of `squircle` Properties

Name Type Default Description
[sx] `number` `1`
[sy] `number` `1`
[radius] `number` `0.5`
[segments] `number` `128`
[innerSegments] `number` `16`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[mapping] `function` `mappings.fgSquircular`
[squareness] `number` `0.95` Squareness (0 < s <= 1)

### stadium([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `StadiumOptions` `{}`

#### stadium~StadiumOptions : `object`

Kind: inner typedef of `stadium` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `sx`
[nx] `number` `1`
[ny] `number` `nx`
[roundSegments] `number` `8`
[edgeSegments] `number` `1`

## superellipse

### superellipse([options]) ⇒ `SimplicialComplex` ⏏

Lamé curve See elliptical-mapping example for a few special cases

Kind: Exported function See

Param Type Default
[options] `SuperellipseOptions` `{}`

#### superellipse~SuperellipseOptions : `object`

Kind: inner typedef of `superellipse` Properties

Name Type Default
[sx] `number` `1`
[sy] `number` `0.5`
[radius] `number` `0.5`
[segments] `number` `32`
[innerSegments] `number` `16`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[mapping] `function` `mappings.lamé`
[m] `number` `2`
[n] `number` `m`

## tetrahedron

### tetrahedron([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `TetrahedronOptions` `{}`

#### tetrahedron~TetrahedronOptions : `object`

Kind: inner typedef of `tetrahedron` Properties

Name Type Default
[radius] `number` `0.5`

## torus

### torus([options]) ⇒ `SimplicialComplex` ⏏

Kind: Exported function

Param Type Default
[options] `TorusOptions` `{}`

#### torus~TorusOptions : `object`

Kind: inner typedef of `torus` Properties

Name Type Default
[radius] `number` `0.4`
[segments] `number` `64`
[minorRadius] `number` `0.1`
[minorSegments] `number` `32`
[theta] `number` `TAU`
[thetaOffset] `number` `0`
[phi] `number` `TAU`
[phiOffset] `number` `0`

## utils

### utils.TAU : `number`

Two times PI.

Kind: static constant of `utils`

### utils.HALF_PI : `number`

Two times PI.

Kind: static constant of `utils`

### utils.SQRT2 : `number`

Square root of 2.

Kind: static constant of `utils`

### utils.getCellsTypedArray ⇒ `Uint8Array` | `Uint16Array` | `Uint32Array`

Select cells typed array from a size determined by amount of vertices.

Kind: static constant of `utils` See: MDN TypedArray objects

Param Type Description
size `number` The max value expected

### utils.normalize(v) ⇒ `Array.<number>`

Normalize a vector 3.

Kind: static method of `utils` Returns: `Array.<number>` - Normalized vector

Param Type Description
v `Array.<number>` Vector 3 array

### utils.checkArguments(...args)

Ensure first argument passed to the primitive functions is an object

Kind: static method of `utils`

Param Type
...args `*`

### utils.setTypedArrayType(type)

Enforce a typed array constructor for cells

Kind: static method of `utils`

Param Type
type `Class.<Uint8Array>` | `Class.<Uint16Array>` | `Class.<Uint32Array>`

## BasicSimplicialComplex : `object`

Geometry definition without normals and UVs.

Kind: global typedef Properties

Name Type
positions `Float32Array`
cells `Uint8Array` | `Uint16Array` | `Uint32Array`

## SimplicialComplex : `object`

Geometry definition.

Kind: global typedef Properties

Name Type
positions `Float32Array`
normals `Float32Array`
uvs `Float32Array`
cells `Uint8Array` | `Uint16Array` | `Uint32Array`

See original packages used in v1:

Differences with v1:

• [x] use 3D positions for circle
• [x] base disc on ellispse and add inner segments
• [x] fix cylinder orientation and uvs
• [x] fix icosphere uvs (based on: https://github.com/mourner/icomesh)
• [x] fix quad normal to +z
• [x] fix subdivision for rounded geometries (rounded-cube and capsule)
• [x] uniformise api and internal names
• [x] use options object
• [x] remove gl-matrix/pex-math and icosphere dependencies
• [x] use only trigonometric operation, no matrix transformation
• [x] base sphere on ellispsoid
• [x] add cone based on cylinder
• [x] use flat typed arrays
• [x] defaults produce geometries contained in a unit bbox
• [x] add jsdoc, prettier, eslint via snowdev

## Package Sidebar

### Install

`npm i primitive-geometry`

### Repository

github.com/dmnsgn/primitive-geometry

### Homepage

github.com/dmnsgn/primitive-geometry

40

2.10.0

MIT

144 kB

59