@woosh/meep-engine 2.139.0 → 2.140.0

package/src/engine/graphics/geometry/CapsuleGeometry.js

@@ -0,0 +1,171 @@
+import { BufferGeometry, Float32BufferAttribute, Vector3 } from "three";
+
+/**
+ * A capsule aligned with the Y axis, built as a single continuous surface of
+ * revolution: a top hemispherical cap, a cylindrical mid-section and a bottom
+ * hemispherical cap.
+ *
+ * Dimensions follow the {@link CapsuleShape3D} convention:
+ *   - `radius` is the radius of both the caps and the cylindrical section.
+ *   - `height` is the length of the cylindrical section ONLY (the caps are
+ *     added on top of it), so the total extent along Y is `height + 2 * radius`,
+ *     spanning `[-(height/2 + radius), +(height/2 + radius)]`, centred at the
+ *     origin.
+ *
+ * Two further parameters control tessellation:
+ *   - `capSegments` rings per hemispherical cap (from equator to pole).
+ *   - `radialSegments` segments around the Y axis.
+ *
+ * Watertightness: the mesh is emitted as one grid of vertex rings running from
+ * the top pole down to the bottom pole. Consecutive rings — including the
+ * top-equator -> bottom-equator ring that spans the cylinder — are stitched
+ * sharing their ring vertices, so there is never a gap between the caps and the
+ * body. The angular seam is duplicated only for UV continuity (the duplicate
+ * sits at the same position) and each pole is a proper triangle fan, so welding
+ * vertices by position yields a closed, consistently oriented 2-manifold.
+ */
+export class CapsuleGeometry extends BufferGeometry {
+    /**
+     * @param {number} [radius=0.5] radius of the caps and the cylindrical section
+     * @param {number} [height=1] length of the cylindrical section, excluding the caps
+     * @param {number} [capSegments=8] number of rings in each hemispherical cap
+     * @param {number} [radialSegments=16] number of segments around the Y axis
+     */
+    constructor(radius = 0.5, height = 1, capSegments = 8, radialSegments = 16) {
+        super();
+
+        this.type = 'CapsuleGeometry';
+
+        this.parameters = {
+            radius: radius,
+            height: height,
+            capSegments: capSegments,
+            radialSegments: radialSegments
+        };
+
+        capSegments = Math.max(1, Math.floor(capSegments));
+        radialSegments = Math.max(3, Math.floor(radialSegments));
+
+        const half_height = height / 2;
+
+        // arc length of the lateral profile, used to keep the V coordinate
+        // proportional to surface distance across the caps and the body
+        const cap_arc = radius * (Math.PI / 2);
+        const profile_length = 2 * cap_arc + height;
+        const inv_profile = profile_length > 0 ? 1 / profile_length : 0;
+
+        // number of vertex rows from the top pole (row 0) to the bottom pole.
+        // top hemisphere: capSegments + 1 rows (pole .. top equator),
+        // bottom hemisphere: capSegments + 1 rows (bottom equator .. pole).
+        const row_count = 2 * (capSegments + 1);
+
+        const indices = [];
+        const vertices = [];
+        const normals = [];
+        const uvs = [];
+
+        const vertex = new Vector3();
+        const normal = new Vector3();
+
+        // grid[row] -> array of vertex indices for that ring
+        const grid = [];
+
+        let index = 0;
+
+        for (let row = 0; row < row_count; row++) {
+
+            // resolve the profile angle (measured from the +Y pole of the owning
+            // hemisphere), that hemisphere's centre Y, and the cumulative surface
+            // arc length from the top pole
+            let angle;
+            let center_y;
+            let arc;
+
+            if (row <= capSegments) {
+                // top hemisphere: alpha 0 .. PI/2, centred at +half_height
+                angle = (row / capSegments) * (Math.PI / 2);
+                center_y = half_height;
+                arc = radius * angle;
+            } else {
+                // bottom hemisphere: beta PI/2 .. PI, centred at -half_height
+                const k = row - (capSegments + 1);
+                angle = (Math.PI / 2) + (k / capSegments) * (Math.PI / 2);
+                center_y = -half_height;
+                arc = cap_arc + height + radius * (angle - Math.PI / 2);
+            }
+
+            const sin_angle = Math.sin(angle);
+            const cos_angle = Math.cos(angle);
+
+            const ring_radius = radius * sin_angle;
+            const y = center_y + radius * cos_angle;
+
+            const v = 1 - arc * inv_profile;
+
+            // nudge the U of the pole vertices half a segment so the texture wraps
+            // symmetrically over the triangle fan (mirrors SphereGeometry)
+            let u_offset = 0;
+            if (row === 0) {
+                u_offset = 0.5 / radialSegments;
+            } else if (row === row_count - 1) {
+                u_offset = -0.5 / radialSegments;
+            }
+
+            const vertices_row = [];
+
+            for (let s = 0; s <= radialSegments; s++) {
+
+                const u = s / radialSegments;
+                const theta = u * Math.PI * 2;
+
+                const cos_theta = Math.cos(theta);
+                const sin_theta = Math.sin(theta);
+
+                // vertex
+                vertex.x = ring_radius * cos_theta;
+                vertex.y = y;
+                vertex.z = ring_radius * sin_theta;
+                vertices.push(vertex.x, vertex.y, vertex.z);
+
+                // normal points away from the central axis on the body and away
+                // from the hemisphere centre on the caps
+                normal.set(sin_angle * cos_theta, cos_angle, sin_angle * sin_theta).normalize();
+                normals.push(normal.x, normal.y, normal.z);
+
+                // uv
+                uvs.push(u + u_offset, v);
+
+                vertices_row.push(index++);
+            }
+
+            grid.push(vertices_row);
+        }
+
+        // indices — stitch every ring to the next, sharing ring vertices so the
+        // caps and the body join with no gaps. The degenerate triangle of each
+        // pole quad is skipped (one vertex pair collapses onto the pole).
+        for (let row = 0; row < row_count - 1; row++) {
+
+            for (let s = 0; s < radialSegments; s++) {
+
+                const a = grid[row][s + 1];
+                const b = grid[row][s];
+                const c = grid[row + 1][s];
+                const d = grid[row + 1][s + 1];
+
+                // wound so the explicit normals face outward
+                if (row !== 0) indices.push(b, a, d);
+                if (row !== row_count - 2) indices.push(b, d, c);
+            }
+        }
+
+        this.setIndex(indices);
+        this.setAttribute('position', new Float32BufferAttribute(vertices, 3));
+        this.setAttribute('normal', new Float32BufferAttribute(normals, 3));
+        this.setAttribute('uv', new Float32BufferAttribute(uvs, 2));
+    }
+
+    static fromJSON(data) {
+        return new CapsuleGeometry(data.radius, data.height, data.capSegments, data.radialSegments);
+    }
+}