primitive-geometry v2.10.0

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

Typedefs

index

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

annulus

• annulus
  • annulus([options]) ⇒ SimplicialComplex ⏏
    • ~AnnulusOptions : object

annulus(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

annulus~AnnulusOptions : object

Kind: inner typedef of annulus Properties

box

• box
  • box([options]) ⇒ BasicSimplicialComplex ⏏
    • ~BoxOptions : object

box(options) ⇒ BasicSimplicialComplex ⏏

Kind: Exported function

box~BoxOptions : object

Kind: inner typedef of box Properties

capsule

• capsule
  • capsule([options]) ⇒ SimplicialComplex ⏏
    • ~CapsuleOptions : object

capsule(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

capsule~CapsuleOptions : object

Kind: inner typedef of capsule Properties

circle

• circle
  • circle([options]) ⇒ BasicSimplicialComplex ⏏
    • ~CircleOptions : object

circle(options) ⇒ BasicSimplicialComplex ⏏

Kind: Exported function

circle~CircleOptions : object

Kind: inner typedef of circle Properties

cone

• cone
  • cone([options]) ⇒ SimplicialComplex ⏏
    • ~ConeOptions : object

cone(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

cone~ConeOptions : object

Kind: inner typedef of cone Properties

cube

• cube
  • cube([options]) ⇒ SimplicialComplex ⏏
    • ~CubeOptions : object

cube(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

cube~CubeOptions : object

Kind: inner typedef of cube Properties

cylinder

• cylinder
  • cylinder([options]) ⇒ SimplicialComplex ⏏
    • ~CylinderOptions : object

cylinder(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

cylinder~CylinderOptions : object

Kind: inner typedef of cylinder Properties

disc

• disc
  • disc([options]) ⇒ SimplicialComplex ⏏
    • ~DiscOptions : object

disc(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

disc~DiscOptions : object

Kind: inner typedef of disc Properties

ellipse

• ellipse
  • ellipse([options]) ⇒ SimplicialComplex ⏏
    • ~EllipseOptions : object

ellipse(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

ellipse~EllipseOptions : object

Kind: inner typedef of ellipse Properties

ellipsoid

• ellipsoid
  • ellipsoid([options]) ⇒ SimplicialComplex ⏏
    • ~EllipsoidOptions : object

ellipsoid(options) ⇒ SimplicialComplex ⏏

Default to an oblate spheroid.

Kind: Exported function

ellipsoid~EllipsoidOptions : object

Kind: inner typedef of ellipsoid Properties

icosahedron

• icosahedron
  • icosahedron([options]) ⇒ SimplicialComplex ⏏
    • ~IcosahedronOptions : object

icosahedron(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

icosahedron~IcosahedronOptions : object

Kind: inner typedef of icosahedron Properties

icosphere

• icosphere
  • icosphere([options]) ⇒ SimplicialComplex ⏏
    • ~IcosphereOptions : object

icosphere(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

icosphere~IcosphereOptions : object

Kind: inner typedef of icosphere Properties

mappings

plane

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

plane(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

plane~PlaneOptions : object

Kind: inner typedef of plane Properties

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

quad~QuadOptions : object

Kind: inner typedef of quad Properties

reuleux

• reuleux
  • reuleux([options]) ⇒ SimplicialComplex ⏏
    • ~ReuleuxOptions : object

reuleux(options) ⇒ SimplicialComplex ⏏

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

reuleux~ReuleuxOptions : object

Kind: inner typedef of reuleux Properties

roundedCube

• roundedCube
  • roundedCube([options]) ⇒ SimplicialComplex ⏏
    • ~RoundedCubeOptions : object

roundedCube(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

roundedCube~RoundedCubeOptions : object

Kind: inner typedef of roundedCube Properties

roundedRectangle

• roundedRectangle
  • roundedRectangle([options]) ⇒ SimplicialComplex ⏏
    • ~RoundedCubeOptions : object

roundedRectangle(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

roundedRectangle~RoundedCubeOptions : object

Kind: inner typedef of roundedRectangle Properties

sphere

• sphere
  • sphere([options]) ⇒ SimplicialComplex ⏏
    • ~SphereOptions : object

sphere(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

sphere~SphereOptions : object

Kind: inner typedef of sphere Properties

squircle

• squircle
  • squircle([options]) ⇒ SimplicialComplex ⏏
    • ~SquircleOptions : object

squircle(options) ⇒ SimplicialComplex ⏏

Fernández-Guasti squircle

Kind: Exported function See: Squircular Calculations – Chamberlain Fong

squircle~SquircleOptions : object

Kind: inner typedef of squircle Properties

stadium

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

stadium(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

stadium~StadiumOptions : object

Kind: inner typedef of stadium Properties

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

superellipse~SuperellipseOptions : object

Kind: inner typedef of superellipse Properties

tetrahedron

• tetrahedron
  • tetrahedron([options]) ⇒ SimplicialComplex ⏏
    • ~TetrahedronOptions : object

tetrahedron(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

tetrahedron~TetrahedronOptions : object

Kind: inner typedef of tetrahedron Properties

torus

• torus
  • torus([options]) ⇒ SimplicialComplex ⏏
    • ~TorusOptions : object

torus(options) ⇒ SimplicialComplex ⏏

Kind: Exported function

torus~TorusOptions : object

Kind: inner typedef of torus Properties

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

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

Normalize a vector 3.

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

utils.checkArguments(...args)

Ensure first argument passed to the primitive functions is an object

Kind: static method of utils

utils.setTypedArrayType(type)

Enforce a typed array constructor for cells

Kind: static method of utils

BasicSimplicialComplex : object

Geometry definition without normals and UVs.

Kind: global typedef Properties

SimplicialComplex : object

Geometry definition.

Kind: global typedef Properties

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.