Skip to content

Latest commit

 

History

History
executable file
·
1286 lines (948 loc) · 49.7 KB

README.md

File metadata and controls

executable file
·
1286 lines (948 loc) · 49.7 KB

primitive-geometry

npm version stability-stable npm minzipped size dependencies types Conventional Commits styled with prettier linted with eslint license

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

paypal coinbase twitter

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([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

mappings

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

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

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

License

See original packages used in v1:

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.