fluidcad 0.0.37 → 0.0.39

package/lib/dist/oc/loft/guided-loft.js

@@ -0,0 +1,368 @@
+import { Vector3d } from "../../math/vector3d.js";
+import { findSpan, basisFunctions } from "../../math/bspline-interpolation.js";
+import { SectionCompatibility } from "./section-compatibility.js";
+import { SectionCurve } from "./section-curve.js";
+import { CurveData } from "./curve-data.js";
+import { Skinning } from "./skinning.js";
+import { evaluateBSplinePoint, closestCurveParameter, flattenKnots } from "./curve-eval.js";
+/**
+ * Loft steered by one or two side rails. OCC's pipe-shell machinery distorts
+ * pinned sections along curved rails (they tilt with the sweep frame, and
+ * the auxiliary-spine contact mode rotates and smears non-circular sections),
+ * so this path builds the surface itself:
+ *
+ * 1. skin the profiles alone (`Skinning`) — the unguided base surface,
+ * 2. slice the base into virtual sections between the profiles,
+ * 3. move each virtual section rigidly so its rail-contact point rides the
+ *    guide (one rail), or map its two contact points onto both rails with a
+ *    rotation + axial stretch (two rails) — profiles themselves stay exact,
+ * 4. re-skin through the full stack and cap/sew into a solid.
+ *
+ * Guides must pass through every profile: sections are pinned where they
+ * were sketched, so a rail that misses a profile is unsatisfiable.
+ *
+ * Start/end conditions compose with guides: the condition's takeoff field
+ * fades smoothly to the natural (unconstrained) takeoff around each guide's
+ * contact point — the rails own their sides of the surface, the condition
+ * shapes the rest. The faded fields drive both the base skin (so the
+ * virtual sections carry the conditioned shape) and the final re-skin (so
+ * the takeoff is pinned exactly where the condition is in force).
+ */
+export class GuidedLoft {
+    /** Virtual sections inserted between consecutive profiles. */
+    static SECTIONS_PER_SPAN = 7;
+    /** How far (mm) a guide may sit from a profile boundary and still count as touching. */
+    static CONTACT_TOLERANCE = 1e-3;
+    /** Fallback condition-falloff radius (in section parameter) for a single guide. */
+    static SINGLE_GUIDE_FALLOFF = 0.25;
+    static build(profileWires, guideWires, startCondition, endCondition) {
+        if (guideWires.length < 1 || guideWires.length > 2) {
+            throw new Error("Guided loft supports one or two guide curves.");
+        }
+        for (const wire of profileWires) {
+            if (!wire.isClosed()) {
+                throw new Error("Loft with guides requires closed profiles.");
+            }
+        }
+        let compatible = SectionCompatibility.build(profileWires.map(w => w.getShape()));
+        const guides = guideWires.map(wire => {
+            const curve = SectionCurve.fromWire(wire.getShape());
+            const data = CurveData.read(curve);
+            curve.delete();
+            return data;
+        });
+        const anchors = guides.map((guide, guideIndex) => GuidedLoft.anchorGuide(guide, guideIndex, compatible));
+        // Vertex matching: re-proportion the sections so each rail's contact
+        // sits at ONE parameter on every profile. Otherwise the flow line under
+        // the rail drifts sideways between profiles (a corner riding a rail
+        // would leave the rail), because the pinned point u-lerps while the
+        // corner stays at its own knot.
+        const wrap = (u) => ((u % 1) + 1) % 1;
+        const contactParams = compatible.sections.map((_, k) => guides.map((_, g) => wrap(anchors[g][k].u)));
+        const alignment = SectionCompatibility.alignParameters(compatible, contactParams);
+        compatible = alignment.compatible;
+        alignment.targets.forEach((target, g) => {
+            if (target !== null) {
+                for (const anchor of anchors[g]) {
+                    anchor.u = target;
+                }
+            }
+        });
+        const base = GuidedLoft.skinBase(compatible, anchors, startCondition, endCondition);
+        const { sections, params } = GuidedLoft.buildSectionStack(compatible, base, guides, anchors);
+        const skinned = Skinning.interpolateColumns(sections, params, GuidedLoft.stackField(compatible, anchors, startCondition, base.averageLength, sections, params, false), GuidedLoft.stackField(compatible, anchors, endCondition, base.averageLength, sections, params, true));
+        return [Skinning.buildLoftSolid(compatible, skinned.grid, skinned.vBasis)];
+    }
+    /**
+     * The unguided base skin, with any end conditions already faded around the
+     * guide contacts (blended towards the natural chord takeoff, per column).
+     */
+    static skinBase(compatible, anchors, startCondition, endCondition) {
+        const { sections } = compatible;
+        const { params, averageLength } = Skinning.loftParameters(sections);
+        const columns = sections.map(section => section.poles);
+        const startField = GuidedLoft.stackField(compatible, anchors, startCondition, averageLength, columns, params, false);
+        const endField = GuidedLoft.stackField(compatible, anchors, endCondition, averageLength, columns, params, true);
+        const { grid, vBasis } = Skinning.interpolateColumns(columns, params, startField, endField);
+        return { grid, vBasis, params, averageLength };
+    }
+    /**
+     * The condition's takeoff field for one end of a section stack, faded to
+     * the stack's own natural takeoff (the chord to the neighbouring section)
+     * around each guide contact. Null when no condition applies to that end.
+     */
+    static stackField(compatible, anchors, condition, averageLength, sections, params, isEnd) {
+        if (!condition) {
+            return null;
+        }
+        const endIndex = isEnd ? compatible.sections.length - 1 : 0;
+        const conditionField = Skinning.derivativeField(compatible.sections[endIndex], condition, averageLength, isEnd);
+        const contacts = anchors.map(anchor => {
+            const u = anchor[endIndex].u;
+            return ((u % 1) + 1) % 1;
+        });
+        const weights = GuidedLoft.falloffWeights(compatible, contacts);
+        const last = sections.length - 1;
+        const [nearIndex, farIndex] = isEnd ? [last, last - 1] : [0, 1];
+        const chordSpan = Math.abs(params[nearIndex] - params[farIndex]);
+        return conditionField.map((target, i) => {
+            // Natural takeoff: the chord towards the neighbouring stack section
+            // (points along increasing v at both ends).
+            const natural = sections[nearIndex][i].map((v, d) => ((isEnd ? v - sections[farIndex][i][d] : sections[farIndex][i][d] - v)) / chordSpan);
+            const w = weights[i];
+            return target.map((t, d) => natural[d] + (t - natural[d]) * w);
+        });
+    }
+    /**
+     * Per-column condition weight: 0 at each guide contact, smoothstepping to
+     * 1 beyond the falloff radius (half the closest contact separation for two
+     * guides). Columns are located by their Greville parameters.
+     */
+    static falloffWeights(compatible, contacts) {
+        const circularDistance = (a, b) => {
+            const d = Math.abs(a - b) % 1;
+            return Math.min(d, 1 - d);
+        };
+        let radius = GuidedLoft.SINGLE_GUIDE_FALLOFF;
+        for (let a = 0; a < contacts.length; a++) {
+            for (let b = a + 1; b < contacts.length; b++) {
+                radius = Math.min(radius, circularDistance(contacts[a], contacts[b]) / 2);
+            }
+        }
+        radius = Math.max(radius, 0.05);
+        const flat = flattenKnots(compatible.knots, compatible.multiplicities);
+        const degree = compatible.degree;
+        const poleCount = compatible.sections[0].poles.length;
+        const weights = [];
+        for (let i = 0; i < poleCount; i++) {
+            let greville = 0;
+            for (let j = 1; j <= degree; j++) {
+                greville += flat[i + j];
+            }
+            greville /= degree;
+            const wrapped = ((greville % 1) + 1) % 1;
+            let distance = Infinity;
+            for (const contact of contacts) {
+                distance = Math.min(distance, circularDistance(wrapped, contact));
+            }
+            const t = Math.min(1, Math.max(0, distance / radius));
+            weights.push(t * t * (3 - 2 * t));
+        }
+        return weights;
+    }
+    /**
+     * Locates the guide's contact with every profile: the guide parameter
+     * where it crosses the profile plane, and the profile parameter of the
+     * nearest boundary point. Off-boundary rails are reported with their gap —
+     * sections stay where they were sketched, so such rails are unsatisfiable.
+     */
+    static anchorGuide(guide, guideIndex, compatible) {
+        const anchors = [];
+        for (let k = 0; k < compatible.sections.length; k++) {
+            const section = compatible.sections[k];
+            const t = GuidedLoft.planeCrossing(guide, section.centroid, section.normal);
+            if (t === null) {
+                throw new Error(`Loft guide ${guideIndex + 1} does not cross the plane of profile ${k + 1} — `
+                    + "each guide must pass through every profile.");
+            }
+            const point = evaluateBSplinePoint(guide, t);
+            const sectionCurve = {
+                degree: compatible.degree,
+                knots: compatible.knots,
+                multiplicities: compatible.multiplicities,
+                poles: section.poles,
+                weights: compatible.weights,
+            };
+            let u = closestCurveParameter(tt => evaluateBSplinePoint(sectionCurve, tt), point);
+            const boundaryPoint = evaluateBSplinePoint(sectionCurve, u);
+            const gap = Math.hypot(boundaryPoint[0] - point[0], boundaryPoint[1] - point[1], boundaryPoint[2] - point[2]);
+            if (gap > GuidedLoft.CONTACT_TOLERANCE) {
+                throw new Error(`Loft guide ${guideIndex + 1} does not touch profile ${k + 1} `
+                    + `(gap ${gap.toFixed(3)} mm) — guides must pass through every profile boundary.`);
+            }
+            // Sections are closed in u — unwrap so per-span interpolation of the
+            // contact parameter never jumps across the seam.
+            if (k > 0) {
+                while (u - anchors[k - 1].u > 0.5) {
+                    u -= 1;
+                }
+                while (u - anchors[k - 1].u < -0.5) {
+                    u += 1;
+                }
+            }
+            anchors.push({ t, u, point });
+        }
+        return anchors;
+    }
+    /**
+     * Guide parameter where the guide crosses the plane (centroid, normal):
+     * the sign-change bracket (or on-plane endpoint) whose crossing point lies
+     * closest to the centroid, refined by bisection. Null when the guide never
+     * reaches the plane.
+     */
+    static planeCrossing(guide, centroid, normal) {
+        const signedDistance = (t) => {
+            const p = evaluateBSplinePoint(guide, t);
+            return (p[0] - centroid.x) * normal.x + (p[1] - centroid.y) * normal.y + (p[2] - centroid.z) * normal.z;
+        };
+        const samples = 256;
+        const values = [];
+        for (let i = 0; i <= samples; i++) {
+            values.push(signedDistance(i / samples));
+        }
+        const candidates = [];
+        if (Math.abs(values[0]) <= GuidedLoft.CONTACT_TOLERANCE) {
+            candidates.push(0);
+        }
+        if (Math.abs(values[samples]) <= GuidedLoft.CONTACT_TOLERANCE) {
+            candidates.push(1);
+        }
+        for (let i = 0; i < samples; i++) {
+            if (values[i] === 0 || values[i] * values[i + 1] < 0) {
+                let low = i / samples;
+                let high = (i + 1) / samples;
+                let lowValue = values[i];
+                for (let iteration = 0; iteration < 60; iteration++) {
+                    const mid = (low + high) / 2;
+                    const midValue = signedDistance(mid);
+                    if (lowValue * midValue <= 0) {
+                        high = mid;
+                    }
+                    else {
+                        low = mid;
+                        lowValue = midValue;
+                    }
+                }
+                candidates.push((low + high) / 2);
+            }
+        }
+        let best = null;
+        let bestDistance = Infinity;
+        for (const t of candidates) {
+            const p = evaluateBSplinePoint(guide, t);
+            const distance = Math.hypot(p[0] - centroid.x, p[1] - centroid.y, p[2] - centroid.z);
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = t;
+            }
+        }
+        return best;
+    }
+    /**
+     * The full section stack: the exact profiles at their own parameters, and
+     * between each pair the base surface's iso-sections carried onto the rails.
+     */
+    static buildSectionStack(compatible, base, guides, anchors) {
+        const sections = [];
+        const params = [];
+        for (let k = 0; k < compatible.sections.length; k++) {
+            sections.push(compatible.sections[k].poles);
+            params.push(base.params[k]);
+            if (k === compatible.sections.length - 1) {
+                break;
+            }
+            for (let m = 1; m <= GuidedLoft.SECTIONS_PER_SPAN; m++) {
+                const s = m / (GuidedLoft.SECTIONS_PER_SPAN + 1);
+                const v = base.params[k] + (base.params[k + 1] - base.params[k]) * s;
+                const poles = GuidedLoft.isoSectionPoles(base, v);
+                sections.push(GuidedLoft.applyRails(poles, compatible, guides, anchors, k, s));
+                params.push(v);
+            }
+        }
+        return { sections, params };
+    }
+    /** Poles of the base surface's iso-section at loft parameter v (a v-basis row blend). */
+    static isoSectionPoles(base, v) {
+        const flat = flattenKnots(base.vBasis.knots, base.vBasis.multiplicities);
+        const vPoleCount = base.grid[0].length;
+        const span = findSpan(vPoleCount, base.vBasis.degree, v, flat);
+        const values = basisFunctions(span, v, base.vBasis.degree, flat);
+        return base.grid.map(row => {
+            const pole = [0, 0, 0];
+            for (let j = 0; j <= base.vBasis.degree; j++) {
+                const source = row[span - base.vBasis.degree + j];
+                pole[0] += values[j] * source[0];
+                pole[1] += values[j] * source[1];
+                pole[2] += values[j] * source[2];
+            }
+            return pole;
+        });
+    }
+    /**
+     * Carries a virtual section onto the rails. One rail translates the
+     * section rigidly; two rails additionally rotate and stretch it along the
+     * contact axis so both contact points land on their rails. Affine maps
+     * leave NURBS weights untouched, so transforming poles transforms the
+     * section exactly.
+     */
+    static applyRails(poles, compatible, guides, anchors, span, s) {
+        const sectionCurve = {
+            degree: compatible.degree,
+            knots: compatible.knots,
+            multiplicities: compatible.multiplicities,
+            poles,
+            weights: compatible.weights,
+        };
+        const current = [];
+        const target = [];
+        for (let g = 0; g < guides.length; g++) {
+            const from = anchors[g][span];
+            const to = anchors[g][span + 1];
+            const u = from.u + (to.u - from.u) * s;
+            const wrapped = ((u % 1) + 1) % 1;
+            const a = evaluateBSplinePoint(sectionCurve, wrapped);
+            current.push(new Vector3d(a[0], a[1], a[2]));
+            const t = from.t + (to.t - from.t) * s;
+            const A = evaluateBSplinePoint(guides[g], t);
+            target.push(new Vector3d(A[0], A[1], A[2]));
+        }
+        if (guides.length === 1) {
+            const delta = target[0].subtract(current[0]);
+            return poles.map(p => [p[0] + delta.x, p[1] + delta.y, p[2] + delta.z]);
+        }
+        return GuidedLoft.mapSegment(poles, current[0], current[1], target[0], target[1]);
+    }
+    /**
+     * Affine map taking segment (a1, a2) onto (A1, A2): stretch along the
+     * segment axis, minimal rotation aligning the axes, rigid perpendicular
+     * components. Degenerate segments fall back to the average translation.
+     */
+    static mapSegment(poles, a1, a2, A1, A2) {
+        const d = a2.subtract(a1);
+        const D = A2.subtract(A1);
+        if (d.length() < 1e-9 || D.length() < 1e-9) {
+            const delta = A1.subtract(a1).add(A2.subtract(a2)).multiply(0.5);
+            return poles.map(p => [p[0] + delta.x, p[1] + delta.y, p[2] + delta.z]);
+        }
+        const dHat = d.normalize();
+        const DHat = D.normalize();
+        const stretch = D.length() / d.length();
+        const rotate = GuidedLoft.minimalRotation(dHat, DHat);
+        return poles.map(p => {
+            const relative = new Vector3d(p[0] - a1.x, p[1] - a1.y, p[2] - a1.z);
+            const axial = relative.dot(dHat);
+            const perpendicular = relative.subtract(dHat.multiply(axial));
+            const mapped = DHat.multiply(axial * stretch).add(rotate(perpendicular));
+            return [A1.x + mapped.x, A1.y + mapped.y, A1.z + mapped.z];
+        });
+    }
+    /** Rodrigues rotation taking unit vector `from` to unit vector `to`. */
+    static minimalRotation(from, to) {
+        const cosAngle = from.dot(to);
+        const axis = from.cross(to);
+        const sinAngle = axis.length();
+        if (sinAngle < 1e-12) {
+            if (cosAngle > 0) {
+                return v => v;
+            }
+            // Antiparallel: 180° about any axis perpendicular to `from`.
+            const helper = Math.abs(from.x) < 0.9 ? new Vector3d(1, 0, 0) : new Vector3d(0, 1, 0);
+            const perpendicular = from.cross(helper).normalize();
+            return v => perpendicular.multiply(2 * v.dot(perpendicular)).subtract(v);
+        }
+        const axisHat = axis.normalize();
+        return v => v.multiply(cosAngle)
+            .add(axisHat.cross(v).multiply(sinAngle))
+            .add(axisHat.multiply(axisHat.dot(v) * (1 - cosAngle)));
+    }
+}

package/lib/dist/oc/loft/section-compatibility.d.ts

@@ -0,0 +1,131 @@
+import type { TopoDS_Wire } from "ocjs-fluidcad";
+import { Vector3d } from "../../math/vector3d.js";
+/** One profile as a compatible section: poles only — knots/degree/weights are shared. */
+export interface CompatibleSection {
+    poles: number[][];
+    /** Centroid of the section (uniform parameter sampling). */
+    centroid: Vector3d;
+    /** Unit section normal, consistently oriented from first section towards last. */
+    normal: Vector3d;
+}
+/**
+ * Sections reduced to a common B-spline basis: every section shares the same
+ * degree, knot vector, and weight vector, differing only in poles — exactly
+ * the form a skinned `Geom_BSplineSurface` needs (its u-basis is this shared
+ * basis; its v-poles come from interpolating matching pole columns).
+ */
+export interface CompatibleSections {
+    degree: number;
+    knots: number[];
+    multiplicities: number[];
+    /** Shared weight vector, or null when all sections are polynomial. */
+    weights: number[] | null;
+    /**
+     * Interior knots where at least one section has a real tangent kink
+     * (profile corners). The skinned surface must be split into separate
+     * faces there — a corner buried inside one face renders with smeared
+     * normals and offers no edge to select or fillet.
+     */
+    creases: number[];
+    sections: CompatibleSection[];
+}
+/**
+ * Brings profile wires onto a common B-spline basis for skinning:
+ *
+ * 1. each wire becomes a single clamped curve over [0, 1] (`SectionCurve`),
+ * 2. winding directions are made consistent along the loft,
+ * 3. seams are chained to the nearest point of the previous section's seam
+ *    (minimal twist),
+ * 4. degrees are raised and knot vectors merged to a common union,
+ * 5. weight vectors must then agree across sections — when they don't (e.g.
+ *    a circle lofted to a rectangle), all rational pieces are re-approximated
+ *    as polynomials and the pipeline reruns once, making everything weightless.
+ */
+export declare class SectionCompatibility {
+    private static readonly SAMPLES;
+    /** Knots closer than this (curves live on [0, 1]) are treated as one. */
+    private static readonly KNOT_TOLERANCE;
+    private static readonly WEIGHT_TOLERANCE;
+    /** Tangent turns above this (radians) across a knot count as a profile corner. */
+    private static readonly CREASE_ANGLE;
+    /**
+     * Relative curvature jumps above this across a knot count as a feature
+     * boundary (e.g. the tangent line→arc junctions of an offset wire's
+     * rounded corner). Well below any real feature transition, well above the
+     * ~1% wobble of polynomial-approximated conics.
+     */
+    private static readonly CREASE_CURVATURE_JUMP;
+    static build(wires: TopoDS_Wire[]): CompatibleSections;
+    /**
+     * Re-proportions every section's parameterization so that the given
+     * per-section parameters land on shared targets (their cross-section
+     * averages), then re-unifies the basis. Rail-guided lofts use this to make
+     * each rail's contact sit at one parameter on every profile — otherwise
+     * the surface's flow lines (and any profile corner riding a rail) drift
+     * away from the rail between and at the profiles.
+     *
+     * `sectionParams[k]` lists the contact parameters of section k, one per
+     * rail, in matching order across sections. Parameters at the seam are
+     * aligned already and are ignored. Returns the input unchanged when there
+     * is nothing to align or when the re-unified sections would lose their
+     * shared weight vector (exotic rational cases degrade gracefully).
+     */
+    static alignParameters(compatible: CompatibleSections, sectionParams: number[][]): {
+        compatible: CompatibleSections;
+        targets: (number | null)[];
+    };
+    /** Re-unifies re-proportioned section curves, keeping the original frames. */
+    private static rebuildAligned;
+    /** Returns null when the sections end up with mismatched weight vectors. */
+    private static buildFromCurves;
+    /**
+     * The shared weight vector: null if every section is polynomial, the common
+     * vector if all rational sections agree (after normalizing to weight 1 on
+     * the first pole), and undefined — "no shared basis" — otherwise.
+     */
+    private static sharedWeights;
+    /**
+     * Makes all sections wind the same way along the loft: the first section's
+     * normal (from its winding, via Newell's method) is oriented towards the
+     * next centroid, then each further section is flipped whenever its winding
+     * normal opposes its predecessor's. Reversing the curve flips its normal.
+     */
+    private static orientConsistently;
+    /** Centroid and winding normal (Newell's method) from uniform parameter samples. */
+    private static sectionFrame;
+    /**
+     * Chains each section's seam (curve origin) to the point nearest the
+     * previous section's seam, so the skinned surface doesn't twist. Closed
+     * clamped curves can't shift their origin in place; the curve is split at
+     * the new seam and re-concatenated.
+     */
+    private static alignSeams;
+    /** Parameter of the point on the curve closest to `target` (sampling + golden-section refine). */
+    private static closestParameter;
+    /**
+     * Returns the curve re-parameterized so its origin sits at parameter `t`
+     * (splitting and re-concatenating), consuming the input. No-op near the
+     * existing seam.
+     */
+    private static moveSeam;
+    private static unifyDegree;
+    /**
+     * Merges every section's interior knots into one union (values clustered
+     * within `KNOT_TOLERANCE` are snapped to a single representative first)
+     * and inserts the union into each curve, so all sections share one knot
+     * vector — and therefore one pole count.
+     */
+    private static unifyKnots;
+    /**
+     * Interior knots where any section changes character: only knots of full
+     * multiplicity (structurally C0) can. Two kinds of feature boundary count:
+     * a tangent kink (a profile corner — turns by degrees, while smooth
+     * junctions from concatenation or seam moves turn by ~0), and a curvature
+     * jump (the tangent line→arc junctions of rounded/offset corners — the
+     * legacy loft splits faces there too, and without the split the near-crease
+     * band renders smeared and offers no edge).
+     */
+    private static detectCreases;
+    private static nearestRepresentative;
+    private static samplePoints;
+}