Three.js Low Poly

Procedural tooling and parametric modeling for Three.js

Example Library scene

See the example gallery for the full catalog of geometry, factory, reference, and studies.

Getting started

npm i three-low-poly

Everything follows the same shape you already know from Three.js: construct with an options object, add it to the scene

Geometry

The primary intent of the library: parametric BufferGeometry subclasses you pair with your own material and mesh, exactly like Three.js's built-in primitives.

import { Mesh, MeshStandardMaterial } from "three";
import { StarGeometry } from "three-low-poly";

const geometry = new StarGeometry({ points: 5, innerRadius: 0.5, outerRadius: 1 });
const material = new MeshStandardMaterial({ color: "#ffcc33", flatShading: true });
const star = new Mesh(geometry, material);
scene.add(star);

Factory

this library favors merged geometry, material groups, and instancing so dense procedural scenes stay batch-friendly

import { scatterMossyRocks } from "three-low-poly";

const rocks = scatterMossyRocks({ count: 12, width: 8, depth: 8, seed: 1337 });
scene.add(rocks);

Effect

Atmospheric layers animate off elapsed seconds — add them to the scene and call update(dt) each frame.

import { RainEffect } from "three-low-poly";

const rain = new RainEffect({ area: 12, height: 16, intensity: 0.45 });
scene.add(rain);

function animate(dt) {
  rain.update(dt);
  renderer.render(scene, camera);
}

Vocabulary and Terminology

Spatial & Kinematic Offsets

• Lean: Rotation relative to the resting vertical axis (pitch/roll). Represents tipping away from an upright rest state without requiring a fixed horizontal axis.
• Twist: Rotation about the vertical axis (yaw/heading). Represents facing a direction or re-orienting in place rather than deforming.
• Sink: Downward vertical displacement ($-Y$). A surface-aware offset that represents bedding or burying past a resting seat rather than an arbitrary raw translation.
• Drift: Planar displacement across the horizontal plane ($XZ$). Represents wandering away from a designated home point rather than a pair of disconnected coordinates.

Directional & Relational Dimensions

• Rise: Additive vertical dimension measured upward from a lower reference point. Total height is derived from this addition.
• Drop: Subtractive vertical dimension measured downward from a top reference point. Inner clearance is derived by subtraction.
• Gap: Edge-to-edge (clearance) distance between adjacent elements in a series.
• Inset: Subtractive horizontal dimension measured inward from an outer boundary. Inner width is derived by subtraction.
• Proud: Positioned forward of, or projecting outward from, a flush reference surface.
• Pitch: Center-to-center distance between repeating elements or features in a series.

Architectural & Profile Geometry

• Springing: The height or datum line on an arch where the curve departs from the vertical supports (jambs).
• Sprung: An installation state where a profile (such as crown molding) sits tilted across an interior angle, leaving a void behind it.
• Rake: An intentional incline, slope, or departure from the horizontal or vertical.
• Sweep: The path, curve, or motion vector along which a cross-section profile is extruded or revolved.
• Cyma: An S-shaped (ogee) architectural molding profile combining a convex and a concave curve.

Repetition & Progression

• Rank: An ordered series of related elements treated as a single geometric arrangement, typically varying progressively in scale, form, or position.
• Progression: The rule or function governing continuous variation across a rank, such as linear, geometric, logarithmic, or eased change.
• Cadence: The discrete rhythm of a progression: the count, interval, or stepping by which successive members are sampled or placed.
• Course: A single linear or horizontal pass of elements within a larger arrangement, borrowed from masonry and construction.
• Pitch: Center-to-center distance between successive repeating elements.

Spatial Domain & Bounds

• Envelope: The bounded 3D extent containing or constraining a geometric distribution, represented by a box, hull, sphere, or arbitrary volume.
• Field: A continuous spatial domain in which a value or influence is evaluated as a function of position, such as distance, density, potential, or noise.
• Footprint: The bounded 2D area occupied by, supporting, or constraining geometry when projected onto its reference plane.
• Margin: A prescribed clearance measured inward or outward from a boundary.
• Girth: The circumference or perimeter around a body or cross-section; a measure of extent rather than clearance.

Distribution & Aggregation

• Gather: An attractive distribution in which elements converge toward one or more focal regions, producing localized concentrations and potentially overlapping mass.
• Clump: A localized high-density grouping produced by attraction, proximity, or shared spatial influence.
• Strew: A naturalistic, non-grid distribution of elements across a region without obvious alignment or regularity.
• Scatter: A general distribution of discrete elements across a region according to random, stochastic, or procedural placement.
• Repulsion: A spatial constraint or influence that drives neighboring elements apart to maintain separation.
• Clearance: The minimum permitted edge-to-edge distance between neighboring elements.
• Packing: The arrangement of elements within a bounded region subject to contact, clearance, density, or overlap constraints.

Extremities & Convergence

• Apex: A terminal point or summit where edges, faces, or profiles converge opposite a base, as at the tip of a cone, pyramid, or pointed arch.
• Base: The supporting face, edge, loop, or footprint opposite an apex or upper extremity.
• Cusp: A singular point where a curve or surface converges sharply or changes direction; may form an inward or outward extremity.
• Tip: The terminal or outermost point of a narrow, tapered, or projecting feature.
• Peak: A localized maximum or summit, generally considered relative to surrounding geometry.

Ridges, Valleys & Surface Form

• Crest: A narrow summit or line of maximum elevation along a profile, wave, thread, tooth, or surface.
• Ridge: An elongated region of locally maximal elevation extending along a surface.
• Root: The innermost or lowest region between adjacent projecting features, particularly teeth, threads, splines, and similar repeated profiles.
• Trough: An elongated region of locally minimal elevation, opposite a crest or ridge.
• Valley: A concave region lying between neighboring elevated regions or ridges.
• Crown: A broad convex rise, camber, or domed summit region of a surface rather than a singular point or narrow ridge.

Usage

Nouns describe structure and spatial relationships, verbs describe operations on form.

• gather a rank across a footprint
• apply a progression with a given cadence and pitch
• crown the profile
• inset the footprint
• sink the resulting geometry
• rake the course

Geometry Symbols & Glyphs

Compact reference for geometric notation, diagram glyphs, computational geometry, and 2D / 3D graphics.

Visual Geometry Glyphs

| | Glyphs | | Glyphs | | ------------------- |---------------------| ----------------- | ------------------------------- | | Axis / Dashed | ╎ ┆ ┊ │ | Arc Quadrants | ◜ ◝ ◞ ◟ | | Lines | ─ │ ━ ┃ | Arcs | ⌒ ⌓ ◠ ◡ | | Rounded Corners | ╭ ╮ ╰ ╯ | Half Circles | ◖ ◗ | | Square Corners | ┏ ┓ ┗ ┛ | Wedges | ◔ ◑ ◕ ◴ ◵ ◶ ◷ | | Junctions | ┼ ├ ┤ ┬ ┴ | Triangles | ▲ ▼ ◀ ▶ ◬ ◭ ◮ | | Diagonals | ╱ ╲ ⟋ ⟍ ╳ | Quadrants | ◢ ◣ ◤ ◥ | | Vector Turns | ↳ ↵ ↱ ⤢ ⤡ | Circles | ● ○ | | Rotation | ↻ ↺ ↷ ↶ ⤸ | Diamonds | ◆ ◇ ◊ | | Markers | ⌖ ✛ | Polygons | ⬟ ⬢ ⬠ ⬡ | | Quads | ▰ ▱ ⏢ | Directional | ↖ ↑ ↗ ← → ↙ ↓ ↘ |

Geometric Relationships & Measurement

| Symbol | Glyph | Common Geometric / 3D Use | | -------------------------- |:-------:| -------------------------------------------------------- | | Angle | ∠ | General angle notation | | Measured Angle | ∡ | Angle with an indicated measurement | | Spherical Angle | ∢ | Spherical or spatial angle | | Right Angle | ∟ | Right angle, $90^\circ$ | | Perpendicular | ⟂ | Perpendicular lines, orthogonal vectors, surface normals | | Parallel | ∥ ⫽ | Parallel lines or vectors | | Not Parallel | ∦ | Non-parallel relationship | | Congruent | ≅ | Congruent geometric objects | | Similar | ∼ ≃ | Geometric similarity | | Identical / Equivalent | ≡ | Identity or equivalence | | Degree | ° | Angular measurement in degrees | | Prime | ′ | Arcminutes; feet in dimensional notation | | Double Prime | ″ | Arcseconds; inches in dimensional notation | | Diameter | ⌀ | Diameter of a circle, cylinder, hole, etc. | | Radius | r R | Radius of a circle, sphere, arc, fillet, etc. |

Angles, Rotation & Trigonometry

| Symbol | Glyph | Common Geometric / 3D Use | | --------- | :---------: | ---------------------------------------------------------------------------------- | | Theta | θ Θ | Primary planar or polar angle; rotation about an axis | | Phi | φ ϕ Φ | Azimuth or polar angle in spherical coordinates; convention varies | | Alpha | α | Triangle angle; generic angular parameter | | Beta | β | Triangle angle; generic angular parameter | | Gamma | γ | Triangle angle; Euler rotation | | Delta | δ Δ | Change or difference; $\Delta x$, $\Delta y$, $\Delta\theta$ | | Omega | ω Ω | Angular velocity; solid angle | | Psi | ψ | Angular parameter; sometimes yaw or orientation | | Rho | ρ | Radial distance in polar or spherical coordinates | | Pi | π | Half turn, $180^\circ$; radians and circular geometry | | Tau | τ | Full turn, $360^\circ = 2\pi$; also commonly torque | | Sigma | σ | Surface/area-related quantities; stress or standard deviation depending on context |

Circular Geometry

| Symbol | Glyph | Common Geometric / 3D Use | | --------------------- | :-------------: | -------------------------------------- | | Radius | r R | Distance from center to circumference | | Diameter | d D ⌀ | Full width through the center | | Circumference | C | Circumference of a circle | | Arc Length | s | Length along a circular or curved path | | Angle | θ | Central or swept angle | | Pi | π | $\pi$ radians = half turn | | Tau | τ | $\tau = 2\pi$ radians = full turn | | Arc | ⌒ ⌓ | Visual arc / circular segment notation | | Upper / Lower Arc | ◠ ◡ | Diagrammatic convex / concave arc | | Half Circle | ◖ ◗ | Semicircular regions | | Quadrant Arc | ◜ ◝ ◞ ◟ | Quarter-circle curves |

Mesh & Topology

| Symbol | Glyph / Notation | Common Geometric / 3D Use | | ------------------ | :----------------: | ----------------------------------------- | | Vertex | v v₀ v₁ v₂ | Point belonging to a mesh | | Vertex Set | V | Set of all mesh vertices | | Edge | e e₀₁ | Connection between two vertices | | Edge Set | E | Set of all mesh edges | | Face | f f₀ | Polygonal mesh face | | Face Set | F | Set of all mesh faces | | Triangle | △ABC ΔABC | Triangle defined by three vertices | | Mesh | M | Polygonal or triangular mesh | | Boundary | ∂M | Boundary of a mesh, surface, or region | | Element Of | ∈ | Membership, e.g. $v \in V$ | | Not Element Of | ∉ | Non-membership | | Union | ∪ | Combination of sets or geometric regions | | Intersection | ∩ | Intersection of sets or geometric regions |

Vectors & Coordinate Frames

| Symbol | Glyph / Notation | Common Geometric / 3D Use | | ----------------- | :--------------: | ------------------------------------------------ | | Position | p p | Point or position vector | | Direction | d d | Direction vector | | Normal | n n | Surface or vertex normal | | Tangent | t t | Tangent direction along a curve or surface | | Bitangent | b b | Secondary tangent direction; tangent-space basis | | Up | u u | Local or world up direction | | Right | r r | Local right direction | | Forward | f f | Local forward/view direction | | Vector | v⃗ | Generic directed quantity | | Unit Vector | v̂ | Normalized vector | | Magnitude | ‖v‖ | Vector length | | Dot Product | a · b | Projection, angle, orthogonality | | Cross Product | a × b | Perpendicular vector; normals and orientation |

Coordinates & Parametric Geometry

| Symbol | Glyph / Notation | Common Geometric / 3D Use | | --------------------------------- | :--------------: | ------------------------------------------- | | Cartesian Coordinates | x y z | Position along coordinate axes | | Texture / Surface Coordinates | u v | 2D parameterization of a surface | | Parameter | t | Position along a curve or interpolation | | Interval | t ∈ [0,1] | Normalized interpolation or parameter range | | Curve | C(t) | Parametric curve | | Surface | S(u,v) | Parametric surface | | Derivative | C′(t) | Curve derivative / tangent | | Partial Derivative | ∂S/∂u ∂S/∂v | Surface tangent directions | | Gradient | ∇f | Direction of greatest scalar-field increase | | Nabla | ∇ | Gradient and other differential operators |

Transform & Rotation

| Symbol | Glyph / Notation | Common Geometric / 3D Use | | -------------------- | :--------------: | ---------------------------------------- | | Translation | T | Translation transform or matrix | | Rotation | R | Rotation transform or matrix | | Scale | S | Scale transform or matrix | | Transform | M | General transformation matrix | | Identity | I | Identity matrix / transform | | Inverse | M⁻¹ | Inverse transformation | | Transpose | Mᵀ | Matrix transpose; normal transformations | | Quaternion | q | 3D orientation / rotation | | Angle | θ | Rotation angle | | Axis | â | Unit rotation axis | | Clockwise | ↻ ↷ | Clockwise rotation | | Counterclockwise | ↺ ↶ | Counterclockwise rotation |

Operators & Relations

| Symbol | Glyph | Common Geometric / Computational Use | | --------------------------- | :-----: | --------------------------------------- | | Approximately Equal | ≈ | Floating-point or approximate equality | | Not Equal | ≠ | Inequality | | Less / Greater | < > | Ordering, bounds, winding tests | | Less / Greater or Equal | ≤ ≥ | Bounds and constraints | | Plus / Minus | ± | Positive/negative offset or tolerance | | Proportional To | ∝ | Proportional geometric relationship | | Infinity | ∞ | Unbounded distance, limits | | Element Of | ∈ | Set membership | | Maps To | ↦ | Mapping one coordinate/value to another | | Arrow | → | Direction, transformation, mapping | | Therefore | ∴ | Logical consequence | | Because | ∵ | Logical justification |

Compact Glyph Palette

For quick copying while constructing diagrams:

• Lines — ─ │ ━ ┃ ╎ ┆ ┊
• Corners — ╭ ╮ ╰ ╯ ┏ ┓ ┗ ┛
• Junctions — ┼ ├ ┤ ┬ ┴
• Diagonals — ╱ ╲ ⟋ ⟍╳
• Arcs — ⌒ ⌓ ◠ ◡ ◜ ◝ ◞ ◟
• Circular — ◖ ◗ ◔ ◑ ◕ ◴ ◵ ◶ ◷
• Triangles — ▲ ▼ ◀ ▶ ◬ ◭ ◮ ◢ ◣ ◤ ◥
• Shapes — ● ○ ◆ ◇ ◊ ⬟ ⬢ ⬠ ⬡ ▰ ▱ ⏢
• Turns — ↳ ↵ ↱ ⤢ ⤡
• Rotation — ↻ ↺ ↷ ↶ ⤸
• Direction — ↖ ↑ ↗ ← → ↙ ↓ ↘
• Markers — ⌖ ✛
• Angles — ∠ ∡ ∢ ∟
• Relations — ⟂ ⊥ ∥ ∦ ≅ ∼ ≃ ≡
• Circular Measures — r R d D ⌀ π τ θ °
• Greek / Angular — θ Θ φ ϕ Φ α β γ δ Δ ω Ω ψ ρ σ τ π
• Vector / Math — · × ‖ ‖ ∇ ∂ ∈ ∉ ∪ ∩ ≈ ≠ ≤ ≥ ± ∝ ∞

Symbology

Coordinate Axes

  Local Space       Basic Axes       Labeled Axes                Negative Directions

      +Y                Y                Y (up)                         +Y
       |                |                |                               |
       |   +X           |                |                               |
       o----->          +---- X          o------- X (right)        -X ---+--- +X
      /                /                /                               /|
    +Z                /                /                               / |
                     Z                Z (forward)                    +Z  |
                                                                        -Y

Mesh Topology

   Vertex           Edge                Face           UV Space          Triangle Shape     Center Division

     v0         v0 ------- v1            v1            (0,1)                   ^                   .
                                        /  \             +                    / \                 /|\
                                       /    \            |\                  /   \               / | \
                                      /      \           | \                /     \             /  |  \
                                    v0 ------ v2         |  \              /       \           /   |   \
                                                         +---+            +---------+         +----+----+
                                                       (0,0) (1,0)


   Standard Quad        Subdivided Quad       Triangle Strip       Quad Strip       Indexed Mesh

   v0 -------- v1        v0 -------- v1        ●───●───●            ●───●───●           0────1
   |         / |         | \       / |          ╲ ╱ ╲ ╱             │   │   │           │  ╱ │
   |       /   |         |   \   /   |           ●───●              ●───●───●           │ ╱  │
   |     /     |         |     C     |                                                  3────2
   |   /       |         |   /   \   |
   | /         |         | /       \ |
   v3 -------- v2        v3 -------- v2
                                                            Cube            Labeled Vertices

  Plane                      Plane Subdivisions           +-------+           4 -------- 7
                                                         /|      /|          /|         /|
  v0 ----------- v1          0 --- 1 --- 2 --- 3        + +-----+ |         5 -------- 6 |
   |              |          |     |     |     |        | |     | |         | |        | |
   |              |          4 --- 5 --- 6 --- 7        | +-----|-+         | 0 -------|-3
   |              |          |     |     |     |        |/      |/          |/         |/
  v3 ----------- v2          8 --- 9 -- 10 -- 11        +-------+           1 -------- 2

Plots

      Sweep           Parametric Curve           Mapping              Parameter Space       Parametric Surface

                                                                    v ↑                        v ↑
   ●───╮                ●──╮                      (u,v)               | +---+                    │   ╱────╱
       ╰──╮                ╰──╮                     │                 | |   |                    │  ╱────╱
          ╰──→                ╰──●           ───────┼───────→         | +---+                    │ ╱────╱
                                                    │                 +------→ u                 └──────→ u


       Cartesian                 Vector Field                 Screen Space / UV Coordinate           Cartesian
                                 (● = Singularity)
    +Y ▲                                                    (0,0) ┌─────────────────► +U            ▲ +Y
   100 ┼      ● (x2,y2)       Y ▲                                 │                                 │
       │     ╱                  │  ↗   ↑   ↑   ↖   ←              │   (u, v)                        │    (x, y)
    50 ┼    ● (x1,y1)           │  →   ↗   ↑   ↖   ←              │     ●────────┐                  │      ┌────────┐
       │   ╱                    │  →   →   ●   ←   ←              │     │ Bounds │                  │      │ Bounds │
     0 └───┼───┼──► +X          │  →   ↘   ↓   ↙   ←              │     └────────┘                  │      ●────────┘
       0  50  100               │  ↘   ↓   ↓   ↙   ←              │                                 │
                              0 └───────────────────► X           ▼ +V                        (0,0) └──────────────────► +X

Structure

This repository contains three-low-poly, a Three.js npm SDK.

• src/ contains the distributable library;
• app/ is a separate Vite host for examples, references, galleries, and studies.

Conventions

tbd.

Units

• Localization: EN-US
• Radians
• Metric: meters and millimeters

Approach

Separation of shape, geometric intent, and construction of cohesive entities.

• Geometry: intrinsic renderable shape
• Profiles: reusable computational shape or boundary
• Factories: spatial or relational composition, variation, batching
• Assemblies: relationships between independent parts
• Options: local definitions composed through ownership
• Variation:

This separation keeps individual geometry APIs small while allowing complex assets and large procedural assemblies to remain cohesive from the caller's perspective.

Geometry

Geometry classes describe independently meaningful shape.

They follow the conventions of Three.js built-ins such as BoxGeometry, LatheGeometry, and ExtrudeGeometry which are immutable after construction. Parameters are for initialization only.

A geometry:

• produces BufferGeometry
• is complete after construction
• contains no scene placement or runtime behavior
• translates to set its anchor origin point
• knows only about its own shape
• may expose parameters needed by higher-level construction
• may use geometry groups when one cohesive shape requires multiple materials

The relationship between independently valid geometries belongs to construction.

Composite Geometry

Some domain objects are naturally represented as one BufferGeometry even when they contain several distinct parts.

• A book combines cover and pages geometry
• A pumpkin combines rind and stem geometry
• A tree combines trunk and leaf geometry

The parts can be authored independently, transformed into their assembled positions, and merged using geometry groups.

The result remains one cohesive geometry:

const geometry = new PumpkinGeometry(options);

const mesh = new Mesh(geometry, [
  rindMaterial,
  stemMaterial,
]);

This is appropriate when the finished object is fundamentally geometric and does not require independently addressable scene objects.

Profiles

Profiles are computational geometry rather than renderable geometry.

They describe reusable boundaries, silhouettes, sections, paths, or other mathematical forms that can participate in multiple construction operations.

A profile may be used to derive:

• shape
• path
• extrusion
• sweep
• loft
• cut

Profiles are especially useful when several parts must agree on the same geometric definition.

For example, an arched window may derive all of the following from one profile:

                         ArchProfile
                              │
             ┌────────────────┼────────────────┐
             │                │                │
             ▼                ▼                ▼
        wall opening       glass pane        frame
                                               │
                                  ┌────────────┼────────────┐
                                  ▼            ▼            ▼
                                jamb        lattice        sill

The profile is not merely an implementation helper, it is the shared geometric intent from which related geometry can be constructed consistently.

Factories

Factories resolve construction or one or many entities.

A factory is used when producing an entity requires knowledge beyond the responsibility of a single geometry.

Construction may include:

• combining independent geometries
• resolving contact or seating relationships
• deriving several geometries from a shared profile
• producing cuts or boundaries for external geometry
• creating meshes and material assignments
• creating Group or InstancedMesh structures
• generating stochastic variation
• batching repeated geometry
• baking transforms into unique geometry
• attaching lights, sprites, effects, or other scene resources
• coordinating behavior intrinsic to the constructed entity

Each call expresses domain intent. The factory chooses the scene representation required to implement it.

Assembly

Assembly describes how independently valid parts relate to one another.

This knowledge belongs to neither component.

For example, placing a Florence flask onto a ring stand requires knowing both:

• the flask's spherical body radius
• the stand's ring radius

The factory can solve the contact relationship and position the flask so the sphere rests correctly on the ring.

Geometry                    Assembly
───────────────────────     ─────────────────

FlorenceFlaskGeometry ─┐
                       ├──► FlaskStandFactory ──► Assembled Entity
RingStandGeometry ─────┘

The same principle applies to:

• seating a pumpkin stem on a rind
• positioning a candle within a lantern
• fitting a liquid volume inside a vessel
• matching a jamb to wall thickness
• placing decorative geometry against a generated boundary

Where possible, relational placement should remain expressible as transforms rather than being permanently embedded into the source geometry.

Examples

Every feature has a matching example in the host gallery,

Text

The Vite app host provides canvas-based text utilities with shared sizing and rendering:

• createTextSprite() creates billboard labels that always face the camera.
• createTextPlane() creates fixed-orientation labels that rotate with their geometry or parent.

Studies

Advanced experimentation belongs in studies.

Studies are durable, isolated explorations. They can prototype an idea, investigate a problem, compare approaches, or demonstrate a particular application. They may call SDK functions, but keep the code essential to the investigation inline when that preserves the idea independently of future SDK changes.

A study may remain an exploration, contribute selected pieces to the SDK while remaining intact, or move into production when the whole study becomes the product. Overlap with production code is not, by itself, a reason to remove or refactor a study.

References primarily explain established behavior; galleries compare named forms or profiles. These boundaries are flexible — a study can also become a useful reference.

Author

Jason Sturges