@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.
- package/CHANGELOG.md +1 -1
- package/api-manifest.json +767 -31
- package/dist/api/core/geom/create/index.d.ts +924 -100
- package/dist/api/core/geom/create/index.d.ts.map +1 -1
- package/dist/api/core/geom/query/brep.d.ts +55 -1
- package/dist/api/core/geom/query/brep.d.ts.map +1 -1
- package/dist/api/core/geom/query/curve.d.ts +58 -35
- package/dist/api/core/geom/query/curve.d.ts.map +1 -1
- package/dist/api/core/geom/query/edge.d.ts +2 -2
- package/dist/api/core/geom/query/face.d.ts +105 -0
- package/dist/api/core/geom/query/face.d.ts.map +1 -1
- package/dist/api/core/geom/update/curve.d.ts +5 -5
- package/dist/api/core/geom/update/profile.d.ts +1 -1
- package/dist/api/design/create/grids.d.ts +2 -2
- package/dist/api/design/create/grids.d.ts.map +1 -1
- package/dist/api/design/family.d.ts +65 -8
- package/dist/api/design/family.d.ts.map +1 -1
- package/dist/api/design/query/geometry/index.d.ts +33 -5
- package/dist/api/design/query/geometry/index.d.ts.map +1 -1
- package/dist/api/design/query/grids.d.ts +4 -3
- package/dist/api/design/query/grids.d.ts.map +1 -1
- package/dist/api/design/query/index.d.ts +47 -0
- package/dist/api/design/query/index.d.ts.map +1 -1
- package/dist/api/design/query/spaces.d.ts +5 -5
- package/dist/api/design/update/index.d.ts +87 -0
- package/dist/api/design/update/index.d.ts.map +1 -1
- package/dist/api/entity/referenceLine.d.ts +2 -2
- package/dist/api/entity/referenceLine.d.ts.map +1 -1
- package/dist/api/entity/space.d.ts +5 -4
- package/dist/api/entity/space.d.ts.map +1 -1
- package/dist/api/entity/story.d.ts +4 -4
- package/dist/api/program/site.d.ts +4 -4
- package/dist/api/program/spreadsheet.d.ts +4 -4
- package/dist/handles.d.ts +12 -3
- package/dist/handles.d.ts.map +1 -1
- package/dist/index.cjs +3413 -2943
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3366 -2943
- package/dist/index.js.map +1 -1
- package/dist/massParameters.d.ts +287 -0
- package/dist/massParameters.d.ts.map +1 -0
- package/dist/massParameters.ops.d.ts +137 -0
- package/dist/massParameters.ops.d.ts.map +1 -0
- package/package.json +13 -13
- package/src/api/core/geom/create/index.ts +1019 -101
- package/src/api/core/geom/query/brep.ts +56 -1
- package/src/api/core/geom/query/curve.ts +25 -2
- package/src/api/core/geom/query/edge.ts +2 -2
- package/src/api/core/geom/query/face.ts +109 -4
- package/src/api/design/family.ts +66 -8
- package/src/api/design/query/geometry/index.ts +35 -4
- package/src/api/design/query/index.ts +50 -0
- package/src/api/design/update/index.ts +94 -0
- package/src/handles.ts +15 -3
- package/src/index.ts +2 -0
- package/src/massParameters.ops.ts +245 -0
- package/src/massParameters.ts +427 -0
- 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
|
|
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
|
|
7
|
-
* and the relationships between two curves
|
|
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
|
|
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 =
|
|
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<
|
package/src/api/design/family.ts
CHANGED
|
@@ -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
|
-
*
|
|
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.
|
|
72
|
-
* {@linkcode PluginDesignFamilyApi.
|
|
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
|
|
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
|
|
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
|
-
* @
|
|
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
|
*
|