README.md

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";

const quadGeometry = Primitives.quad({
  scale: 0.5,
});
console.log(quadGeometry);
// {
//   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",
  quads: false,
});
const roundedRectangleGeometry = Primitives.roundedRectangle({
  sx: 1,
  sy: 1,
  nx: 1,
  ny: 1,
  radius: 0.25,
  roundSegments: 8,
  edgeSegments: 1,
});
const stadiumGeometry = Primitives.stadium({
  sx: 1,
  sy: 0.5,
  nx: 1,
  ny: 1,
  roundSegments: 8,
  edgeSegments: 1,
});

const ellipseGeometry = Primitives.ellipse({
  sx: 1,
  sy: 0.5,
  radius: 0.5,
  segments: 32,
  innerSegments: 16,
  theta: Math.PI * 2,
  thetaOffset: 0,
  mapping: mappings.elliptical,
});
const disc = Primitives.disc({
  radius: 0.5,
  segments: 32,
  innerSegments: 16,
  theta: Math.PI * 2,
  thetaOffset: 0,
  mapping: mappings.concentric,
});
const superellipse = Primitives.superellipse({
  sx: 1,
  sy: 0.5,
  radius: 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,
  radius: 0.5,
  segments: 128,
  innerSegments: 16,
  theta: Math.PI * 2,
  thetaOffset: 0,
  mapping: mappings.fgSquircular,
  squareness: 0.95,
});
const annulus = Primitives.annulus({
  radius: 0.5,
  segments: 32,
  innerSegments: 16,
  theta: Math.PI * 2,
  thetaOffset: 0,
  innerRadius: 0.25,
  mapping: mappings.concentric,
});
const reuleux = Primitives.reuleux({
  radius: 0.5,
  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,
  radius: 0.25,
  roundSegments: 8,
  edgeSegments: 1,
});

const sphereGeometry = Primitives.sphere({
  radius: 0.5,
  nx: 32,
  ny: 16,
  theta: Math.PI,
  thetaOffset: 0,
  phi: Math.PI * 2,
  phiOffset: 0,
});
const icosphereGeometry = Primitives.icosphere({
  radius: 0.5,
  subdivisions: 2,
});
const ellipsoidGeometry = Primitives.ellipsoid({
  radius: 1,
  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,
  radius: 0.25,
  nx: 16,
  ny: 1,
  radiusApex: 0.25,
  capSegments: 1,
  capApex: true,
  capBase: true,
  capBaseSegments: 1,
  phi: Math.PI * 2,
});
const coneGeometry = Primitives.cone({
  height: 1,
  radius: 0.25,
  nx: 16,
  ny: 1,
  capSegments: 1,
  capBase: true,
  theta: Math.PI * 2,
});
const capsuleGeometry = Primitives.capsule({
  height: 0.5,
  radius: 0.25,
  nx: 16,
  ny: 1,
  roundSegments: 16,
  theta: Math.PI * 2,
});
const torusGeometry = Primitives.torus({
  radius: 0.4,
  segments: 64,
  minorRadius: 0.1,
  minorSegments: 32,
  theta: Math.PI * 2,
  thetaOffset: 0,
  phi: Math.PI * 2,
  phiOffset: 0,
});

const tetrahedron = Primitives.tetrahedron({
  radius: 0.5,
});
const icosahedron = Primitives.icosahedron({
  radius: 0.5,
});

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

API

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

quad

reuleux

roundedCube

roundedRectangle

sphere

squircle

stadium

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
  • annulus([options]) ⇒ SimplicialComplex ⏏
    • ~AnnulusOptions : object

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
  • box([options]) ⇒ BasicSimplicialComplex ⏏
    • ~BoxOptions : object

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
  • capsule([options]) ⇒ SimplicialComplex ⏏
    • ~CapsuleOptions : object

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
  • circle([options]) ⇒ BasicSimplicialComplex ⏏
    • ~CircleOptions : object

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
  • cone([options]) ⇒ SimplicialComplex ⏏
    • ~ConeOptions : object

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
  • cube([options]) ⇒ SimplicialComplex ⏏
    • ~CubeOptions : object

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
  • cylinder([options]) ⇒ SimplicialComplex ⏏
    • ~CylinderOptions : object

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
  • disc([options]) ⇒ SimplicialComplex ⏏
    • ~DiscOptions : object

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
  • ellipse([options]) ⇒ SimplicialComplex ⏏
    • ~EllipseOptions : object

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
  • ellipsoid([options]) ⇒ SimplicialComplex ⏏
    • ~EllipsoidOptions : object

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
  • icosahedron([options]) ⇒ SimplicialComplex ⏏
    • ~IcosahedronOptions : object

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
  • icosphere([options]) ⇒ SimplicialComplex ⏏
    • ~IcosphereOptions : object

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

mappings

plane

• plane
  • plane([options]) ⇒ SimplicialComplex ⏏
    • ~PlaneOptions : object
    • ~PlaneDirection : "x" | "-x" | "y" | "-y" | "z" | "-z"

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

• quad
  • quad([options]) ⇒ SimplicialComplex ⏏
    • ~QuadOptions : object

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
  • reuleux([options]) ⇒ SimplicialComplex ⏏
    • ~ReuleuxOptions : object

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
  • roundedCube([options]) ⇒ SimplicialComplex ⏏
    • ~RoundedCubeOptions : object

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
  • roundedRectangle([options]) ⇒ SimplicialComplex ⏏
    • ~RoundedCubeOptions : object

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
  • sphere([options]) ⇒ SimplicialComplex ⏏
    • ~SphereOptions : object

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
  • squircle([options]) ⇒ SimplicialComplex ⏏
    • ~SquircleOptions : object

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

• stadium
  • stadium([options]) ⇒ SimplicialComplex ⏏
    • ~StadiumOptions : object

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
  • superellipse([options]) ⇒ SimplicialComplex ⏏
    • ~SuperellipseOptions : object

superellipse([options]) ⇒ SimplicialComplex ⏏

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

Kind: Exported function See

• Wolfram MathWorld – Superellipse
• Wikipedia – Superellipse

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
  • tetrahedron([options]) ⇒ SimplicialComplex ⏏
    • ~TetrahedronOptions : object

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
  • torus([options]) ⇒ SimplicialComplex ⏏
    • ~TorusOptions : object

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
  • .HALF_PI : number
  • .SQRT2 : number
  • .getCellsTypedArray ⇒ Uint8Array | Uint16Array | Uint32Array
  • .normalize(v) ⇒ Array.<number>
  • .checkArguments(...args)
  • .setTypedArrayType(type)

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

License

See original packages used in v1:

• primitive-quad
• primitive-plane
• primitive-cube
• primitive-rounded-cube
• primitive-capsule
• primitive-sphere
• primitive-icosphere
• primitive-ellipsoid
• primitive-torus
• primitive-cylinder
• primitive-box
• primitive-circle

Differences with v1:

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

MIT. See license file.