brep-io-kernel 1.0.0-ci.9

package/src/features/sheetMetal/SheetMetalHemFeature.js

@@ -0,0 +1,43 @@
+import { SheetMetalFlangeFeature } from "./SheetMetalFlangeFeature.js";
+
+const baseSchema = SheetMetalFlangeFeature.inputParamsSchema || {};
+const inputParamsSchema = {
+  ...baseSchema,
+  id: {
+    ...(baseSchema.id || {}),
+    hint: "Unique identifier for the hem feature",
+  },
+  flangeLength: {
+    ...(baseSchema.flangeLength || {}),
+    label: "Hem length",
+    hint: "Optional straight leg length extruded from the hem end face. Set to 0 to create only the bend.",
+  },
+  flangeLengthReference: {
+    ...(baseSchema.flangeLengthReference || {}),
+    label: "Hem length reference",
+    hint: "Measurement basis for the hem leg: inside, outside, or web.",
+  },
+  angle: {
+    ...(baseSchema.angle || {}),
+    default_value: 180,
+    min: 180,
+    max: 180,
+    hint: "Hem angle is fixed at 180 degrees.",
+  },
+  bendRadius: {
+    ...(baseSchema.bendRadius || {}),
+    default_value: 0.0001,
+    hint: "Hem bend radius (inside). Defaults to 0.0001.",
+  },
+};
+
+export class SheetMetalHemFeature extends SheetMetalFlangeFeature {
+  static shortName = "SM.HEM";
+  static longName = "Sheet Metal Hem";
+  static inputParamsSchema = inputParamsSchema;
+  static baseType = "HEM";
+  static logTag = "SheetMetalHem";
+  static defaultAngle = 180;
+  static angleOverride = 180;
+  static defaultBendRadius = 0.0001;
+}

package/src/features/sheetMetal/SheetMetalObject.js

@@ -0,0 +1,141 @@
+import { Solid } from "../../BREP/BetterSolid.js";
+import { buildSheetMetalFlatPatternSolids } from "../../exporters/sheetMetalFlatPattern.js";
+import { applySheetMetalMetadata } from "./sheetMetalMetadata.js";
+import { propagateSheetMetalFaceTypesToEdges } from "./sheetMetalFaceTypes.js";
+import { buildSheetMetalSolidFromTree } from "./sheetMetalPipeline.js";
+import {
+  SHEET_METAL_NODE_TYPES,
+  appendSheetMetalNode,
+  cloneSheetMetalTree,
+  getSheetMetalBaseNode,
+} from "./sheetMetalTree.js";
+
+export class SheetMetalObject extends Solid {
+  constructor({ tree = null, kFactor = null, thickness = null, bendRadius = null } = {}) {
+    super();
+    this.tree = tree ? cloneSheetMetalTree(tree) : { version: 1, nodes: [] };
+    this.kFactor = kFactor;
+    this.thickness = thickness;
+    this.bendRadius = bendRadius;
+  }
+
+  cloneWithNode(node) {
+    const next = new SheetMetalObject({
+      tree: appendSheetMetalNode(this.tree, node),
+      kFactor: this.kFactor,
+      thickness: this.thickness,
+      bendRadius: this.bendRadius,
+    });
+    next.name = this.name;
+    return next;
+  }
+
+  appendNode(node) {
+    this.tree = appendSheetMetalNode(this.tree, node);
+    return this;
+  }
+
+  async generate({
+    partHistory = null,
+    metadataManager = null,
+    mode = "solid",
+    flatPatternOptions = null,
+  } = {}) {
+    const built = await buildSheetMetalSolidFromTree(this.tree, { partHistory });
+    this._replaceFromSolid(built);
+
+    const baseNode = getSheetMetalBaseNode(this.tree);
+    const baseParams = baseNode?.params || {};
+    const baseType = baseNode?.type === SHEET_METAL_NODE_TYPES.CONTOUR_FLANGE
+      ? "CONTOUR_FLANGE"
+      : "TAB";
+    let baseExtra = {};
+    if (baseType === "CONTOUR_FLANGE") {
+      const signedDistanceRaw = Number(baseParams.signedDistance ?? baseParams.distance);
+      const signedDistance = Number.isFinite(signedDistanceRaw) ? signedDistanceRaw : 0;
+      const distance = Math.abs(signedDistance);
+      baseExtra = {
+        signedThickness: baseParams.signedThickness,
+        sheetSide: baseParams.sheetSide,
+        reverseSheetSide: baseParams.reverseSheetSide,
+        signedDistance,
+        distance,
+        consumePathSketch: baseParams.consumePathSketch,
+        pathRefCount: Array.isArray(baseParams.pathRefs) ? baseParams.pathRefs.length : null,
+      };
+    } else {
+      baseExtra = {
+        placementMode: baseParams.placementMode,
+        signedThickness: baseParams.signedThickness,
+        consumeProfileSketch: baseParams.consumeProfileSketch,
+        profileName: baseParams.profileName,
+      };
+    }
+    applySheetMetalMetadata([this], metadataManager, {
+      featureID: baseParams.featureID || null,
+      thickness: this.thickness ?? baseParams.thickness ?? null,
+      bendRadius: this.bendRadius ?? baseParams.bendRadius ?? null,
+      neutralFactor: this.kFactor ?? baseParams.neutralFactor ?? null,
+      baseType,
+      extra: baseExtra,
+      forceBaseOverwrite: true,
+    });
+    propagateSheetMetalFaceTypesToEdges([this]);
+
+    this.userData = this.userData || {};
+    this.userData.sheetMetalTree = cloneSheetMetalTree(this.tree);
+    this.userData.sheetMetalKFactor = this.kFactor;
+
+    let flat = null;
+    if (mode === "flat" || mode === "both") {
+      const flatOptions = { ...(flatPatternOptions || {}) };
+      if (flatOptions.metadataManager == null && metadataManager) {
+        flatOptions.metadataManager = metadataManager;
+      }
+      if (flatOptions.thickness == null) {
+        const thickness = this.thickness ?? baseParams.thickness ?? null;
+        if (thickness != null) flatOptions.thickness = thickness;
+      }
+      if (flatOptions.neutralFactor == null) {
+        const neutralFactor = this.kFactor ?? baseParams.neutralFactor ?? null;
+        if (neutralFactor != null) flatOptions.neutralFactor = neutralFactor;
+      }
+      const entries = buildSheetMetalFlatPatternSolids([this], flatOptions);
+      flat = Array.isArray(entries) && entries.length ? entries[0] : null;
+    }
+
+    if (mode === "solid") return { solid: this };
+    if (mode === "flat") return { solid: this, flat };
+    if (mode === "both") return { solid: this, flat };
+    return { solid: this };
+  }
+
+  _replaceFromSolid(source) {
+    this._numProp = source._numProp;
+    this._vertProperties = source._vertProperties.slice();
+    this._triVerts = source._triVerts.slice();
+    this._triIDs = source._triIDs.slice();
+    this._vertKeyToIndex = new Map(source._vertKeyToIndex);
+    this._faceNameToID = new Map(source._faceNameToID);
+    this._idToFaceName = new Map(source._idToFaceName);
+    this._faceMetadata = new Map(source._faceMetadata);
+    this._edgeMetadata = new Map(source._edgeMetadata);
+    this._auxEdges = Array.isArray(source._auxEdges)
+      ? source._auxEdges.map((edge) => ({
+          name: edge?.name,
+          closedLoop: !!edge?.closedLoop,
+          polylineWorld: !!edge?.polylineWorld,
+          materialKey: edge?.materialKey,
+          centerline: !!edge?.centerline,
+          points: Array.isArray(edge?.points)
+            ? edge.points.map((p) => (Array.isArray(p) ? [p[0], p[1], p[2]] : p))
+            : [],
+        }))
+      : [];
+    this._dirty = true;
+    this._manifold = null;
+    this._faceIndex = null;
+    this.type = "SOLID";
+    this.renderOrder = source.renderOrder ?? this.renderOrder;
+  }
+}

package/src/features/sheetMetal/SheetMetalTabFeature.js

@@ -0,0 +1,176 @@
+import { BREP } from "../../BREP/BREP.js";
+import { selectionHasSketch } from "../selectionUtils.js";
+import { normalizeThickness, normalizeBendRadius, normalizeNeutralFactor, applySheetMetalMetadata } from "./sheetMetalMetadata.js";
+import { propagateSheetMetalFaceTypesToEdges } from "./sheetMetalFaceTypes.js";
+import { resolveProfileFace, collectSketchParents } from "./profileUtils.js";
+import { cleanupSheetMetalOppositeEdgeFaces } from "./sheetMetalCleanup.js";
+import { SheetMetalObject } from "./SheetMetalObject.js";
+import { cloneSheetMetalTree, createSheetMetalTree, createSheetMetalTabNode } from "./sheetMetalTree.js";
+import { resolvePlacementMode } from "./sheetMetalTabUtils.js";
+import { cloneProfileGroups, collectProfileEdges } from "./sheetMetalProfileUtils.js";
+
+const inputParamsSchema = {
+  id: {
+    type: "string",
+    default_value: null,
+    hint: "Unique identifier for the sheet metal tab",
+  },
+  profile: {
+    type: "reference_selection",
+    selectionFilter: ["FACE", "SKETCH"],
+    multiple: false,
+    default_value: null,
+    hint: "Closed sketch or face defining the tab footprint",
+  },
+  thickness: {
+    type: "number",
+    default_value: 1,
+    min: 0,
+    hint: "Sheet metal thickness. Also used as the tab extrusion distance.",
+  },
+  placementMode: {
+    type: "options",
+    options: ["forward", "reverse", "midplane"],
+    default_value: "forward",
+    hint: "Controls whether material is added forward, backward, or split about the sketch plane.",
+  },
+  bendRadius: {
+    type: "number",
+    default_value: 0.125,
+    min: 0,
+    hint: "Default bend radius captured with the sheet-metal base feature.",
+  },
+  neutralFactor: {
+    type: "number",
+    default_value: 0.5,
+    min: 0,
+    max: 1,
+    step: 0.01,
+    hint: "Neutral factor used for flat pattern bend allowance (0-1).",
+  },
+  consumeProfileSketch: {
+    type: "boolean",
+    default_value: true,
+    hint: "Remove the referenced sketch after creating the tab. Turn off to keep it in the scene.",
+  },
+  boolean: {
+    type: "boolean_operation",
+    default_value: { targets: [], operation: "NONE" },
+    hint: "Optional boolean operation with existing solids.",
+  },
+};
+
+export class SheetMetalTabFeature {
+  static shortName = "SM.TAB";
+  static longName = "Sheet Metal Tab";
+  static inputParamsSchema = inputParamsSchema;
+
+  constructor() {
+    this.inputParams = {};
+    this.persistentData = {};
+  }
+
+  uiFieldsTest(context) {
+    const params = this.inputParams || context?.params || {};
+    const partHistory = context?.history || null;
+    return selectionHasSketch(params.profile, partHistory) ? [] : ["consumeProfileSketch"];
+  }
+
+  async run(partHistory) {
+    const faceObj = resolveProfileFace(this.inputParams?.profile, partHistory);
+    if (!faceObj) {
+      throw new Error("Sheet Metal Tab requires a valid FACE or SKETCH selection.");
+    }
+
+    const sketchParentsToRemove = collectSketchParents(faceObj);
+    const { magnitude: thicknessAbs, signed: signedThickness } = normalizeThickness(
+      this.inputParams?.thickness ?? 1
+    );
+    const bendRadius = normalizeBendRadius(this.inputParams?.bendRadius ?? 0.125);
+    const neutralFactor = normalizeNeutralFactor(this.inputParams?.neutralFactor ?? 0.5);
+    const placement = resolvePlacementMode(this.inputParams?.placementMode, signedThickness);
+    const sheetMetal = new SheetMetalObject({
+      tree: createSheetMetalTree(),
+      kFactor: neutralFactor,
+      thickness: thicknessAbs,
+      bendRadius,
+    });
+    const profileGroups = cloneProfileGroups(faceObj);
+    const profileEdges = collectProfileEdges(faceObj);
+    const tabNode = createSheetMetalTabNode({
+      featureID: this.inputParams?.featureID || null,
+      profileRef: this.inputParams?.profile ?? null,
+      profileName: faceObj?.name || null,
+      profileGroups,
+      profileEdges,
+      thickness: thicknessAbs,
+      placementMode: placement,
+      bendRadius,
+      neutralFactor,
+      signedThickness,
+      consumeProfileSketch: this.inputParams?.consumeProfileSketch !== false,
+    });
+    sheetMetal.appendNode(tabNode);
+    await sheetMetal.generate({
+      partHistory,
+      metadataManager: partHistory?.metadataManager,
+      mode: "solid",
+    });
+
+    const effects = await BREP.applyBooleanOperation(
+      partHistory || {},
+      sheetMetal,
+      this.inputParams?.boolean,
+      this.inputParams?.featureID
+    );
+
+    const consumeSketch = this.inputParams?.consumeProfileSketch !== false;
+    const removedArtifacts = [
+      ...(consumeSketch ? sketchParentsToRemove : []),
+      ...(effects?.removed || []),
+    ];
+    const added = effects?.added || [];
+
+    cleanupSheetMetalOppositeEdgeFaces(added);
+    propagateSheetMetalFaceTypesToEdges(added);
+
+    applySheetMetalMetadata(added, partHistory?.metadataManager, {
+      featureID: this.inputParams?.featureID || null,
+      thickness: thicknessAbs,
+      bendRadius,
+      baseType: "TAB",
+      extra: { placementMode: placement, signedThickness, consumeProfileSketch: consumeSketch },
+      neutralFactor,
+      forceBaseOverwrite: true,
+    });
+
+    for (const solid of added) {
+      if (!solid) continue;
+      solid.userData = solid.userData || {};
+      solid.userData.sheetMetalTree = cloneSheetMetalTree(sheetMetal.tree);
+      solid.userData.sheetMetalKFactor = neutralFactor;
+    }
+
+    this.persistentData = this.persistentData || {};
+    this.persistentData.sheetMetal = {
+      baseType: "TAB",
+      thickness: thicknessAbs,
+      bendRadius,
+      neutralFactor,
+      placementMode: placement,
+      signedThickness,
+      consumeProfileSketch: consumeSketch,
+      profileName: faceObj?.name || null,
+      tree: sheetMetal.tree,
+    };
+
+    // Flag removed parents so history cleans them up
+    try {
+      for (const obj of removedArtifacts) {
+        if (obj) obj.__removeFlag = true;
+      }
+    } catch { /* flag optional */ }
+
+    return { added, removed: removedArtifacts };
+  }
+}

package/src/features/sheetMetal/UNFOLD_NEUTRAL_REQUIREMENTS.md

@@ -0,0 +1,153 @@
+# Sheet Metal Unfolding Requirements (Neutral Surface)
+
+This document defines the requirements for unfolding a triangulated sheet metal mesh using a neutral value (neutral factor) so that bend regions are distorted correctly in the resulting flat pattern.
+
+## 1) Scope
+
+These requirements apply to:
+- The neutral surface mesh construction used for flat pattern generation.
+- The hinge- or triangle-based unfolding steps that transform 3D geometry into a 2D flat pattern.
+- The preview and export paths (SVG/DXF) that use the unfolded mesh.
+
+## 2) Definitions
+
+- **Thickness (t)**: The sheet metal thickness.
+- **Neutral factor (k)**: A value in [0, 1] representing where the neutral surface lies between the A-side (outer) and B-side (inner) faces.
+- **Neutral surface**: The surface offset from the A or B face by `k * t` (A-side reference) or `(1 - k) * t` (B-side reference), used to preserve material length during flattening.
+- **Bend region**: Faces classified as cylindrical or conical in metadata; these should be unfolded using neutral surface geometry.
+- **Planar region**: Faces classified as planar (A or B), carried through unfold without distortion.
+- **Island**: A disconnected triangle component in the mesh used for unfolding.
+
+## 3) Inputs and Preconditions
+
+### 3.1 Geometry and Topology
+- The input mesh MUST provide:
+  - `vertProperties` (Float32Array or equivalent), `triVerts` (triangulated indices), and `faceID` for each triangle.
+  - Consistent face metadata for identifying planar vs bend faces.
+- Triangle winding MUST be coherent across connected triangles. If not, the system MUST correct it or alert.
+- Shared edges MUST be detected across the full mesh. If shared vertices are duplicated or nearly coincident, the system MUST merge or connect them via tolerance rules.
+
+### 3.2 Neutral Factor and Thickness
+- The neutral factor MUST be resolved deterministically using metadata, with a default fallback (for example, 0.5) if not provided.
+- Thickness MUST be resolved from sheet metal metadata with a fallback if not provided.
+- The system MUST reject or warn on invalid thickness (<= 0) or a neutral factor outside [0, 1].
+
+## 4) Neutral Surface Construction Requirements
+
+### 4.1 Face Classification
+- Faces MUST be classified into:
+  - A-side planar faces.
+  - B-side planar faces.
+  - Bend faces (cylindrical or conical).
+- Bend faces MUST be included in the unfolding set if they are required to connect planar faces.
+
+### 4.2 Offset Direction and Magnitude
+- For A-side reference, neutral offset MUST be:
+
+```
+neutral_offset = k * t
+```
+
+- For B-side reference, neutral offset MUST be:
+
+```
+neutral_offset = (1 - k) * t
+```
+
+- The system MUST be consistent about which side is used (A or B) and apply the same rule for planar faces in the unfolding mesh.
+- For cylindrical or conical bend faces, the flat pattern MUST correct bend allowance perpendicular to the bend centerline so that equal bend angles yield equal flat widths regardless of bend direction. The correction MAY be applied as a post-unfold translation of downstream faces rather than by changing the global neutral offset.
+
+### 4.3 Vertex Normal Handling
+- Vertex normals used to generate the neutral surface MUST be computed from the unified mesh (shared vertices across all included triangles).
+- Normals MUST be oriented consistently toward the A-side reference used by the offset.
+- If the system detects normals that oppose their neighbors, it MUST flip them or alert.
+
+### 4.4 Connectivity (Islands)
+- The neutral surface mesh MUST be connected for a valid single-piece flat pattern.
+- If multiple islands remain after offsetting, the system MUST:
+  - Attempt to align islands using edge matching (parallel + overlap) or vertex matching.
+  - Weld vertices within a tolerance once alignment occurs.
+  - If islands remain, the system MUST alert that the flat pattern will be disconnected.
+
+## 5) Unfolding Requirements
+
+### 5.1 Hinge Graph Construction
+- Adjacent triangles MUST be detected by shared edges. If shared edges are not exact matches, the system MUST:
+  - Use position tolerance to group near-coincident vertices.
+  - Or match boundary edges that are parallel and partially overlapping within tolerance.
+- Non-manifold edges (shared by > 2 triangles) MUST be flagged, and the system MUST choose the best pair or alert.
+
+### 5.2 Hinge Angle Selection
+- For each shared edge, the system MUST select the hinge rotation that aligns adjacent triangle normals in the same direction (never opposite).
+- The rotation MUST be chosen so that the angle between triangles after unfolding is 180 degrees (flat), not 0 degrees (folded back).
+
+### 5.3 Component Unfold Order
+- The system MUST choose a base component (typically the largest area) and unfold adjacent components via BFS/DFS.
+- Every reachable component MUST be transformed using the same hinge graph.
+- If components remain unreachable, the system MUST alert that islands persist.
+
+### 5.4 Second-Pass Unfold
+- The system MUST support a second unfold pass using the already-unfolded mesh to reduce residual bends.
+- The second pass MUST recompute hinge data from the mostly-flat geometry and re-apply the full unfolding sequence.
+
+## 6) 2D Placement Requirements
+
+### 6.1 Distance Preservation
+- The unfolded mesh MUST preserve edge lengths from the neutral surface (within tolerance) for all triangles.
+- Distortion beyond tolerance MUST be reported.
+
+### 6.2 Planarity
+- The final unfolded mesh MUST be coplanar. All vertices MUST lie on a single plane within tolerance.
+- If planarity fails after the second pass, the system MUST force a planar projection of vertices and alert.
+
+### 6.3 Island Handling
+- If the unfolded mesh still contains multiple islands, the system MUST:
+  - Alert the user with the island count.
+  - Continue generating the flat pattern unless the user explicitly requests a hard stop.
+
+## 7) Output Requirements
+
+- The flat pattern mesh MUST include:
+  - `vertProperties` (2D positions, Z = 0 or planar),
+  - `triVerts` (indices),
+  - `triFaces` (face ids),
+  - `thickness`, `faceMetaById`, `faceNameById`.
+- Debug artifacts MUST include:
+  - Placement order,
+  - Unfold steps or hinge steps,
+  - Island count.
+
+## 8) Validation and Error Reporting
+
+### 8.1 Required Checks
+- **Triangle winding**: Must be coherent across all connected triangles.
+- **Islands**: Component count MUST be computed and reported.
+- **Planarity**: Max distance from plane MUST be computed and compared to a tolerance.
+
+### 8.2 Tolerances
+- A size-based tolerance MUST be used for geometric comparisons, for example:
+
+```
+edge_tol = max(1e-5, diag * 1e-5)
+planar_tol = max(1e-6, diag * 1e-5)
+```
+
+Where `diag` is the bounding box diagonal of the working mesh.
+
+### 8.3 Alerts
+- The system MUST alert when:
+  - Islands remain after unfolding (include island count).
+  - The final mesh is not planar after the second pass (include max deviation).
+
+## 9) Acceptance Criteria
+
+The unfolding implementation is considered correct if:
+- All triangles are coplanar within tolerance after the second pass or forced planarization.
+- The neutral surface offset produces correct bend allowance (edge lengths on the neutral surface are preserved).
+- Islands are reported clearly if they remain.
+- SVG/DXF exports represent the same unfolded topology as the preview.
+
+## 10) Non-Goals
+
+- Exact manufacturing simulation of material spring-back or stretching beyond neutral surface modeling.
+- Automatic resolution of topological errors beyond island alignment and vertex welding.