Nth Power Matrix

# npm

## quads

1.2.0 • Public • Published

# `quads` - Geometry Tools

This package is a collection of quad geometry creation and manipulation tools. They can be used agnostic to any given library as they only operate on simple arrays and objects. Please note that this package is an early release, and the APIs may stabilize over time. More rigorous testing is also in the works.

## Types

### SimplicialComplex

This is a complicated math word that means an object with `{ positions, cells }`. The word `mesh` is used for convenience in this module, and `normals` are included with this object.

Additional attributes may be added for one's own applications. For example:

Type: Object

Properties

### Position

An array of 3 values representing a position [x, y, z].

Type: Array

### Cell

In a simplicial complex, a cell is an array of of indices that refer to a position or some other attribute like normals. Quads have 4 indices, and this module uses the convention of `[a, b, c, d]` with clockwise winding order.

`````` b-------c
|       |
|       |
a-------d
``````

Type: Array

### Normal

An array of 3 values, [x, y, z] representing a surface normal. A valid normal has a length of 1. Normals are used for lighting calculation, and for knowing which way a surface is oriented in space. Many operation rely on valid normals.

Type: Array

## API

### averageNormalForPosition

Computes the average normal for a position given the connected cells.

Parameters

• `mesh` SimplicialComplex
• `positionIndex` Number
• `target` Array? = []
• `normalCache` Map? A Map can be provided to cache intermediate normal computations.
• `positionIndexToCells` Map? A Map where positionIndex is mapped to its cell, used primarily internally.

Returns Normal target

### clone

Clones a cell. Returns the new cell.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell

Returns Cell cloned cell

### computeCellCenter

Computes the center of a single cell.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell

Returns Position center

### computeCenterPositions

Computes all of the centers of all the cells.

Parameters

• `mesh` SimplicialComplex

Returns Array<Position> centers

### computeNormals

Updates all of the normals for all the positions using #averageNormalForPosition. If a normal doesn't exist, then it is created.

Parameters

• `mesh` SimplicialComplex

Returns SimplicialComplex

### createBox

Creates a quad box of the given dimensions. This box will render as a smoothed out box, as the normals are averaged. This is typically used for a starting place for subdividing or extrusion operations. If the `optionalMesh` object is passed, then the box will be created inside of that simplicial complex, otherwise a new mesh simplicial complex will be generated.

Parameters

• `x` Number? = 1
• `y` Number? = 1
• `z` Number? = 1
• `optionalMesh` Object?

Returns SimplicialComplex

### createBoxDisjoint

Creates a quad box of the given dimensions, but with non-joined positions. This box renders as a flat shaded box. If the optionalMesh object is passed, then the box will be created inside of that simplicial complex, otherwise a new mesh simplicial complex will be generated.

Parameters

Returns SimplicialComplex

### createQuad

Create a quad with options. If the optionalMesh object is passed, then the quad will be created inside of that simplicial complex, otherwise a new mesh simplicial complex will be generated. Both the mesh simplicial complex and the created cell are returned in an object.

Parameters

• `options` Object
• `mesh` SimplicialComplex?= {}

Examples

Usage:

Returns Object `{mesh, cell}`

### elementsFromQuads

Returns an elements array using the given `ArrayType`, which can be used by WebGL.

Parameters

• `mesh` SimplicialComplex
• `drawMode` String?= 'triangles'
• `ArrayType` typeof?= Uint16Array

Returns Array Elements using the given `ArrayType`, which can be used by WebGL.

### extrude

Given a target cell, first inset it, then move it along the cell's normal outwards by a given distance.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `insetT` Number Value ranged from `0` to `1`, defaults to `0`
• `extrude` Number Distance to extrude, defaults to `0`

### extrudeDisjoint

Given a target cell, first inset it, then move it along the cell's normal outwards by a given distance, but all new geometry generated will not share positions.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `insetT` Number = 0, ranged from `0` (the edge) to `1` (the center).
• `extrude` Number = 0, the distance to extrude out.

### flip

Flip a cell's normal to point the other way. Returns the cell.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell

Returns Cell The cell

### getCellFromEdge

Find a cell given two position indices. Optionally provide a `previousCell` that will not be matched against. Returns the first cell that matches.

Parameters

• `mesh` SimplicialComplex
• `positionIndexA` Number
• `positionIndexB` Number
• `previousCell` Cell? Optional will not be matched against

Returns Cell

### getCellNormal

Compute a cell's normal regardless of it's neighboring cells.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `target` Normal? = []

Returns Normal The target normal.

### getCellsFromPositionIndex

Given a position index, find any cells that include it.

Parameters

• `mesh` SimplicialComplex
• `index` Number
• `target` Array<Cell>?= []

Returns Array<Cell> The target cells.

### getCenter

Computes the center of a cell.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `target` Position?= []

Returns Position center

### getLoop

Gets a loop of cells. Given a single cell, start walking in both directions to select a loop. .

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `type` String can either be `"cells"`, `"positions"`, or `"normals"`.
• `opposite` Boolean will walk in the opposite direction, e.g. up and down, versus left and right

Returns Array an array according to the `type`.

### getNewGeometry

Get all newly created geometry of the given type from whatever arbitrary operations were done on the mesh. This assumes new geometry was created and not destroyed.

Parameters

• `mesh` SimplicialComplex
• `key` Number
• `callback` Function

Examples

Usage:

Returns Array

### inset

Inset a cell some value between `0` (its edges) and `1` (its center).

`````` b----------c
|\   q1   /|
| \      / |
|  f----g  |
|q0| tC |q2| tc = targetCell
|  e----h  |
| /      \ |
|/   q3   \|
a----------d
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number Specifies where the split should be. Ranged from `0` to `1`, defaults to `0`.

Returns Array<Cell> cells `[q0, q1, q2, q3, targetCell]`

### insetDisjoint

Inset a cell some value between `0` (its edges) and `1` (its center), but keep the new cells disjoint so they do not share any positions.

``````     bT----------cT
bL   \    qT    /   cR
|\    \        /    /|
| \    fT----gT    / |
|  fL  fM----gM  gR  |
|qL|   |  tC |    |qR|   tC = targetCell
|  eL  eM----hM  hR  |
| /    eB----hB    \ |
|/    /        \    \|
aL   /    qB    \   dR
aB----------dB
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number? value between 0 - 1 (optional, default `0`)

Returns Array<Cell> cells `[qL, qT, qR, qB, targetCell]`.

### insetLoop

Given a cell, walk a loop and inset the loop, where 0 is the inset being on the edge, and 1 the inset being in the enter. Setting opposite to true will make the cell walk the loop in the opposite direction, e.g. up/down rather than left/right.

``````*----*----*----*----*----*----*----*----*----*
|    |    |    |    |    |    |    |    |    |
|    |    |<---|----|----|----|--->|    |    |
|    |    |    |    |cell|    |    |    |    |
|    |    |<---|----|----|----|--->|    |    |
|    |    |    |    |    |    |    |    |    |
*----*----*----*----*----*----*----*----*----*
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number?= 0.5 Specifies where the split should be. Ranged from `0` to `1`
• `opposite` Boolean will walk in the opposite direction, e.g. up and down, versus left and right

Returns SimplicialComplex

### mergePositions

Combine all positions together and recompute the normals.

Parameters

• `mesh` SimplicialComplex

Returns SimplicialComplex

### mirror

Clone all existing geometry, and mirror it about the given axis.

Parameters

• `mesh` SimplicialComplex
• `cells` Cell
• `axis` Number is either `0`, `1`, or `2`, which represents the `x`, `y`, and `z` axis respectively.

### splitHorizontal

Split a cell horizontally.

`````` b--------c
|        |
ab------cd
|        |
a--------d
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number?= 0.5 Specifies where the split should be. Ranged from `0` to `1`
• `targetCell`

### splitHorizontalDisjoint

Split a cell horizontally into two new disconnected cells.

`````` b--------c
|        |
ab1----cd1
ab2----cd2
| target |
a--------d
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number?= 0.5 Specifies where the split should be. Ranged from `0` to `1`
• `targetCell`

### splitLoop

Given a cell, walk along the mesh in both directions and split the cell.

``````*--------*--------*--------*--------*--------*--------*--------*
|        |        |        |        |        |        |        |
*        *<-------*--------*--cell--*--------*------->*        *
|        |        |        |        |        |        |        |
*--------*--------*--------*--------*--------*--------*--------*
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number?= 0.5 Specifies where the split should be. Ranged from `0` to `1`
• `opposite` Boolean will walk in the opposite direction, e.g. up and down, versus left and right

Returns SimplicialComplex

### splitVertical

Split a cell horizontally.

`````` b---bc---c
|   |    |
|   |    |
a---ad---d
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number?= 0.5 Specifies where the split should be. Ranged from `0` to `1`, defaults to `0.5`.
• `targetCell`

### splitVerticalDisjoint

Split a cell horizontally into two new disconnected cells.

`````` b---bc1  bc2---c
|     |  |     |
|     |  |     |
a---ad1  ad2---d
``````

Parameters

• `mesh` SimplicialComplex
• `cell` Cell
• `t` Number?= 0.5 Specifies where the split should be. Ranged from `0` to `1`, defaults to `0.5`.
• `targetCell`

### subdivide

Use catmull clark subdivision to smooth out the geometry. All normals will be recomputed. Under the hood this is a convenience function for the module gl-catmull-clark.

Parameters

• `mesh` SimplicialComplex
• `subdivisions` Number
• `positions` Array<Position>?= mesh.positions
• `cells` Cell?= mesh.cells

Returns SimplicialComplex

### updateNormals

Updates all of the normals for all the positions using #averageNormalForPosition. If a normal doesn't exist, then it is created.

Parameters

• `mesh` SimplicialComplex
• `cell` Cell

Returns SimplicialComplex

## Three

### splitVertical

Split a cell horizontally.

`````` b---bc---c
|   |    |
|   |    |
a---ad---d
``````

Parameters

• `\$0` Object quad
• `\$0.positions` Array
• `\$0.cells` Array
• `targetCell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`
• `_ref`

### splitVerticalDisjoint

Split a cell horizontally into two new disconnected cells.

`````` b---bc1  bc2---c
|     |  |     |
|     |  |     |
a---ad1  ad2---d
``````

Parameters

• `mesh` Object
• `targetCell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`

### splitHorizontal

Split a cell horizontally.

`````` b--------c
|        |
ab------cd
|        |
a--------d
``````

Parameters

• `\$0.positions` Array
• `\$0.cells` Array
• `targetCell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`
• `_ref2`

### splitHorizontalDisjoint

Split a cell horizontally into two new disconnected cells.

`````` b--------c
|        |
ab1----cd1
ab2----cd2
| target |
a--------d
``````

Parameters

• `mesh` Object
• `targetCell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`

### inset

Inset a cell some value between `0` (its edges) and `1` (its center).

`````` b----------c
|\   q1   /|
| \      / |
|  f----g  |
|q0| tQ |q2|
|  e----h  |
| /      \ |
|/   q3   \|
a----------d
``````

Parameters

• `mesh` Object
• `targetCell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`

Returns Array cells `[q0, q1, q2, q3, tC]` where `tC` is the `targetCell`.

### extrude

Given a target cell, first inset it, then move it along the cell's normal outwards by a given distance.

Parameters

• `mesh` Object
• `targetCell` Array
• `insetT` Number
• `extrude` Number

### averageNormalForPosition

Computes the average normal for a position given the connected cells.

Parameters

• `mesh` Object
• `positionIndex` Number
• `target` Array? = []
• `normalCache` Map? = new Map() can be provided to cache intermediate normal computations.
• `positionIndexToCells` Number

Returns any the `targetNormal`

### insetDisjoint

Inset a cell some value between `0` (its edges) and `1` (its center), but keep the new cells disjoint so they do not share any positions.

``````     bT----------cT
bL   \    qT    /   cR
|\    \        /    /|
| \    fT----gT    / |
|  fL  fM----gM  gR  |
|qL|   |  tC |    |qR|   tC = targetCell
|  eL  eM----hM  hR  |
| /    eB----hB    \ |
|/    /        \    \|
aL   /    qB    \   dR
aB----------dB
``````

Parameters

• `mesh` Object
• `targetCell` Array
• `t` Number? =0

Returns Array cells `[q0, q1, q2, q3, tC]` where `tC` is the `targetCell`.

### extrudeDisjoint

Given a target cell, first inset it, then move it along the cell's normal outwards by a given distance, but all new geometry generated will not share positions.

Parameters

• `mesh` Object
• `targetCell` Array
• `insetT` Number
• `extrude` Number

### getCenter

Computes the center of a cell

Parameters

Returns Array the targetPosition

### clone

Clones a cell. Returns the new cell.

Parameters

Returns Array a new cell

### updateNormals

Updates all of the normals for all the positions using #averageNormalForPosition. If a normal doesn't exist, then it is created.

Parameters

Returns Object mesh

### getCellNormal

Compute a cell's normal regardless of it's neighboring cells.

Parameters

• `mesh` Object
• `cell` Array
• `target` Array? = []

Returns Array The target normal.

### getCellsFromPositionIndex

Given a position index, find any cells that include it.

Parameters

Returns Array The target cells.

### flip

Flip a cell's normal to point the other way. Returns the cell.

Parameters

Returns Array The cell

### createQuad

Create a quad with options. If the optionalMesh object is passed, then the quad will be created inside of that simplicial complex, otherwise a new mesh simplicial complex will be generated. Both the mesh simplicial complex and the created cell are returned in an object.

Parameters

Examples

Usage:

Returns Object `{mesh, cell}`

### createBoxDisjoint

Creates a quad box of the given dimensions, but with non-joined positions. This box renders as a flat shaded box. If the optionalMesh object is passed, then the box will be created inside of that simplicial complex, otherwise a new mesh simplicial complex will be generated.

Parameters

Returns Object a simplicial complex

### createBox

Creates a quad box of the given dimensions. This box will render as a smoothed out box, as the normals are averaged. This is typically used for a starting place for subdividing or extrusion operations. If the `optionalMesh` object is passed, then the box will be created inside of that simplicial complex, otherwise a new mesh simplicial complex will be generated.

Parameters

Returns Object a simplicial complex

### mergePositions

Combine all positions together and recompute the normals.

Parameters

Returns Object mesh

### elementsFromQuads

Returns an elements array using the given `ArrayType`, which can be used by WebGL.

Parameters

• `mesh` Object
• `drawMode` String
• `ArrayType` typeof

Returns Array Elements using the given `ArrayType`, which can be used by WebGL.

### computeNormals

Updates all of the normals for all the positions using #averageNormalForPosition. If a normal doesn't exist, then it is created.

Parameters

Returns Object The mesh

### splitLoop

Given a cell, walk along the mesh in both directions and split the cell.

``````*--------*--------*--------*--------*--------*--------*--------*
|        |        |        |        |        |        |        |
*        *<-------*--------*--cell--*--------*------->*        *
|        |        |        |        |        |        |        |
*--------*--------*--------*--------*--------*--------*--------*
``````

Parameters

• `mesh` Object
• `cell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`
• `opposite` Boolean will walk in the opposite direction, e.g. up and down, versus left and right

Returns Object mesh

### getCellFromEdge

Find a cell given two position indices. Optionally provide a `previousCell` that will not be matched against. Returns the first cell that matches.

Parameters

• `mesh` Object
• `positionIndexA` Number
• `positionIndexB` Number
• `previousCell` Array? Optional will not be matched against

Returns Array Elements using the given `ArrayType`, which can be used by WebGL.

### getNewGeometry

Get all newly created geometry of the given type from whatever arbitrary operations were done on the mesh. This assumes new geometry was created and not destroyed.

Parameters

Examples

Usage:

Returns Array

### subdivide

Use catmull clark subdivision to smooth out the geometry. All normals will be recomputed. Under the hood this is a convenience function for the module gl-catmull-clark.

Parameters

• `mesh` Object
• `subdivisions` Number
• `positions` Array
• `cells` Array

Returns Object mesh

### computeCenterPositions

Computes all of the centers of all the cells.

Parameters

Returns any A new array

### computeCellCenter

Computes the center of a single cell.

Parameters

Returns any A new array

### insetLoop

Given a cell, walk a loop and inset the loop, where 0 is the inset being on the edge, and 1 the inset being in the enter. Setting opposite to true will make the cell walk the loop in the opposite direction, e.g. up/down rather than left/right.

``````*----*----*----*----*----*----*----*----*----*
|    |    |    |    |    |    |    |    |    |
|    |    |<---|----|----|----|--->|    |    |
|    |    |    |    |cell|    |    |    |    |
|    |    |<---|----|----|----|--->|    |    |
|    |    |    |    |    |    |    |    |    |
*----*----*----*----*----*----*----*----*----*
``````

Parameters

• `mesh` Object
• `cell` Array
• `t` Number Specifies where the split should be. Ranged from `0` to `1`
• `opposite` Boolean will walk in the opposite direction, e.g. up and down, versus left and right

Returns Object mesh

### getLoop

Gets a loop of cells. Given a single cell, start walking in both directions to select a loop. .

Parameters

• `mesh` Object
• `cell` Array
• `type` String can either be `"cells"`, `"positions"`, or `"normals"`.
• `opposite` Boolean will walk in the opposite direction, e.g. up and down, versus left and right

Returns Array an array according to the `type`.

### mirror

Clone all existing geometry, and mirror it about the given axis.

Parameters

• `mesh` Object
• `cells` Array
• `axis` Number is either `0`, `1`, or `2`, which represents the `x`, `y`, and `z` axis respectively.

## Keywords

### Install

`npm i quads`

### Repository

github.com/gregtatum/quads

### Homepage

github.com/gregtatum/quads#readme

0

1.2.0

MIT

141 kB

10