@snaptrude/plugin-core 0.0.0-dev-20260921132444 → 0.0.0-surfaces-20260923052616

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +1 -1
  2. package/api-manifest.json +767 -31
  3. package/dist/api/core/geom/create/index.d.ts +924 -100
  4. package/dist/api/core/geom/create/index.d.ts.map +1 -1
  5. package/dist/api/core/geom/query/brep.d.ts +55 -1
  6. package/dist/api/core/geom/query/brep.d.ts.map +1 -1
  7. package/dist/api/core/geom/query/curve.d.ts +58 -35
  8. package/dist/api/core/geom/query/curve.d.ts.map +1 -1
  9. package/dist/api/core/geom/query/edge.d.ts +2 -2
  10. package/dist/api/core/geom/query/face.d.ts +105 -0
  11. package/dist/api/core/geom/query/face.d.ts.map +1 -1
  12. package/dist/api/core/geom/update/curve.d.ts +5 -5
  13. package/dist/api/core/geom/update/profile.d.ts +1 -1
  14. package/dist/api/design/create/grids.d.ts +2 -2
  15. package/dist/api/design/create/grids.d.ts.map +1 -1
  16. package/dist/api/design/family.d.ts +65 -8
  17. package/dist/api/design/family.d.ts.map +1 -1
  18. package/dist/api/design/query/geometry/index.d.ts +33 -5
  19. package/dist/api/design/query/geometry/index.d.ts.map +1 -1
  20. package/dist/api/design/query/grids.d.ts +4 -3
  21. package/dist/api/design/query/grids.d.ts.map +1 -1
  22. package/dist/api/design/query/index.d.ts +47 -0
  23. package/dist/api/design/query/index.d.ts.map +1 -1
  24. package/dist/api/design/query/spaces.d.ts +5 -5
  25. package/dist/api/design/update/index.d.ts +87 -0
  26. package/dist/api/design/update/index.d.ts.map +1 -1
  27. package/dist/api/entity/referenceLine.d.ts +2 -2
  28. package/dist/api/entity/referenceLine.d.ts.map +1 -1
  29. package/dist/api/entity/space.d.ts +5 -4
  30. package/dist/api/entity/space.d.ts.map +1 -1
  31. package/dist/api/entity/story.d.ts +4 -4
  32. package/dist/api/program/site.d.ts +4 -4
  33. package/dist/api/program/spreadsheet.d.ts +4 -4
  34. package/dist/handles.d.ts +12 -3
  35. package/dist/handles.d.ts.map +1 -1
  36. package/dist/index.cjs +3413 -2943
  37. package/dist/index.cjs.map +1 -1
  38. package/dist/index.d.ts +2 -0
  39. package/dist/index.d.ts.map +1 -1
  40. package/dist/index.js +3366 -2943
  41. package/dist/index.js.map +1 -1
  42. package/dist/massParameters.d.ts +287 -0
  43. package/dist/massParameters.d.ts.map +1 -0
  44. package/dist/massParameters.ops.d.ts +137 -0
  45. package/dist/massParameters.ops.d.ts.map +1 -0
  46. package/package.json +13 -13
  47. package/src/api/core/geom/create/index.ts +1019 -101
  48. package/src/api/core/geom/query/brep.ts +56 -1
  49. package/src/api/core/geom/query/curve.ts +25 -2
  50. package/src/api/core/geom/query/edge.ts +2 -2
  51. package/src/api/core/geom/query/face.ts +109 -4
  52. package/src/api/design/family.ts +66 -8
  53. package/src/api/design/query/geometry/index.ts +35 -4
  54. package/src/api/design/query/index.ts +50 -0
  55. package/src/api/design/update/index.ts +94 -0
  56. package/src/handles.ts +15 -3
  57. package/src/index.ts +2 -0
  58. package/src/massParameters.ops.ts +245 -0
  59. package/src/massParameters.ts +427 -0
  60. package/test/massParameters.test.mjs +938 -0
@@ -1,15 +1,46 @@
1
1
  import * as z from "zod"
2
2
  import { PluginApiReturn } from "../../../../types"
3
- import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, FaceHandle, EdgeHandle, Vec3Components } from "../../../../handles"
3
+ import {
4
+ MAX_SPLINE_THROUGH_POINTS,
5
+ MAX_SPLINE_POLES,
6
+ MAX_PATH_CURVES,
7
+ MAX_TWIST_LEVELS,
8
+ MAX_FILLET_LAW_SAMPLES,
9
+ } from "../../../../massParameters"
10
+ import type { SweepAlongCurveRecordOptions } from "../../../../massParameters"
11
+ import { Vec3Handle, LineHandle, ArcHandle, SplineHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, FaceHandle, EdgeHandle, Vec3Components } from "../../../../handles"
12
+
13
+ /** Maximum boundary items one patch may span. */
14
+ export const MAX_PATCH_BOUNDARY_CURVES = 16
15
+ /** Maximum interior points one patch may be pulled through. */
16
+ export const MAX_PATCH_INTERIOR_POINTS = 64
17
+
18
+ /**
19
+ * An edge named together with the solid it belongs to — an edge handle cannot
20
+ * name its own solid, and one patch may meet two solids. `face` is the adjacent
21
+ * face a tangent patch continues: REQUIRED under `continuity: "tangent"`
22
+ * (a solid edge has two faces — the wall or the top of a rim — and only the
23
+ * caller knows which), ignored otherwise. Owner LAST, like every read that
24
+ * takes `(face, brep)`.
25
+ */
26
+ export type OwnedEdge = { edge: EdgeHandle; brep: BrepHandle; face?: FaceHandle }
27
+
28
+ /**
29
+ * The trailing bag of {@linkcode PluginGeomCreateApi.brepFromSweepAlongCurve}:
30
+ * the recorded switches plus `rail`, a live curve handle that never enters a
31
+ * record (a record is pure JSON, and a dead handle would not regenerate).
32
+ */
33
+ export type SweepAlongCurveOptions = SweepAlongCurveRecordOptions & { rail?: CurveHandle }
4
34
 
5
35
  /**
6
36
  * Curve creation — construct new geometric curves from point handles (all-handle
7
37
  * model, §11).
8
38
  *
9
39
  * Each method takes point handles ({@linkcode Vec3Handle}) and returns an opaque
10
- * curve handle ({@linkcode LineHandle} or {@linkcode ArcHandle}) that you pass to
11
- * query, update, or entity-creation methods. Read geometry back as plain values
12
- * via the `snaptrude.core.geom.query.*` methods.
40
+ * curve handle ({@linkcode LineHandle}, {@linkcode ArcHandle}, or
41
+ * {@linkcode SplineHandle}) that you pass to query, update, or entity-creation
42
+ * methods. Read geometry back as plain values via the
43
+ * `snaptrude.core.geom.query.*` methods.
13
44
  *
14
45
  * Accessed via `snaptrude.core.geom.create`.
15
46
  */
@@ -83,6 +114,96 @@ export abstract class PluginGeomCreateApi {
83
114
  radius: number,
84
115
  ): PluginApiReturn<CircleHandle>
85
116
 
117
+ /**
118
+ * Create an open NURBS curve passing exactly THROUGH each point, in order
119
+ * (centripetal Catmull-Rom fit → clamped cubic B-spline; C1-smooth, no cusps
120
+ * on uneven spacing). Host API call — returns a handle. The points are
121
+ * interpolated, NOT control points. For a CLOSED smooth loop use
122
+ * {@linkcode PluginGeomCreateApi.profileFromSplinePoints} — closed splines
123
+ * exist only as profiles, never as a single curve handle.
124
+ *
125
+ * Pure host-side math — the geometry kernel is not loaded. The result is a
126
+ * {@linkcode CurveHandle}: pass it to `profileFromCurves` alongside lines and
127
+ * arcs, or read it back via `core.geom.query.curve.*`.
128
+ *
129
+ * @param points 3..256 ordered through-points; consecutive points must be distinct
130
+ * @returns The new open curve as a {@linkcode SplineHandle}
131
+ * @throws VALIDATION if fewer than 3 points (2 points are a straight line —
132
+ * use {@linkcode PluginGeomCreateApi.line}), more than 256 points, or two
133
+ * consecutive points coincide
134
+ *
135
+ * @examplePrompt Draw a smooth curve through these points
136
+ * @examplePrompt Make a wavy edge that passes through A, B, C and D
137
+ * @examplePrompt Freeform curved wall path through these clicks
138
+ *
139
+ * # Example
140
+ * ```ts
141
+ * const spline = await snaptrude.core.geom.create.splineFromPoints([p0, p1, p2, p3])
142
+ * // Mixed profile: smooth top, straight closing base
143
+ * const base = await snaptrude.core.geom.create.line(p3, p0)
144
+ * const profile = await snaptrude.core.geom.create.profileFromCurves([spline, base])
145
+ * ```
146
+ */
147
+ public abstract splineFromPoints(points: Vec3Handle[]): PluginApiReturn<SplineHandle>
148
+
149
+ /**
150
+ * Create an open NURBS curve DEFINED BY control points — the curve is pulled
151
+ * TOWARD the interior points, not through them; it starts at the first point
152
+ * and ends at the last. Knots are computed for you (clamped, uniform) —
153
+ * there is no knot-vector argument. For a curve that must pass THROUGH given
154
+ * points use {@linkcode PluginGeomCreateApi.splineFromPoints}.
155
+ *
156
+ * A curve made here records as `splinePoles` in a mass recipe and is
157
+ * re-minted verbatim on edit — so an agent that read a `splinePoles` curve
158
+ * back off a mass can move its poles and rebuild the mass with
159
+ * `design.update.parameters`. Pure host-side math — the geometry kernel is
160
+ * not loaded, and nothing is created in the scene.
161
+ *
162
+ * @param controlPoints 3..512 control points ({@linkcode Vec3Handle}s), in order
163
+ * @param options.degree 2 or 3; default `min(3, controlPoints.length - 1)`
164
+ * @returns The new open curve as a {@linkcode SplineHandle}
165
+ * @throws VALIDATION when fewer than `degree + 1` points are given, two
166
+ * consecutive points coincide, or `degree` is not 2 or 3
167
+ *
168
+ * @examplePrompt Draw a smooth curve controlled by these four points
169
+ * @examplePrompt Rebuild this edge from its control polygon
170
+ *
171
+ * # Example
172
+ * ```ts
173
+ * const curve = await snaptrude.core.geom.create.splineFromControlPoints([p0, p1, p2, p3])
174
+ * // Quadratic instead of the default cubic
175
+ * const tighter = await snaptrude.core.geom.create.splineFromControlPoints(
176
+ * [p0, p1, p2, p3],
177
+ * { degree: 2 },
178
+ * )
179
+ * ```
180
+ */
181
+ public abstract splineFromControlPoints(
182
+ controlPoints: Vec3Handle[],
183
+ options?: { degree?: number },
184
+ ): PluginApiReturn<SplineHandle>
185
+
186
+ /**
187
+ * Drops a curve onto a face along the face's normal and returns the curves it
188
+ * lands on — one per connected run, empty when the curve misses the face
189
+ * entirely. Host API call — returns new curve handles; the inputs are
190
+ * read-only. No lengths are involved: the result is a curve in the same
191
+ * internal length units as its inputs.
192
+ *
193
+ * @param curve The curve to project
194
+ * @param face The face to project onto
195
+ * @param faceBrep The solid `face` belongs to — a face handle cannot name its
196
+ * own solid
197
+ * @returns The projected curves as {@linkcode CurveHandle}`[]`
198
+ * @throws VALIDATION if `face` is not a face of `faceBrep`
199
+ * @throws OPERATION_FAILED if the kernel could not project the curve
200
+ */
201
+ public abstract curvesFromProjection(
202
+ curve: CurveHandle,
203
+ face: FaceHandle,
204
+ faceBrep: BrepHandle,
205
+ ): PluginApiReturn<CurveHandle[]>
206
+
86
207
  /**
87
208
  * Create a closed profile from an ordered list of point handles connected by
88
209
  * line segments (last auto-connected to first). Host API call — returns a handle.
@@ -117,8 +238,42 @@ export abstract class PluginGeomCreateApi {
117
238
  public abstract profileFromCurves(curves: CurveHandle[]): PluginApiReturn<ProfileHandle>
118
239
 
119
240
  /**
120
- * Create an axis-aligned **rectangle** profile (XZ plane) of `width` × `depth`,
121
- * centred at `center` (defaults to the origin). Host API call — returns a handle.
241
+ * Create a CLOSED smooth profile passing through each point, in order, with
242
+ * the loop closed smoothly back from the last point to the first (do NOT
243
+ * repeat the first point). Host API call — returns a handle. This is the
244
+ * closed counterpart of {@linkcode PluginGeomCreateApi.splineFromPoints} and
245
+ * the one-call route from points to an extrudable outline: wrap in
246
+ * `contourFromProfile` and extrude/loft/sweep as usual.
247
+ *
248
+ * The whole loop is smooth — this call takes no mixed straight/spline input.
249
+ * For a profile that is part curve and part straight, build the pieces with
250
+ * `splineFromPoints` + `line` and join them with
251
+ * {@linkcode PluginGeomCreateApi.profileFromCurves}.
252
+ *
253
+ * @param points 3..256 ordered through-points of the loop (first point NOT repeated)
254
+ * @returns The new closed profile as a {@linkcode ProfileHandle}
255
+ * @throws VALIDATION if fewer than 3 points, more than 256 points,
256
+ * consecutive points coincide (including last→first), or the loop
257
+ * self-intersects
258
+ *
259
+ * @examplePrompt Make a blob-shaped floor plate through these points
260
+ * @examplePrompt Organic curved outline through these corners
261
+ * @examplePrompt Freeform podium profile
262
+ *
263
+ * # Example
264
+ * ```ts
265
+ * const profile = await snaptrude.core.geom.create.profileFromSplinePoints([p0, p1, p2, p3, p4])
266
+ * const contour = await snaptrude.core.geom.create.contourFromProfile(profile)
267
+ * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
268
+ * const podium = await snaptrude.design.create.massFromBrep(brep, "Podium")
269
+ * ```
270
+ */
271
+ public abstract profileFromSplinePoints(points: Vec3Handle[]): PluginApiReturn<ProfileHandle>
272
+
273
+ /**
274
+ * Create an axis-aligned **rectangle** profile in the XZ plane,
275
+ * `width` × `depth`, centred at `center` (defaults to the origin). Host API
276
+ * call — returns a handle.
122
277
  *
123
278
  * Pair with `design.create.space` / `design.create.spaces` to author a rectangular
124
279
  * (box) space — there is no dedicated rectangular-space creator; build the profile
@@ -237,15 +392,30 @@ export abstract class PluginGeomCreateApi {
237
392
  *
238
393
  * @param contour The cross-section to extrude (outer profile + optional holes)
239
394
  * @param direction Extrusion direction as plain `{x, y, z}` components (non-zero, normalised by the host)
240
- * @param amount Extrusion distance (non-zero; negative extrudes opposite to `direction`)
395
+ * @param amount Extrusion distance in internal length units (non-zero; negative extrudes opposite to `direction`)
396
+ * @param options Optional twist and taper, both about `direction` through the
397
+ * base contour's centroid. `twistInDegrees` — total rotation base → top in
398
+ * DEGREES (an angle: never scaled by the project's length unit), positive
399
+ * turning the top CLOCKWISE seen from the far end of `direction` looking
400
+ * back at the base — for the usual upward extrusion, the plan view;
401
+ * `topScale` — the top outline's scale, a ratio (1 = no taper); `levels` —
402
+ * how many sections to build through, a count (2..64). Leave `levels` out
403
+ * and the host resolves one and writes it into the record, so the mass
404
+ * regenerates identically ever after. An extrusion without twist or
405
+ * taper (no `options`, or zero twist and a `topScale` of 1) is
406
+ * built exactly as before these options existed.
241
407
  * @returns The new solid as a {@linkcode BrepHandle}
242
408
  * @throws if the extrusion is degenerate (zero amount, zero direction, or a
243
- * direction lying in the contour plane) or the contour cannot be extruded
244
- * into a valid solid
409
+ * direction lying in the plane of the contour) or the contour cannot be
410
+ * extruded into a valid solid
411
+ * @throws VALIDATION if `twistInDegrees` is not finite, `topScale` is not a
412
+ * positive finite ratio, or `levels` is outside 2..64
245
413
  *
246
414
  * @examplePrompt Extrude this profile 3 metres up
247
415
  * @examplePrompt Make a solid by extruding this outline
248
416
  * @examplePrompt Create a cylinder from a circle profile
417
+ * @examplePrompt Extrude this floor plate 40m up with a 90 degree twist
418
+ * @examplePrompt Taper this tower to 60 percent of its footprint at the top
249
419
  *
250
420
  * # Example
251
421
  * ```ts
@@ -259,6 +429,81 @@ export abstract class PluginGeomCreateApi {
259
429
  contour: ContourHandle,
260
430
  direction: Vec3Components,
261
431
  amount: number,
432
+ options?: { twistInDegrees?: number; topScale?: number; levels?: number },
433
+ ): PluginApiReturn<BrepHandle>
434
+
435
+ /**
436
+ * Stretches a surface across a closed loop of boundary curves and thickens it
437
+ * into a SOLID in one call — a roof over four curves, a canopy between two
438
+ * rails, a blend across a gap. `thickness` is in internal length units and is
439
+ * required: only solids reach the canvas, and there is no separate surface
440
+ * object to keep. Pass edges as `{ edge, brep, face }` with
441
+ * `continuity: "tangent"` to leave the named face smoothly. The result carries
442
+ * NO recipe (`design.query.getParameters` returns `null`) — label it when you
443
+ * commit it, because the label is all the provenance there is.
444
+ *
445
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
446
+ * of MB — expect a pause of seconds).
447
+ *
448
+ * @param boundary 3..16 items forming ONE closed loop (ends meeting within
449
+ * tolerance): a curve, or an edge named WITH the solid it belongs to
450
+ * ({@linkcode OwnedEdge}) — an edge handle cannot name its own solid, and
451
+ * one patch may meet two solids. Read scene breps with
452
+ * `design.query.geometry.getBrep(x, { frame: "world" })` so every item is in
453
+ * one frame.
454
+ * @param thickness Solid thickness in internal length units (> 0)
455
+ * @param options `interiorPoints` pull the surface through them (≤ 64, plain
456
+ * `{x, y, z}` in the same frame as the boundary). `continuity` —
457
+ * `"position"` (default) or `"tangent"`: every boundary item must then be an
458
+ * edge item that also names the `face` to continue (a solid edge has two
459
+ * faces — the wall or the top of a rim). `side` — `"below"` (default) or
460
+ * `"above"`: which side of the boundary the solid grows to.
461
+ * @returns The thickened patch as a new {@linkcode BrepHandle}
462
+ * @throws VALIDATION if the boundary is not one closed loop (the message names
463
+ * the gap and its size), a count cap is exceeded, `thickness` is not
464
+ * positive, `continuity: "tangent"` is used with a curve item or with an
465
+ * edge item that names no `face` (the message names the edge's two candidate
466
+ * faces), or a `face` is not adjacent to its `edge`
467
+ * @throws OPERATION_FAILED if the kernel could not fill the boundary, the
468
+ * filled surface misses its own boundary by more than 0.254 mm (the message
469
+ * carries the measured gap), or the thicken produced no solid
470
+ *
471
+ * @examplePrompt Patch a roof over these four boundary curves, 250 mm thick
472
+ * @examplePrompt Span a canopy between these two curved rails, 300 mm thick
473
+ *
474
+ * # Example
475
+ * ```ts
476
+ * // A roof over four curves
477
+ * const roof = await snaptrude.core.geom.create.brepFromPatch(
478
+ * [curveA, curveB, curveC, curveD],
479
+ * 0.25,
480
+ * )
481
+ * const mass = await snaptrude.design.create.massFromBrep(roof, "Roof patch")
482
+ * ```
483
+ *
484
+ * ```ts
485
+ * // A canopy between two towers' rims, leaving every wall it meets smoothly:
486
+ * // with `continuity: "tangent"` EVERY item is an edge naming its face.
487
+ * const canopy = await snaptrude.core.geom.create.brepFromPatch(
488
+ * [
489
+ * { edge: rimA, brep: towerA, face: wallA },
490
+ * { edge: sideA, brep: towerA, face: endA },
491
+ * { edge: rimB, brep: towerB, face: wallB },
492
+ * { edge: sideB, brep: towerB, face: endB },
493
+ * ],
494
+ * 0.3,
495
+ * { continuity: "tangent" },
496
+ * )
497
+ * ```
498
+ */
499
+ public abstract brepFromPatch(
500
+ boundary: (CurveHandle | OwnedEdge)[],
501
+ thickness: number,
502
+ options?: {
503
+ interiorPoints?: Vec3Components[]
504
+ continuity?: "position" | "tangent"
505
+ side?: "below" | "above"
506
+ },
262
507
  ): PluginApiReturn<BrepHandle>
263
508
 
264
509
  /**
@@ -274,8 +519,8 @@ export abstract class PluginGeomCreateApi {
274
519
  * unchanged. A pair whose side faces would be non-planar under every
275
520
  * correspondence still builds for hole-free straight-edged pairs — planar
276
521
  * side quads stay quads and warped ones split into planar triangles (the
277
- * triangulated lane); arc-bearing or holed twisted pairs are rejected, as is
278
- * auto-matching that would pair an arc with a straight edge. Matching hole
522
+ * triangulated fallback); arc-bearing or holed twisted pairs are rejected, as
523
+ * is auto-matching that would pair an arc with a straight edge. Matching hole
279
524
  * counts are allowed in the two-section form. With intermediates the loft
280
525
  * is a chain of ruled segments folded into one solid: sections must be
281
526
  * planar and hole-free, ordered bottom → intermediates → top. The contours
@@ -289,7 +534,9 @@ export abstract class PluginGeomCreateApi {
289
534
  * bottom — sections are auto-matched)
290
535
  * @param intermediateContours Optional in-between cross-sections, ordered
291
536
  * bottom to top (hole-free; edge counts may differ — every section is
292
- * normalized to the largest)
537
+ * normalized to the largest). Any count is accepted; a loft of more
538
+ * than 32 sections counting the bottom and the top still builds but
539
+ * carries no parameter record (records are capped, calls are not)
293
540
  * @param options Optional behavior switches. `compatibility` — `"auto"`
294
541
  * (default) inserts vertices to match differing edge counts; `"strict"`
295
542
  * skips normalization and throws VALIDATION when outer edge counts (or,
@@ -297,9 +544,13 @@ export abstract class PluginGeomCreateApi {
297
544
  * `"auto"` (default) searches seam rotations on straight-edge sections to
298
545
  * avoid a twist; `"authored"` keeps the authored start-vertex
299
546
  * correspondence unchanged (a twisted correspondence then builds through
300
- * the triangulated lane for hole-free straight-edged pairs).
547
+ * the triangulated fallback for hole-free straight-edged pairs).
301
548
  * `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
302
- * pre-0.9.4 lofting exactly.
549
+ * pre-0.9.4 lofting exactly. `smoothing` — `"ruled"` (default) keeps the
550
+ * straight-sided behaviour described above; `"smooth"` lofts every
551
+ * section in ONE kernel pass, so the sides curve continuously through the
552
+ * intermediates instead of creasing at each one (a vase, a curved tower —
553
+ * the sections must still be planar and hole-free).
303
554
  * @returns The new solid as a {@linkcode BrepHandle}
304
555
  * @throws VALIDATION if the contours are coincident, their hole counts
305
556
  * differ, any section has holes when intermediates are present
@@ -321,6 +572,7 @@ export abstract class PluginGeomCreateApi {
321
572
  * @examplePrompt Loft these outlines even though their corners don't line up
322
573
  * @examplePrompt Loft these outlines exactly as authored, corner to corner
323
574
  * @examplePrompt Fail the loft if my sections don't have matching edge counts
575
+ * @examplePrompt Loft these three outlines with smoothly curving sides
324
576
  *
325
577
  * # Example
326
578
  * ```ts
@@ -338,7 +590,11 @@ export abstract class PluginGeomCreateApi {
338
590
  bottomContour: ContourHandle,
339
591
  topContour: ContourHandle,
340
592
  intermediateContours?: ContourHandle[],
341
- options?: { compatibility?: "strict" | "auto"; seamAlignment?: "authored" | "auto" },
593
+ options?: {
594
+ compatibility?: "strict" | "auto"
595
+ seamAlignment?: "authored" | "auto"
596
+ smoothing?: "ruled" | "smooth"
597
+ },
342
598
  ): PluginApiReturn<BrepHandle>
343
599
 
344
600
  /**
@@ -474,44 +730,92 @@ export abstract class PluginGeomCreateApi {
474
730
  public abstract brepFromIntersection(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
475
731
 
476
732
  /**
477
- * Rounds the given straight edges of a solid with a constant radius. Host
478
- * API call — returns a new {@linkcode BrepHandle}; the input brep is
479
- * read-only.
480
- *
481
- * v1 fillets straight edges only, and no two filleted edges may share a
482
- * vertex — corner blends produce spherical patches Snaptrude cannot
483
- * represent. Runs on the OpenCascade kernel (the first kernel call loads a
484
- * wasm of tens of MB — expect a pause of seconds).
733
+ * Rounds the given edges of a solid with a constant radius. Host API call —
734
+ * returns a new {@linkcode BrepHandle}; the input brep is read-only.
735
+ *
736
+ * Works on curved solids: edges may be straight, circular or spline, and
737
+ * adjacent edges (corner blends) are allowed. To pick a **rim** — the circle
738
+ * where a cylinder meets a flat cap — walk the edges and keep the ones whose
739
+ * two faces are a `cylinder` and a `plane`:
740
+ * `core.geom.query.brep.listEdges(brep)` → per edge
741
+ * `core.geom.query.edge.listFaces(edge)` → `core.geom.query.face.getSurfaceKind`
742
+ * on both faces. (`core.geom.query.brep.listEdgesBetween` takes two VERTEX
743
+ * indices — it is NOT a face-pair lookup.) For one cap's rim only, the
744
+ * shorter walk is: find the cap (call `getSurfaceKind` on each face from
745
+ * `brep.listFaces`), then `core.geom.query.face.listEdges(capFace)`.
746
+ *
747
+ * When the input brep carries a creation recipe, the result carries it too,
748
+ * with this operation appended to `operations`; `design.create.massFromBrep`
749
+ * then keeps the mass editable through `design.update.parameters`.
750
+ *
751
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
752
+ * of MB — expect a pause of seconds).
485
753
  *
486
754
  * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
487
755
  * with `design.create.massFromBrep`.
488
756
  *
489
757
  * @param brep The solid whose edges to round
490
- * @param edges The straight edges to fillet (≥1, all on `brep`, no two sharing a vertex)
491
- * @param radius Fillet radius (positive, finite)
758
+ * @param edges The edges to fillet (one or more, all on `brep`, no
759
+ * duplicates; more than 64 still fillets but the result carries no
760
+ * parameter record)
761
+ * @param radius Fillet radius in internal length units (positive, finite) —
762
+ * the radius at the START of the blend when a variable form is used
763
+ * @param options Optional VARIABLE blend, in one of two forms, each naming
764
+ * exactly ONE edge: the law belongs to the whole tangent chain that edge
765
+ * lies on, and it is measured from that edge's start. `endRadius` —
766
+ * the radius at the far end, in internal length units, interpolated
767
+ * linearly along the chain; needs an OPEN chain with two distinct ends, and
768
+ * is refused on a closed rim (where the kernel silently builds a constant
769
+ * radius) — use `radii` there. `radii` — a sampled law instead:
770
+ * `position` is normalised ARC LENGTH along the chain (a ratio 0..1, never
771
+ * converted), `radius` is internal length units; 2..32 rows with strictly
772
+ * increasing `position`. On a closed rim 0 and 1 are the same point, so give
773
+ * them the same radius and put the variation in the interior rows. The two
774
+ * forms are mutually exclusive; without either, the fillet has one constant
775
+ * radius.
492
776
  * @returns The filleted solid as a new {@linkcode BrepHandle}
493
- * @throws VALIDATION if `edges` is empty, `radius` is not a positive finite
494
- * number, an edge is not on `brep`, an edge is an arc (v1 fillets straight
495
- * edges only), or two edges share a vertex (fillet non-adjacent edges)
496
- * @throws OPERATION_FAILED if the kernel cannot build the fillet (the radius
497
- * likely exceeds the adjacent face size — reduce it) or the result
498
- * contains curved surfaces Snaptrude cannot represent
499
- *
500
- * @examplePrompt Round the edges of this mass
777
+ * @throws VALIDATION if `edges` is empty or holds a duplicate, `radius` is
778
+ * not a positive finite number, an edge is not on `brep`, or an edge has no
779
+ * crease to round — it is a seam of a closed face, or it lies between two
780
+ * patches of one smooth surface; for a variable blend, if `endRadius` and
781
+ * `radii` are both given, more than one edge is passed, a `radii` table is
782
+ * outside 2..32 rows or its positions do not strictly increase within
783
+ * 0..1, or `endRadius` names a closed rim (the message points at `radii`)
784
+ * @throws PRECONDITION_FAILED if an edge could not be located on the kernel
785
+ * solid after healing (select a different edge, or fillet before the
786
+ * operation that curved the solid), or the kernel could not blend the edge
787
+ * named in the message (reduce the radius or drop that edge)
788
+ * @throws OPERATION_FAILED if the kernel or the translation fails, or the
789
+ * result is non-manifold, splits into several solids, or contains a surface
790
+ * Snaptrude cannot represent
791
+ *
792
+ * @examplePrompt Round the rim of the column with 200 mm
793
+ * @examplePrompt Soften where the dome meets the wall
501
794
  * @examplePrompt Fillet the corners of the podium with a 0.5m radius
502
795
  * @examplePrompt Soften the vertical edges of this tower
796
+ * @examplePrompt Blend this edge from 200mm at one end to 600mm at the other
797
+ * @examplePrompt Round this rim wider at the back than at the front
503
798
  *
504
799
  * # Example
505
800
  * ```ts
506
- * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
507
- * const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
508
- * const rounded = await snaptrude.core.geom.create.brepFromFillet(brep, [edges[0]], 0.3)
801
+ * // Rim = every edge between the cylinder side and a plane cap
802
+ * const edges = await snaptrude.core.geom.query.brep.listEdges(column)
803
+ * const rim = []
804
+ * for (const edge of edges) {
805
+ * const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
806
+ * const kinds = await Promise.all(
807
+ * faces.map((f) => snaptrude.core.geom.query.face.getSurfaceKind(f)),
808
+ * )
809
+ * if (kinds.includes("cylinder") && kinds.includes("plane")) rim.push(edge)
810
+ * }
811
+ * const rounded = await snaptrude.core.geom.create.brepFromFillet(column, rim, 0.787) // 200 mm
509
812
  * ```
510
813
  */
511
814
  public abstract brepFromFillet(
512
815
  brep: BrepHandle,
513
816
  edges: EdgeHandle[],
514
817
  radius: number,
818
+ options?: { endRadius?: number; radii?: { position: number; radius: number }[] },
515
819
  ): PluginApiReturn<BrepHandle>
516
820
 
517
821
  /**
@@ -519,6 +823,14 @@ export abstract class PluginGeomCreateApi {
519
823
  * moves faces outward, negative moves them inward. Host API call — returns
520
824
  * a new {@linkcode BrepHandle}; the input brep is read-only.
521
825
  *
826
+ * Works on curved solids: a sphere offsets to a sphere, a torus to a torus,
827
+ * a cylinder to a cylinder. There is nothing to select — the whole solid is
828
+ * offset.
829
+ *
830
+ * When the input brep carries a creation recipe, the result carries it too,
831
+ * with this operation appended to `operations`; `design.create.massFromBrep`
832
+ * then keeps the mass editable through `design.update.parameters`.
833
+ *
522
834
  * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
523
835
  * tens of MB — expect a pause of seconds).
524
836
  *
@@ -530,9 +842,15 @@ export abstract class PluginGeomCreateApi {
530
842
  * @returns The offset solid as a new {@linkcode BrepHandle}
531
843
  * @throws VALIDATION if `distance` is not finite, is too small to offset
532
844
  * anything, or an inward distance consumes the solid entirely
533
- * @throws OPERATION_FAILED if the kernel cannot build the offset or the
534
- * result contains curved surfaces Snaptrude cannot represent
535
- *
845
+ * @throws OPERATION_FAILED if the kernel or the translation fails, or the
846
+ * result is non-manifold, splits into several solids, or contains a surface
847
+ * Snaptrude cannot represent (an offset free-form NURBS surface may have no
848
+ * exact representation — the model is left unchanged). A distance too
849
+ * large for the solid is reported here, with a hint asking for a smaller
850
+ * one. There is no per-face refusal: the whole call fails, and the error
851
+ * names no face
852
+ *
853
+ * @examplePrompt Thicken the torus ring by 100 mm
536
854
  * @examplePrompt Grow this solid by 0.5m in every direction
537
855
  * @examplePrompt Shrink this mass by 200mm
538
856
  * @examplePrompt Offset the building envelope outward by 1m
@@ -551,6 +869,18 @@ export abstract class PluginGeomCreateApi {
551
869
  * input brep is read-only. The outer surface is kept and the walls grow
552
870
  * inward.
553
871
  *
872
+ * Works on curved solids: the open faces may be spherical, cylindrical,
873
+ * conical, toroidal or free-form patches, not only flat ones. To open the
874
+ * flat base of a dome, check every face first —
875
+ * `core.geom.query.brep.listFaces` then
876
+ * `core.geom.query.face.getSurfaceKind` on each — and keep the `"plane"`
877
+ * one. A closed curved surface is stored as several patches (a sphere as
878
+ * lunes), so opening "the sphere" may mean passing several faces.
879
+ *
880
+ * When the input brep carries a creation recipe, the result carries it too,
881
+ * with this operation appended to `operations`; `design.create.massFromBrep`
882
+ * then keeps the mass editable through `design.update.parameters`.
883
+ *
554
884
  * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
555
885
  * tens of MB — expect a pause of seconds).
556
886
  *
@@ -558,24 +888,36 @@ export abstract class PluginGeomCreateApi {
558
888
  * with `design.create.massFromBrep`.
559
889
  *
560
890
  * @param brep The solid to hollow
561
- * @param openFaces The faces to remove as openings (≥1, all on `brep`)
891
+ * @param openFaces The faces to remove as openings (one or more, all on
892
+ * `brep`, no duplicates; more than 32 still shells but the result carries
893
+ * no parameter record)
562
894
  * @param thickness Wall thickness (positive, finite, smaller than half the solid's smallest span)
563
895
  * @returns The hollowed solid as a new {@linkcode BrepHandle}
564
- * @throws VALIDATION if `openFaces` is empty, a face is not on `brep`,
565
- * `thickness` is not a positive finite number, or the thickness is too
566
- * large (it must be smaller than half the solid's smallest span)
567
- * @throws OPERATION_FAILED if the kernel cannot build the shell or the
568
- * result contains curved surfaces Snaptrude cannot represent
569
- *
896
+ * @throws VALIDATION if `openFaces` is empty or holds a duplicate, a face is
897
+ * not on `brep`, `thickness` is not a positive finite number, or the
898
+ * thickness is too large (it must be smaller than half the solid's smallest
899
+ * span)
900
+ * @throws OPERATION_FAILED if the kernel or the translation fails, or the
901
+ * result is non-manifold, splits into several solids, or contains a surface
902
+ * Snaptrude cannot represent. A thickness too large for the solid is
903
+ * reported here, with a hint asking for one below half the smallest span.
904
+ * There is no per-face refusal: the whole call fails, and the error
905
+ * names no face
906
+ *
907
+ * @examplePrompt Hollow the dome into a 300 mm shell, open at the base
570
908
  * @examplePrompt Hollow this mass into 200mm walls
571
909
  * @examplePrompt Shell this form with the top face open
572
910
  * @examplePrompt Turn this solid tower into a tube open at both ends
573
911
  *
574
912
  * # Example
575
913
  * ```ts
576
- * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
577
- * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
578
- * const hollow = await snaptrude.core.geom.create.brepFromShell(brep, [faces[0]], 0.2)
914
+ * // Open the dome at its flat base: the one face whose surface is a plane
915
+ * const faces = await snaptrude.core.geom.query.brep.listFaces(dome)
916
+ * const base = []
917
+ * for (const face of faces) {
918
+ * if ((await snaptrude.core.geom.query.face.getSurfaceKind(face)) === "plane") base.push(face)
919
+ * }
920
+ * const hollow = await snaptrude.core.geom.create.brepFromShell(dome, base, 1.181) // 300 mm
579
921
  * ```
580
922
  */
581
923
  public abstract brepFromShell(
@@ -625,28 +967,89 @@ export abstract class PluginGeomCreateApi {
625
967
  ): PluginApiReturn<BrepHandle[]>
626
968
 
627
969
  /**
628
- * Bevels the given straight edges of a solid with a symmetric planar cut.
629
- * Host API call — returns a new {@linkcode BrepHandle}; the input brep is
630
- * read-only.
970
+ * Cuts a solid with a FACE of another solid — the curved twin of
971
+ * {@linkcode PluginGeomCreateApi.brepsFromSplit}, which cuts with a plane.
972
+ * Host API call — returns new {@linkcode BrepHandle}s; both inputs are
973
+ * read-only. BOTH breps must be in the same frame: read scene masses with
974
+ * `design.query.geometry.getBrep(x, { frame: "world" })` (the default is each
975
+ * mass's own local frame, and two masses have two). The pieces come back in
976
+ * DESCENDING volume order; pick the one you want with
977
+ * `core.geom.query.brep.getCentroid` or `getVolume` and commit it. A piece
978
+ * carries no recipe — label it.
979
+ *
980
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
981
+ * of MB — expect a pause of seconds).
982
+ *
983
+ * @param brep The solid to cut
984
+ * @param toolFace The cutting face, read-only
985
+ * @param toolBrep The solid `toolFace` belongs to — a face handle cannot name
986
+ * its own solid
987
+ * @returns The resulting pieces as {@linkcode BrepHandle}`[]`, largest first
988
+ * @throws VALIDATION if `toolFace` is not a face of `toolBrep`, `toolBrep` IS
989
+ * `brep`, or the cut produced a single part — the surface does not pass all
990
+ * the way through (extend it past the mass on every side, and check both
991
+ * breps were read in the same frame)
992
+ * @throws OPERATION_FAILED if the kernel could not split the solid
993
+ *
994
+ * @examplePrompt Cut this mass with the curved roof surface and keep the lower part
631
995
  *
632
- * v1 chamfers straight edges only, and no two chamfered edges may share a
633
- * vertex. Runs on the OpenCascade kernel (the first kernel call loads a
634
- * wasm of tens of MB — expect a pause of seconds).
996
+ * # Example
997
+ * ```ts
998
+ * const target = await snaptrude.design.query.geometry.getBrep(tower, { frame: "world" })
999
+ * const tool = await snaptrude.design.query.geometry.getBrep(roof, { frame: "world" })
1000
+ * const [toolFace] = await snaptrude.core.geom.query.brep.listFaces(tool)
1001
+ * const pieces = await snaptrude.core.geom.create.brepsFromSplitByFace(target, toolFace, tool)
1002
+ * ```
1003
+ */
1004
+ public abstract brepsFromSplitByFace(
1005
+ brep: BrepHandle,
1006
+ toolFace: FaceHandle,
1007
+ toolBrep: BrepHandle,
1008
+ ): PluginApiReturn<BrepHandle[]>
1009
+
1010
+ /**
1011
+ * Bevels the given edges of a solid with a symmetric planar cut. Host API
1012
+ * call — returns a new {@linkcode BrepHandle}; the input brep is read-only.
1013
+ *
1014
+ * Works on curved solids: edges may be straight, circular or spline, and
1015
+ * adjacent edges are allowed. Pick edges the same way as for
1016
+ * {@linkcode PluginGeomCreateApi.brepFromFillet} — `brep.listEdges`, then
1017
+ * `core.geom.query.edge.listFaces` and `core.geom.query.face.getSurfaceKind`
1018
+ * on both faces of each edge. (`core.geom.query.brep.listEdgesBetween` takes
1019
+ * two VERTEX indices — it is NOT a face-pair lookup.) Chamfering a cylinder's
1020
+ * rim yields a cone patch where a fillet would yield a torus patch.
1021
+ *
1022
+ * When the input brep carries a creation recipe, the result carries it too,
1023
+ * with this operation appended to `operations`; `design.create.massFromBrep`
1024
+ * then keeps the mass editable through `design.update.parameters`.
1025
+ *
1026
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
1027
+ * of MB — expect a pause of seconds).
635
1028
  *
636
1029
  * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
637
1030
  * with `design.create.massFromBrep`.
638
1031
  *
639
1032
  * @param brep The solid whose edges to bevel
640
- * @param edges The straight edges to chamfer (≥1, all on `brep`, no two sharing a vertex)
1033
+ * @param edges The edges to chamfer (one or more, all on `brep`, no
1034
+ * duplicates; more than 64 still chamfers but the result carries no
1035
+ * parameter record)
641
1036
  * @param distance Chamfer distance from the edge on each adjacent face (positive, finite)
642
1037
  * @returns The chamfered solid as a new {@linkcode BrepHandle}
643
- * @throws VALIDATION if `edges` is empty, `distance` is not a positive
644
- * finite number, an edge is not on `brep`, an edge is an arc (v1 chamfers
645
- * straight edges only), or two edges share a vertex (chamfer non-adjacent
646
- * edges)
647
- * @throws OPERATION_FAILED if the kernel cannot build the chamfer (the
648
- * distance likely exceeds the adjacent face size — reduce it)
649
- *
1038
+ * @throws VALIDATION if `edges` is empty or holds a duplicate, `distance` is
1039
+ * not a positive finite number, an edge is not on `brep`, or an edge has no
1040
+ * crease to cut — it is a seam of a closed face, or it lies between two
1041
+ * patches of one smooth surface
1042
+ * @throws PRECONDITION_FAILED if an edge could not be located on the kernel
1043
+ * solid after healing (select a different edge, or chamfer before the
1044
+ * operation that curved the solid)
1045
+ * @throws OPERATION_FAILED if the kernel or the translation fails, or the
1046
+ * result is non-manifold, splits into several solids, or contains a surface
1047
+ * Snaptrude cannot represent. A distance larger than an adjacent face
1048
+ * is reported here, with a hint asking for a smaller one. Unlike
1049
+ * {@linkcode PluginGeomCreateApi.brepFromFillet}, the kernel does not say
1050
+ * which edge failed a chamfer, so the error names no edge
1051
+ *
1052
+ * @examplePrompt Chamfer the top edge of the cylinder
650
1053
  * @examplePrompt Bevel these edges by 100mm
651
1054
  * @examplePrompt Chamfer the top edges of the plinth
652
1055
  * @examplePrompt Cut a 45-degree flat along the corners of this mass
@@ -682,11 +1085,15 @@ export abstract class PluginGeomCreateApi {
682
1085
  * tapering across a bend or along an arc edge would create faces Snaptrude
683
1086
  * cannot represent and throws (sweep each straight run separately and union
684
1087
  * the results instead). An optional `transition` picks the corner
685
- * treatment: `"miter"` (default) is today's sharp mitred bend;
1088
+ * treatment: `"miter"` (default) is a sharp mitred bend; `"round"`
1089
+ * carries the section around each turning corner on a tangent circular arc,
1090
+ * so the corner patch is a real curved (cylindrical) surface rather than a
1091
+ * flat cut (open paths only — `"round"` on a closed ring path is refused);
686
1092
  * `{ bevel: b }` chamfers each turning corner by cutting `b` back along
687
1093
  * both adjacent legs (works on open and closed paths — each leg must be
688
- * long enough for its cuts). On a corner-less path `transition` has no effect, and the
689
- * varying-scale lane takes straight paths, so it never sees a corner.
1094
+ * long enough for its cuts). On a corner-less path `transition` has no
1095
+ * effect, and a varying scale only accepts straight paths, so it never meets
1096
+ * a corner.
690
1097
  *
691
1098
  * Open paths run on the OpenCascade kernel (the first kernel call loads a
692
1099
  * wasm of tens of MB — expect a pause of seconds); closed paths are
@@ -696,19 +1103,22 @@ export abstract class PluginGeomCreateApi {
696
1103
  * with `design.create.massFromBrep`.
697
1104
  *
698
1105
  * @param profile The cross-section to sweep (hole-free contour)
699
- * @param path The polyline path as plain `{x, y, z}` points (≥2; repeat the
700
- * first point as the last to close the path into a ring)
1106
+ * @param path The polyline path as plain `{x, y, z}` points (2 or more;
1107
+ * repeat the first point as the last to close the path into a ring; more
1108
+ * than 512 points still sweeps but the result carries no parameter record)
701
1109
  * @param options Optional scale law and corner transition. Scale law:
702
1110
  * `startScale`/`endScale` (linear taper by arc length) or `scales` (one
703
1111
  * factor per path point; mutually exclusive with
704
1112
  * `startScale`/`endScale`); every factor must be finite and within
705
- * 1e-3..1e3. `transition`: `"miter"` (default, sharp corners) or
706
- * `{ bevel: b }` (chamfered corners, `b` finite within 1e-3..1e3; open
707
- * and closed paths)
1113
+ * 1e-3..1e3. `transition`: `"miter"` (default, sharp corners),
1114
+ * `"round"` (arc-carried corners — curved corner patches; open paths
1115
+ * only) or `{ bevel: b }` (chamfered corners, `b` finite within
1116
+ * 1e-3..1e3; open and closed paths)
708
1117
  * @returns The swept solid as a new {@linkcode BrepHandle}
709
1118
  * @throws VALIDATION if the profile has holes, the path has fewer than 2
710
- * points, consecutive path points coincide, a coordinate is not finite,
711
- * or the profile plane contains the first path segment's direction
1119
+ * points, consecutive path points coincide, a
1120
+ * coordinate is not finite, or the profile plane contains the first
1121
+ * path segment's direction
712
1122
  * (degenerate sweep); for closed paths, if the ring has fewer than 3
713
1123
  * distinct corners, the path is non-planar, a corner doubles back, the
714
1124
  * profile has an arc edge, or the profile is too large for a mitred
@@ -716,11 +1126,14 @@ export abstract class PluginGeomCreateApi {
716
1126
  * is combined with `startScale`/`endScale`, `scales` does not match the
717
1127
  * path length, or a varying scale is used on a bent or closed path or
718
1128
  * with an arc-edged profile; for `{ bevel }`, if a leg is too short for
719
- * the cuts its beveled corners take from it or a corner nearly doubles
720
- * back so its chamfer collapses (the errors name the corner)
1129
+ * the cuts its bevelled corners take from it or a corner nearly doubles
1130
+ * back so its bevel collapses (the errors name the corner)
1131
+ * @throws PRECONDITION_FAILED if `transition` is `"round"` and the path is
1132
+ * closed — round corners work on open paths only; use `"miter"` or
1133
+ * `{ bevel }` on a ring
721
1134
  * @throws OPERATION_FAILED if the kernel cannot sweep the profile into a
722
- * valid solid or a transition patch is a curved surface Snaptrude cannot
723
- * represent
1135
+ * valid solid — including a `"round"` corner whose arc does not fit its
1136
+ * legs, which is not pre-checked and so is not named per corner
724
1137
  *
725
1138
  * @examplePrompt Sweep this profile along the corridor path
726
1139
  * @examplePrompt Extrude the railing section along this route
@@ -729,6 +1142,7 @@ export abstract class PluginGeomCreateApi {
729
1142
  * @examplePrompt Taper this duct from 1x1 to 2x2 along its run
730
1143
  * @examplePrompt Sweep a column section that narrows toward the top
731
1144
  * @examplePrompt Chamfer the corners of this swept frame by 200mm
1145
+ * @examplePrompt Sweep this handrail with rounded corners at the bends
732
1146
  *
733
1147
  * # Example
734
1148
  * ```ts
@@ -767,17 +1181,74 @@ export abstract class PluginGeomCreateApi {
767
1181
  startScale?: number
768
1182
  endScale?: number
769
1183
  scales?: number[]
770
- transition?: "miter" | { bevel: number }
1184
+ transition?: "miter" | "round" | { bevel: number }
771
1185
  },
772
1186
  ): PluginApiReturn<BrepHandle>
773
1187
 
1188
+ /**
1189
+ * Sweeps a cross-section along a SMOOTH path — splines, arcs and lines chained
1190
+ * end to end — with control of how the profile turns.
1191
+ * {@linkcode PluginGeomCreateApi.brepFromSweep} takes a polyline path; this
1192
+ * takes curves. Host API call — returns a new {@linkcode BrepHandle}; the
1193
+ * inputs are read-only. Records as `sweepAlongCurve`, so the orientation stays
1194
+ * editable through `design.update.parameters`. The properties panel shows it
1195
+ * read-only, because it is a text value, not a number.
1196
+ *
1197
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
1198
+ * of MB — expect a pause of seconds).
1199
+ *
1200
+ * @param profile Hole-free cross-section contour; placed at the first curve's start
1201
+ * @param path 1..64 curves, ordered, meeting end to end within tolerance
1202
+ * @param options `orientation` — `"upright"` (default) keeps the profile's up
1203
+ * aligned with world up (ducts, handrails, ribbons that must not roll);
1204
+ * `"frenet"` lets it roll with the path's curvature; `"fixed"` carries the
1205
+ * authored frame along unchanged, which is a pure translation — use it to
1206
+ * bend a footprint along an arc. `rail` is a second guide curve.
1207
+ * @returns The swept solid as a new {@linkcode BrepHandle}
1208
+ * @throws VALIDATION if the path curves are not connected, the path is closed,
1209
+ * the profile has holes, the first tangent lies in the profile plane, the
1210
+ * path runs vertically under `"upright"` (that frame is undefined there —
1211
+ * the message names the run and points at `"frenet"`), the path turns
1212
+ * parallel to the profile under `"fixed"`, or `rail` is passed on a kernel
1213
+ * build that cannot carry it
1214
+ * @throws OPERATION_FAILED if the kernel could not sweep the profile — a
1215
+ * self-intersection on a tight bend
1216
+ *
1217
+ * @examplePrompt Sweep a 600x400 duct along this curved route and keep it upright
1218
+ * @examplePrompt Run this handrail along the curved stair edge
1219
+ * @examplePrompt Bend this footprint along the arc
1220
+ *
1221
+ * # Example
1222
+ * ```ts
1223
+ * const route = await snaptrude.core.geom.create.splineFromPoints(points)
1224
+ * const duct = await snaptrude.core.geom.create.brepFromSweepAlongCurve(profile, [route], {
1225
+ * orientation: "upright",
1226
+ * })
1227
+ * ```
1228
+ */
1229
+ public abstract brepFromSweepAlongCurve(
1230
+ profile: ContourHandle,
1231
+ path: CurveHandle[],
1232
+ options?: SweepAlongCurveOptions,
1233
+ ): PluginApiReturn<BrepHandle>
1234
+
774
1235
  /**
775
1236
  * Revolves a planar profile about an axis to make a solid of revolution — a
776
1237
  * full turn by default. Host API call — returns a new
777
1238
  * {@linkcode BrepHandle}; the input contour is read-only. Holes in the
778
- * profile are allowed. Profile segments must stay parallel or perpendicular
779
- * to the axis — inclined or arc segments would revolve into surfaces
780
- * Snaptrude cannot represent.
1239
+ * profile are allowed, and segments may run at any angle to the axis: an
1240
+ * inclined segment revolves into a cone, an arc into a sphere or torus
1241
+ * section. This is the general route to domes, vases, columns and rotundas.
1242
+ *
1243
+ * Two rules bind the axis to the profile. First, the axis line must lie IN
1244
+ * the profile's plane — a revolution turns a planar section about a line
1245
+ * drawn in that same plane. An axis that misses the plane (skew to it, or
1246
+ * parallel but offset out of it) is refused: move the axis into the
1247
+ * profile's plane, or move the profile onto the axis's plane. Second,
1248
+ * within that plane the whole profile stays on ONE side of the axis.
1249
+ * Vertices and whole segments may lie ON the axis — that is how a dome's
1250
+ * pole and a cylinder's inner edge are authored — but no part of the profile
1251
+ * may cross to the other side, which would sweep a self-intersecting solid.
781
1252
  *
782
1253
  * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
783
1254
  * tens of MB — expect a pause of seconds).
@@ -791,19 +1262,25 @@ export abstract class PluginGeomCreateApi {
791
1262
  * @param angleInDegrees Optional revolution angle in degrees (0 < angle ≤ 360; default 360)
792
1263
  * @returns The revolved solid as a new {@linkcode BrepHandle}
793
1264
  * @throws VALIDATION if `axisDirection` is zero-length, `angleInDegrees` is
794
- * not in (0, 360], the axis passes through the profile interior, or a
795
- * coordinate is not finite
796
- * @throws OPERATION_FAILED if the kernel cannot revolve the profile or the
797
- * result contains curved surfaces Snaptrude cannot represent (keep
798
- * profile segments parallel or perpendicular to the axis)
1265
+ * not in (0, 360], a coordinate is not finite, or the profile crosses the
1266
+ * axis (the message names the offending segment — keep the whole profile
1267
+ * on one side; points may touch the axis but not cross it)
1268
+ * @throws PRECONDITION_FAILED if the axis does not lie in the profile's
1269
+ * plane — skew to it, or parallel but offset out of it (the message asks
1270
+ * you to move the axis into the plane of the profile)
1271
+ * @throws OPERATION_FAILED if the kernel cannot revolve the profile into a
1272
+ * valid solid
799
1273
  *
800
1274
  * @examplePrompt Create a dome from this section
801
1275
  * @examplePrompt Revolve this profile 360 degrees around the vertical axis
802
1276
  * @examplePrompt Build a rotunda by revolving this wall section
1277
+ * @examplePrompt Make a dome by revolving a quarter-circle about the vertical axis
1278
+ * @examplePrompt Turn this curved outline into a vase
803
1279
  *
804
1280
  * # Example
805
1281
  * ```ts
806
- * // A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at its edge
1282
+ * // A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at
1283
+ * // its edge — the left edge sits ON the axis, which is legal.
807
1284
  * const rect = await snaptrude.core.geom.create.profileFromLinePoints([
808
1285
  * await snaptrude.core.math.vec3.new(0, 0, 0),
809
1286
  * await snaptrude.core.math.vec3.new(2, 0, 0),
@@ -824,6 +1301,159 @@ export abstract class PluginGeomCreateApi {
824
1301
  axisDirection: Vec3Components,
825
1302
  angleInDegrees?: number,
826
1303
  ): PluginApiReturn<BrepHandle>
1304
+
1305
+ /**
1306
+ * Create a solid **sphere** B-rep (boundary representation: the solid's
1307
+ * exact faces, edges and vertices) from a centre and radius. Host API call
1308
+ * — returns a {@linkcode BrepHandle}; commit it to the scene with
1309
+ * `design.create.massFromBrep`. The result carries an exact spherical
1310
+ * surface (not a faceted approximation) and a creation recipe — read the
1311
+ * committed mass's parameters back with `design.query.getParameters` and edit
1312
+ * them with `design.update.parameters`.
1313
+ *
1314
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
1315
+ * of MB — expect a pause of seconds).
1316
+ *
1317
+ * @param centre Sphere centre as plain `{x, y, z}` components (raw Babylon units)
1318
+ * @param radius Sphere radius (> 0, raw Babylon units)
1319
+ * @returns The new solid as a {@linkcode BrepHandle}
1320
+ * @throws VALIDATION if `radius` is not a positive finite number or a
1321
+ * coordinate is not finite
1322
+ *
1323
+ * @examplePrompt Create a sphere of radius 5 at the origin
1324
+ * @examplePrompt Add a 3m ball on top of the tower
1325
+ *
1326
+ * # Example
1327
+ * ```ts
1328
+ * const brep = await snaptrude.core.geom.create.brepFromSphere({ x: 0, y: 5, z: 0 }, 5)
1329
+ * const mass = await snaptrude.design.create.massFromBrep(brep, "Sphere")
1330
+ * ```
1331
+ */
1332
+ public abstract brepFromSphere(
1333
+ centre: Vec3Components,
1334
+ radius: number,
1335
+ ): PluginApiReturn<BrepHandle>
1336
+
1337
+ /**
1338
+ * Create a solid **cylinder** B-rep from its bottom-cap centre, axis
1339
+ * direction, radius and height. Host API call — returns a
1340
+ * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. The
1341
+ * bottom cap sits AT `base` and the solid extends `height` along `axis` —
1342
+ * place `base` on the floor and use axis `{x: 0, y: 1, z: 0}` for an upright
1343
+ * column. Carries a creation recipe (radius, height), editable through
1344
+ * `design.update.parameters`.
1345
+ *
1346
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
1347
+ * of MB — expect a pause of seconds).
1348
+ *
1349
+ * @param base Centre of the bottom cap as plain `{x, y, z}` components
1350
+ * @param axis Axis direction as plain `{x, y, z}` components (non-zero, normalised by the host)
1351
+ * @param radius Cylinder radius (> 0)
1352
+ * @param height Cylinder height along `axis` (> 0)
1353
+ * @returns The new solid as a {@linkcode BrepHandle}
1354
+ * @throws VALIDATION if `radius`/`height` are not positive finite numbers or
1355
+ * `axis` is zero-length
1356
+ *
1357
+ * @examplePrompt Create a cylinder 2m across and 4m tall
1358
+ * @examplePrompt Add a circular column here
1359
+ *
1360
+ * # Example
1361
+ * ```ts
1362
+ * const brep = await snaptrude.core.geom.create.brepFromCylinder(
1363
+ * { x: 0, y: 0, z: 0 },
1364
+ * { x: 0, y: 1, z: 0 },
1365
+ * 1,
1366
+ * 4,
1367
+ * )
1368
+ * const column = await snaptrude.design.create.massFromBrep(brep, "Column")
1369
+ * ```
1370
+ */
1371
+ public abstract brepFromCylinder(
1372
+ base: Vec3Components,
1373
+ axis: Vec3Components,
1374
+ radius: number,
1375
+ height: number,
1376
+ ): PluginApiReturn<BrepHandle>
1377
+
1378
+ /**
1379
+ * Create a solid **cone or frustum** B-rep: bottom-cap centre, axis, base
1380
+ * radius, height, and an optional top radius (default 0 — a full cone to a
1381
+ * point; > 0 — a frustum / tapered column). Host API call — returns a
1382
+ * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. Carries
1383
+ * a creation recipe (radii + height), editable through `design.update.parameters`.
1384
+ *
1385
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
1386
+ * of MB — expect a pause of seconds).
1387
+ *
1388
+ * @param base Centre of the bottom cap as plain `{x, y, z}` components
1389
+ * @param axis Axis direction as plain `{x, y, z}` components (non-zero, normalised by the host)
1390
+ * @param baseRadius Radius at the base (> 0)
1391
+ * @param height Height along `axis` (> 0)
1392
+ * @param topRadius Optional radius at the top (≥ 0, ≠ `baseRadius`; default 0 = apex)
1393
+ * @returns The new solid as a {@linkcode BrepHandle}
1394
+ * @throws VALIDATION if radii/height are invalid, `topRadius === baseRadius`
1395
+ * (that is a cylinder — use {@linkcode PluginGeomCreateApi.brepFromCylinder}),
1396
+ * or `axis` is zero-length
1397
+ *
1398
+ * @examplePrompt Create a cone roof 4m wide and 3m tall
1399
+ * @examplePrompt Make a tapered column narrowing from 1m to 0.6m
1400
+ *
1401
+ * # Example
1402
+ * ```ts
1403
+ * const roof = await snaptrude.core.geom.create.brepFromCone(
1404
+ * { x: 0, y: 9, z: 0 },
1405
+ * { x: 0, y: 1, z: 0 },
1406
+ * 2,
1407
+ * 3,
1408
+ * )
1409
+ * ```
1410
+ */
1411
+ public abstract brepFromCone(
1412
+ base: Vec3Components,
1413
+ axis: Vec3Components,
1414
+ baseRadius: number,
1415
+ height: number,
1416
+ topRadius?: number,
1417
+ ): PluginApiReturn<BrepHandle>
1418
+
1419
+ /**
1420
+ * Create a solid **torus** (ring / donut) B-rep from its centre, plane
1421
+ * normal, ring radius and tube radius. Host API call — returns a
1422
+ * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`.
1423
+ * `majorRadius` is centre-to-tube-centre; `minorRadius` is the tube's own
1424
+ * radius and must be strictly smaller. Carries a creation recipe, editable
1425
+ * through `design.update.parameters`.
1426
+ *
1427
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
1428
+ * of MB — expect a pause of seconds).
1429
+ *
1430
+ * @param centre Torus centre as plain `{x, y, z}` components
1431
+ * @param axis Plane normal of the ring as plain `{x, y, z}` components (non-zero)
1432
+ * @param majorRadius Ring radius, centre to tube centre (> 0)
1433
+ * @param minorRadius Tube radius (> 0 and < `majorRadius` — a self-intersecting torus is rejected)
1434
+ * @returns The new solid as a {@linkcode BrepHandle}
1435
+ * @throws VALIDATION if a radius is invalid, `minorRadius >= majorRadius`,
1436
+ * or `axis` is zero-length
1437
+ *
1438
+ * @examplePrompt Create a donut-shaped ring 10m across with a 1m tube
1439
+ * @examplePrompt Add a torus canopy around the tower
1440
+ *
1441
+ * # Example
1442
+ * ```ts
1443
+ * const ring = await snaptrude.core.geom.create.brepFromTorus(
1444
+ * { x: 0, y: 6, z: 0 },
1445
+ * { x: 0, y: 1, z: 0 },
1446
+ * 5,
1447
+ * 1,
1448
+ * )
1449
+ * ```
1450
+ */
1451
+ public abstract brepFromTorus(
1452
+ centre: Vec3Components,
1453
+ axis: Vec3Components,
1454
+ majorRadius: number,
1455
+ minorRadius: number,
1456
+ ): PluginApiReturn<BrepHandle>
827
1457
  }
828
1458
 
829
1459
  /**
@@ -877,6 +1507,38 @@ export const PluginGeomCreateCircleArgs = z.object({
877
1507
 
878
1508
  export type PluginGeomCreateCircleArgs = z.infer<typeof PluginGeomCreateCircleArgs>
879
1509
 
1510
+ /**
1511
+ * Arguments for {@linkcode PluginGeomCreateApi.splineFromPoints}.
1512
+ *
1513
+ * | Property | Type | Description |
1514
+ * |---|---|---|
1515
+ * | `points` | {@linkcode Vec3Handle}`[]` | 3..256 ordered through-points of the curve |
1516
+ */
1517
+ export const PluginGeomCreateSplineFromPointsArgs = z.object({
1518
+ points: z.array(Vec3Handle).min(3).max(MAX_SPLINE_THROUGH_POINTS),
1519
+ })
1520
+
1521
+ export type PluginGeomCreateSplineFromPointsArgs = z.infer<
1522
+ typeof PluginGeomCreateSplineFromPointsArgs
1523
+ >
1524
+
1525
+ /**
1526
+ * Arguments for {@linkcode PluginGeomCreateApi.splineFromControlPoints}.
1527
+ *
1528
+ * | Property | Type | Description |
1529
+ * |---|---|---|
1530
+ * | `controlPoints` | {@linkcode Vec3Handle}`[]` | 3..512 control points of the curve, in order |
1531
+ * | `options` | `object`? | `degree`: 2 or 3 (default `min(3, controlPoints.length - 1)`) |
1532
+ */
1533
+ export const PluginGeomCreateSplineFromControlPointsArgs = z.object({
1534
+ controlPoints: z.array(Vec3Handle).min(3).max(MAX_SPLINE_POLES),
1535
+ options: z.object({ degree: z.number().int().min(2).max(3).optional() }).optional(),
1536
+ })
1537
+
1538
+ export type PluginGeomCreateSplineFromControlPointsArgs = z.infer<
1539
+ typeof PluginGeomCreateSplineFromControlPointsArgs
1540
+ >
1541
+
880
1542
  /**
881
1543
  * Arguments for {@linkcode PluginGeomCreateApi.profileFromLinePoints}.
882
1544
  *
@@ -907,6 +1569,21 @@ export type PluginGeomCreateProfileFromCurvesArgs = z.infer<
907
1569
  typeof PluginGeomCreateProfileFromCurvesArgs
908
1570
  >
909
1571
 
1572
+ /**
1573
+ * Arguments for {@linkcode PluginGeomCreateApi.profileFromSplinePoints}.
1574
+ *
1575
+ * | Property | Type | Description |
1576
+ * |---|---|---|
1577
+ * | `points` | {@linkcode Vec3Handle}`[]` | 3..256 ordered through-points of the closed loop (first point NOT repeated) |
1578
+ */
1579
+ export const PluginGeomCreateProfileFromSplinePointsArgs = z.object({
1580
+ points: z.array(Vec3Handle).min(3).max(MAX_SPLINE_THROUGH_POINTS),
1581
+ })
1582
+
1583
+ export type PluginGeomCreateProfileFromSplinePointsArgs = z.infer<
1584
+ typeof PluginGeomCreateProfileFromSplinePointsArgs
1585
+ >
1586
+
910
1587
  /**
911
1588
  * Arguments for {@linkcode PluginGeomCreateApi.contourFromProfile}.
912
1589
  *
@@ -962,6 +1639,7 @@ export type PluginGeomCreateBrepFromFacesArgs = z.infer<
962
1639
  * | `contour` | {@linkcode ContourHandle} | The cross-section to extrude |
963
1640
  * | `direction` | {@linkcode Vec3Components} | Extrusion direction (non-zero, finite components) |
964
1641
  * | `amount` | `number` | Extrusion distance (finite, non-zero) |
1642
+ * | `options` | `object`? | Optional twist and taper: `twistInDegrees` (an angle, finite), `topScale` (a ratio, finite and positive) and `levels` (a count, 2..64) |
965
1643
  */
966
1644
  export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
967
1645
  contour: ContourHandle,
@@ -974,6 +1652,13 @@ export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
974
1652
  .number()
975
1653
  .finite()
976
1654
  .refine((value) => value !== 0, { message: "amount must be non-zero" }),
1655
+ options: z
1656
+ .object({
1657
+ twistInDegrees: z.number().finite().optional(),
1658
+ topScale: z.number().finite().positive().optional(),
1659
+ levels: z.number().int().min(2).max(MAX_TWIST_LEVELS).optional(),
1660
+ })
1661
+ .optional(),
977
1662
  })
978
1663
 
979
1664
  export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
@@ -987,8 +1672,8 @@ export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
987
1672
  * |---|---|---|
988
1673
  * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
989
1674
  * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
990
- * | `intermediateContours` | {@linkcode ContourHandle}`[]`? | Optional in-between cross-sections, ordered bottom to top |
991
- * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`) and `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) |
1675
+ * | `intermediateContours` | {@linkcode ContourHandle}`[]`? | Optional in-between cross-sections, ordered bottom to top (any count; more than 32 sections in all builds but carries no parameter record) |
1676
+ * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`), `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) and `smoothing` (`"smooth"` lofts every section in one pass, so the sides curve through the intermediates; default `"ruled"`) |
992
1677
  */
993
1678
  export const PluginGeomCreateBrepFromLoftArgs = z.object({
994
1679
  bottomContour: ContourHandle,
@@ -998,6 +1683,7 @@ export const PluginGeomCreateBrepFromLoftArgs = z.object({
998
1683
  .object({
999
1684
  compatibility: z.enum(["strict", "auto"]).optional(),
1000
1685
  seamAlignment: z.enum(["authored", "auto"]).optional(),
1686
+ smoothing: z.enum(["ruled", "smooth"]).optional(),
1001
1687
  })
1002
1688
  .optional(),
1003
1689
  })
@@ -1050,16 +1736,99 @@ const FiniteVec3Components = z.object({
1050
1736
  * | Property | Type | Description |
1051
1737
  * |---|---|---|
1052
1738
  * | `brep` | {@linkcode BrepHandle} | The solid whose edges to round |
1053
- * | `edges` | {@linkcode EdgeHandle}`[]` | The straight edges to fillet (≥1) |
1054
- * | `radius` | `number` | Fillet radius (positive, finite) |
1739
+ * | `edges` | {@linkcode EdgeHandle}`[]` | The edges to fillet (one or more; more than 64 builds but carries no parameter record) |
1740
+ * | `radius` | `number` | Fillet radius (positive, finite); the start radius of a variable blend |
1741
+ * | `options` | `object`? | Optional variable blend: `endRadius` (positive, finite) or `radii` (2..32 rows of `{ position, radius }`, `position` a ratio 0..1 strictly increasing). Mutually exclusive, and either one takes exactly ONE edge |
1055
1742
  */
1056
- export const PluginGeomCreateBrepFromFilletArgs = z.object({
1743
+ export const PluginGeomCreateBrepFromFilletArgs = z
1744
+ .object({
1745
+ brep: BrepHandle,
1746
+ edges: z.array(EdgeHandle).min(1),
1747
+ radius: z.number().finite().positive(),
1748
+ options: z
1749
+ .object({
1750
+ endRadius: z.number().finite().positive().optional(),
1751
+ radii: z
1752
+ .array(
1753
+ z.object({
1754
+ position: z.number().finite().min(0).max(1),
1755
+ radius: z.number().finite().positive(),
1756
+ }),
1757
+ )
1758
+ .min(2)
1759
+ .max(MAX_FILLET_LAW_SAMPLES)
1760
+ .optional(),
1761
+ })
1762
+ .optional(),
1763
+ })
1764
+ .superRefine((a, ctx) => {
1765
+ const { endRadius, radii } = a.options ?? {}
1766
+ if (endRadius === undefined && radii === undefined) return
1767
+ if (endRadius !== undefined && radii !== undefined) {
1768
+ ctx.addIssue({ code: "custom", message: "endRadius is mutually exclusive with radii" })
1769
+ }
1770
+ // The law belongs to the blend contour the one edge lies on, and `position`
1771
+ // is measured from that edge's start: a second edge would have no origin.
1772
+ if (a.edges.length !== 1) {
1773
+ ctx.addIssue({
1774
+ code: "custom",
1775
+ message: "a variable fillet takes exactly one edge — the blend contour it runs along",
1776
+ })
1777
+ }
1778
+ if (radii?.some((row, i) => i > 0 && row.position <= radii[i - 1].position)) {
1779
+ ctx.addIssue({ code: "custom", message: "radii positions must strictly increase" })
1780
+ }
1781
+ })
1782
+
1783
+ export type PluginGeomCreateBrepFromFilletArgs = z.infer<typeof PluginGeomCreateBrepFromFilletArgs>
1784
+
1785
+ /** An edge with the solid it belongs to. See {@linkcode OwnedEdge}. */
1786
+ export const OwnedEdge = z.object({
1787
+ edge: EdgeHandle,
1057
1788
  brep: BrepHandle,
1058
- edges: z.array(EdgeHandle).min(1),
1059
- radius: z.number().finite().positive(),
1789
+ face: FaceHandle.optional(),
1060
1790
  })
1061
1791
 
1062
- export type PluginGeomCreateBrepFromFilletArgs = z.infer<typeof PluginGeomCreateBrepFromFilletArgs>
1792
+ /**
1793
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromPatch}.
1794
+ *
1795
+ * | Property | Type | Description |
1796
+ * |---|---|---|
1797
+ * | `boundary` | ({@linkcode CurveHandle} \| {@linkcode OwnedEdge})`[]` | 3..16 items forming one closed loop |
1798
+ * | `thickness` | `number` | Solid thickness in internal length units (positive, finite) |
1799
+ * | `options` | `object`? | `interiorPoints` (≤ 64 plain `{x, y, z}` the surface is pulled through), `continuity` (`"position"` default, or `"tangent"` — every item must then be an edge item naming its `face`), `side` (`"below"` default, or `"above"`) |
1800
+ */
1801
+ export const PluginGeomCreateBrepFromPatchArgs = z
1802
+ .object({
1803
+ boundary: z
1804
+ .array(z.union([CurveHandle, OwnedEdge]))
1805
+ .min(3)
1806
+ .max(MAX_PATCH_BOUNDARY_CURVES),
1807
+ thickness: z.number().finite().positive(),
1808
+ options: z
1809
+ .object({
1810
+ interiorPoints: z.array(FiniteVec3Components).max(MAX_PATCH_INTERIOR_POINTS).optional(),
1811
+ continuity: z.enum(["position", "tangent"]).optional(),
1812
+ side: z.enum(["below", "above"]).optional(),
1813
+ })
1814
+ .optional(),
1815
+ })
1816
+ .superRefine((a, ctx) => {
1817
+ if (a.options?.continuity !== "tangent") return
1818
+ // The kernel's filling call (`Add_2`) follows exactly ONE support face per
1819
+ // edge, but a solid edge touches two faces. So a tangent patch must say
1820
+ // which face to follow, for every item, and this is checked before the host
1821
+ // runs.
1822
+ if (a.boundary.some((item) => !("edge" in item) || item.face === undefined)) {
1823
+ ctx.addIssue({
1824
+ code: "custom",
1825
+ message:
1826
+ 'continuity: "tangent" needs every boundary item to be an edge with its brep and the face to continue',
1827
+ })
1828
+ }
1829
+ })
1830
+
1831
+ export type PluginGeomCreateBrepFromPatchArgs = z.infer<typeof PluginGeomCreateBrepFromPatchArgs>
1063
1832
 
1064
1833
  /**
1065
1834
  * Arguments for {@linkcode PluginGeomCreateApi.brepFromOffset}.
@@ -1085,7 +1854,7 @@ export type PluginGeomCreateBrepFromOffsetArgs = z.infer<typeof PluginGeomCreate
1085
1854
  * | Property | Type | Description |
1086
1855
  * |---|---|---|
1087
1856
  * | `brep` | {@linkcode BrepHandle} | The solid to hollow |
1088
- * | `openFaces` | {@linkcode FaceHandle}`[]` | The faces to remove as openings (≥1) |
1857
+ * | `openFaces` | {@linkcode FaceHandle}`[]` | The faces to remove as openings (one or more; more than 32 builds but carries no parameter record) |
1089
1858
  * | `thickness` | `number` | Wall thickness (positive, finite) |
1090
1859
  */
1091
1860
  export const PluginGeomCreateBrepFromShellArgs = z.object({
@@ -1113,13 +1882,51 @@ export const PluginGeomCreateBrepsFromSplitArgs = z.object({
1113
1882
 
1114
1883
  export type PluginGeomCreateBrepsFromSplitArgs = z.infer<typeof PluginGeomCreateBrepsFromSplitArgs>
1115
1884
 
1885
+ /**
1886
+ * Arguments for {@linkcode PluginGeomCreateApi.brepsFromSplitByFace}.
1887
+ *
1888
+ * | Property | Type | Description |
1889
+ * |---|---|---|
1890
+ * | `brep` | {@linkcode BrepHandle} | The solid to cut |
1891
+ * | `toolFace` | {@linkcode FaceHandle} | The cutting face (read-only) |
1892
+ * | `toolBrep` | {@linkcode BrepHandle} | The solid `toolFace` belongs to (owner last) |
1893
+ */
1894
+ export const PluginGeomCreateBrepsFromSplitByFaceArgs = z.object({
1895
+ brep: BrepHandle,
1896
+ toolFace: FaceHandle,
1897
+ toolBrep: BrepHandle,
1898
+ })
1899
+
1900
+ export type PluginGeomCreateBrepsFromSplitByFaceArgs = z.infer<
1901
+ typeof PluginGeomCreateBrepsFromSplitByFaceArgs
1902
+ >
1903
+
1904
+ /**
1905
+ * Arguments for {@linkcode PluginGeomCreateApi.curvesFromProjection}.
1906
+ *
1907
+ * | Property | Type | Description |
1908
+ * |---|---|---|
1909
+ * | `curve` | {@linkcode CurveHandle} | The curve to project |
1910
+ * | `face` | {@linkcode FaceHandle} | The face to project onto |
1911
+ * | `faceBrep` | {@linkcode BrepHandle} | The solid `face` belongs to (owner last) |
1912
+ */
1913
+ export const PluginGeomCreateCurvesFromProjectionArgs = z.object({
1914
+ curve: CurveHandle,
1915
+ face: FaceHandle,
1916
+ faceBrep: BrepHandle,
1917
+ })
1918
+
1919
+ export type PluginGeomCreateCurvesFromProjectionArgs = z.infer<
1920
+ typeof PluginGeomCreateCurvesFromProjectionArgs
1921
+ >
1922
+
1116
1923
  /**
1117
1924
  * Arguments for {@linkcode PluginGeomCreateApi.brepFromChamfer}.
1118
1925
  *
1119
1926
  * | Property | Type | Description |
1120
1927
  * |---|---|---|
1121
1928
  * | `brep` | {@linkcode BrepHandle} | The solid whose edges to bevel |
1122
- * | `edges` | {@linkcode EdgeHandle}`[]` | The straight edges to chamfer (≥1) |
1929
+ * | `edges` | {@linkcode EdgeHandle}`[]` | The edges to chamfer (one or more; more than 64 builds but carries no parameter record) |
1123
1930
  * | `distance` | `number` | Chamfer distance from the edge on each adjacent face (positive, finite) |
1124
1931
  */
1125
1932
  export const PluginGeomCreateBrepFromChamferArgs = z.object({
@@ -1142,8 +1949,8 @@ const SweepScaleFactor = z.number().finite().min(1e-3).max(1e3)
1142
1949
  * | Property | Type | Description |
1143
1950
  * |---|---|---|
1144
1951
  * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
1145
- * | `path` | {@linkcode Vec3Components}`[]` | The polyline path (≥2 points, finite components; repeating the first point as the last closes it into a ring — closed paths must be flat and straight-segmented and take a straight-edged profile) |
1146
- * | `options` | `object`? | Optional scale law: `startScale`/`endScale` (linear taper by arc length) or per-point `scales` (mutually exclusive; factors finite, 1e-3..1e3; `scales.length` must equal `path.length`). Optional corner `transition`: `"miter"` (default) or `{ bevel }` (chamfered corners; finite, 1e-3..1e3) |
1952
+ * | `path` | {@linkcode Vec3Components}`[]` | The polyline path (2 or more points, finite components — more than 512 builds but carries no parameter record; repeating the first point as the last closes it into a ring — closed paths must be flat and straight-segmented and take a straight-edged profile) |
1953
+ * | `options` | `object`? | Optional scale law: `startScale`/`endScale` (linear taper by arc length) or per-point `scales` (mutually exclusive; factors finite, 1e-3..1e3; `scales.length` must equal `path.length`). Optional corner `transition`: `"miter"` (default), `"round"` (arc-carried corners) or `{ bevel }` (chamfered corners; finite, 1e-3..1e3) |
1147
1954
  */
1148
1955
  export const PluginGeomCreateBrepFromSweepArgs = z
1149
1956
  .object({
@@ -1157,6 +1964,7 @@ export const PluginGeomCreateBrepFromSweepArgs = z
1157
1964
  transition: z
1158
1965
  .union([
1159
1966
  z.literal("miter"),
1967
+ z.literal("round"),
1160
1968
  z.object({ bevel: z.number().finite().min(1e-3).max(1e3) }),
1161
1969
  ])
1162
1970
  .optional(),
@@ -1182,14 +1990,38 @@ export const PluginGeomCreateBrepFromSweepArgs = z
1182
1990
 
1183
1991
  export type PluginGeomCreateBrepFromSweepArgs = z.infer<typeof PluginGeomCreateBrepFromSweepArgs>
1184
1992
 
1993
+ /**
1994
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromSweepAlongCurve}.
1995
+ *
1996
+ * | Property | Type | Description |
1997
+ * |---|---|---|
1998
+ * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
1999
+ * | `path` | {@linkcode CurveHandle}`[]` | 1..64 curves, ordered, meeting end to end |
2000
+ * | `options` | `object`? | `orientation` — `"upright"` (default), `"frenet"` or `"fixed"`; `rail` — a second guide {@linkcode CurveHandle} |
2001
+ */
2002
+ export const PluginGeomCreateBrepFromSweepAlongCurveArgs = z.object({
2003
+ profile: ContourHandle,
2004
+ path: z.array(CurveHandle).min(1).max(MAX_PATH_CURVES),
2005
+ options: z
2006
+ .object({
2007
+ orientation: z.enum(["frenet", "fixed", "upright"]).optional(),
2008
+ rail: CurveHandle.optional(),
2009
+ })
2010
+ .optional(),
2011
+ })
2012
+
2013
+ export type PluginGeomCreateBrepFromSweepAlongCurveArgs = z.infer<
2014
+ typeof PluginGeomCreateBrepFromSweepAlongCurveArgs
2015
+ >
2016
+
1185
2017
  /**
1186
2018
  * Arguments for {@linkcode PluginGeomCreateApi.brepFromRevolution}.
1187
2019
  *
1188
2020
  * | Property | Type | Description |
1189
2021
  * |---|---|---|
1190
2022
  * | `profile` | {@linkcode ContourHandle} | The cross-section to revolve (holes allowed) |
1191
- * | `axisOrigin` | {@linkcode Vec3Components} | A point on the revolution axis (finite components) |
1192
- * | `axisDirection` | {@linkcode Vec3Components} | The axis direction (non-zero, finite components) |
2023
+ * | `axisOrigin` | {@linkcode Vec3Components} | A point on the revolution axis (finite components; the axis must lie in the plane of the profile) |
2024
+ * | `axisDirection` | {@linkcode Vec3Components} | The axis direction (non-zero, finite components; the axis must lie in the plane of the profile) |
1193
2025
  * | `angleInDegrees` | `number`? | Revolution angle in degrees (0 < angle ≤ 360; default 360) |
1194
2026
  */
1195
2027
  export const PluginGeomCreateBrepFromRevolutionArgs = z.object({
@@ -1202,3 +2034,89 @@ export const PluginGeomCreateBrepFromRevolutionArgs = z.object({
1202
2034
  export type PluginGeomCreateBrepFromRevolutionArgs = z.infer<
1203
2035
  typeof PluginGeomCreateBrepFromRevolutionArgs
1204
2036
  >
2037
+
2038
+ /**
2039
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromSphere}.
2040
+ *
2041
+ * | Property | Type | Description |
2042
+ * |---|---|---|
2043
+ * | `centre` | {@linkcode Vec3Components} | Sphere centre (finite components) |
2044
+ * | `radius` | `number` | Sphere radius (finite; positivity is checked host-side so the error names the parameter) |
2045
+ */
2046
+ export const PluginGeomCreateBrepFromSphereArgs = z.object({
2047
+ centre: FiniteVec3Components,
2048
+ radius: z.number().finite(),
2049
+ })
2050
+
2051
+ export type PluginGeomCreateBrepFromSphereArgs = z.infer<
2052
+ typeof PluginGeomCreateBrepFromSphereArgs
2053
+ >
2054
+
2055
+ /**
2056
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromCylinder}.
2057
+ *
2058
+ * | Property | Type | Description |
2059
+ * |---|---|---|
2060
+ * | `base` | {@linkcode Vec3Components} | Centre of the bottom cap (finite components) |
2061
+ * | `axis` | {@linkcode Vec3Components} | Axis direction (non-zero, finite components) |
2062
+ * | `radius` | `number` | Cylinder radius (finite, positive) |
2063
+ * | `height` | `number` | Height along `axis` (finite, positive) |
2064
+ */
2065
+ export const PluginGeomCreateBrepFromCylinderArgs = z.object({
2066
+ base: FiniteVec3Components,
2067
+ axis: FiniteVec3Components,
2068
+ radius: z.number().finite(),
2069
+ height: z.number().finite(),
2070
+ })
2071
+
2072
+ export type PluginGeomCreateBrepFromCylinderArgs = z.infer<
2073
+ typeof PluginGeomCreateBrepFromCylinderArgs
2074
+ >
2075
+
2076
+ /**
2077
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromCone}.
2078
+ *
2079
+ * | Property | Type | Description |
2080
+ * |---|---|---|
2081
+ * | `base` | {@linkcode Vec3Components} | Centre of the bottom cap (finite components) |
2082
+ * | `axis` | {@linkcode Vec3Components} | Axis direction (non-zero, finite components) |
2083
+ * | `baseRadius` | `number` | Radius at the base (finite, positive) |
2084
+ * | `height` | `number` | Height along `axis` (finite, positive) |
2085
+ * | `topRadius` | `number`? | Radius at the top (finite, ≥ 0, ≠ `baseRadius`; default 0 = apex) |
2086
+ */
2087
+ export const PluginGeomCreateBrepFromConeArgs = z
2088
+ .object({
2089
+ base: FiniteVec3Components,
2090
+ axis: FiniteVec3Components,
2091
+ baseRadius: z.number().finite(),
2092
+ height: z.number().finite(),
2093
+ topRadius: z.number().finite().optional(),
2094
+ })
2095
+ .refine((a) => (a.topRadius ?? 0) !== a.baseRadius, {
2096
+ message: "topRadius must differ from baseRadius — equal radii are a cylinder",
2097
+ })
2098
+
2099
+ export type PluginGeomCreateBrepFromConeArgs = z.infer<typeof PluginGeomCreateBrepFromConeArgs>
2100
+
2101
+ /**
2102
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromTorus}.
2103
+ *
2104
+ * | Property | Type | Description |
2105
+ * |---|---|---|
2106
+ * | `centre` | {@linkcode Vec3Components} | Torus centre (finite components) |
2107
+ * | `axis` | {@linkcode Vec3Components} | Plane normal of the ring (non-zero, finite components) |
2108
+ * | `majorRadius` | `number` | Ring radius, centre to tube centre (finite, positive) |
2109
+ * | `minorRadius` | `number` | Tube radius (finite, positive, strictly less than `majorRadius`) |
2110
+ */
2111
+ export const PluginGeomCreateBrepFromTorusArgs = z
2112
+ .object({
2113
+ centre: FiniteVec3Components,
2114
+ axis: FiniteVec3Components,
2115
+ majorRadius: z.number().finite(),
2116
+ minorRadius: z.number().finite(),
2117
+ })
2118
+ .refine((a) => a.minorRadius < a.majorRadius, {
2119
+ message: "minorRadius must be smaller than majorRadius — the torus would self-intersect",
2120
+ })
2121
+
2122
+ export type PluginGeomCreateBrepFromTorusArgs = z.infer<typeof PluginGeomCreateBrepFromTorusArgs>