@snaptrude/plugin-core 0.0.0-dev-20260911064951 → 0.0.0-surfaces-20260921090636

package/src/api/core/geom/query/brep.ts

@@ -174,6 +174,11 @@ export abstract class PluginGeomQueryBrepApi {
    * | `"line"` | `startPoint`, `endPoint`, `length` |
    * | `"arc"` | `startPoint`, `endPoint`, `centre`, `axis`, `radius`, `length` |
    * | `"circle"` | `centre`, `axis`, `radius`, `length` — a full-circle edge (e.g. a cylinder cap rim) |
+   * | `"spline"` | `startPoint`, `endPoint`, `degree`, `controlPoints`, `knots`, `length` — a free-form NURBS edge |
+   *
+   * For a `"spline"` edge, `knots` is the **expanded** knot vector — each knot
+   * repeated by its multiplicity, the textbook NURBS form — so
+   * `knots.length === controlPoints.length + degree + 1`.
    *
    * @param brep The brep the edge belongs to
    * @param edge The edge whose curve to read
@@ -184,6 +189,7 @@ export abstract class PluginGeomQueryBrepApi {
    * @examplePrompt Is this edge straight or an arc?
    * @examplePrompt Get the exact start and end points of this edge
    * @examplePrompt Measure the length of each edge of this mass
+   * @examplePrompt Read the control points of this curved edge
    *
    * # Example
    * ```ts
@@ -219,6 +225,16 @@ export abstract class PluginGeomQueryBrepApi {
         radius: number
         length: number
       }
+    | {
+        type: "spline"
+        startPoint: Vec3Components
+        endPoint: Vec3Components
+        degree: number
+        controlPoints: Vec3Components[]
+        /** Expanded by multiplicity: `controlPoints.length + degree + 1` entries. */
+        knots: number[]
+        length: number
+      }
   >
 
   /**
@@ -366,6 +382,37 @@ export abstract class PluginGeomQueryBrepApi {
    */
   public abstract getBoundingBox(brep: BrepHandle): PluginApiReturn<BBoxComponents>
 
+  /**
+   * Get the enclosed **volume** of a closed solid, integrated from its exact
+   * surfaces. Curved faces are measured analytically, not from their
+   * tessellation — a real sphere of radius 5 reports 523.6, whatever its
+   * triangle count. That makes this the reliable way to confirm a solid is the
+   * shape you intended (a torus should measure 2·π²·R·r²).
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param brep The solid to measure
+   * @returns The enclosed volume in cubic raw Babylon units
+   * @throws OPERATION_FAILED if the kernel cannot compute the volume (the brep
+   *   is not a closed solid)
+   *
+   * @examplePrompt What is the volume of this mass?
+   * @examplePrompt How much concrete is in this shape?
+   * @examplePrompt Check the volume of the dome I just made
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const volume = await snaptrude.core.geom.query.brep.getVolume(brep)
+   *   console.log("volume:", volume)
+   * }
+   * ```
+   */
+  public abstract getVolume(brep: BrepHandle): PluginApiReturn<number>
+
   /**
    * Test whether two breps are geometrically equal.
    * @param brepA First brep
@@ -534,6 +581,10 @@ export type PluginGeomQueryBrepGetBoundingBoxArgs = z.infer<
   typeof PluginGeomQueryBrepGetBoundingBoxArgs
 >
 
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getVolume}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetVolumeArgs = brepArg
+export type PluginGeomQueryBrepGetVolumeArgs = z.infer<typeof PluginGeomQueryBrepGetVolumeArgs>
+
 /**
  * Arguments for {@linkcode PluginGeomQueryBrepApi.isEqual}.
  *

package/src/api/core/geom/query/curve.ts

@@ -3,8 +3,8 @@ import { PluginApiReturn } from "../../../../types"
 import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../../handles"
 
 /**
- * Curve queries — read-only geometric questions about curves (lines and arcs)
- * and the relationships between two curves (all-handle model, §11).
+ * Curve queries — read-only geometric questions about curves (lines, arcs and
+ * splines) and the relationships between two curves (all-handle model, §11).
  *
  * Every method takes opaque curve handles ({@linkcode CurveHandle}/{@linkcode LineHandle})
  * and point handles ({@linkcode Vec3Handle}) and returns plain values — points as
@@ -13,6 +13,29 @@ import { Vec3Handle, CurveHandle, LineHandle, Vec3Components } from "../../../..
  * {@linkcode CurveHandle} (or `null` when there is no result). No query mutates its
  * inputs.
  *
+ * ## Splines
+ *
+ * A {@linkcode CurveHandle} is a line, an arc, or a NURBS spline (minted by
+ * `core.geom.create.splineFromPoints`). Every method here accepts a spline at
+ * compile time, but only the reads backed by the engine's spline math answer
+ * for one today. The rest throw `PRECONDITION_FAILED` ("not supported for
+ * splines yet") — a typed refusal, never a quietly wrong answer.
+ *
+ * | Splines | Members |
+ * |---|---|
+ * | **supported** | {@linkcode PluginGeomQueryCurveApi.getStartPoint}, {@linkcode PluginGeomQueryCurveApi.getEndPoint}, {@linkcode PluginGeomQueryCurveApi.getLength}, {@linkcode PluginGeomQueryCurveApi.getTangent}, {@linkcode PluginGeomQueryCurveApi.listPoints}, {@linkcode PluginGeomQueryCurveApi.getNearestPoint} |
+ * | **not yet** | `getMidPoint`, `getChordLength`, `getNormal`, `getProjection`, `getPointAtDistance`, `getParameterAtPoint`, `getCurvature`, `getDistanceToPoint`, `getDistanceAlong`, `listSubdivisions`, `isLinear`, `isOnCurve`, `hasPoint`, `isEqual`, `isOverlapping`, `getCommonPart`, `listIntersections`, `getMergedCurve`, `isContinuous`, `isParallel`, `getShortestGap`, `getDistanceBetween` |
+ *
+ * {@linkcode PluginGeomQueryCurveApi.isOverlapping} is deliberately in the
+ * second row: its line/arc path falls back to structural equality, which would
+ * answer a spline pair wrongly rather than not at all.
+ *
+ * To work around the second row, sample the curve —
+ * {@linkcode PluginGeomQueryCurveApi.listPoints} then the ordinary
+ * `core.math.vec3` operations — or read a spline brep edge exactly with
+ * `core.geom.query.brep.getEdgeCurve`, which returns its degree, control points
+ * and knots.
+ *
  * Accessed via `snaptrude.core.geom.query.curve`.
  */
 export abstract class PluginGeomQueryCurveApi {

package/src/api/core/geom/query/edge.ts

@@ -69,9 +69,9 @@ export abstract class PluginGeomQueryEdgeApi {
   public abstract listVertices(edge: EdgeHandle): PluginApiReturn<VertexHandle[]>
 
   /**
-   * Get the underlying curve geometry of an edge (a line or arc).
+   * Get the underlying curve geometry of an edge (a line, arc or spline).
    * @param edge The edge to query
-   * @returns The curve as a {@linkcode CurveHandle}, or `null` if it is a circle or unset
+   * @returns The curve as a {@linkcode CurveHandle} (`line_`, `arc_` or `spline_`), or `null` if it is a circle or unset
    *
    * # Example
    * ```ts

package/src/api/core/geom/query/face.ts

@@ -59,6 +59,49 @@ export abstract class PluginGeomQueryFaceApi {
    */
   public abstract getMaterialIndex(face: FaceHandle): PluginApiReturn<number>
 
+  /**
+   * Read what KIND of surface a face lies on. This is the one read that tells a
+   * genuinely curved face from a faceted approximation of one: every face of a
+   * 200-triangle "dome" answers `"plane"`, while a real dome has faces
+   * answering `"sphere"`. Use it to confirm a curved solid actually came out
+   * curved.
+   *
+   * | Value | Surface |
+   * |---|---|
+   * | `"plane"` | Flat face |
+   * | `"cylinder"` | Cylindrical face — constant radius about an axis |
+   * | `"cone"` | Conical face — a tapered ring (a cone or frustum side) |
+   * | `"sphere"` | Spherical face |
+   * | `"torus"` | Toroidal face — the ring surface of a donut |
+   * | `"spline"` | Free-form NURBS face |
+   *
+   * Pure read: no geometry kernel is loaded.
+   *
+   * @param face The face to query
+   * @returns The surface kind (see the table), or `null` when the face carries
+   *   no surface classification
+   *
+   * @examplePrompt Is this face flat or curved?
+   * @examplePrompt Check that this dome is a real sphere, not a faceted approximation
+   * @examplePrompt What kind of surface is this face?
+   * @examplePrompt How many curved faces does this mass have?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const kinds = []
+   *   for (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))
+   *   console.log("spherical faces:", kinds.filter((k) => k === "sphere").length)
+   * }
+   * ```
+   */
+  public abstract getSurfaceKind(
+    face: FaceHandle,
+  ): PluginApiReturn<"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null>
+
   /**
    * Get a seed half-edge of a face's outer loop.
    * @param face The face to query
@@ -257,6 +300,56 @@ export abstract class PluginGeomQueryFaceApi {
     brep: BrepHandle,
   ): PluginApiReturn<Vec3Components[]>
 
+  /**
+   * Exact surface area of one face of `brep`, in internal length units SQUARED —
+   * integrated off the face's own surface, not its facets, so a curved patch
+   * reads exactly rather than as its triangles. Needs the parent brep: a face
+   * handle cannot name its own solid.
+   * @param face The face to measure
+   * @param brep The parent brep (owner last, as in
+   *   {@linkcode PluginGeomQueryFaceApi.listVertexPositions})
+   * @returns The area as a `number`
+   * @throws VALIDATION if `face` is not a face of `brep`
+   * @throws OPERATION_FAILED if the kernel could not measure the face
+   *
+   * @examplePrompt How big is this roof patch?
+   * @examplePrompt Which face of this mass has the largest area?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const areas = await Promise.all(
+   *     faces.map((f) => snaptrude.core.geom.query.face.getArea(f, brep)),
+   *   )
+   * }
+   * ```
+   */
+  public abstract getArea(face: FaceHandle, brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Centre of area of one face of `brep`, as a point in that brep's frame
+   * (internal length units). On a solid whose every face reads `"spline"` this
+   * is the read that tells two patches apart — the top of a thickened patch from
+   * its bottom, one quarter of a closed surface from the next.
+   * @param face The face to measure
+   * @param brep The parent brep (owner last)
+   * @returns The centroid as {@linkcode Vec3Components}
+   * @throws VALIDATION if `face` is not a face of `brep`
+   * @throws OPERATION_FAILED if the kernel could not measure the face
+   *
+   * @examplePrompt Where is the middle of this face?
+   * @examplePrompt Pick the topmost face of this curved mass
+   *
+   * # Example
+   * ```ts
+   * const centre = await snaptrude.core.geom.query.face.getCentroid(face, brep)
+   * ```
+   */
+  public abstract getCentroid(face: FaceHandle, brep: BrepHandle): PluginApiReturn<Vec3Components>
+
   /**
    * List the tessellated boundary points of a face's outer loop (arcs sampled,
    * sense-corrected). Not cardinality-equal to {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
@@ -301,6 +394,7 @@ export abstract class PluginGeomQueryFaceApi {
 }
 
 const faceArg = z.object({ face: FaceHandle })
+const faceWithBrepArg = z.object({ face: FaceHandle, brep: BrepHandle })
 
 /** Arguments for {@linkcode PluginGeomQueryFaceApi.getIndex}. `{ face: FaceHandle }` */
 export const PluginGeomQueryFaceGetIndexArgs = faceArg
@@ -312,6 +406,12 @@ export type PluginGeomQueryFaceGetMaterialIndexArgs = z.infer<
   typeof PluginGeomQueryFaceGetMaterialIndexArgs
 >
 
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getSurfaceKind}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetSurfaceKindArgs = faceArg
+export type PluginGeomQueryFaceGetSurfaceKindArgs = z.infer<
+  typeof PluginGeomQueryFaceGetSurfaceKindArgs
+>
+
 /** Arguments for {@linkcode PluginGeomQueryFaceApi.getHalfEdge}. `{ face: FaceHandle }` */
 export const PluginGeomQueryFaceGetHalfEdgeArgs = faceArg
 export type PluginGeomQueryFaceGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryFaceGetHalfEdgeArgs>
@@ -382,14 +482,19 @@ export type PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.infer<
  * | `face` | {@linkcode FaceHandle} | The face to query |
  * | `brep` | {@linkcode BrepHandle} | The parent brep (source of vertex coordinates) |
  */
-export const PluginGeomQueryFaceListVertexPositionsArgs = z.object({
-  face: FaceHandle,
-  brep: BrepHandle,
-})
+export const PluginGeomQueryFaceListVertexPositionsArgs = faceWithBrepArg
 export type PluginGeomQueryFaceListVertexPositionsArgs = z.infer<
   typeof PluginGeomQueryFaceListVertexPositionsArgs
 >
 
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getArea}. `{ face: FaceHandle, brep: BrepHandle }` */
+export const PluginGeomQueryFaceGetAreaArgs = faceWithBrepArg
+export type PluginGeomQueryFaceGetAreaArgs = z.infer<typeof PluginGeomQueryFaceGetAreaArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getCentroid}. `{ face: FaceHandle, brep: BrepHandle }` */
+export const PluginGeomQueryFaceGetCentroidArgs = faceWithBrepArg
+export type PluginGeomQueryFaceGetCentroidArgs = z.infer<typeof PluginGeomQueryFaceGetCentroidArgs>
+
 /** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositionsWithCurves}. `{ face: FaceHandle }` */
 export const PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = faceArg
 export type PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = z.infer<

package/src/api/core/io/import/index.ts

@@ -183,10 +183,7 @@ export abstract class PluginCoreIoImportApi {
    * if (cad) console.log("DWG imported as CAD underlay:", cad)
    * ```
    */
-  public abstract dwg(
-    source: string,
-    storey?: number,
-  ): PluginApiReturn<ImportJobHandle>
+  public abstract dwg(source: string, storey?: number): PluginApiReturn<ImportJobHandle>
 
   /**
    * Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no
@@ -217,10 +214,7 @@ export abstract class PluginCoreIoImportApi {
    * )
    * ```
    */
-  public abstract cadJson(
-    cad: CadJsonInput,
-    storey?: number,
-  ): PluginApiReturn<UnderlayHandle>
+  public abstract cadJson(cad: CadJsonInput, storey?: number): PluginApiReturn<UnderlayHandle>
 
   /**
    * Import a **3D model** file and place it in the scene as a component.
@@ -245,9 +239,7 @@ export abstract class PluginCoreIoImportApi {
    * @returns the placed {@linkcode ComponentHandle}.
    * @throws if writes are disabled, the source can't be loaded, the format is
    *   unsupported, conversion/placement fails, or the converted model cannot be
-   *   found in the library after upload; `PRECONDITION_FAILED`
-   *   (`details.engineCode: "TOOL_ACTIVE"`) while the interactive furniture tool is
-   *   active — finish or cancel it first.
+   *   found in the library after upload.
    *
    * @examplePrompt Import this SketchUp model onto storey 1
    * @examplePrompt Bring in this OBJ file and place it at the origin