@woosh/meep-engine 3.42.0 → 3.44.0

package/src/shade/renderer/geometry/UVSphereGeometry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sphere of rings and meridians with its poles on the Y axis, ready to render. Constructs a regular
+ * triangulated `Geometry` and immediately converts it to the meshlet representation the renderer
+ * consumes.
+ *
+ * @see make_uv_sphere_geometry
+ */
+export class UVSphereGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius]
+     * @param {number} [widthSegments] segments around the axis, at least 3
+     * @param {number} [heightSegments] segments from pole to pole, at least 2
+     * @param {number} [phiStart]
+     * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+     * @param {number} [thetaStart] where to start, in radians down from the north pole
+     * @param {number} [thetaLength] how far toward the south pole to build, in radians
+     */
+    constructor(radius?: number, widthSegments?: number, heightSegments?: number, phiStart?: number, phiLength?: number, thetaStart?: number, thetaLength?: number);
+}
+import { MeshletGeometry } from "./MeshletGeometry.js";
+//# sourceMappingURL=UVSphereGeometry.d.ts.map

package/src/shade/renderer/geometry/UVSphereGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UVSphereGeometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/UVSphereGeometry.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IACI;;;;;;;;OAQG;IACH,qBARW,MAAM,kBACN,MAAM,mBACN,MAAM,aACN,MAAM,cACN,MAAM,eACN,MAAM,gBACN,MAAM,EAahB;CACJ;gCAhC+B,sBAAsB"}

package/src/shade/renderer/geometry/UVSphereGeometry.js

@@ -0,0 +1,34 @@
+import { meshlet_geometry_build_from_geometry } from "./meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "./MeshletGeometry.js";
+import { make_uv_sphere_geometry } from "./primitives/make_uv_sphere_geometry.js";
+
+/**
+ * Sphere of rings and meridians with its poles on the Y axis, ready to render. Constructs a regular
+ * triangulated `Geometry` and immediately converts it to the meshlet representation the renderer
+ * consumes.
+ *
+ * @see make_uv_sphere_geometry
+ */
+export class UVSphereGeometry extends MeshletGeometry {
+    /**
+     * @param {number} [radius]
+     * @param {number} [widthSegments] segments around the axis, at least 3
+     * @param {number} [heightSegments] segments from pole to pole, at least 2
+     * @param {number} [phiStart]
+     * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+     * @param {number} [thetaStart] where to start, in radians down from the north pole
+     * @param {number} [thetaLength] how far toward the south pole to build, in radians
+     */
+    constructor(
+        radius = 1,
+        widthSegments = 32,
+        heightSegments = 16,
+        phiStart = 0,
+        phiLength = Math.PI * 2,
+        thetaStart = 0,
+        thetaLength = Math.PI
+    ) {
+        super();
+        meshlet_geometry_build_from_geometry(make_uv_sphere_geometry(radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength), this);
+    }
+}

package/src/shade/renderer/geometry/primitives/make_capsule_geometry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A capsule along the Y axis, centred on the origin: a cylinder of length `height` closed by two
+ * hemispheres of `radius`, so the whole body spans `height + 2 * radius`. That is the same shape
+ * `CapsuleShape3D` describes for the same two numbers, so a collider and its mesh agree.
+ *
+ * The texture coordinates wrap `u` once around the axis and run `v` from the south pole (0) to the
+ * north pole (1) by arc length along the profile, so a texture is not stretched over the caps
+ * relative to the straight section.
+ *
+ * @param {number} [radius]
+ * @param {number} [height] length of the straight section, not counting the caps
+ * @param {number} [capSegments] segments from each pole to the equator, at least 1
+ * @param {number} [radialSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments along the straight section, at least 1 unless `height` is zero
+ * @returns {Geometry}
+ */
+export function make_capsule_geometry(radius?: number, height?: number, capSegments?: number, radialSegments?: number, heightSegments?: number): Geometry;
+import { Geometry } from "../Geometry.js";
+//# sourceMappingURL=make_capsule_geometry.d.ts.map

package/src/shade/renderer/geometry/primitives/make_capsule_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_capsule_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_capsule_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,+CAPW,MAAM,WACN,MAAM,gBACN,MAAM,mBACN,MAAM,mBACN,MAAM,GACJ,QAAQ,CA0LpB;yBA3MwB,gBAAgB"}

package/src/shade/renderer/geometry/primitives/make_capsule_geometry.js

@@ -0,0 +1,205 @@
+import { Attribute } from "../Attribute.js";
+import { Geometry } from "../Geometry.js";
+import { StandardAttributes } from "../StandardAttributes.js";
+
+/**
+ * A capsule along the Y axis, centred on the origin: a cylinder of length `height` closed by two
+ * hemispheres of `radius`, so the whole body spans `height + 2 * radius`. That is the same shape
+ * `CapsuleShape3D` describes for the same two numbers, so a collider and its mesh agree.
+ *
+ * The texture coordinates wrap `u` once around the axis and run `v` from the south pole (0) to the
+ * north pole (1) by arc length along the profile, so a texture is not stretched over the caps
+ * relative to the straight section.
+ *
+ * @param {number} [radius]
+ * @param {number} [height] length of the straight section, not counting the caps
+ * @param {number} [capSegments] segments from each pole to the equator, at least 1
+ * @param {number} [radialSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments along the straight section, at least 1 unless `height` is zero
+ * @returns {Geometry}
+ */
+export function make_capsule_geometry(radius = 1, height = 1, capSegments = 4, radialSegments = 8, heightSegments = 1) {
+
+    /*
+     A port of three's `CapsuleGeometry` onto `Geometry`: the same parameterisation, the same
+     arc-length texture coordinates and the same winding, writing meep attributes instead of three
+     ones. It departs at the poles, see below.
+
+     Derived from three.js (https://github.com/mrdoob/three.js), Copyright (c) 2010-2024 three.js authors, MIT licence.
+    */
+
+    const geo = new Geometry();
+
+    geo.name = "Capsule";
+
+    // segments
+
+    height = Math.max(0, height);
+    capSegments = Math.max(1, Math.floor(capSegments));
+    radialSegments = Math.max(3, Math.floor(radialSegments));
+
+    // a straight section of no length would be bands of no area, so then there is none and the two
+    // caps meet at a single equator, which is a sphere
+    heightSegments = height > 0 ? Math.max(1, Math.floor(heightSegments)) : 0;
+
+    // buffers
+
+    const indices = [];
+    const vertices = [];
+    const normals = [];
+    const uvs = [];
+
+    // helper variables
+
+    const halfHeight = height / 2;
+    const capArcLength = (Math.PI / 2) * radius;
+    const totalArcLength = 2 * capArcLength + height;
+
+    // rows run from the south pole up to the north pole; the two equators belong to the straight
+    // section, so both of its ends sit exactly at +-halfHeight with a level normal
+    const lastRow = capSegments * 2 + heightSegments;
+
+    let index = 0;
+    const grid = [];
+
+    // generate vertices, normals and uvs
+
+    for (let iy = 0; iy <= lastRow; iy++) {
+
+        // the profile: the outward normal in the (radial, Y) half plane, the row's height and its
+        // arc length from the south pole
+
+        let normalRadial;
+        let normalY;
+        let profileY;
+        let arcLength;
+
+        if (iy < capSegments) {
+
+            // southern cap, the angle measured up from the south pole
+
+            const angle = (iy / capSegments) * (Math.PI / 2);
+
+            normalRadial = Math.sin(angle);
+            normalY = -Math.cos(angle);
+            profileY = -halfHeight + radius * normalY;
+            arcLength = angle * radius;
+
+        } else if (iy <= capSegments + heightSegments) {
+
+            // straight section
+
+            const t = heightSegments > 0 ? (iy - capSegments) / heightSegments : 0;
+
+            normalRadial = 1;
+            normalY = 0;
+            profileY = -halfHeight + t * height;
+            arcLength = capArcLength + t * height;
+
+        } else {
+
+            // northern cap, the angle measured down from the north pole, so that the pole itself is
+            // an angle of exactly zero rather than a `Math.cos(Math.PI / 2)` that is not
+
+            const angle = ((lastRow - iy) / capSegments) * (Math.PI / 2);
+
+            normalRadial = Math.sin(angle);
+            normalY = Math.cos(angle);
+            profileY = halfHeight + radius * normalY;
+            arcLength = totalArcLength - angle * radius;
+
+        }
+
+        const profileRadius = radius * normalRadial;
+
+        const v = arcLength / totalArcLength;
+
+        // A ring at a pole is a single point. Three's grid still gives it a vertex per meridian,
+        // which puts two corners of every polar triangle on the same point. Here a pole holds one
+        // vertex per segment, turned to the middle of that segment, and each segment draws just the
+        // one triangle that has area; see `make_uv_sphere_geometry`, which does the same.
+        const pole = iy === 0 || iy === lastRow;
+
+        const rowVertexCount = pole ? radialSegments : radialSegments + 1;
+        const uOffset = pole ? 0.5 : 0;
+
+        const verticesRow = [];
+
+        for (let ix = 0; ix < rowVertexCount; ix++) {
+
+            const u = (ix + uOffset) / radialSegments;
+
+            const theta = u * Math.PI * 2;
+
+            const sinTheta = Math.sin(theta);
+            const cosTheta = Math.cos(theta);
+
+            // vertex
+
+            vertices.push(-profileRadius * cosTheta, profileY, profileRadius * sinTheta);
+
+            // normal, from the profile's angles rather than by normalising, so it is unit length by
+            // construction and stays defined at radius zero
+
+            normals.push(-normalRadial * cosTheta, normalY, normalRadial * sinTheta);
+
+            // uv
+
+            uvs.push(u, v);
+
+            verticesRow.push(index++);
+
+        }
+
+        grid.push(verticesRow);
+
+    }
+
+    // indices
+
+    for (let iy = 1; iy <= lastRow; iy++) {
+
+        const lower = grid[iy - 1];
+        const upper = grid[iy];
+
+        for (let ix = 0; ix < radialSegments; ix++) {
+
+            if (iy === 1) {
+
+                // the segment's south pole vertex stands in for both lower corners
+
+                indices.push(lower[ix], upper[ix + 1], upper[ix]);
+
+            } else if (iy === lastRow) {
+
+                // the segment's north pole vertex stands in for both upper corners
+
+                indices.push(lower[ix], lower[ix + 1], upper[ix]);
+
+            } else {
+
+                const i1 = lower[ix];
+                const i2 = lower[ix + 1];
+                const i3 = upper[ix];
+                const i4 = upper[ix + 1];
+
+                // faces
+
+                indices.push(i1, i2, i3);
+                indices.push(i2, i4, i3);
+
+            }
+
+        }
+
+    }
+
+    // build geometry
+
+    geo.index = Attribute.from(new Uint32Array(indices), 1, 'index');
+    geo.addAttribute(Attribute.from(new Float32Array(vertices), 3, StandardAttributes.Position));
+    geo.addAttribute(Attribute.from(new Float32Array(normals), 3, StandardAttributes.Normal));
+    geo.addAttribute(Attribute.from(new Float32Array(uvs), 2, StandardAttributes.TextureCoordinates0));
+
+    return geo;
+}

package/src/shade/renderer/geometry/primitives/make_cone_geometry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @typedef {import("../Geometry.js").Geometry} Geometry
+ */
+/**
+ * The axis runs along Y with the apex at the top, and the body is centred on the origin.
+ *
+ * A cone is a cylinder whose top radius is zero, exactly as three's `ConeGeometry` is, so this is
+ * {@link make_cylinder_geometry} under its own name; the apex handling lives there.
+ *
+ * @param {number} [radius] radius of the base
+ * @param {number} [height]
+ * @param {number} [radialSegments] segments around the axis
+ * @param {number} [heightSegments] segments along the axis
+ * @param {boolean} [openEnded] leave the base off, which makes the surface a hollow shell rather than a solid
+ * @param {number} [thetaStart]
+ * @param {number} [thetaLength] how much of the turn to build, in radians
+ * @returns {Geometry}
+ */
+export function make_cone_geometry(radius?: number, height?: number, radialSegments?: number, heightSegments?: number, openEnded?: boolean, thetaStart?: number, thetaLength?: number): Geometry;
+export type Geometry = import("../Geometry.js").Geometry;
+//# sourceMappingURL=make_cone_geometry.d.ts.map

package/src/shade/renderer/geometry/primitives/make_cone_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_cone_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_cone_geometry.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,4CATW,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,GACJ,QAAQ,CAgBpB;uBAhCY,OAAO,gBAAgB,EAAE,QAAQ"}

package/src/shade/renderer/geometry/primitives/make_cone_geometry.js

@@ -0,0 +1,36 @@
+import { make_cylinder_geometry } from "./make_cylinder_geometry.js";
+
+/**
+ * @typedef {import("../Geometry.js").Geometry} Geometry
+ */
+
+/**
+ * The axis runs along Y with the apex at the top, and the body is centred on the origin.
+ *
+ * A cone is a cylinder whose top radius is zero, exactly as three's `ConeGeometry` is, so this is
+ * {@link make_cylinder_geometry} under its own name; the apex handling lives there.
+ *
+ * @param {number} [radius] radius of the base
+ * @param {number} [height]
+ * @param {number} [radialSegments] segments around the axis
+ * @param {number} [heightSegments] segments along the axis
+ * @param {boolean} [openEnded] leave the base off, which makes the surface a hollow shell rather than a solid
+ * @param {number} [thetaStart]
+ * @param {number} [thetaLength] how much of the turn to build, in radians
+ * @returns {Geometry}
+ */
+export function make_cone_geometry(
+    radius = 1,
+    height = 1,
+    radialSegments = 8,
+    heightSegments = 1,
+    openEnded = false,
+    thetaStart = 0,
+    thetaLength = Math.PI * 2
+) {
+    const geo = make_cylinder_geometry(0, radius, height, radialSegments, heightSegments, openEnded, thetaStart, thetaLength);
+
+    geo.name = "Cone";
+
+    return geo;
+}

package/src/shade/renderer/geometry/primitives/make_cylinder_geometry.d.ts

@@ -4,7 +4,7 @@
  * `Geometry` carries no multi-material groups, so the torso and the two caps are one index run
  * rather than three; three's cylinder splits them only to address a material array.
  *
- * @param {number} [radiusTop]
+ * @param {number} [radiusTop] zero makes a cone, which is what `make_cone_geometry` does
  * @param {number} [radiusBottom]
  * @param {number} [height]
  * @param {number} [radialSegments] segments around the axis

package/src/shade/renderer/geometry/primitives/make_cylinder_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_cylinder_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_cylinder_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,mDAVW,MAAM,iBACN,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,GACJ,QAAQ,CA6NpB;yBA9OwB,gBAAgB"}
+{"version":3,"file":"make_cylinder_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_cylinder_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,mDAVW,MAAM,iBACN,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,GACJ,QAAQ,CAgQpB;yBAjRwB,gBAAgB"}

package/src/shade/renderer/geometry/primitives/make_cylinder_geometry.js

@@ -8,7 +8,7 @@ import { StandardAttributes } from "../StandardAttributes.js";
  * `Geometry` carries no multi-material groups, so the torso and the two caps are one index run
  * rather than three; three's cylinder splits them only to address a material array.
  *
- * @param {number} [radiusTop]
+ * @param {number} [radiusTop] zero makes a cone, which is what `make_cone_geometry` does
  * @param {number} [radiusBottom]
  * @param {number} [height]
  * @param {number} [radialSegments] segments around the axis
@@ -31,7 +31,8 @@ export function make_cylinder_geometry(
 
     /*
      A port of three's `CylinderGeometry` onto `Geometry`: the same parameterisation and the same
-     winding, writing meep attributes instead of three ones.
+     winding, writing meep attributes instead of three ones. It departs at a cone's apex, see
+     `generateTorso`.
 
      Derived from three.js (https://github.com/mrdoob/three.js), Copyright (c) 2010-2024 three.js authors, MIT licence.
     */
@@ -56,6 +57,7 @@ export function make_cylinder_geometry(
 
     let index = 0;
     const indexArray = [];
+    const apexRows = [];
     const halfHeight = height / 2;
 
     // generate geometry
@@ -98,9 +100,21 @@ export function make_cylinder_geometry(
 
             const radius = v * (radiusBottom - radiusTop) + radiusTop;
 
-            for (let x = 0; x <= radialSegments; x++) {
+            // A row of zero radius is a cone's apex, where three's grid would put two corners of
+            // every segment's upper triangle on the same point and lean the other one's apex normal
+            // toward one edge. Instead the apex holds one vertex per segment, turned to the middle of
+            // that segment, and each segment draws just the one triangle that has area. The `u` is
+            // offset the same way, as three's own sphere does at its poles.
+            const apex = radius === 0;
 
-                const u = x / radialSegments;
+            apexRows.push(apex);
+
+            const rowVertexCount = apex ? radialSegments : radialSegments + 1;
+            const uOffset = apex ? 0.5 : 0;
+
+            for (let x = 0; x < rowVertexCount; x++) {
+
+                const u = (x + uOffset) / radialSegments;
 
                 const theta = u * thetaLength + thetaStart;
 
@@ -143,13 +157,34 @@ export function make_cylinder_geometry(
 
                 const a = indexArray[y][x];
                 const b = indexArray[y + 1][x];
-                const c = indexArray[y + 1][x + 1];
-                const d = indexArray[y][x + 1];
 
-                // faces
+                if (apexRows[y] && apexRows[y + 1]) {
+
+                    // both rows on the axis, so the band has no area
+
+                } else if (apexRows[y]) {
+
+                    // `a` is the segment's apex vertex and stands in for `d` as well
+
+                    indices.push(b, indexArray[y + 1][x + 1], a);
+
+                } else if (apexRows[y + 1]) {
+
+                    // `b` is the segment's apex vertex and stands in for `c` as well
+
+                    indices.push(a, b, indexArray[y][x + 1]);
+
+                } else {
+
+                    const c = indexArray[y + 1][x + 1];
+                    const d = indexArray[y][x + 1];
+
+                    // faces
+
+                    indices.push(a, b, d);
+                    indices.push(b, c, d);
 
-                indices.push(a, b, d);
-                indices.push(b, c, d);
+                }
 
             }
 

package/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A sphere of rings of latitude and meridians of longitude, centred on the origin with its poles on
+ * the Y axis. The texture coordinates are equirectangular: `u` runs once around the axis and `v`
+ * from the south pole (0) to the north pole (1).
+ *
+ * The two angular intervals cut a partial sphere: `phi` turns about the Y axis and `theta` runs
+ * down from the north pole, so a `thetaLength` of `Math.PI / 2` is a dome.
+ *
+ * @param {number} [radius]
+ * @param {number} [widthSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments from pole to pole, at least 2
+ * @param {number} [phiStart]
+ * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+ * @param {number} [thetaStart] where to start, in radians down from the north pole
+ * @param {number} [thetaLength] how far toward the south pole to build, in radians; stops at the pole
+ * @returns {Geometry}
+ */
+export function make_uv_sphere_geometry(radius?: number, widthSegments?: number, heightSegments?: number, phiStart?: number, phiLength?: number, thetaStart?: number, thetaLength?: number): Geometry;
+import { Geometry } from "../Geometry.js";
+//# sourceMappingURL=make_uv_sphere_geometry.d.ts.map

package/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_uv_sphere_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;GAgBG;AACH,iDATW,MAAM,kBACN,MAAM,mBACN,MAAM,aACN,MAAM,cACN,MAAM,eACN,MAAM,gBACN,MAAM,GACJ,QAAQ,CAkKpB;yBA5LwB,gBAAgB"}

package/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.js

@@ -0,0 +1,190 @@
+import { Attribute } from "../Attribute.js";
+import { Geometry } from "../Geometry.js";
+import { StandardAttributes } from "../StandardAttributes.js";
+
+/**
+ * How far short of `Math.PI`, in radians, a theta interval may end and still close at the south
+ * pole: four ulps of pi, room for the rounding of a sum of two or three rounded angles.
+ *
+ * @type {number}
+ */
+const SOUTH_POLE_TOLERANCE = 8 * Number.EPSILON;
+
+/**
+ * A sphere of rings of latitude and meridians of longitude, centred on the origin with its poles on
+ * the Y axis. The texture coordinates are equirectangular: `u` runs once around the axis and `v`
+ * from the south pole (0) to the north pole (1).
+ *
+ * The two angular intervals cut a partial sphere: `phi` turns about the Y axis and `theta` runs
+ * down from the north pole, so a `thetaLength` of `Math.PI / 2` is a dome.
+ *
+ * @param {number} [radius]
+ * @param {number} [widthSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments from pole to pole, at least 2
+ * @param {number} [phiStart]
+ * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+ * @param {number} [thetaStart] where to start, in radians down from the north pole
+ * @param {number} [thetaLength] how far toward the south pole to build, in radians; stops at the pole
+ * @returns {Geometry}
+ */
+export function make_uv_sphere_geometry(
+    radius = 1,
+    widthSegments = 32,
+    heightSegments = 16,
+    phiStart = 0,
+    phiLength = Math.PI * 2,
+    thetaStart = 0,
+    thetaLength = Math.PI
+) {
+
+    /*
+     A port of three's `SphereGeometry` onto `Geometry`: the same parameterisation and the same
+     winding, writing meep attributes instead of three ones. It departs at the poles, see below.
+
+     Derived from three.js (https://github.com/mrdoob/three.js), Copyright (c) 2010-2024 three.js authors, MIT licence.
+    */
+
+    const geo = new Geometry();
+
+    geo.name = "UVSphere";
+
+    // segments
+
+    widthSegments = Math.max(3, Math.floor(widthSegments));
+    heightSegments = Math.max(2, Math.floor(heightSegments));
+
+    // three clamps only its triangle selection to the south pole; clamping the rows too keeps a
+    // long `thetaLength` from folding the last band back over the sphere
+    let thetaEnd = Math.min(thetaStart + thetaLength, Math.PI);
+
+    // an interval meant to end at the pole is the sum of two rounded angles, and lands short of
+    // `Math.PI` often enough (`Math.PI / 6 + Math.PI / 6 * 5` is an ulp short) that within a few
+    // ulps it is taken to mean the pole
+    if (Math.PI - thetaEnd <= SOUTH_POLE_TOLERANCE) {
+        thetaEnd = Math.PI;
+    }
+
+    // A ring at a pole is a single point. Three's grid still gives it a vertex per meridian, which
+    // puts two corners of every polar triangle on the same point. Here a pole holds one vertex per
+    // segment, turned to the middle of that segment, and each segment draws just the one triangle
+    // that has area. A pole's normal is the axis whichever way it is turned, so only its `u` moves.
+    const northPole = thetaStart === 0;
+    const southPole = thetaEnd === Math.PI;
+
+    // buffers
+
+    const indices = [];
+    const vertices = [];
+    const normals = [];
+    const uvs = [];
+
+    // helper variables
+
+    let index = 0;
+    const grid = [];
+
+    // generate vertices, normals and uvs
+
+    for (let iy = 0; iy <= heightSegments; iy++) {
+
+        const verticesRow = [];
+
+        const v = iy / heightSegments;
+
+        const atNorthPole = iy === 0 && northPole;
+        const atSouthPole = iy === heightSegments && southPole;
+        const pole = atNorthPole || atSouthPole;
+
+        // `Math.sin(Math.PI)` is not zero, so a pole is put on the axis rather than computed onto it
+
+        const theta = thetaStart + v * (thetaEnd - thetaStart);
+
+        const sinTheta = pole ? 0 : Math.sin(theta);
+        const cosTheta = atNorthPole ? 1 : (atSouthPole ? -1 : Math.cos(theta));
+
+        const rowVertexCount = pole ? widthSegments : widthSegments + 1;
+        const uOffset = pole ? 0.5 : 0;
+
+        for (let ix = 0; ix < rowVertexCount; ix++) {
+
+            const u = (ix + uOffset) / widthSegments;
+
+            const phi = phiStart + u * phiLength;
+
+            // normal, the direction from the centre, which is what the vertex is scaled from; taking
+            // it from the angles rather than normalising the vertex keeps it defined at radius zero
+
+            const normal_x = -Math.cos(phi) * sinTheta;
+            const normal_y = cosTheta;
+            const normal_z = Math.sin(phi) * sinTheta;
+
+            normals.push(normal_x, normal_y, normal_z);
+
+            // vertex
+
+            vertices.push(radius * normal_x, radius * normal_y, radius * normal_z);
+
+            // uv
+
+            uvs.push(u, 1 - v);
+
+            verticesRow.push(index++);
+
+        }
+
+        grid.push(verticesRow);
+
+    }
+
+    // indices
+
+    for (let iy = 0; iy < heightSegments; iy++) {
+
+        const upper = grid[iy];
+        const lower = grid[iy + 1];
+
+        // at least two segments from pole to pole, so a band never has a pole on both sides
+        const upperIsPole = iy === 0 && northPole;
+        const lowerIsPole = iy + 1 === heightSegments && southPole;
+
+        for (let ix = 0; ix < widthSegments; ix++) {
+
+            if (upperIsPole) {
+
+                // the segment's pole vertex stands in for both upper corners
+
+                indices.push(upper[ix], lower[ix], lower[ix + 1]);
+
+            } else if (lowerIsPole) {
+
+                // the segment's pole vertex stands in for both lower corners
+
+                indices.push(upper[ix + 1], upper[ix], lower[ix]);
+
+            } else {
+
+                const a = upper[ix + 1];
+                const b = upper[ix];
+                const c = lower[ix];
+                const d = lower[ix + 1];
+
+                // faces
+
+                indices.push(a, b, d);
+                indices.push(b, c, d);
+
+            }
+
+        }
+
+    }
+
+    // build geometry
+
+    geo.index = Attribute.from(new Uint32Array(indices), 1, 'index');
+    geo.addAttribute(Attribute.from(new Float32Array(vertices), 3, StandardAttributes.Position));
+    geo.addAttribute(Attribute.from(new Float32Array(normals), 3, StandardAttributes.Normal));
+    geo.addAttribute(Attribute.from(new Float32Array(uvs), 2, StandardAttributes.TextureCoordinates0));
+
+    return geo;
+}