brepjs-sheetmetal 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,128 @@
+import { Result, Solid } from 'brepjs';
+import { AuthorSpec, FlangeSpec } from './authorFns.js';
+import { MiterPlane } from './miterFns.js';
+import { SlotPlacement } from './tabFns.js';
+import { DxfOptions } from './dxfFns.js';
+import { NestOptions, NestResult } from './nestFns.js';
+import { BendTable } from './bendTableFns.js';
+import { SheetMetalPart, FlatPattern, FlatInput, BendReport, BendRule, ReliefSpec, CutoutSpec, TabSpec, ContourFlangeSpec, LoftedFlangeSpec, HemSpec, JogSpec, UnfoldResult, SheetMetalWarning } from './types.js';
+/** Author a straight-bend part: a base flat plus folded-up flanges. */
+export declare function author(spec: AuthorSpec): Result<SheetMetalPart>;
+/** Flatten an authored part into a developed flat pattern + bend report + warnings. */
+export declare function unfold(part: SheetMetalPart): Result<UnfoldResult>;
+/**
+ * Unfold an imported sheet-metal solid that has no feature tree, by detecting its
+ * geometry (planar panels + cylindrical bends) numerically. `kFactor` defaults to
+ * the mid-surface neutral axis (0.5); supply a known material's K-factor to match
+ * its development.
+ */
+export declare function unfoldSolid(solid: Solid, opts?: {
+    kFactor?: number;
+}): Result<UnfoldResult>;
+/** Fold a flat pattern (region-tree) up into a 3D part — the inverse of {@link unfold}. */
+export declare function fold(input: FlatInput): Result<SheetMetalPart>;
+/** Cut a part by an oriented plane, removing material on the `+normal` side. */
+export declare function miter(part: SheetMetalPart, plane: MiterPlane): Result<SheetMetalPart>;
+/** Auto-miter the shared corner of two flanges with an optional gap. */
+export declare function miterCorner(part: SheetMetalPart, flangeIdA: string, flangeIdB: string, gap?: number): Result<SheetMetalPart>;
+/** Add a bend relief slot at each mid-edge end of a partial flange's bend line. */
+export declare function bendRelief(part: SheetMetalPart, flangeId: string, spec?: ReliefSpec): Result<SheetMetalPart>;
+/** Add a bend relief to every partial-span bend in the part. */
+export declare function autoReliefs(part: SheetMetalPart, spec?: ReliefSpec): Result<SheetMetalPart>;
+/** Cut a corner relief notch at the shared corner of two adjacent flanges. */
+export declare function relieveCorner(part: SheetMetalPart, flangeIdA: string, flangeIdB: string, spec?: ReliefSpec): Result<SheetMetalPart>;
+/** Punch a cutout (hole / slot / polygon) through a named flat region's thickness. */
+export declare function addCutout(part: SheetMetalPart, spec: CutoutSpec): Result<SheetMetalPart>;
+/** Punch a circular hole of `diameter` centred at region-local `(x, y)`. */
+export declare function addHole(part: SheetMetalPart, region: string, x: number, y: number, diameter: number): Result<SheetMetalPart>;
+/** Punch a slot (rectangular or obround) centred at region-local `(x, y)`. */
+export declare function addSlot(part: SheetMetalPart, region: string, opts: {
+    x: number;
+    y: number;
+    length: number;
+    width: number;
+    angleDeg?: number;
+    round?: boolean;
+}): Result<SheetMetalPart>;
+/** Punch an arbitrary polygon cutout from its region-local `points`. */
+export declare function addPolygonCutout(part: SheetMetalPart, region: string, points: [number, number][]): Result<SheetMetalPart>;
+/** Fuse a rectangular tab (additive protrusion) onto a region's edge. */
+export declare function addTab(part: SheetMetalPart, spec: TabSpec): Result<SheetMetalPart>;
+/** Self-fixturing tab-and-slot joint: a tab on one region + a matching slot on another. */
+export declare function tabAndSlot(part: SheetMetalPart, tab: TabSpec, slot: SlotPlacement): Result<SheetMetalPart>;
+/** Form a louver (vent flap cut on 3 sides, formed up along the hinge) on a region. */
+export declare function louver(part: SheetMetalPart, opts: {
+    region: string;
+    x: number;
+    y: number;
+    length: number;
+    width: number;
+    height: number;
+    direction?: 'up' | 'down';
+}): Result<SheetMetalPart>;
+/** Form a round emboss (raised) or dimple (recessed) on a region. */
+export declare function emboss(part: SheetMetalPart, opts: {
+    region: string;
+    x: number;
+    y: number;
+    diameter: number;
+    height: number;
+    kind: 'dimple' | 'emboss';
+}): Result<SheetMetalPart>;
+/**
+ * Author a contour flange: an open line/arc profile swept along a base edge into a
+ * multi-bend cross-section. The development is exact (Σ segment developed lengths).
+ */
+export declare function contourFlange(part: SheetMetalPart, spec: ContourFlangeSpec): Result<SheetMetalPart>;
+/**
+ * Author a lofted / ruled transition flange between two parallel open profiles. The
+ * development is by triangulation — exact for a developable transition, an
+ * approximation (with a `DEVELOPMENT_APPROXIMATE` unfold warning) otherwise.
+ */
+export declare function loftedFlange(part: SheetMetalPart, spec: LoftedFlangeSpec): Result<SheetMetalPart>;
+/**
+ * Author a hem: fold a region edge back ~180°+ onto its parent and run a short
+ * return leg. The development is exact (Σ curl bend allowances + return length).
+ */
+export declare function hem(part: SheetMetalPart, spec: HemSpec): Result<SheetMetalPart>;
+/**
+ * Author a jog (joggle): two opposite bends stepping the flat by `offsetHeight`
+ * perpendicular to its plane, then continuing parallel. Development is exact.
+ */
+export declare function jog(part: SheetMetalPart, spec: JogSpec): Result<SheetMetalPart>;
+/** Emit an annotated multi-layer DXF string for a flat pattern. */
+export declare function toDXF(pattern: FlatPattern, options?: DxfOptions): Result<string>;
+/**
+ * Nest developed flat patterns onto stock sheets to reduce waste. The default
+ * `strategy: "bbox"` packs each part as its outline bounding box (fast, no
+ * interlocking). `strategy: "nfp"` is true-shape / no-fit-polygon nesting: the actual
+ * outline polygons are packed so concave (L-shaped) parts interlock for higher
+ * utilization. The NFP packer is a HEURISTIC (bottom-left-fill) — not provably
+ * optimal — but never overlaps parts and never drops a part silently.
+ */
+export declare function nest(patterns: FlatPattern[], options: NestOptions): Result<NestResult>;
+/** Emit one fabrication-ready DXF for a single nested sheet (all parts placed). */
+export declare function nestToDXF(result: NestResult, patterns: FlatPattern[], sheetIndex: number, options?: DxfOptions): Result<string>;
+/** Build a bend report by walking the part's feature tree. */
+export declare function report(part: SheetMetalPart): Result<BendReport>;
+/** Project the report already computed by {@link unfold} without re-walking the tree. */
+export declare function reportFrom(result: UnfoldResult): Result<BendReport>;
+/** Serialize a bend report to stable pretty-printed JSON. */
+export declare function reportJSON(report: BendReport): string;
+/** Manufacturability checks — advisory warnings, never errors. */
+export declare function validate(part: SheetMetalPart): SheetMetalWarning[];
+/** Bend allowance `BA = (π/180)·|angle|·(R + K·T)` for a single bend. */
+export declare function allowance(angleDeg: number, thickness: number, rule: BendRule, onWarning?: (warning: SheetMetalWarning) => void): Result<number>;
+/** Neutral-axis developed length of a bend region (numerically equal to the allowance). */
+export declare function developed(angleDeg: number, thickness: number, rule: BendRule, onWarning?: (warning: SheetMetalWarning) => void): Result<number>;
+/** Register (or replace) a shop bend table so rules can reference it by id. */
+export declare function addBendTable(table: BendTable): Result<BendTable>;
+/** Look up a registered bend table by id (starter tables included). */
+export declare function bendTable(id: string): BendTable | undefined;
+/**
+ * Resolve a bend's developed allowance through the single resolution point:
+ * a referenced bend table, then an explicit `rule.allowance`, then the K-factor
+ * formula. This is what {@link developed} delegates to.
+ */
+export declare function resolveAllowance(rule: BendRule, angleDeg: number, thickness: number, onWarning?: (warning: SheetMetalWarning) => void): Result<number>;
+export type { AuthorSpec, FlangeSpec, MiterPlane, DxfOptions, SlotPlacement, NestOptions, NestResult };

package/dist/authorFns.d.ts

@@ -0,0 +1,100 @@
+import { Result, Vec3 } from 'brepjs';
+import { BendRule, EdgeRef, FlatSide, MaterialSpec, MiterSpec, SheetMetalPart } from './types.js';
+import { FeatureTree } from './featureTreeFns.js';
+/** Authoring options for the base flat the flanges attach to. */
+export interface BaseFlatSpec {
+    /** Extent along the run (+X) axis. */
+    length: number;
+    /** Extent along the width (+Y) axis. */
+    width: number;
+}
+/** Which edge a flange folds off (of the base, or of its parent flange). */
+export type FlangeSide = FlatSide;
+/** A single flange to author off an edge of its parent flat. */
+export interface FlangeSpec {
+    id: string;
+    /** Flat length measured from the end of the bend along the flange plane. */
+    length: number;
+    /** Signed fold angle in degrees. */
+    angleDeg: number;
+    rule: BendRule;
+    /** Parent edge to attach to. Default `'xmax'` (the leading +X edge). */
+    side?: FlangeSide | undefined;
+    /** Fold direction relative to the parent face normal. Default `'up'`. */
+    direction?: 'up' | 'down' | undefined;
+    /** Id of another flange this flange folds off (its distal edge). Default = base flat. */
+    parent?: string | undefined;
+    /** Start position along the parent edge. Default `0`. */
+    offset?: number | undefined;
+    /** Extent along the parent edge. Default = full parent-edge length. */
+    width?: number | undefined;
+    miter?: MiterSpec | undefined;
+}
+/**
+ * A seam: a bend connecting two already-authored flats that is intentionally left
+ * unfolded (a free edge). Closing the last wall of a box/tube back onto an earlier
+ * flat produces a cyclic feature graph; the feature tree turns this edge into a
+ * SEAM_CUT, and the unfold leaves the flats connected through the spanning tree.
+ */
+export interface SeamSpec {
+    /** Flat id the seam folds from (an authored flange, or `'root'`/`'face-0'` for the base). */
+    parent: string;
+    /** Flat id the seam meets (must already be authored; `'root'`/`'face-0'` = base). */
+    child: string;
+    angleDeg: number;
+    rule: BendRule;
+}
+/** Inputs for {@link authorPart}. */
+export interface AuthorSpec {
+    thickness: number;
+    base: BaseFlatSpec;
+    flanges: FlangeSpec[];
+    material?: MaterialSpec | undefined;
+    /** Optional seams that close a profile into a tube/box (left unfolded). */
+    seams?: SeamSpec[] | undefined;
+}
+/**
+ * Stable edge reference for flange attachment. The base flat is `face-0`; every
+ * flange face is `face-<n+1>` in authoring order. The leading edge of a flat is
+ * `edgeIndex 0`. The reference also carries `parentId`/`side`/`offset`/`extent`
+ * so the feature tree and recursive unfold can resolve the exact parent edge a
+ * flange folds from without reading topology back out of the B-rep.
+ */
+export declare function baseEdgeRef(faceIndex: number): EdgeRef;
+/**
+ * A flat in the part: the base, or a placed flange face. Each carries the world
+ * frame (origin + orthonormal axes) of its top surface so a child flange can be
+ * built directly off any of its four edges, at any fold direction.
+ */
+export interface FlatFrame {
+    id: string;
+    /** Near corner of the flat on its −normal (bottom) surface; the flat spans
+     * `thickness` along +n. Local `(x, y)` maps to `origin + x·u + y·v`. */
+    origin: Vec3;
+    /** In-plane direction; the flat spans `[0, uLen]` along it. */
+    u: Vec3;
+    /** In-plane direction; the flat spans `[0, vLen]` along it. */
+    v: Vec3;
+    /** Outward face normal of the top surface (n = u × v). */
+    n: Vec3;
+    uLen: number;
+    vLen: number;
+}
+/**
+ * Author a sheet-metal part: a base flat plus an arbitrary tree of flanges. Each
+ * flange folds off one of the four edges of its parent flat (the base by default,
+ * or another flange via `parent`), in the requested direction (up/down), over an
+ * optional sub-span of that edge (`offset`/`width`). Returns a {@link SheetMetalPart}
+ * carrying the folded 3D solid and the recorded bend feature tree the unfold
+ * consumes. All construction stays on the public, OCCT-WASM-safe API.
+ */
+export declare function authorPart(spec: AuthorSpec): Result<SheetMetalPart>;
+/**
+ * World {@link FlatFrame} of every flat region of an authored part, keyed by region
+ * id (`'root'` for the base). Reconstructed from the recorded bend/flange feature
+ * tree using the exact same edge/transform/child-frame math {@link authorPart} uses
+ * to place the geometry, so a cutout authored in a region's local `(x, y)` lands on
+ * the matching folded face. Walks the feature tree in BFS order so a chained
+ * flange's parent frame is always known first.
+ */
+export declare function worldFrames(part: SheetMetalPart, tree?: FeatureTree): Result<Map<string, FlatFrame>>;

package/dist/bendTableFns.d.ts

@@ -0,0 +1,58 @@
+import { Result } from 'brepjs';
+import { BendRule, SheetMetalWarning } from './types.js';
+/**
+ * One row of a shop bend table: the tabulated value for a single
+ * (thickness, innerRadius, bend-angle) operating point. `value` is a bend
+ * allowance (`kind: 'allowance'`) or a bend deduction (`kind: 'deduction'`),
+ * per the owning {@link BendTable}.
+ */
+export interface BendTableRow {
+    /** Material thickness the row was measured at. */
+    thickness: number;
+    /** Inner bend radius the row was measured at. */
+    radius: number;
+    /** Swept bend angle in degrees (90° = a right-angle bend). */
+    angleDeg: number;
+    /** Bend allowance or bend deduction, per the table's {@link BendTable.kind}. */
+    value: number;
+}
+/**
+ * A named shop bend table: empirical bend-allowance or bend-deduction values
+ * measured per (thickness, radius, angle). When a {@link BendRule} references a
+ * table by id, {@link resolveBendAllowance} interpolates the table instead of
+ * applying the K-factor formula, so the developed length matches the shop's
+ * actual press-brake results.
+ *
+ * `kind` selects how a row's `value` is interpreted: an `'allowance'` table
+ * tabulates the developed arc length directly; a `'deduction'` table tabulates
+ * the bend deduction, which is converted to an allowance on lookup (see
+ * {@link resolveBendAllowance} for the OSSB conversion).
+ */
+export interface BendTable {
+    id: string;
+    kind: 'allowance' | 'deduction';
+    rows: BendTableRow[];
+}
+/**
+ * Register (or replace) a bend table under its id, so a {@link BendRule} with a
+ * matching `bendTableRef` resolves against it. Returns the registered table.
+ */
+export declare function registerBendTable(table: BendTable): Result<BendTable>;
+/** Look up a registered bend table by id (registers the starter tables on first use). */
+export declare function getBendTable(id: string): BendTable | undefined;
+/**
+ * The single source of truth for a bend's developed (neutral-axis) length.
+ *
+ * Precedence:
+ *  1. `rule.bendTableRef` — look up the table and interpolate it (linear in
+ *     angle, bilinear across thickness × radius), converting a deduction table
+ *     to an allowance via {@link allowanceFromDeduction}. Outside the table
+ *     extents the lookup clamps to the nearest breakpoint and reports a
+ *     `MIN_RADIUS`-class warning through `onWarning` rather than extrapolating.
+ *  2. `rule.allowance` — an explicit per-bend override, returned verbatim.
+ *  3. The K-factor formula BA = (π/180)·|angle|·(R + K·T).
+ *
+ * The returned value is in the same units and sense the rest of the package's
+ * `developedLength` consumes (a strip width along the developed pattern).
+ */
+export declare function resolveBendAllowance(rule: BendRule, angleDeg: number, thickness: number, onWarning?: (warning: SheetMetalWarning) => void): Result<number>;