brep-io-kernel 1.0.0

package/src/BREP/helix.js

@@ -0,0 +1,193 @@
+import * as THREE from 'three';
+
+const EPS = 1e-9;
+
+const finiteOr = (value, fallback) => {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+const toVec3 = (value, fallback = [0, 0, 0]) => {
+  if (value && typeof value.x === 'number') {
+    return new THREE.Vector3(
+      Number(value.x) || 0,
+      Number(value.y) || 0,
+      Number(value.z) || 0,
+    );
+  }
+  if (Array.isArray(value)) {
+    return new THREE.Vector3(
+      Number(value[0]) || 0,
+      Number(value[1]) || 0,
+      Number(value[2]) || 0,
+    );
+  }
+  return new THREE.Vector3(
+    Number(fallback?.[0]) || 0,
+    Number(fallback?.[1]) || 0,
+    Number(fallback?.[2]) || 0,
+  );
+};
+
+const normalizedOr = (vec, fallback = new THREE.Vector3(0, 0, 1)) => {
+  const out = vec.clone();
+  if (out.lengthSq() < EPS) return fallback.clone().normalize();
+  return out.normalize();
+};
+
+const matrixFromTransform = (transform) => {
+  if (!transform) return null;
+  if (transform.isMatrix4) return transform.clone();
+
+  const pos = Array.isArray(transform.position) ? transform.position : [0, 0, 0];
+  const rot = Array.isArray(transform.rotationEuler) ? transform.rotationEuler : [0, 0, 0];
+  const scl = Array.isArray(transform.scale) ? transform.scale : [1, 1, 1];
+
+  const position = new THREE.Vector3(
+    Number(pos[0]) || 0,
+    Number(pos[1]) || 0,
+    Number(pos[2]) || 0,
+  );
+  const euler = new THREE.Euler(
+    THREE.MathUtils.degToRad(Number(rot[0]) || 0),
+    THREE.MathUtils.degToRad(Number(rot[1]) || 0),
+    THREE.MathUtils.degToRad(Number(rot[2]) || 0),
+    'XYZ',
+  );
+  const quat = new THREE.Quaternion().setFromEuler(euler);
+  const scale = new THREE.Vector3(
+    Math.abs(Number(scl[0]) || 1),
+    Math.abs(Number(scl[1]) || 1),
+    Math.abs(Number(scl[2]) || 1),
+  );
+
+  return new THREE.Matrix4().compose(position, quat, scale);
+};
+
+const buildPlacementMatrix = (opts = {}) => {
+  const fromTransform = matrixFromTransform(opts.transform);
+  if (fromTransform) return fromTransform;
+
+  const origin = toVec3(opts.origin, [0, 0, 0]);
+  const axisDir = normalizedOr(toVec3(opts.axis, [0, 0, 1]), new THREE.Vector3(0, 0, 1));
+
+  let xDir = opts.xDirection ? toVec3(opts.xDirection) : null;
+  if (!xDir || xDir.lengthSq() < EPS) {
+    const fallback = Math.abs(axisDir.y) < 0.9 ? new THREE.Vector3(0, 1, 0) : new THREE.Vector3(1, 0, 0);
+    xDir = new THREE.Vector3().crossVectors(fallback, axisDir);
+  } else {
+    // Remove any component along the axis so we remain perpendicular
+    xDir = xDir.addScaledVector(axisDir, -xDir.dot(axisDir));
+  }
+  if (xDir.lengthSq() < EPS) {
+    const fallback = Math.abs(axisDir.z) < 0.9 ? new THREE.Vector3(0, 0, 1) : new THREE.Vector3(0, 1, 0);
+    xDir = new THREE.Vector3().crossVectors(axisDir, fallback);
+  }
+  xDir.normalize();
+  const yDir = new THREE.Vector3().crossVectors(axisDir, xDir).normalize();
+
+  const m = new THREE.Matrix4().makeBasis(xDir, yDir, axisDir);
+  m.setPosition(origin);
+  return m;
+};
+
+/**
+ * Build a helix polyline in 3D.
+ * - Generates points for a right/left-handed helix with optional taper.
+ * - Orientation is controlled by a transform matrix, or by origin/axis/xDirection.
+ * - Returns world-space polyline points for reuse by features (threads, sweep paths, etc.).
+ * Options: radius/endRadius, height + pitch with mode (turns|pitch) controlling which value is derived, startAngleDeg/startAngle, clockwise,
+ * segmentsPerTurn (or resolution), and placement via `transform` or `{ origin, axis, xDirection }`.
+ */
+export function buildHelixPolyline(opts = {}) {
+  const r0 = Math.max(1e-6, Math.abs(finiteOr(opts.radius, 5)));
+  const hasEndRadius = opts.endRadius != null && Number.isFinite(Number(opts.endRadius));
+  const r1 = hasEndRadius ? Math.max(1e-6, Math.abs(finiteOr(opts.endRadius, r0))) : r0;
+
+  const minPitch = 1e-6;
+  const rawPitch = finiteOr(opts.pitch, finiteOr(opts.pitchDefault, NaN));
+  if (!Number.isFinite(rawPitch) || Math.abs(rawPitch) < minPitch) {
+    throw new Error('[buildHelixPolyline] pitch must be a finite, non-zero number.');
+  }
+  let pitch = Math.abs(rawPitch);
+  const modeRaw = String(opts.lengthMode || opts.mode || 'turns').toLowerCase();
+  const lengthMode = modeRaw === 'pitch' || modeRaw === 'height' ? 'pitch' : 'turns';
+  let turns = finiteOr(opts.turns, NaN);
+  let height = finiteOr(opts.height, NaN);
+
+  // Allow negative height to flip the axis direction while keeping a positive magnitude
+  let axisSign = 1;
+  if (Number.isFinite(height) && height < 0) {
+    axisSign = -1;
+    height = Math.abs(height);
+  }
+
+  if (lengthMode === 'pitch' && Number.isFinite(height) && height > EPS) {
+    turns = height / pitch;
+  } else {
+    if (!Number.isFinite(turns) || turns <= 0) {
+      if (Number.isFinite(height) && height > EPS) turns = height / pitch;
+      else turns = 1;
+    }
+    height = Number.isFinite(height) && height > EPS ? height : pitch * turns;
+  }
+
+  // Keep pitch consistent with the resolved height/turns
+  if (Number.isFinite(turns) && turns > EPS) pitch = height / turns;
+  else {
+    turns = 1;
+    height = pitch;
+  }
+
+  const segsPerTurn = Math.max(8, Math.floor(finiteOr(opts.segmentsPerTurn, finiteOr(opts.resolution, 64))));
+  const totalSeg = Math.max(1, Math.round(segsPerTurn * Math.max(turns, EPS)));
+
+  const startAngleDeg = finiteOr(opts.startAngleDeg, NaN);
+  const startAngleRad = Number.isFinite(startAngleDeg)
+    ? THREE.MathUtils.degToRad(startAngleDeg)
+    : finiteOr(opts.startAngle, 0);
+  const handedRaw = String(opts.handedness || (opts.clockwise ? 'left' : 'right')).toLowerCase();
+  const clockwise = handedRaw === 'left' || opts.clockwise === true;
+  const angleSign = clockwise ? -1 : 1;
+
+  const placement = buildPlacementMatrix(opts);
+  const normalMat = new THREE.Matrix3();
+  normalMat.getNormalMatrix(placement);
+
+  const origin = new THREE.Vector3().setFromMatrixPosition(placement);
+  const axisDir = new THREE.Vector3(0, 0, axisSign).applyMatrix3(normalMat).normalize();
+
+  const polyline = [];
+  // Keep winding direction stable even if the helix height is negative by folding the axis sign into angular direction
+  const angularSign = angleSign * axisSign;
+  const tmp = new THREE.Vector3();
+  for (let i = 0; i <= totalSeg; i++) {
+    const t = i / totalSeg;
+    const theta = startAngleRad + angularSign * (turns * t * Math.PI * 2);
+    const radius = r0 + (r1 - r0) * t;
+    tmp.set(Math.cos(theta) * radius, Math.sin(theta) * radius, height * t * axisSign);
+    tmp.applyMatrix4(placement);
+    polyline.push([tmp.x, tmp.y, tmp.z]);
+  }
+
+  const axisEnd = origin.clone().addScaledVector(axisDir, height);
+
+  return {
+    polyline,
+    closedLoop: false,
+    pitch,
+    turns,
+    height,
+    radiusStart: r0,
+    radiusEnd: r1,
+    clockwise,
+    handedness: clockwise ? 'left' : 'right',
+    startAngleRad,
+    origin: [origin.x, origin.y, origin.z],
+    axisDirection: [axisDir.x, axisDir.y, axisDir.z],
+    axisLine: [
+      [origin.x, origin.y, origin.z],
+      [axisEnd.x, axisEnd.y, axisEnd.z],
+    ],
+  };
+}

package/src/BREP/meshToBrep.js

@@ -0,0 +1,234 @@
+import * as THREE from "three";
+import { Solid } from "./BetterSolid.js";
+
+/**
+ * MeshToBrep: Builds a Solid from a triangle mesh by grouping triangles
+ * into face labels based on the deflection angle between neighboring
+ * triangle normals.
+ *
+ * Usage
+ *   const solid = new MeshToBrep(geometryOrMesh, 15  deg );
+ *   solid.name = "ImportedSTL";
+ *   solid.visualize();
+ *
+ * Notes
+ * - Accepts a THREE.BufferGeometry or a THREE.Mesh (uses its geometry).
+ * - Triangles are welded to a grid (weldTolerance) so shared edges use
+ *   identical vertex positions for manifoldization.
+ * - If the input geometry has a `normal` attribute (STLLoader does),
+ *   those normals are used for deflection. Otherwise, per-triangle
+ *   normals are computed from positions.
+ */
+export class MeshToBrep extends Solid {
+    /**
+     * @param {THREE.BufferGeometry|THREE.Mesh} geometryOrMesh
+     * @param {number} faceDeflectionAngle Degrees; neighbors within this angle join a face
+     * @param {number} weldTolerance Vertex welding tolerance (units). Default 1e-5.
+     */
+    constructor(geometryOrMesh, faceDeflectionAngle = 30, weldTolerance = 1e-5) {
+        super();
+        const geom = (geometryOrMesh && geometryOrMesh.isMesh)
+            ? geometryOrMesh.geometry
+            : geometryOrMesh;
+        if (!geom || !geom.isBufferGeometry) {
+            throw new Error("MeshToBrep requires a THREE.BufferGeometry or THREE.Mesh");
+        }
+
+        this.faceDeflectionAngle = Number(faceDeflectionAngle) || 0;
+        this.weldTolerance = Number(weldTolerance) || 0;
+
+        // Build internal mesh arrays and face labels
+        this._buildFromGeometry(geom);
+    }
+
+    toBrep() { return this; }
+
+    _buildFromGeometry(geometry) {
+        // Ensure we have positions
+        const posAttr = geometry.getAttribute('position');
+        if (!posAttr) throw new Error("Geometry has no 'position' attribute");
+
+        const idxAttr = geometry.getIndex();
+        const norAttr = geometry.getAttribute('normal');
+
+        // Accessor helpers
+        const getPos = (i, out) => {
+            out.x = posAttr.getX(i);
+            out.y = posAttr.getY(i);
+            out.z = posAttr.getZ(i);
+            return out;
+        };
+        const getTri = (t) => {
+            if (idxAttr) {
+                const i0 = idxAttr.getX(3 * t + 0) >>> 0;
+                const i1 = idxAttr.getX(3 * t + 1) >>> 0;
+                const i2 = idxAttr.getX(3 * t + 2) >>> 0;
+                return [i0, i1, i2];
+            } else {
+                const base = 3 * t;
+                return [base + 0, base + 1, base + 2];
+            }
+        };
+
+        const triCount = idxAttr ? ((idxAttr.count / 3) | 0) : ((posAttr.count / 3) | 0);
+        if (triCount <= 0) return;
+
+        // Build canonical vertices using a weld grid so that shared edges truly share indices
+        const q = Math.max(0, this.weldTolerance) || 0;
+        const gridKey = (x, y, z) => {
+            if (q <= 0) return `${x},${y},${z}`; // exact
+            const rx = Math.round(x / q);
+            const ry = Math.round(y / q);
+            const rz = Math.round(z / q);
+            return `${rx},${ry},${rz}`;
+        };
+        const tmpA = new THREE.Vector3();
+        const tmpB = new THREE.Vector3();
+        const tmpC = new THREE.Vector3();
+
+        // Vertex dictionary and arrays
+        const keyToIndex = new Map();
+        const indexToPos = []; // [ [x,y,z], ... ] matching canonical vertices
+
+        // Triangle data arrays
+        const triVerts = new Array(triCount);
+        const triNormals = new Array(triCount);
+
+        // Grab per-vertex normals if available (STL facet normals replicated per-vertex)
+        const getTriNormal = (t) => {
+            if (norAttr && norAttr.count === posAttr.count) {
+                const [i0] = getTri(t);
+                // normals are constant per tri for STL; use any vertex's normal
+                const nx = norAttr.getX(i0);
+                const ny = norAttr.getY(i0);
+                const nz = norAttr.getZ(i0);
+                const n = new THREE.Vector3(nx, ny, nz);
+                if (n.lengthSq() > 0) return n.normalize();
+            }
+            // Fallback: compute from positions
+            const [a, b, c] = getTri(t);
+            getPos(a, tmpA); getPos(b, tmpB); getPos(c, tmpC);
+            tmpB.sub(tmpA); tmpC.sub(tmpA);
+            const n = tmpB.clone().cross(tmpC);
+            if (n.lengthSq() > 0) return n.normalize();
+            return new THREE.Vector3(0, 0, 1);
+        };
+
+        // Build canonical vertices and triangle index triplets
+        for (let t = 0; t < triCount; t++) {
+            const [ia, ib, ic] = getTri(t);
+            const a = getPos(ia, tmpA.clone());
+            const b = getPos(ib, tmpB.clone());
+            const c = getPos(ic, tmpC.clone());
+
+            const keyA = gridKey(a.x, a.y, a.z);
+            const keyB = gridKey(b.x, b.y, b.z);
+            const keyC = gridKey(c.x, c.y, c.z);
+
+            let ai = keyToIndex.get(keyA);
+            if (ai === undefined) {
+                ai = indexToPos.length;
+                keyToIndex.set(keyA, ai);
+                const [xr, yr, zr] = (q <= 0) ? [a.x, a.y, a.z] : [Math.round(a.x / q) * q, Math.round(a.y / q) * q, Math.round(a.z / q) * q];
+                indexToPos.push([xr, yr, zr]);
+            }
+            let bi = keyToIndex.get(keyB);
+            if (bi === undefined) {
+                bi = indexToPos.length;
+                keyToIndex.set(keyB, bi);
+                const [xr, yr, zr] = (q <= 0) ? [b.x, b.y, b.z] : [Math.round(b.x / q) * q, Math.round(b.y / q) * q, Math.round(b.z / q) * q];
+                indexToPos.push([xr, yr, zr]);
+            }
+            let ci = keyToIndex.get(keyC);
+            if (ci === undefined) {
+                ci = indexToPos.length;
+                keyToIndex.set(keyC, ci);
+                const [xr, yr, zr] = (q <= 0) ? [c.x, c.y, c.z] : [Math.round(c.x / q) * q, Math.round(c.y / q) * q, Math.round(c.z / q) * q];
+                indexToPos.push([xr, yr, zr]);
+            }
+
+            triVerts[t] = [ai, bi, ci];
+            triNormals[t] = getTriNormal(t);
+        }
+
+        // Build adjacency via undirected edge -> list of triangle indices
+        const ek = (u, v) => (u < v ? `${u},${v}` : `${v},${u}`);
+        const edgeToTris = new Map();
+        for (let t = 0; t < triCount; t++) {
+            const [a, b, c] = triVerts[t];
+            const edges = [[a, b], [b, c], [c, a]];
+            for (const [u, v] of edges) {
+                const key = ek(u, v);
+                let list = edgeToTris.get(key);
+                if (!list) { list = []; edgeToTris.set(key, list); }
+                list.push(t);
+            }
+        }
+
+        // Convert to per-triangle neighbor lists
+        const neighbors = new Array(triCount);
+        for (let i = 0; i < triCount; i++) neighbors[i] = [];
+        for (const list of edgeToTris.values()) {
+            if (list.length < 2) continue;
+            // each pair of triangles sharing this edge are neighbors
+            for (let i = 0; i < list.length; i++) {
+                for (let j = i + 1; j < list.length; j++) {
+                    const a = list[i], b = list[j];
+                    neighbors[a].push(b);
+                    neighbors[b].push(a);
+                }
+            }
+        }
+
+        // Region grow faces by deflection angle between neighboring triangle normals
+        const maxAngleRad = Math.max(0, this.faceDeflectionAngle) * Math.PI / 180.0;
+        const cosThresh = Math.cos(maxAngleRad);
+        const visited = new Uint8Array(triCount);
+        let faceCounter = 0;
+        const triFaceName = new Array(triCount);
+
+        const dot = (a, b) => {
+            const d = a.x * b.x + a.y * b.y + a.z * b.z;
+            const la = Math.hypot(a.x, a.y, a.z);
+            const lb = Math.hypot(b.x, b.y, b.z);
+            if (la === 0 || lb === 0) return 1; // treat degenerate as same
+            return d / (la * lb);
+        };
+
+        for (let seed = 0; seed < triCount; seed++) {
+            if (visited[seed]) continue;
+            const faceName = `STL_FACE_${++faceCounter}`;
+            // BFS using pairwise deflection with the parent triangle
+            const queue = [seed];
+            visited[seed] = 1;
+            triFaceName[seed] = faceName;
+            while (queue.length) {
+                const t = queue.shift();
+                const nrmT = triNormals[t];
+                for (const nb of neighbors[t]) {
+                    if (visited[nb]) continue;
+                    const nrmN = triNormals[nb];
+                    // If normals are close (angle <= threshold), grow region
+                    if (dot(nrmT, nrmN) >= cosThresh) {
+                        visited[nb] = 1;
+                        triFaceName[nb] = faceName;
+                        queue.push(nb);
+                    }
+                }
+            }
+        }
+
+        // Author triangles into this Solid with their face labels
+        for (let t = 0; t < triCount; t++) {
+            const name = triFaceName[t] || `STL_FACE_${faceCounter + 1}`;
+            const [a, b, c] = triVerts[t];
+            const pa = indexToPos[a];
+            const pb = indexToPos[b];
+            const pc = indexToPos[c];
+            this.addTriangle(name, pa, pb, pc);
+        }
+
+        // Let downstream visualization build per-face meshes and edges
+        // We'll leave winding correction/orientation to _manifoldize()
+    }
+}