primitive-geometry
v2.11.0
Published
Geometries for 3D rendering, including normals, UVs and cell indices (faces). Perfect if you want to supercharge your dependency folder... with 30KB of geometries.
Maintainers
Readme
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-geometryFeatures
- Common API: options object in, simplicial complex out
- Outputs TypedArray (
Float32Arrayfor geometry data andUint8Array|Uint16Array|Uint32Arrayfor 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,
mergeCentroid: true,
mapping: mappings.elliptical,
});
const disc = Primitives.disc({
radius: 0.5,
segments: 32,
innerSegments: 16,
theta: Math.PI * 2,
thetaOffset: 0,
mergeCentroid: true,
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,
mergeCentroid: true,
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,
mergeCentroid: true,
mapping: mappings.fgSquircular,
squareness: 0.95,
});
const annulus = Primitives.annulus({
sx: 1,
sy: 1,
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,
mergeCentroid: true,
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
Typedefs
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 | | --------------- | --------------------- | -------------------------------- | | [sx] | number | 1 | | [sy] | number | 1 | | [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 ⏏
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
- cone([options]) ⇒ SimplicialComplex ⏏
- ~ConeOptions : object
- cone([options]) ⇒ SimplicialComplex ⏏
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 ⏏
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
- disc([options]) ⇒ SimplicialComplex ⏏
- ~DiscOptions : object
- disc([options]) ⇒ SimplicialComplex ⏏
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 | | [mergeCentroid] | boolean | true | | [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 | | [mergeCentroid] | boolean | true | | [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 |
mappings
plane
- plane
- plane([options]) ⇒ SimplicialComplex ⏏
- ~PlaneOptions : object
- ~PlaneDirection : "x" | "-x" | "y" | "-y" | "z" | "-z"
- plane([options]) ⇒ SimplicialComplex ⏏
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 ⏏
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 | | [mergeCentroid] | boolean | true | | [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
- sphere([options]) ⇒ SimplicialComplex ⏏
- ~SphereOptions : object
- sphere([options]) ⇒ SimplicialComplex ⏏
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 | | | [mergeCentroid] | boolean | true | | | [mapping] | function | mappings.fgSquircular | | | [squareness] | number | 0.95 | Squareness (0 < s <= 1) |
stadium
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 | | [mergeCentroid] | boolean | true | | [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
- torus([options]) ⇒ SimplicialComplex ⏏
- ~TorusOptions : object
- torus([options]) ⇒ SimplicialComplex ⏏
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:
- [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
MIT. See license file.
