primitive-geometry
v2.10.1
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.
Downloads
3,080
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-geometry
Features
- Common API: options object in, simplicial complex out
- Outputs TypedArray (
Float32Array
for geometry data andUint8Array|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
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 | | --------------- | --------------------- | -------------------------------- | | [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 | | [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 |
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 | | [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 | | | [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 | | [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.