brep-io-kernel 1.0.0

package/src/BREP/Edge.js

@@ -0,0 +1,103 @@
+import * as THREE from "three";
+import { CADmaterials } from "../UI/CADmaterials.js";
+import { Line2 } from "three/examples/jsm/Addons.js";
+
+export class Edge extends Line2 {
+    constructor(geometry) {
+        super(geometry, CADmaterials.EDGE.BASE);
+        this.faces = [];
+        this.name = null;
+        this.type = 'EDGE';
+        this.renderOrder = 2;
+        this.closedLoop = false;
+    }
+
+    // Total polyline length in world space
+    length() {
+        const tmpA = new THREE.Vector3();
+        const tmpB = new THREE.Vector3();
+        let total = 0;
+
+        // Prefer positions from visualize() payload
+        const pts = this.userData && Array.isArray(this.userData.polylineLocal)
+            ? this.userData.polylineLocal
+            : null;
+
+        const addSeg = (ax, ay, az, bx, by, bz) => {
+            tmpA.set(ax, ay, az).applyMatrix4(this.matrixWorld);
+            tmpB.set(bx, by, bz).applyMatrix4(this.matrixWorld);
+            total += tmpA.distanceTo(tmpB);
+        };
+
+        if (pts && pts.length >= 2) {
+            for (let i = 0; i < pts.length - 1; i++) {
+                const p = pts[i];
+                const q = pts[i + 1];
+                addSeg(p[0], p[1], p[2], q[0], q[1], q[2]);
+            }
+            return total;
+        }
+
+        // Fallback: read from geometry positions if available
+        const pos = this.geometry && this.geometry.getAttribute && this.geometry.getAttribute('position');
+        if (pos && pos.itemSize === 3 && pos.count >= 2) {
+            for (let i = 0; i < pos.count - 1; i++) {
+                addSeg(
+                    pos.getX(i), pos.getY(i), pos.getZ(i),
+                    pos.getX(i + 1), pos.getY(i + 1), pos.getZ(i + 1)
+                );
+            }
+            return total;
+        }
+
+        return 0;
+    }
+
+    points(applyWorld = true) {
+        // Return an array of {x,y,z} points along the polyline.
+        // Prefer polylineLocal from userData (installed by visualize), else fallback to geometry positions.
+        const tmp = new THREE.Vector3();
+        const out = [];
+
+        const pts = this.userData && Array.isArray(this.userData.polylineLocal)
+            ? this.userData.polylineLocal
+            : null;
+
+        if (pts && pts.length) {
+            for (let i = 0; i < pts.length; i++) {
+                const p = pts[i];
+                tmp.set(p[0], p[1], p[2]);
+                if (applyWorld) tmp.applyMatrix4(this.matrixWorld);
+                out.push({ x: tmp.x, y: tmp.y, z: tmp.z });
+            }
+            return out;
+        }
+
+        const pos = this.geometry && this.geometry.getAttribute && this.geometry.getAttribute('position');
+        if (pos && pos.itemSize === 3 && pos.count >= 1) {
+            for (let i = 0; i < pos.count; i++) {
+                tmp.set(pos.getX(i), pos.getY(i), pos.getZ(i));
+                if (applyWorld) tmp.applyMatrix4(this.matrixWorld);
+                out.push({ x: tmp.x, y: tmp.y, z: tmp.z });
+            }
+        }
+        return out;
+    }
+
+
+    setMetadata(metadata) {
+        // call the approriate method in the parent solid
+        if (this.parentSolid && typeof this.parentSolid.setEdgeMetadata === 'function') {
+            this.parentSolid.setEdgeMetadata(this.name, metadata);
+        }
+        return this;
+    }
+
+    getMetadata() {
+        // call the approriate method in the parent solid
+        if (this.parentSolid && typeof this.parentSolid.getEdgeMetadata === 'function') {
+            return this.parentSolid.getEdgeMetadata(this.name);
+        }
+        return null;
+    }
+}

package/src/BREP/Extrude.js

@@ -0,0 +1,403 @@
+import * as THREE from 'three';
+import { Solid } from './BetterSolid.js';
+import { getEdgePolylineWorld } from './edgePolylineUtils.js';
+import { computeBoundsFromVertices } from './boundsUtils.js';
+
+// Build a closed extruded solid from a single face by translating
+// the face and sweeping exactly one side wall per original edge.
+//
+// Guarantees
+// - One labeled side wall per input edge: `${edge.name||'EDGE'}_SW`.
+// - Caps are a translation of the original face triangles: start is reversed,
+//   end is translated by `dirF`. If `dirB` is provided, start cap is placed at
+//   `face + dirB`; otherwise it uses the base face.
+// - Never attempts to close an open edge polyline unless its endpoints are
+//   exactly identical. Consecutive duplicate points are removed.
+// - Calls `setEpsilon(adaptive)` to weld vertices and drop degenerates.
+export class ExtrudeSolid extends Solid {
+  /**
+   * @param {object} [opts]
+   * @param {import('./Face.js').Face} opts.face Source face to extrude
+   * @param {number|import('three').Vector3} [opts.distance=1] Extrusion distance or explicit vector
+   * @param {import('three').Vector3|null} [opts.dir=null] Optional direction vector override
+   * @param {number} [opts.distanceBack=0] Optional backward extrusion distance
+   * @param {string} [opts.name='Extrude'] Name of the resulting solid
+   * @param {string|null} [opts.sideFaceName=null] Optional override for all side-wall face names
+   */
+  constructor({ face, distance = 1, dir = null, distanceBack = 0, name = 'Extrude', sideFaceName = null } = {}) {
+    super();
+    this.name = name;
+    this.params = { face, distance, dir, distanceBack, sideFaceName };
+    this.generate();
+  }
+
+  generate() {
+    const { face, distance, dir, distanceBack } = this.params;
+    if (!face || !face.geometry) return this;
+
+    // Compute forward/backward translation vectors
+    let dirF = null; let dirB = null;
+    if (dir && dir.isVector3) {
+      dirF = dir.clone();
+    } else if (distance instanceof THREE.Vector3) {
+      dirF = distance.clone();
+    } else if (typeof distance === 'number') {
+      const n = (typeof face.getAverageNormal === 'function') ? face.getAverageNormal().clone() : new THREE.Vector3(0, 1, 0);
+      if (n.lengthSq() < 1e-20) n.set(0, 1, 0);
+      dirF = n.normalize().multiplyScalar(distance);
+    } else {
+      dirF = new THREE.Vector3(0, 1, 0);
+    }
+    const backMag = Math.abs(Number(distanceBack));
+    if (Number.isFinite(backMag) && backMag > 0) {
+      const n = dirF.clone();
+      if (n.lengthSq() < 1e-20) {
+        const nf = (typeof face.getAverageNormal === 'function') ? face.getAverageNormal().clone() : new THREE.Vector3(0, 1, 0);
+        dirB = nf.normalize().multiplyScalar(-backMag); // back is opposite of forward
+      } else {
+        dirB = n.normalize().multiplyScalar(-backMag); // back is opposite of forward
+      }
+    }
+
+    const featureTag = this.name ? `${this.name}:` : '';
+    const startName = `${featureTag}${face.name || 'Face'}_START`;
+    const endName = `${featureTag}${face.name || 'Face'}_END`;
+
+    // Helper: add two triangles for a quad using the better diagonal.
+    const addQuad = (faceName, A0, B0, B1, A1, isHole) => {
+      const v = (p, q) => new THREE.Vector3(q[0] - p[0], q[1] - p[1], q[2] - p[2]);
+      const areaTri = (a, b, c) => v(a, b).cross(v(a, c)).length();
+      const areaD1 = areaTri(A0, B0, B1) + areaTri(A0, B1, A1);
+      const areaD2 = areaTri(A0, B0, A1) + areaTri(B0, B1, A1);
+      const epsA = 1e-18;
+      if (!(areaD1 > epsA || areaD2 > epsA)) return;
+      if (areaD2 > areaD1) {
+        if (isHole) { this.addTriangle(faceName, A0, A1, B0); this.addTriangle(faceName, B0, A1, B1); }
+        else        { this.addTriangle(faceName, A0, B0, A1); this.addTriangle(faceName, B0, B1, A1); }
+      } else {
+        if (isHole) { this.addTriangle(faceName, A0, B1, B0); this.addTriangle(faceName, A0, A1, B1); }
+        else        { this.addTriangle(faceName, A0, B0, B1); this.addTriangle(faceName, A0, B1, A1); }
+      }
+    };
+
+    // Caps: copy face triangles in world space, translate end, reverse start.
+    const baseGeom = face.geometry;
+    const posAttr = baseGeom.getAttribute && baseGeom.getAttribute('position');
+    // Snap helpers to ensure side walls share exact vertices with caps
+    let __capWorld = null; // base cap vertices in world coords
+    let __snapStart = null; // Map rounded -> exact start cap vertex
+    let __snapEnd = null;   // Map rounded -> exact end cap vertex
+    const __key = (p) => `${p[0].toFixed(7)},${p[1].toFixed(7)},${p[2].toFixed(7)}`;
+    const __makeSnapMap = (worldPts, offset) => {
+      if (!worldPts) return null;
+      const off = offset || new THREE.Vector3(0,0,0);
+      const m = new Map();
+      for (let i = 0; i < worldPts.length; i++) {
+        const w = worldPts[i];
+        const q = [w[0] + off.x, w[1] + off.y, w[2] + off.z];
+        m.set(__key(q), q);
+      }
+      return m;
+    };
+    const __snap = (map, p) => {
+      if (!map) return p;
+      const s = map.get(__key(p));
+      return s ? s : p;
+    };
+    if (posAttr) {
+      const idxAttr = baseGeom.getIndex && baseGeom.getIndex();
+      const v = new THREE.Vector3();
+      const world = new Array(posAttr.count);
+      for (let i = 0; i < posAttr.count; i++) {
+        v.set(posAttr.getX(i), posAttr.getY(i), posAttr.getZ(i)).applyMatrix4(face.matrixWorld);
+        world[i] = [v.x, v.y, v.z];
+      }
+      __capWorld = world;
+      const emit = (i0, i1, i2) => {
+        const p0 = world[i0], p1 = world[i1], p2 = world[i2];
+        // Start cap
+        if (dirB) {
+          const b0 = [p0[0] + dirB.x, p0[1] + dirB.y, p0[2] + dirB.z];
+          const b1 = [p1[0] + dirB.x, p1[1] + dirB.y, p1[2] + dirB.z];
+          const b2 = [p2[0] + dirB.x, p2[1] + dirB.y, p2[2] + dirB.z];
+          this.addTriangle(startName, b0, b2, b1);
+        } else {
+          this.addTriangle(startName, p0, p2, p1);
+        }
+        // End cap
+        const q0 = [p0[0] + dirF.x, p0[1] + dirF.y, p0[2] + dirF.z];
+        const q1 = [p1[0] + dirF.x, p1[1] + dirF.y, p1[2] + dirF.z];
+        const q2 = [p2[0] + dirF.x, p2[1] + dirF.y, p2[2] + dirF.z];
+        this.addTriangle(endName, q0, q1, q2);
+      };
+      if (idxAttr) {
+        for (let t = 0; t < idxAttr.count; t += 3) emit(idxAttr.getX(t + 0) >>> 0, idxAttr.getX(t + 1) >>> 0, idxAttr.getX(t + 2) >>> 0);
+      } else {
+        const triCount = (posAttr.count / 3) | 0;
+        for (let t = 0; t < triCount; t++) emit(3 * t + 0, 3 * t + 1, 3 * t + 2);
+      }
+    }
+    // Build snap maps once caps are authored
+    if (__capWorld) {
+      __snapStart = __makeSnapMap(__capWorld, dirB ? dirB : new THREE.Vector3(0,0,0));
+      __snapEnd = __makeSnapMap(__capWorld, dirF);
+    }
+
+    // Prefer explicit boundary loops (outer + holes) to guarantee identical
+    // vertices with caps, but emit one side face per original sketch edge.
+    // Fallback to per-edge polylines if loops are unavailable.
+    const sideSegments = [];
+    const loops = face?.userData?.boundaryLoopsWorld;
+    const nearEq = (a, b, eps = 1e-6) => Math.abs(a - b) <= eps;
+    const samePt = (P, Q) => P && Q && nearEq(P[0], Q[0]) && nearEq(P[1], Q[1]) && nearEq(P[2], Q[2]);
+    const edgeGroups = face?.userData?.boundaryEdgeGroups;
+    if (Array.isArray(edgeGroups) && edgeGroups.length) {
+      for (const g of edgeGroups) {
+        const pts = Array.isArray(g?.pts) ? g.pts : [];
+        if (pts.length < 2) continue;
+        const base = g?.name || 'EDGE';
+        const swBase = String(base).endsWith('_SW') ? String(base) : `${base}_SW`;
+        const nmRaw = `${featureTag}${swBase}`;
+        const nm = this.params.sideFaceName ? this.params.sideFaceName : nmRaw;
+        const poly = pts.map((p) => (Array.isArray(p) ? [p[0], p[1], p[2]] : [p.x, p.y, p.z]));
+        sideSegments.push({ name: nm, poly, isHole: !!g?.isHole });
+      }
+    } else {
+      // Precompute world polylines for edges to allow segment->edge matching
+      const edges = Array.isArray(face?.edges) ? face.edges : [];
+      const edgePolys = edges.map((e) => getEdgePolylineWorld(e));
+
+      // Find edge index whose polyline contains consecutive points A->B (or B->A)
+      const matchEdge = (A, B) => {
+        for (let i = 0; i < edgePolys.length; i++) {
+          const poly = edgePolys[i];
+          if (!Array.isArray(poly) || poly.length < 2) continue;
+          for (let k = 0; k < poly.length - 1; k++) {
+            const p0 = poly[k], p1 = poly[k + 1];
+            if ((samePt(p0, A) && samePt(p1, B)) || (samePt(p0, B) && samePt(p1, A))) {
+              const e = edges[i];
+              const nm = `${featureTag}${e?.name || 'EDGE'}_SW`;
+              return { name: nm, isHole: !!(e && e.userData && e.userData.isHole) };
+            }
+          }
+        }
+        return null;
+      };
+
+      if (Array.isArray(loops) && loops.length) {
+        for (let li = 0; li < loops.length; li++) {
+          const l = loops[li];
+          if (!l || !Array.isArray(l.pts) || l.pts.length < 2) continue;
+          const pts = [];
+          for (const p of l.pts) { if (p && p.length >= 3) pts.push([p[0], p[1], p[2]]); }
+          // Dedup consecutive duplicates
+          for (let i = pts.length - 2; i >= 0; i--) { const a = pts[i], b = pts[i + 1]; if (samePt(a, b)) pts.splice(i + 1, 1); }
+          const M = pts.length;
+          if (M < 2) continue;
+
+          // Walk segments and group consecutive ones that map to the same edge name.
+          let currentName = null;
+          let currentPoly = [];
+          const flush = () => {
+            if (currentPoly.length >= 2) {
+              const nm = currentName || `${featureTag}${face.name || 'Face'}_${li}_SEG${sideSegments.length}_SW`;
+              sideSegments.push({ name: this.params.sideFaceName || nm, poly: currentPoly.slice(), isHole: !!l.isHole });
+            }
+            currentPoly = [];
+          };
+
+          const processSegment = (A, B) => {
+            const match = matchEdge(A, B);
+            const nm = match ? match.name : null;
+            const edgeHole = match ? match.isHole : !!l.isHole;
+            if (!currentName) {
+              currentName = nm;
+              currentPoly = [A, B];
+            } else if (nm === currentName) {
+              currentPoly.push(B);
+            } else {
+              flush();
+              currentName = nm;
+              currentPoly = [A, B];
+            }
+            // propagate hole flag to current group
+            if (sideSegments.length && currentPoly.length && edgeHole) {
+              sideSegments[sideSegments.length - 1].isHole = edgeHole;
+            }
+          };
+
+          for (let i = 0; i < M; i++) {
+            const A = pts[i];
+            const B = pts[(i + 1) % M];
+            processSegment(A, B);
+          }
+          flush();
+        }
+      } else {
+        for (let i = 0; i < edges.length; i++) {
+          const edge = edges[i];
+          const poly = edgePolys[i];
+          const nmRaw = `${featureTag}${edge?.name || 'EDGE'}_SW`;
+          const nm = this.params.sideFaceName ? this.params.sideFaceName : nmRaw;
+          sideSegments.push({ name: nm, poly, isHole: !!(edge && edge.userData && edge.userData.isHole) });
+        }
+      }
+    }
+
+    // One ribbon per segment/polyline
+    for (const { name, poly, isHole } of sideSegments) {
+      // Pre-count triangles already authored for this sidewall label so we
+      // can verify how many were added for this edge (should be 2 per segment).
+      const sideID = this._getOrCreateID(name);
+      const triCountByID = (id) => {
+        let c = 0; const ids = this._triIDs;
+        for (let i = 0; i < ids.length; i++) if (ids[i] === id) c++;
+        return c;
+      };
+      const beforeTris = triCountByID(sideID);
+      if (!Array.isArray(poly) || poly.length < 2) continue;
+      // Do NOT drop the final point even if it duplicates the start. We only
+      // generate quads between consecutive samples and never auto-close the
+      // polyline (no last->first segment). Keeping the duplicate ensures the
+      // last actual segment (second-to-last -> last) is emitted for closed
+      // edge polylines that repeat the first point at the end.
+      const n = poly.length;
+      const expectedSegments = Math.max(0, n - 1);
+      if (dirB) {
+        for (let i = 0; i < n - 1; i++) {
+          const a = poly[i];
+          const b = poly[i + 1];
+          let A0 = [a[0] + dirB.x, a[1] + dirB.y, a[2] + dirB.z];
+          let B0 = [b[0] + dirB.x, b[1] + dirB.y, b[2] + dirB.z];
+          let A1 = [a[0] + dirF.x, a[1] + dirF.y, a[2] + dirF.z];
+          let B1 = [b[0] + dirF.x, b[1] + dirF.y, b[2] + dirF.z];
+          A0 = __snap(__snapStart, A0); B0 = __snap(__snapStart, B0);
+          A1 = __snap(__snapEnd, A1);   B1 = __snap(__snapEnd, B1);
+          addQuad(name, A0, B0, B1, A1, isHole);
+        }
+        // Closing handled upstream by emitting an explicit last->first segment when loops are available.
+      } else {
+        for (let i = 0; i < n - 1; i++) {
+          const a = poly[i];
+          const b = poly[i + 1];
+          let A0 = [a[0], a[1], a[2]];
+          let B0 = [b[0], b[1], b[2]];
+          let A1 = [a[0] + dirF.x, a[1] + dirF.y, a[2] + dirF.z];
+          let B1 = [b[0] + dirF.x, b[1] + dirF.y, b[2] + dirF.z];
+          A0 = __snap(__snapStart, A0); B0 = __snap(__snapStart, B0);
+          A1 = __snap(__snapEnd, A1);   B1 = __snap(__snapEnd, B1);
+          addQuad(name, A0, B0, B1, A1, isHole);
+        }
+        // Closing handled upstream by emitting an explicit last->first segment when loops are available.
+      }
+
+      // Post-check: count how many triangles were added for this sidewall.
+      const afterTris = triCountByID(sideID);
+      const added = afterTris - beforeTris;
+      const expected = expectedSegments * 2;
+      if (added !== expected) {
+        const msg = `Extrude sidewall triangle mismatch for ${name}: segments=${expectedSegments}, triangles=${added} (expected ${expected})`;
+        try {
+          if (typeof window !== 'undefined' && typeof window.alert === 'function') window.alert(msg);
+        } catch {}
+        try { console.warn(msg); } catch {}
+      }
+    }
+
+    // Check for cylindrical face metadata from circular edges
+    try {
+      // Look for edges that might be circular/arc and add metadata
+      if (face && Array.isArray(face.edges)) {
+        for (const edge of face.edges) {
+          if (edge && edge.userData) {
+            const geomType = edge.userData.sketchGeomType;
+            let radius = null;
+            let center = null;
+            
+            // Check if it's a circle
+            if (geomType === 'circle' && 
+                Array.isArray(edge.userData.circleCenter) && 
+                typeof edge.userData.circleRadius === 'number') {
+              radius = edge.userData.circleRadius;
+              center = edge.userData.circleCenter;
+            }
+            // Check if it's an arc (any arc creates cylindrical surface when extruded)
+            else if (geomType === 'arc' && 
+                     Array.isArray(edge.userData.arcCenter) && 
+                     typeof edge.userData.arcRadius === 'number') {
+              radius = edge.userData.arcRadius;
+              center = edge.userData.arcCenter;
+            }
+            
+            // If we found a circular edge, add cylindrical face metadata
+            if (radius !== null && center !== null) {
+              const sidewallName = `${featureTag}${edge?.name || 'EDGE'}_SW`;
+
+              // Bring the sketch-space center into the solid's coordinate system
+              const transformMatrix = edge?.matrixWorld || face?.matrixWorld || null;
+              const centerVec = new THREE.Vector3(center[0], center[1], center[2]);
+              if (transformMatrix) centerVec.applyMatrix4(transformMatrix);
+
+              // Forward/back vectors describing the sweep in world space
+              const forwardVec = dirF ? dirF.clone() : new THREE.Vector3(0, 1, 0);
+              const backwardVec = dirB ? dirB.clone() : new THREE.Vector3(0, 0, 0);
+
+              // Axis endpoints (start/end of the cylindrical wall)
+              const startPoint = centerVec.clone().add(backwardVec);
+              const endPoint = centerVec.clone().add(forwardVec);
+              const axisVec = endPoint.clone().sub(startPoint);
+
+              let height = axisVec.length();
+              if (!Number.isFinite(height) || height <= 1e-9) {
+                height = forwardVec.length() + backwardVec.length();
+              }
+
+              let axisDir = axisVec.clone();
+              if (axisDir.lengthSq() > 1e-12) {
+                axisDir.normalize();
+              } else {
+                axisDir = forwardVec.clone();
+                if (axisDir.lengthSq() > 1e-12) axisDir.normalize();
+                else axisDir.set(0, 1, 0);
+              }
+
+              const axisCenter = startPoint.clone().addScaledVector(axisVec, 0.5);
+              if (!Number.isFinite(axisCenter.x) || !Number.isFinite(axisCenter.y) || !Number.isFinite(axisCenter.z)) {
+                axisCenter.copy(centerVec);
+              }
+
+              if (!Number.isFinite(axisDir.x) || !Number.isFinite(axisDir.y) || !Number.isFinite(axisDir.z)) {
+                axisDir.set(0, 1, 0);
+              }
+
+              this.setFaceMetadata(sidewallName, {
+                type: 'cylindrical',
+                radius: radius,
+                height: Number.isFinite(height) ? height : 0,
+                axis: [axisDir.x, axisDir.y, axisDir.z],
+                center: [axisCenter.x, axisCenter.y, axisCenter.z]
+              });
+            }
+          }
+        }
+      }
+    } catch (err) {
+      // Silently continue if metadata detection fails
+    }
+
+    // Adaptive weld epsilon so caps and sides share vertices exactly.
+    let eps = 1e-5;
+    if (this._vertProperties.length >= 6) {
+      const bounds = computeBoundsFromVertices(this._vertProperties);
+      const diag = (bounds && bounds.diag) ? bounds.diag : 1;
+      eps = Math.min(1e-4, Math.max(1e-7, diag * 1e-6));
+    }
+    this.setEpsilon(eps);
+    try { this.removeSmallIslands({ maxTriangles: 12, removeInternal: true, removeExternal: true }); } catch {}
+    return this;
+  }
+}
+
+export function extrudeFace({ face, distance = 1, dir = null, distanceBack = 0, name = 'Extrude' } = {}) {
+  return new ExtrudeSolid({ face, distance, dir, distanceBack, name });
+}

package/src/BREP/Face.js

@@ -0,0 +1,187 @@
+import * as THREE from "three";
+import { CADmaterials } from "../UI/CADmaterials.js";
+import { computeTriangleArea } from "./triangleUtils.js";
+
+export class Face extends THREE.Mesh {
+    constructor(geometry) {
+        super(geometry, CADmaterials.FACE.BASE);
+        this.edges = [];
+        this.name = null;
+        this.type = 'FACE';
+        this.renderOrder = 1;
+        this.parentSolid = null;
+    }
+
+    // Compute the average geometric normal of this face's triangles in world space.
+    // Weighted by triangle area via cross product magnitude.
+    getAverageNormal() {
+        const geom = this.geometry;
+        if (!geom) return new THREE.Vector3(0, 1, 0);
+        const pos = geom.getAttribute('position');
+        if (!pos || pos.itemSize !== 3 || pos.count < 3) return new THREE.Vector3(0, 1, 0);
+
+        const idx = geom.getIndex();
+        const a = new THREE.Vector3();
+        const b = new THREE.Vector3();
+        const c = new THREE.Vector3();
+        const ab = new THREE.Vector3();
+        const ac = new THREE.Vector3();
+        const accum = new THREE.Vector3();
+
+        const toWorld = (out, i) => {
+            out.set(pos.getX(i), pos.getY(i), pos.getZ(i)).applyMatrix4(this.matrixWorld);
+            return out;
+        };
+
+        if (idx) {
+            const triCount = (idx.count / 3) | 0;
+            for (let t = 0; t < triCount; t++) {
+                const i0 = idx.getX(3 * t + 0) >>> 0;
+                const i1 = idx.getX(3 * t + 1) >>> 0;
+                const i2 = idx.getX(3 * t + 2) >>> 0;
+                toWorld(a, i0); toWorld(b, i1); toWorld(c, i2);
+                ab.subVectors(b, a);
+                ac.subVectors(c, a);
+                accum.add(ac.cross(ab));
+            }
+        } else {
+            const triCount = (pos.count / 3) | 0;
+            for (let t = 0; t < triCount; t++) {
+                const i0 = 3 * t + 0;
+                const i1 = 3 * t + 1;
+                const i2 = 3 * t + 2;
+                toWorld(a, i0); toWorld(b, i1); toWorld(c, i2);
+                ab.subVectors(b, a);
+                ac.subVectors(c, a);
+                accum.add(ac.cross(ab));
+            }
+        }
+
+        if (accum.lengthSq() === 0) return new THREE.Vector3(0, 1, 0);
+        return accum.normalize();
+    }
+
+    // Sum triangle areas in world space
+    surfaceArea() {
+        const geom = this.geometry;
+        if (!geom) return 0;
+        const pos = geom.getAttribute && geom.getAttribute('position');
+        if (!pos || pos.itemSize !== 3) return 0;
+
+        const idx = geom.getIndex && geom.getIndex();
+        const a = new THREE.Vector3();
+        const b = new THREE.Vector3();
+        const c = new THREE.Vector3();
+        let area = 0;
+
+        const toWorld = (out, i) => out.set(pos.getX(i), pos.getY(i), pos.getZ(i)).applyMatrix4(this.matrixWorld);
+
+        if (idx) {
+            const triCount = (idx.count / 3) | 0;
+            for (let t = 0; t < triCount; t++) {
+                const i0 = idx.getX(3 * t + 0) >>> 0;
+                const i1 = idx.getX(3 * t + 1) >>> 0;
+                const i2 = idx.getX(3 * t + 2) >>> 0;
+                toWorld(a, i0); toWorld(b, i1); toWorld(c, i2);
+                area += computeTriangleArea(a.x, a.y, a.z, b.x, b.y, b.z, c.x, c.y, c.z);
+            }
+        } else {
+            const triCount = (pos.count / 3) | 0;
+            for (let t = 0; t < triCount; t++) {
+                const i0 = 3 * t + 0;
+                const i1 = 3 * t + 1;
+                const i2 = 3 * t + 2;
+                toWorld(a, i0); toWorld(b, i1); toWorld(c, i2);
+                area += computeTriangleArea(a.x, a.y, a.z, b.x, b.y, b.z, c.x, c.y, c.z);
+            }
+        }
+        return area;
+    }
+
+    async points() {
+        // return an array of point objects {x,y,z} in world space
+        const tmp = new THREE.Vector3();
+        const arr = [];
+        const pos = this.geometry && this.geometry.getAttribute && this.geometry.getAttribute('position');
+        if (pos && pos.itemSize === 3 && pos.count >= 2) {
+            for (let i = 0; i < pos.count; i++) {
+                tmp.set(pos.getX(i), pos.getY(i), pos.getZ(i));
+                if (applyWorld) tmp.applyMatrix4(this.matrixWorld);
+                arr.push({ x: tmp.x, y: tmp.y, z: tmp.z });
+            }
+        }
+        return arr;
+    }
+
+    setMetadata(metadata) {
+        // call the approriate method in the parent solid
+        if (this.parentSolid && typeof this.parentSolid.setFaceMetadata === 'function') {
+            this.parentSolid.setFaceMetadata(this.name, metadata);
+        }
+        return this;
+    }
+
+    getMetadata() {
+        // call the approriate method in the parent solid
+        if (this.parentSolid && typeof this.parentSolid.getFaceMetadata === 'function') {
+            return this.parentSolid.getFaceMetadata(this.name);
+        }
+        return null;
+    }
+
+    renameFace(newName) {
+        this.parentSolid.renameFace(this.name, newName);
+    }
+
+    /**
+     * Return neighboring face objects that share an edge with this face.
+     * Prefers the face's edges (populated after visualize); if unavailable, falls back to
+     * boundary polylines on the parent solid and resolves to face objects.
+     * @returns {Face[]} array of neighbor face objects (deduped, excluding this face)
+     */
+    getNeighbors() {
+        const self = this;
+        const name = self?.name || self?.userData?.faceName || null;
+        if (!name) return [];
+        const solid = self.parentSolid || self.userData?.parentSolid || null;
+        const neighbors = new Set();
+
+        const addFace = (f) => {
+            if (!f) return;
+            if (f === self) return;
+            neighbors.add(f);
+        };
+
+        // Primary: use edges already attached to this face
+        if (Array.isArray(self.edges)) {
+            for (const e of self.edges) {
+                if (!e || !Array.isArray(e.faces)) continue;
+                for (const f of e.faces) addFace(f);
+            }
+        }
+
+        // Fallback: use boundary polylines from the parent solid to resolve neighbor faces
+        if (neighbors.size === 0 && solid && typeof solid.getBoundaryEdgePolylines === 'function') {
+            const faceMap = new Map();
+            if (Array.isArray(solid.children)) {
+                for (const ch of solid.children) {
+                    if (ch && ch.type === 'FACE') {
+                        const n = ch.name || ch.userData?.faceName || null;
+                        if (n) faceMap.set(n, ch);
+                    }
+                }
+            }
+            try {
+                const boundaries = solid.getBoundaryEdgePolylines() || [];
+                for (const poly of boundaries) {
+                    const a = poly?.faceA;
+                    const b = poly?.faceB;
+                    if (a === name && b) addFace(faceMap.get(b));
+                    else if (b === name && a) addFace(faceMap.get(a));
+                }
+            } catch { /* ignore */ }
+        }
+
+        return Array.from(neighbors);
+    }
+}