@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
@@ -174,16 +174,26 @@ export abstract class PluginGeomQueryBrepApi {
174
174
  * | `"line"` | `startPoint`, `endPoint`, `length` |
175
175
  * | `"arc"` | `startPoint`, `endPoint`, `centre`, `axis`, `radius`, `length` |
176
176
  * | `"circle"` | `centre`, `axis`, `radius`, `length` — a full-circle edge (e.g. a cylinder cap rim) |
177
+ * | `"spline"` | `startPoint`, `endPoint`, `degree`, `controlPoints`, `knots`, `length` — a free-form NURBS edge |
178
+ *
179
+ * For a `"spline"` edge, `knots` is the **expanded** knot vector — each knot
180
+ * repeated by its multiplicity, the textbook NURBS form — so
181
+ * `knots.length === controlPoints.length + degree + 1`.
177
182
  *
178
183
  * @param brep The brep the edge belongs to
179
184
  * @param edge The edge whose curve to read
180
185
  * @returns The curve data as a discriminated union on `type` (see table above)
181
186
  * @throws VALIDATION if the edge is not on `brep`
187
+ * @throws PRECONDITION_FAILED if the edge is a RATIONAL (weighted) spline —
188
+ * e.g. a NURBS-converted elliptical intersection edge. The wire form
189
+ * carries no weights, so such an edge is refused rather than reported as a
190
+ * different curve; sample it instead.
182
191
  *
183
192
  * @examplePrompt Read the radius of this curved edge
184
193
  * @examplePrompt Is this edge straight or an arc?
185
194
  * @examplePrompt Get the exact start and end points of this edge
186
195
  * @examplePrompt Measure the length of each edge of this mass
196
+ * @examplePrompt Read the control points of this curved edge
187
197
  *
188
198
  * # Example
189
199
  * ```ts
@@ -219,6 +229,16 @@ export abstract class PluginGeomQueryBrepApi {
219
229
  radius: number
220
230
  length: number
221
231
  }
232
+ | {
233
+ type: "spline"
234
+ startPoint: Vec3Components
235
+ endPoint: Vec3Components
236
+ degree: number
237
+ controlPoints: Vec3Components[]
238
+ /** Expanded by multiplicity: `controlPoints.length + degree + 1` entries. */
239
+ knots: number[]
240
+ length: number
241
+ }
222
242
  >
223
243
 
224
244
  /**
@@ -366,6 +386,37 @@ export abstract class PluginGeomQueryBrepApi {
366
386
  */
367
387
  public abstract getBoundingBox(brep: BrepHandle): PluginApiReturn<BBoxComponents>
368
388
 
389
+ /**
390
+ * Get the enclosed **volume** of a closed solid, integrated from its exact
391
+ * surfaces. Curved faces are measured analytically, not from their
392
+ * tessellation — a real sphere of radius 5 reports 523.6, whatever its
393
+ * triangle count. That makes this the reliable way to confirm a solid is the
394
+ * shape you intended (a torus should measure 2·π²·R·r²).
395
+ *
396
+ * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
397
+ * of MB — expect a pause of seconds).
398
+ *
399
+ * @param brep The solid to measure
400
+ * @returns The enclosed volume in cubic raw Babylon units
401
+ * @throws OPERATION_FAILED if the kernel cannot compute the volume (the brep
402
+ * is not a closed solid)
403
+ *
404
+ * @examplePrompt What is the volume of this mass?
405
+ * @examplePrompt How much concrete is in this shape?
406
+ * @examplePrompt Check the volume of the dome I just made
407
+ *
408
+ * # Example
409
+ * ```ts
410
+ * const [mass] = await snaptrude.design.query.listMasses()
411
+ * const brep = await snaptrude.design.query.geometry.getBrep(mass)
412
+ * if (brep) {
413
+ * const volume = await snaptrude.core.geom.query.brep.getVolume(brep)
414
+ * console.log("volume:", volume)
415
+ * }
416
+ * ```
417
+ */
418
+ public abstract getVolume(brep: BrepHandle): PluginApiReturn<number>
419
+
369
420
  /**
370
421
  * Test whether two breps are geometrically equal.
371
422
  * @param brepA First brep
@@ -388,7 +439,7 @@ export abstract class PluginGeomQueryBrepApi {
388
439
  public abstract isEqual(brepA: BrepHandle, brepB: BrepHandle): PluginApiReturn<boolean>
389
440
 
390
441
  /**
391
- * Measures the minimum distance between two solids, with the closest witness
442
+ * Measures the minimum distance between two solids, with the closest
392
443
  * point on each. Touching or overlapping solids report a distance of 0 with
393
444
  * contact points.
394
445
  *
@@ -534,6 +585,10 @@ export type PluginGeomQueryBrepGetBoundingBoxArgs = z.infer<
534
585
  typeof PluginGeomQueryBrepGetBoundingBoxArgs
535
586
  >
536
587
 
588
+ /** Arguments for {@linkcode PluginGeomQueryBrepApi.getVolume}. `{ brep: BrepHandle }` */
589
+ export const PluginGeomQueryBrepGetVolumeArgs = brepArg
590
+ export type PluginGeomQueryBrepGetVolumeArgs = z.infer<typeof PluginGeomQueryBrepGetVolumeArgs>
591
+
537
592
  /**
538
593
  * Arguments for {@linkcode PluginGeomQueryBrepApi.isEqual}.
539
594
  *
@@ -3,8 +3,8 @@ import { PluginApiReturn } from "../../../../types"
3
3
  import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../../handles"
4
4
 
5
5
  /**
6
- * Curve queries — read-only geometric questions about curves (lines and arcs)
7
- * and the relationships between two curves (all-handle model, §11).
6
+ * Curve queries — read-only geometric questions about curves (lines, arcs and
7
+ * splines) and the relationships between two curves.
8
8
  *
9
9
  * Every method takes opaque curve handles ({@linkcode CurveHandle}/{@linkcode LineHandle})
10
10
  * and point handles ({@linkcode Vec3Handle}) and returns plain values — points as
@@ -13,6 +13,29 @@ import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../..
13
13
  * {@linkcode CurveHandle} (or `null` when there is no result). No query mutates its
14
14
  * inputs.
15
15
  *
16
+ * ## Splines
17
+ *
18
+ * A {@linkcode CurveHandle} is a line, an arc, or a NURBS spline (minted by
19
+ * `core.geom.create.splineFromPoints`). Every method here accepts a spline at
20
+ * compile time, but only the reads backed by the engine's spline math answer
21
+ * for one today. The rest throw `PRECONDITION_FAILED` ("not supported for
22
+ * splines yet") — a typed refusal, never a quietly wrong answer.
23
+ *
24
+ * | Splines | Members |
25
+ * |---|---|
26
+ * | **supported** | {@linkcode PluginGeomQueryCurveApi.getStartPoint}, {@linkcode PluginGeomQueryCurveApi.getEndPoint}, {@linkcode PluginGeomQueryCurveApi.getLength}, {@linkcode PluginGeomQueryCurveApi.getTangent}, {@linkcode PluginGeomQueryCurveApi.listPoints}, {@linkcode PluginGeomQueryCurveApi.getNearestPoint} |
27
+ * | **not yet** | `getMidPoint`, `getChordLength`, `getNormal`, `getProjection`, `getPointAtDistance`, `getParameterAtPoint`, `getCurvature`, `getDistanceToPoint`, `getDistanceAlong`, `listSubdivisions`, `isLinear`, `isOnCurve`, `hasPoint`, `isEqual`, `isOverlapping`, `getCommonPart`, `listIntersections`, `getMergedCurve`, `isContinuous`, `isParallel`, `getShortestGap`, `getDistanceBetween` |
28
+ *
29
+ * {@linkcode PluginGeomQueryCurveApi.isOverlapping} is deliberately in the
30
+ * second row: its line/arc path falls back to structural equality, which would
31
+ * answer a spline pair wrongly rather than not at all.
32
+ *
33
+ * To work around the second row, sample the curve —
34
+ * {@linkcode PluginGeomQueryCurveApi.listPoints} then the ordinary
35
+ * `core.math.vec3` operations — or read a spline brep edge exactly with
36
+ * `core.geom.query.brep.getEdgeCurve`, which returns its degree, control points
37
+ * and knots.
38
+ *
16
39
  * Accessed via `snaptrude.core.geom.query.curve`.
17
40
  */
18
41
  export abstract class PluginGeomQueryCurveApi {
@@ -69,9 +69,9 @@ export abstract class PluginGeomQueryEdgeApi {
69
69
  public abstract listVertices(edge: EdgeHandle): PluginApiReturn<VertexHandle[]>
70
70
 
71
71
  /**
72
- * Get the underlying curve geometry of an edge (a line or arc).
72
+ * Get the underlying curve geometry of an edge (a line, arc or spline).
73
73
  * @param edge The edge to query
74
- * @returns The curve as a {@linkcode CurveHandle}, or `null` if it is a circle or unset
74
+ * @returns The curve as a {@linkcode CurveHandle} (`line_`, `arc_` or `spline_`), or `null` if it is a circle or unset
75
75
  *
76
76
  * # Example
77
77
  * ```ts
@@ -59,6 +59,49 @@ export abstract class PluginGeomQueryFaceApi {
59
59
  */
60
60
  public abstract getMaterialIndex(face: FaceHandle): PluginApiReturn<number>
61
61
 
62
+ /**
63
+ * Read what KIND of surface a face lies on. This is the one read that tells a
64
+ * genuinely curved face from a faceted approximation of one: every face of a
65
+ * 200-triangle "dome" answers `"plane"`, while a real dome has faces
66
+ * answering `"sphere"`. Use it to confirm a curved solid actually came out
67
+ * curved.
68
+ *
69
+ * | Value | Surface |
70
+ * |---|---|
71
+ * | `"plane"` | Flat face |
72
+ * | `"cylinder"` | Cylindrical face — constant radius about an axis |
73
+ * | `"cone"` | Conical face — a tapered ring (a cone or frustum side) |
74
+ * | `"sphere"` | Spherical face |
75
+ * | `"torus"` | Toroidal face — the ring surface of a donut |
76
+ * | `"spline"` | Free-form NURBS face |
77
+ *
78
+ * Pure read: no geometry kernel is loaded.
79
+ *
80
+ * @param face The face to query
81
+ * @returns The surface kind (see the table), or `null` when the face carries
82
+ * no surface classification
83
+ *
84
+ * @examplePrompt Is this face flat or curved?
85
+ * @examplePrompt Check that this dome is a real sphere, not a faceted approximation
86
+ * @examplePrompt What kind of surface is this face?
87
+ * @examplePrompt How many curved faces does this mass have?
88
+ *
89
+ * # Example
90
+ * ```ts
91
+ * const [mass] = await snaptrude.design.query.listMasses()
92
+ * const brep = await snaptrude.design.query.geometry.getBrep(mass)
93
+ * if (brep) {
94
+ * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
95
+ * const kinds = []
96
+ * for (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))
97
+ * console.log("spherical faces:", kinds.filter((k) => k === "sphere").length)
98
+ * }
99
+ * ```
100
+ */
101
+ public abstract getSurfaceKind(
102
+ face: FaceHandle,
103
+ ): PluginApiReturn<"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null>
104
+
62
105
  /**
63
106
  * Get a seed half-edge of a face's outer loop.
64
107
  * @param face The face to query
@@ -257,6 +300,56 @@ export abstract class PluginGeomQueryFaceApi {
257
300
  brep: BrepHandle,
258
301
  ): PluginApiReturn<Vec3Components[]>
259
302
 
303
+ /**
304
+ * Exact surface area of one face of `brep`, in internal length units SQUARED —
305
+ * integrated off the face's own surface, not its facets, so a curved patch
306
+ * reads exactly rather than as its triangles. Needs the parent brep: a face
307
+ * handle cannot name its own solid.
308
+ * @param face The face to measure
309
+ * @param brep The parent brep (owner last, as in
310
+ * {@linkcode PluginGeomQueryFaceApi.listVertexPositions})
311
+ * @returns The area as a `number`
312
+ * @throws VALIDATION if `face` is not a face of `brep`
313
+ * @throws OPERATION_FAILED if the kernel could not measure the face
314
+ *
315
+ * @examplePrompt How big is this roof patch?
316
+ * @examplePrompt Which face of this mass has the largest area?
317
+ *
318
+ * # Example
319
+ * ```ts
320
+ * const [mass] = await snaptrude.design.query.listMasses()
321
+ * const brep = await snaptrude.design.query.geometry.getBrep(mass)
322
+ * if (brep) {
323
+ * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
324
+ * const areas = await Promise.all(
325
+ * faces.map((f) => snaptrude.core.geom.query.face.getArea(f, brep)),
326
+ * )
327
+ * }
328
+ * ```
329
+ */
330
+ public abstract getArea(face: FaceHandle, brep: BrepHandle): PluginApiReturn<number>
331
+
332
+ /**
333
+ * Centre of area of one face of `brep`, as a point in that brep's frame
334
+ * (internal length units). On a solid whose every face reads `"spline"` this
335
+ * is the read that tells two patches apart — the top of a thickened patch from
336
+ * its bottom, one quarter of a closed surface from the next.
337
+ * @param face The face to measure
338
+ * @param brep The parent brep (owner last)
339
+ * @returns The centroid as {@linkcode Vec3Components}
340
+ * @throws VALIDATION if `face` is not a face of `brep`
341
+ * @throws OPERATION_FAILED if the kernel could not measure the face
342
+ *
343
+ * @examplePrompt Where is the middle of this face?
344
+ * @examplePrompt Pick the topmost face of this curved mass
345
+ *
346
+ * # Example
347
+ * ```ts
348
+ * const centre = await snaptrude.core.geom.query.face.getCentroid(face, brep)
349
+ * ```
350
+ */
351
+ public abstract getCentroid(face: FaceHandle, brep: BrepHandle): PluginApiReturn<Vec3Components>
352
+
260
353
  /**
261
354
  * List the tessellated boundary points of a face's outer loop (arcs sampled,
262
355
  * sense-corrected). Not cardinality-equal to {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
@@ -301,6 +394,7 @@ export abstract class PluginGeomQueryFaceApi {
301
394
  }
302
395
 
303
396
  const faceArg = z.object({ face: FaceHandle })
397
+ const faceWithBrepArg = z.object({ face: FaceHandle, brep: BrepHandle })
304
398
 
305
399
  /** Arguments for {@linkcode PluginGeomQueryFaceApi.getIndex}. `{ face: FaceHandle }` */
306
400
  export const PluginGeomQueryFaceGetIndexArgs = faceArg
@@ -312,6 +406,12 @@ export type PluginGeomQueryFaceGetMaterialIndexArgs = z.infer<
312
406
  typeof PluginGeomQueryFaceGetMaterialIndexArgs
313
407
  >
314
408
 
409
+ /** Arguments for {@linkcode PluginGeomQueryFaceApi.getSurfaceKind}. `{ face: FaceHandle }` */
410
+ export const PluginGeomQueryFaceGetSurfaceKindArgs = faceArg
411
+ export type PluginGeomQueryFaceGetSurfaceKindArgs = z.infer<
412
+ typeof PluginGeomQueryFaceGetSurfaceKindArgs
413
+ >
414
+
315
415
  /** Arguments for {@linkcode PluginGeomQueryFaceApi.getHalfEdge}. `{ face: FaceHandle }` */
316
416
  export const PluginGeomQueryFaceGetHalfEdgeArgs = faceArg
317
417
  export type PluginGeomQueryFaceGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryFaceGetHalfEdgeArgs>
@@ -382,14 +482,19 @@ export type PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.infer<
382
482
  * | `face` | {@linkcode FaceHandle} | The face to query |
383
483
  * | `brep` | {@linkcode BrepHandle} | The parent brep (source of vertex coordinates) |
384
484
  */
385
- export const PluginGeomQueryFaceListVertexPositionsArgs = z.object({
386
- face: FaceHandle,
387
- brep: BrepHandle,
388
- })
485
+ export const PluginGeomQueryFaceListVertexPositionsArgs = faceWithBrepArg
389
486
  export type PluginGeomQueryFaceListVertexPositionsArgs = z.infer<
390
487
  typeof PluginGeomQueryFaceListVertexPositionsArgs
391
488
  >
392
489
 
490
+ /** Arguments for {@linkcode PluginGeomQueryFaceApi.getArea}. `{ face: FaceHandle, brep: BrepHandle }` */
491
+ export const PluginGeomQueryFaceGetAreaArgs = faceWithBrepArg
492
+ export type PluginGeomQueryFaceGetAreaArgs = z.infer<typeof PluginGeomQueryFaceGetAreaArgs>
493
+
494
+ /** Arguments for {@linkcode PluginGeomQueryFaceApi.getCentroid}. `{ face: FaceHandle, brep: BrepHandle }` */
495
+ export const PluginGeomQueryFaceGetCentroidArgs = faceWithBrepArg
496
+ export type PluginGeomQueryFaceGetCentroidArgs = z.infer<typeof PluginGeomQueryFaceGetCentroidArgs>
497
+
393
498
  /** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositionsWithCurves}. `{ face: FaceHandle }` */
394
499
  export const PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = faceArg
395
500
  export type PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = z.infer<
@@ -1,6 +1,6 @@
1
1
  import * as z from "zod"
2
2
  import { PluginApiReturn } from "../../types"
3
- import { ComponentHandle, Vec3Components } from "../../handles"
3
+ import { BrepHandle, ComponentHandle, Vec3Components } from "../../handles"
4
4
 
5
5
  /**
6
6
  * `snaptrude.design.family.*` — author NATIVE parametric families from a JSON spec.
@@ -18,15 +18,21 @@ import { ComponentHandle, Vec3Components } from "../../handles"
18
18
  * getReference() read the spec DSL once — grammar, ops, expressions, example
19
19
  * prepare({ bundle }) validate + compile + show a live ghost; nothing committed
20
20
  * flex({ values }) re-run at new values; returns the geometry delta
21
- * place() arm placement — the USER clicks to drop it
22
21
  * create({ name }) commit it to the project's family library
22
+ * place() put it in the model — at `position`, or the USER clicks
23
23
  * ```
24
24
  *
25
+ * `create` comes BEFORE `place`: `place` refuses a draft that was never
26
+ * created (`VALIDATION`), because an instance of a family that is not in the
27
+ * library cannot be reloaded.
28
+ *
25
29
  * ## Read getReference() first
26
30
  *
27
31
  * The spec DSL is a closed expression language with its own op set, coordinate
28
- * convention (**+Y up, Snaptrude units** — the scene's own unit, 1 SU = 254 mm;
29
- * literals may carry a unit suffix such as `600mm` or `2ft`)
32
+ * convention (**+Y up, Snaptrude units** — the scene's own unit, 1 SU = 254 mm,
33
+ * the same unit `core.units.getBabylonType()` names and every geometry API
34
+ * takes; literals inside spec expressions may carry a unit suffix such as
35
+ * `600mm` or `2ft`)
30
36
  * and part-naming law. It is deliberately NOT duplicated in these types:
31
37
  * {@linkcode PluginDesignFamilyApi.getReference} returns the whole reference,
32
38
  * generated from a family that is actually registered in the host, so the
@@ -41,6 +47,18 @@ import { ComponentHandle, Vec3Components } from "../../handles"
41
47
  * leaves the previous good draft standing, so it costs nothing but the node you
42
48
  * broke. Re-authoring from scratch throws away everything already correct.
43
49
  *
50
+ * ## Curved parts are exact
51
+ *
52
+ * A part whose sketch has a curved edge — any `revolve`, or an `extrude` /
53
+ * `sweep` / `loft` with an arc or circle in its profile (or an arc in a sweep
54
+ * path) — is built by the exact geometry kernel, the same one behind curved
55
+ * masses. Straight-edged parts keep the fast mesh builder. `getParameters` on a
56
+ * placed component reports which built each part in `parts[].engine`, and a
57
+ * kernel part carries a `brep`: read it with `core.geom.query.brep.*` and
58
+ * `core.geom.query.face.getSurfaceKind` — the same face-kind check as for a
59
+ * curved mass. If the kernel is unavailable a part falls back to the mesh
60
+ * builder (`engine: "mesh"`) rather than failing the family.
61
+ *
44
62
  * Accessed via `snaptrude.design.family`.
45
63
  */
46
64
  export abstract class PluginDesignFamilyApi {
@@ -68,20 +86,25 @@ export abstract class PluginDesignFamilyApi {
68
86
 
69
87
  /**
70
88
  * Validate, compile and preview a family spec. Nothing is committed to the
71
- * model or the library — call {@linkcode PluginDesignFamilyApi.place} or
72
- * {@linkcode PluginDesignFamilyApi.create} for that.
89
+ * model or the library — call {@linkcode PluginDesignFamilyApi.create} to save
90
+ * it, then {@linkcode PluginDesignFamilyApi.place} to put it in the model.
73
91
  *
74
92
  * Safe to call repeatedly while iterating. On success, check `partCount` and
75
93
  * `bbox` against what you intended before treating the family as correct — a
76
94
  * facade that built 3 parts, or a 3 m screen reporting 40 m of height, is a
77
95
  * visible bug the validator cannot catch.
78
96
  *
97
+ * Lengths — the spec's bare numbers, `bbox`, the sheet's `length` values — are
98
+ * Snaptrude units: the same 254 mm unit as the kernel's internal (`"babylon"`)
99
+ * unit. A unit suffix (`600mm`) is legal only inside a spec expression.
100
+ *
79
101
  * @param args The spec bundle, as `{ bundle }` or `{ spec }`
80
102
  * @returns Build report, or `{ ok: false, errors }` with JSON-pointer paths
81
103
  *
82
104
  * @examplePrompt Make a louvre screen with adjustable blade count and tilt
83
105
  * @examplePrompt Design a curtain wall panel family with 8 bays
84
106
  * @examplePrompt Create a railing family I can adjust
107
+ * @examplePrompt Make a pendant lamp family with a domed shade I can resize
85
108
  *
86
109
  * # Example
87
110
  * ```ts
@@ -147,6 +170,10 @@ export abstract class PluginDesignFamilyApi {
147
170
  * Put a family into the model — either the prepared draft or any family from
148
171
  * {@linkcode PluginDesignFamilyApi.list}.
149
172
  *
173
+ * The prepared draft must be saved with {@linkcode PluginDesignFamilyApi.create}
174
+ * first: placing a draft that was never created throws `VALIDATION`, because
175
+ * its instances could not be reloaded.
176
+ *
150
177
  * Two modes, chosen by whether you pass `position`:
151
178
  *
152
179
  * **With `position`** the component is created there and then, undoably. Use
@@ -195,6 +222,9 @@ export abstract class PluginDesignFamilyApi {
195
222
  * label the user says, and a Revit-imported family carries parameters that
196
223
  * do not drive geometry at all.
197
224
  *
225
+ * `length` values are Snaptrude units: the same 254 mm unit as the kernel's
226
+ * internal (`"babylon"`) unit — convert with `core.units.convert` to report.
227
+ *
198
228
  * @param args The component to read
199
229
  * @returns Its definition, current values, and the parameter sheet
200
230
  *
@@ -220,6 +250,11 @@ export abstract class PluginDesignFamilyApi {
220
250
  * that does not is accepted and stored (it round-trips to Revit) but nothing
221
251
  * visible happens — say so rather than claiming a change the user cannot see.
222
252
  *
253
+ * `length` values are Snaptrude units: the same 254 mm unit as the kernel's
254
+ * internal (`"babylon"`) unit — convert the user's number with
255
+ * `core.units.convert` first; a bare `400` is 400 SU, not 400 mm. Kernel part
256
+ * breps read before the edit are stale: re-read `getParameters`.
257
+ *
223
258
  * @param args The component and the values to change
224
259
  * @returns The values now in effect
225
260
  *
@@ -237,7 +272,9 @@ export abstract class PluginDesignFamilyApi {
237
272
 
238
273
  /**
239
274
  * Commit the prepared bundle to the project's parametric-definition library,
240
- * so it survives the session and appears in the Families panel.
275
+ * so it survives the session and appears in the Families panel. Call it
276
+ * BEFORE {@linkcode PluginDesignFamilyApi.place} — only a created family can
277
+ * be placed; `place()` without `id` then places the saved family.
241
278
  *
242
279
  * @param args Optional library name and team scope
243
280
  * @returns The catalogued definition's id and version
@@ -292,7 +329,7 @@ export interface PluginFamilyParameter {
292
329
  key: string
293
330
  label: string
294
331
  type: "length" | "integer" | "enum" | "text" | "boolean"
295
- /** Current value. `length`/`integer` are numbers; the rest are strings. */
332
+ /** Current value. `length` (Snaptrude units) and `integer` are numbers; the rest are strings. */
296
333
  value: string | number
297
334
  default: string | number
298
335
  /**
@@ -328,6 +365,25 @@ export interface PluginFamilyDiagnostic {
328
365
  hint?: string
329
366
  }
330
367
 
368
+ /**
369
+ * One placed part and which engine built it, from `getParameters`. `"kernel"` —
370
+ * a curved sketch built exactly; `"mesh"` — straight-edged, or the kernel
371
+ * fallback.
372
+ */
373
+ export interface PluginFamilyPart {
374
+ name: string
375
+ engine: "kernel" | "mesh"
376
+ /**
377
+ * Kernel parts only: the part's exact solid, for `core.geom.query.brep.*` /
378
+ * `core.geom.query.face.getSurfaceKind`. READ-ONLY and PART-LOCAL — in the
379
+ * part's own frame, not where the component sits, so never pass it to a
380
+ * boolean or `design.create.massFromBrep` (a family changes only through
381
+ * `setParameters`). Valid until the next parameter change: re-read
382
+ * `getParameters` after `setParameters`.
383
+ */
384
+ brep?: BrepHandle
385
+ }
386
+
331
387
  /** What `prepare` reports. */
332
388
  export interface PluginFamilyPrepareResult {
333
389
  /** `false` means the spec was rejected — read `errors`, fix, re-prepare. */
@@ -429,6 +485,8 @@ export interface PluginFamilyInstanceParameters {
429
485
  values: Record<string, number | string>
430
486
  /** The sheet: what each key means, its bounds, and whether it moves geometry. */
431
487
  parameters: PluginFamilyParameter[]
488
+ /** The placed parts; kernel parts carry their exact `brep`. */
489
+ parts?: PluginFamilyPart[]
432
490
  /** Present when `getParameters` was asked for a `snapshot`. */
433
491
  snapshot?: PluginFamilySnapshot
434
492
  }
@@ -19,8 +19,8 @@ import {
19
19
  * {@linkcode PluginDesignQueryGeometryApi.getCenterline} mints a
20
20
  * {@linkcode CurveHandle} for a wall's core curve.
21
21
  * {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes} is the
22
- * handle-free exception: it returns the triangulated render meshes as plain
23
- * world-space arrays.
22
+ * handle-free exception: it returns `{ meshes }` — the triangulated render
23
+ * meshes as plain world-space arrays, wrapped in an object, never bare.
24
24
  *
25
25
  * Returned handles are session-ephemeral and go stale on undo/redo/re-topologize
26
26
  * — re-fetch a fresh one after edits.
@@ -34,10 +34,26 @@ export abstract class PluginDesignQueryGeometryApi {
34
34
  * scene entity, as a reusable {@linkcode BrepHandle} for the
35
35
  * `core.geom.query.brep.*` reads.
36
36
  *
37
+ * **Frame.** By default the brep comes back in the component's own LOCAL frame
38
+ * (its vertices are relative to the mesh origin, exactly as stored). This is
39
+ * the long-standing default, and existing callers rely on it. Pass
40
+ * `{ frame: "world" }` to get the same solid placed where it sits in the
41
+ * scene (world coordinates, like
42
+ * `getBottomContour` / `getTriangulatedMeshes` and every `design.query.measure`
43
+ * read). Use `"world"` whenever the handle will be COMBINED with other scene
44
+ * geometry or committed back beside its source: booleans between two scene
45
+ * masses, `brepFromFillet` / `brepFromShell` / `brepFromOffset` /
46
+ * `brepFromChamfer` on a scene mass followed by `massFromBrep`, or comparing
47
+ * its vertices with a bounding box. A world-frame handle from a parametrically
48
+ * live mass also carries that mass's recipe, so an operation result keeps an
49
+ * editable record.
50
+ *
37
51
  * @param component - The scene component to read
38
- * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry
52
+ * @param options - `frame`: `"local"` (default, mesh-local coordinates) or `"world"` (scene coordinates)
53
+ * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry — also `null` for a parametric family: read `design.family.getParameters({ component }).parts[].brep`
39
54
  *
40
55
  * @examplePrompt Get the 3D solid geometry of the selected wall
56
+ * @examplePrompt Round the top rim of this column and put it back where it is
41
57
  * @examplePrompt How many faces does this mass have?
42
58
  * @examplePrompt Inspect the mesh of this slab so I can look at its faces and edges
43
59
  * @examplePrompt Read the vertices of the selected column's geometry
@@ -48,10 +64,16 @@ export abstract class PluginDesignQueryGeometryApi {
48
64
  * if (brep) {
49
65
  * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
50
66
  * }
67
+ *
68
+ * // Operate on a scene mass and commit the result where the mass sits:
69
+ * const placed = await snaptrude.design.query.geometry.getBrep(mass, { frame: "world" })
70
+ * const rounded = await snaptrude.core.geom.create.brepFromFillet(placed, edges, 0.2)
71
+ * await snaptrude.design.create.massFromBrep(rounded, "Rounded")
51
72
  * ```
52
73
  */
53
74
  public abstract getBrep(
54
75
  component: ComponentHandle,
76
+ options?: PluginDesignQueryGeometryGetBrepOptions,
55
77
  ): PluginApiReturn<BrepHandle | null>
56
78
 
57
79
  /**
@@ -126,7 +148,8 @@ export abstract class PluginDesignQueryGeometryApi {
126
148
  * Get the **triangulated render meshes** of scene components as plain,
127
149
  * serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0,
128
150
  * x1, …]`) and triangle `indices` (three per triangle), one record per
129
- * requested component.
151
+ * requested component. The result is `{ meshes }`, not a bare array —
152
+ * destructure it before iterating.
130
153
  *
131
154
  * Unlike the other `geometry.*` reads this does NOT mint kernel handles — the
132
155
  * raw arrays cross the boundary directly, ready for export, custom analysis,
@@ -189,8 +212,16 @@ export abstract class PluginDesignQueryGeometryApi {
189
212
  * |---|---|---|
190
213
  * | `component` | {@linkcode ComponentHandle} | The scene component to read |
191
214
  */
215
+ /** Options for {@linkcode PluginDesignQueryGeometryApi.getBrep}: `frame` defaults to `"local"`. */
216
+ export type PluginDesignQueryGeometryGetBrepOptions = { frame?: "local" | "world" }
217
+ export const PluginDesignQueryGeometryGetBrepOptions: z.ZodType<
218
+ PluginDesignQueryGeometryGetBrepOptions,
219
+ PluginDesignQueryGeometryGetBrepOptions
220
+ > = z.object({ frame: z.enum(["local", "world"]).optional() })
221
+
192
222
  export const PluginDesignQueryGeometryGetBrepArgs = z.object({
193
223
  component: ComponentHandle,
224
+ options: PluginDesignQueryGeometryGetBrepOptions.optional(),
194
225
  })
195
226
 
196
227
  export type PluginDesignQueryGeometryGetBrepArgs = z.infer<
@@ -1,6 +1,7 @@
1
1
  import * as z from "zod"
2
2
  import { PluginApiReturn } from "../../../types"
3
3
  import { ComponentHandle, BBoxComponents } from "../../../handles"
4
+ import type { MassParametersRecord } from "../../../massParameters"
4
5
  import {
5
6
  PluginSpaceType,
6
7
  PluginMassType,
@@ -1040,6 +1041,55 @@ export abstract class PluginDesignQueryApi {
1040
1041
  staircase: ComponentHandle,
1041
1042
  ): PluginApiReturn<PluginStaircaseParams | null>
1042
1043
 
1044
+ /**
1045
+ * Read a mass's creation-parameter record — the recipe it was built from
1046
+ * (`kind` plus the values that constructor was called with). Present on
1047
+ * masses committed from a `core.geom.create` brep constructor that carries a
1048
+ * recipe: {@linkcode MassParametersRecord} covers the four primitives
1049
+ * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
1050
+ *
1051
+ * A fillet, chamfer, shell or offset of a recorded solid keeps the record
1052
+ * too: `kind` stays the base constructor and the operation is appended to the
1053
+ * record's `operations` list. Edit any of it with `design.update.parameters`.
1054
+ *
1055
+ * `null` for everything else — drawn masses, imported geometry, booleans,
1056
+ * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
1057
+ * source that carried no record — and for a mass whose record no longer
1058
+ * matches what is on
1059
+ * screen (a later free-form edit dropped the recipe, or the mass carries a
1060
+ * baked scale). `null` too when the recipe was not recordable: the record
1061
+ * schema has its own caps (a sweep path of at most 512 points, a loft of at
1062
+ * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
1063
+ * profile loop and 64 holes in one contour), and a mass built past one of
1064
+ * them — through a route that does not enforce the matching creator cap —
1065
+ * commits as ordinary geometry carrying no record. The `operations` cap is
1066
+ * the one an agent can walk into by accident: a 9th chained
1067
+ * fillet/chamfer/shell/offset drops the record silently, so the result
1068
+ * commits as ordinary geometry and reads back `null` here. A record is never
1069
+ * reported unless it is still the truth.
1070
+ *
1071
+ * Points and axes come back in **world** coordinates. Pure read — nothing is
1072
+ * created or modified.
1073
+ *
1074
+ * @param component - the mass's {@linkcode ComponentHandle}
1075
+ * @returns the {@linkcode MassParametersRecord}, or `null`
1076
+ *
1077
+ * @examplePrompt What radius is this sphere?
1078
+ * @examplePrompt Is this mass parametric?
1079
+ * @examplePrompt Read back the dome's creation parameters
1080
+ * @examplePrompt How tall was this cylinder made?
1081
+ *
1082
+ * # Example
1083
+ * ```ts
1084
+ * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
1085
+ * const params = await snaptrude.design.query.getParameters(mass)
1086
+ * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
1087
+ * ```
1088
+ */
1089
+ public abstract getParameters(
1090
+ component: ComponentHandle,
1091
+ ): PluginApiReturn<MassParametersRecord | null>
1092
+
1043
1093
  /**
1044
1094
  * Get the **union** axis-aligned bounding box enclosing a set of entities.
1045
1095
  *