geom-extrude

Extrude a planar simplicial complex or closed polylines into a solid with caps, walls, normals and uvs.

Installation

npm install geom-extrude

Usage

import geomExtrude from "geom-extrude";
import { star, starPath } from "primitive-geometry";

const geometry = geomExtrude(star(), {
  thickness: 1,
  direction: "z",
  center: false,
  capStart: true,
  capEnd: true,
  capMapping: undefined, // Shape uvs, or mappings.circumferential if none
  creaseAngle: Math.PI / 6,
  ignoreSeams: true,
});
// => { positions, normals, uvs, cells }

// Closed polylines: caps are triangulated, nested loops are holes
const fromPath = geomExtrude(starPath(), { thickness: 0.2 });

API

Modules

Typedefs

geomExtrude

• geomExtrude
  • geomExtrude(shape, [options]) ⇒ SimplicialShape ⏏
    • .getVertexAttributes(geometry, vertexCount, [excluded]) ⇒ Array.<VertexAttribute>
    • .copyAttributes(geometry, attributes, offset, count, [sourceIndices])
    • .computeBoundary(cells, vertexCount) ⇒ Array.<Array.<number>>
    • .computeProfile(shape, [options]) ⇒ Profile
    • .computeCapUvs(positions, profile, [mapping]) ⇒ Float32Array
    • .computeColumns(positions, loops, normal, [creaseAngle]) ⇒ Columns
    • .stitchRings(out, columns, options) ⇒ number

geomExtrude(shape, [options]) ⇒ SimplicialShape ⏏

Extrude a planar shape into a solid: a start cap, an end cap and walls along its boundary loops, holes included.

A PolylineComplex shape is read as non-intersecting polylines: closed loops nested an odd number of times are holes, open polylines only get walls.

Walls wrap u once around each loop and v from start to end. Caps keep the shape uvs unless a capMapping is set or the shape has none.

Other flat per-vertex shape attributes (eg. vertexColors) are copied unchanged to the caps and walls, keeping their array type: direction dependent ones (eg. tangents) don't follow the walls and end cap orientation.

Kind: Exported function

| Param | Type | Default | | --------- | ------------------------------------------------------------------------------------------------ | --------------- | | shape | SimplicialShape | PolylineShape | | | [options] | GeomExtrudeOptions | {} |

geomExtrude.getVertexAttributes(geometry, vertexCount, [excluded]) ⇒ Array.<VertexAttribute>

Find the flat per-vertex attributes of a geometry, eg. vertexColors.

Told apart by length only: any flat array whose length is a multiple of the vertex count.

Kind: static method of geomExtrude

| Param | Type | Default | Description | | ----------- | ------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | geometry | object | | | | vertexCount | number | | | | [excluded] | Iterable.<string> | ["positions", "normals", "uvs", "cells"] | Attributes left out, eg. the ones a generator computes. |

geomExtrude.copyAttributes(geometry, attributes, offset, count, [sourceIndices])

Copy vertex attributes into a geometry: source vertex i, or sourceIndices[i], to vertex offset + i.

Target arrays must be allocated, eg. new source.constructor(count * size).

Kind: static method of geomExtrude

| Param | Type | Description | | --------------- | -------------------------------------------------------------- | ------------------------------------ | | geometry | object | | | attributes | Array.<VertexAttribute> | | | offset | number | First target vertex. | | count | number | Number of vertices to copy. | | [sourceIndices] | ArrayLike.<number> | Source vertex of each target vertex. |

geomExtrude.computeBoundary(cells, vertexCount) ⇒ Array.<Array.<number>>

Compute the boundary loops of a triangle mesh, holes included: edges used by a single cell, chained following the cells winding.

Kind: static method of geomExtrude Returns: Array.<Array.<number>> - PolylineComplex cells: closed loops repeat their first index.

| Param | Type | Description | | ----------- | ---------------------------------------------- | -------------------------------------------------- | | cells | TypedArrayLike | Consistently wound triangles over welded vertices. | | vertexCount | number | |

geomExtrude.computeProfile(shape, [options]) ⇒ Profile

Analyze a planar shape: the side it faces, its cap triangles and its wall loops, holes included.

Only direction, ignoreSeams and closed options apply.

Kind: static method of geomExtrude

| Param | Type | Default | | --------- | -------------------------------------------------------------------------------------------------------- | --------------- | | shape | SimplicialComplex | PolylineComplex | | | [options] | GeomExtrudeOptions | {} |

geomExtrude.computeCapUvs(positions, profile, [mapping]) ⇒ Float32Array

Compute cap uvs in the profile plane, scaled to its longest loop so they match walls wrapping u once around each loop.

Caps don't split vertices: angle based mappings (eg. polar) show a wrap seam.

Kind: static method of geomExtrude

| Param | Type | Default | | --------- | ------------------------------------------ | ------------------------------------- | | positions | Float32Array | | | profile | Profile | | | [mapping] | CapMappingFn | mappings.circumferential |

geomExtrude.computeColumns(positions, loops, normal, [creaseAngle]) ⇒ Columns

Compute the wall cross-section of profile loops: columns shared by adjacent edges, split at creases and at the u seam of closed loops.

Kind: static method of geomExtrude

| Param | Type | Default | Description | | ------------- | ----------------------------------------------- | ------------------------ | --------------------------------------------------------- | | positions | Float32Array | | | | loops | Array.<Array.<number>> | | Profile loops. | | normal | Array.<number> | | Profile facing normal. | | [creaseAngle] | number | Math.PI / 6 | Turns sharper than this angle (in radians) split columns. |

geomExtrude.stitchRings(out, columns, options) ⇒ number

Write the wall triangles between consecutive rings of columns. Ring vertices are laid out ring after ring, column after column.

Kind: static method of geomExtrude Returns: number - Index in out after the last written triangle index.

| Param | Type | Default | Description | | ---------------------- | ---------------------------------------------- | ------------------ | ------------------------------------------- | | out | TypedArrayLike | | Cells to write into. | | columns | Columns | | | | options | object | | | | options.ringCount | number | | | | [options.closed] | boolean | false | Also stitch the last ring to the first one. | | [options.vertexOffset] | number | 0 | Index of the first ring vertex. | | [options.cellOffset] | number | 0 | Index in out of the first triangle index. | | [options.flip] | boolean | false | Reverse the triangles winding. |

TypedArrayLike : Array.<number> | Uint8Array | Uint16Array | Uint32Array

Kind: global typedef

PlaneDirection : "x" | "-x" | "y" | "-y" | "z" | "-z"

Kind: global typedef

SimplicialComplex : object

Triangle cells over shared positions.

Kind: global typedef Properties

| Name | Type | | --------- | ------------------------------------------------------------------------------- | | positions | Float32Array | | [normals] | Float32Array | | [uvs] | Float32Array | | cells | Uint8Array | Uint16Array | Uint32Array |

VertexAttributes : Object.<string, ArrayLike.<any>>

Other flat per-vertex arrays (eg. vertexColors), copied to the extruded geometry.

Kind: global typedef

PolylineComplex : object

Polyline cells over shared positions: each cell is an open polyline; closed loops repeat their first index at the end.

Kind: global typedef Properties

| Name | Type | | --------- | ------------------------------------------------------------ | | positions | Float32Array | | cells | Array.<TypedArrayLike> |

VertexAttribute : object

Kind: global typedef Properties

| Name | Type | Description | | ------ | ---------------------------------- | ---------------------- | | name | string | | | source | ArrayLike.<any> | | | size | number | Components per vertex. |

SimplicialShape : SimplicialComplex | VertexAttributes

Kind: global typedef

PolylineShape : PolylineComplex | VertexAttributes

Kind: global typedef

Profile : object

A planar shape analyzed for extrusion.

Kind: global typedef Properties

| Name | Type | Description | | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | normal | Array.<number> | Side the shape faces. | | cells | TypedArrayLike | Cap triangles, counter-clockwise around the normal. | | loops | Array.<Array.<number>> | Wall loops. Closed ones repeat their first index and wind counter-clockwise around solids, clockwise around holes. |

Columns : object

Wall cross-section of profile loops.

Kind: global typedef Properties

| Name | Type | Description | | ------------ | ------------------------- | ------------------------------------------------ | | shapeIndices | Uint32Array | Shape vertex of each column. | | normals | Float32Array | Wall normal of each column, in the shape plane. | | u | Float32Array | Distance along its loop over the loop perimeter. | | cells | Uint32Array | Pairs of columns, one per loop edge. |

CapMappingFn : function

Kind: global typedef

| Param | Type | Description | | -------------------------- | ------------------------- | ----------------------------------------------------- | | mappingOptions | object | | | mappingOptions.uvs | Float32Array | | | mappingOptions.index | number | | | mappingOptions.x | number | In the shape plane, from its bounds center. | | mappingOptions.y | number | | | mappingOptions.u | number | x scaled so the shape fits the unit disc. | | mappingOptions.v | number | y scaled so the shape fits the unit disc. | | mappingOptions.radius | number | Half the bounds largest side. | | mappingOptions.t | number | Angle around the bounds center, within [0, 2π). | | mappingOptions.radiusRatio | number | Distance from the bounds center over the largest one. | | mappingOptions.thetaRatio | number | t within [0, 1). | | mappingOptions.perimeter | number | Longest boundary loop length. |

GeomExtrudeOptions : object

Kind: global typedef Properties

| Name | Type | Default | Description | | -------------- | ------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [thickness] | number | 1 | Distance from the start cap to the end cap, away from the facing side. Negative values extrude towards it. | | [direction] | PlaneDirection | "auto" | "z" | Side the shape faces, matching its cells winding. "auto" derives it from the cells. | | [center] | boolean | false | Straddle the shape plane instead of starting from it. | | [capStart] | boolean | true | Cap on the shape side. | | [capEnd] | boolean | true | Cap on the extruded side. | | [capMapping] | CapMappingFn | mappings.circumferential | Overrides the shape uvs. Defaults to primitive-geometry's mappings.circumferential when the shape has none: undistorted, at the walls u scale. | | [creaseAngle] | number | Math.PI / 6 | Turns of the boundary sharper than this angle (in radians) keep hard wall edges. | | [ignoreSeams] | boolean | true | Treat vertices at the exact same position as connected when finding the boundary, so split seams (eg. mergeSeam: false) don't get walls. Caps keep their split vertices. | | [closed] | boolean | "auto" | "auto" | Close PolylineComplex cells into capped loops. "auto" only closes the ones ending on their first index or position. | | [wallSegments] | number | 1 | Subdivisions of the walls from the start cap to the end cap. |

License

MIT. See license file.