@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,563 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  BrepHandle,
+  FaceHandle,
+  EdgeHandle,
+  VertexHandle,
+  HalfEdgeHandle,
+  Vec3Components,
+  BBoxComponents,
+} from "../../../../handles"
+
+/**
+ * BREP queries — read the topology and geometry of a boundary-representation mesh
+ * as plain values / child handles (all-handle model, §11). A {@linkcode BrepHandle}
+ * is a session-ephemeral resource handle obtained from `design.query.geometry.getBrep`;
+ * it goes stale on undo/redo/re-topologize.
+ *
+ * Enumerations mint fresh child topology handles ({@linkcode FaceHandle},
+ * {@linkcode EdgeHandle}, {@linkcode VertexHandle}, {@linkcode HalfEdgeHandle}); the
+ * registry dedupes by identity, so re-enumeration returns the same handles. Position
+ * reads return {@linkcode Vec3Components}. No query mutates its inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.brep`.
+ */
+export abstract class PluginGeomQueryBrepApi {
+  constructor() {}
+
+  /**
+   * List the faces of a brep.
+   * @param brep The brep to query
+   * @returns The faces as {@linkcode FaceHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   * }
+   * ```
+   */
+  public abstract listFaces(brep: BrepHandle): PluginApiReturn<FaceHandle[]>
+
+  /**
+   * List the edges of a brep.
+   * @param brep The brep to query
+   * @returns The edges as {@linkcode EdgeHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
+   * }
+   * ```
+   */
+  public abstract listEdges(brep: BrepHandle): PluginApiReturn<EdgeHandle[]>
+
+  /**
+   * List the vertices of a brep.
+   * @param brep The brep to query
+   * @returns The vertices as {@linkcode VertexHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const vertices = await snaptrude.core.geom.query.brep.listVertices(brep)
+   * }
+   * ```
+   */
+  public abstract listVertices(brep: BrepHandle): PluginApiReturn<VertexHandle[]>
+
+  /**
+   * List the half-edges of a brep.
+   * @param brep The brep to query
+   * @returns The half-edges as {@linkcode HalfEdgeHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const halfEdges = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   * }
+   * ```
+   */
+  public abstract listHalfEdges(brep: BrepHandle): PluginApiReturn<HalfEdgeHandle[]>
+
+  /**
+   * Get the edge connecting two vertices (by their brep vertex indices).
+   * @param brep The brep to query
+   * @param vertexIndexA First vertex index
+   * @param vertexIndexB Second vertex index
+   * @returns The edge as an {@linkcode EdgeHandle}, or `null` if no such edge exists
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [va, vb] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const ia = await snaptrude.core.geom.query.vertex.getIndex(va)
+   *   const ib = await snaptrude.core.geom.query.vertex.getIndex(vb)
+   *   const edge = await snaptrude.core.geom.query.brep.getEdge(brep, ia, ib)
+   *   if (edge) console.log("those two vertices are connected")
+   * }
+   * ```
+   */
+  public abstract getEdge(
+    brep: BrepHandle,
+    vertexIndexA: number,
+    vertexIndexB: number
+  ): PluginApiReturn<EdgeHandle | null>
+
+  /**
+   * Test whether an edge connects two vertices (by their brep vertex indices).
+   * @param brep The brep to query
+   * @param vertexIndexA First vertex index
+   * @param vertexIndexB Second vertex index
+   * @returns `true` if such an edge exists, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   // brep vertex indices (get one from core.geom.query.vertex.getIndex)
+   *   const connected = await snaptrude.core.geom.query.brep.hasEdge(brep, 0, 1)
+   * }
+   * ```
+   */
+  public abstract hasEdge(
+    brep: BrepHandle,
+    vertexIndexA: number,
+    vertexIndexB: number
+  ): PluginApiReturn<boolean>
+
+  /**
+   * List every edge connecting two vertices (by their brep vertex indices).
+   * @param brep The brep to query
+   * @param vertexIndexA First vertex index
+   * @param vertexIndexB Second vertex index
+   * @returns The edges as {@linkcode EdgeHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   // brep vertex indices (get one from core.geom.query.vertex.getIndex)
+   *   const edges = await snaptrude.core.geom.query.brep.listEdgesBetween(brep, 0, 1)
+   *   console.log("edges between vertices 0 and 1:", edges.length)
+   * }
+   * ```
+   */
+  public abstract listEdgesBetween(
+    brep: BrepHandle,
+    vertexIndexA: number,
+    vertexIndexB: number
+  ): PluginApiReturn<EdgeHandle[]>
+
+  /**
+   * Read the exact curve of a brep edge as plain values — a discriminated
+   * union on `type`. Pure read: no geometry kernel is loaded. Points and
+   * directions are {@linkcode Vec3Components}; lengths and radii are raw
+   * Babylon units.
+   *
+   * | `type` | Fields |
+   * |---|---|
+   * | `"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) |
+   *
+   * @param brep The brep the edge belongs to
+   * @param edge The edge whose curve to read
+   * @returns The curve data as a discriminated union on `type` (see table above)
+   * @throws VALIDATION if the edge is not on `brep`
+   *
+   * @examplePrompt Read the radius of this curved edge
+   * @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
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   for (const edge of edges) {
+   *     const curve = await snaptrude.core.geom.query.brep.getEdgeCurve(brep, edge)
+   *     if (curve.type === "arc") console.log("arc radius:", curve.radius)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getEdgeCurve(
+    brep: BrepHandle,
+    edge: EdgeHandle
+  ): PluginApiReturn<
+    | { type: "line"; startPoint: Vec3Components; endPoint: Vec3Components; length: number }
+    | {
+        type: "arc"
+        startPoint: Vec3Components
+        endPoint: Vec3Components
+        centre: Vec3Components
+        axis: Vec3Components
+        radius: number
+        length: number
+      }
+    | {
+        type: "circle"
+        centre: Vec3Components
+        axis: Vec3Components
+        radius: number
+        length: number
+      }
+  >
+
+  /**
+   * Get the position of a vertex within a brep.
+   * @param brep The brep to query
+   * @param vertex The vertex whose position to read
+   * @returns The position as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const { x, y, z } = await snaptrude.core.geom.query.brep.getVertexPosition(brep, vertex)
+   * }
+   * ```
+   */
+  public abstract getVertexPosition(
+    brep: BrepHandle,
+    vertex: VertexHandle
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * List the positions of all vertices in a brep (ordered as {@linkcode PluginGeomQueryBrepApi.listVertices}).
+   * @param brep The brep to query
+   * @returns The positions as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt Get the coordinates of every corner of this shape
+   * @examplePrompt Give me all the corner points of the selected mass as XYZ coordinates
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const positions = await snaptrude.core.geom.query.brep.listVertexPositions(brep)
+   *   for (const p of positions) console.log(p.x, p.y, p.z)
+   * }
+   * ```
+   */
+  public abstract listVertexPositions(brep: BrepHandle): PluginApiReturn<Vec3Components[]>
+
+  /**
+   * Get the centroid (mean of all vertex positions) of a brep.
+   * @param brep The brep to query
+   * @returns The centroid as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the centre point of this shape
+   * @examplePrompt What is the centroid of the selected object?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const centroid = await snaptrude.core.geom.query.brep.getCentroid(brep)
+   *   console.log(centroid.x, centroid.y, centroid.z)
+   * }
+   * ```
+   */
+  public abstract getCentroid(brep: BrepHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the number of faces in a brep.
+   * @param brep The brep to query
+   * @returns The face count as a `number`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep)
+   * }
+   * ```
+   */
+  public abstract getFaceCount(brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Get the number of edges in a brep.
+   * @param brep The brep to query
+   * @returns The edge count as a `number`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const edgeCount = await snaptrude.core.geom.query.brep.getEdgeCount(brep)
+   * }
+   * ```
+   */
+  public abstract getEdgeCount(brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Get the number of vertices in a brep.
+   * @param brep The brep to query
+   * @returns The vertex count as a `number`
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const vertexCount = await snaptrude.core.geom.query.brep.getVertexCount(brep)
+   * }
+   * ```
+   */
+  public abstract getVertexCount(brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Get the number of half-edges in a brep.
+   * @param brep The brep to query
+   * @returns The half-edge count as a `number`
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const halfEdgeCount = await snaptrude.core.geom.query.brep.getHalfEdgeCount(brep)
+   * }
+   * ```
+   */
+  public abstract getHalfEdgeCount(brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Get the axis-aligned bounding box of a brep.
+   * @param brep The brep to query
+   * @returns The bounding box as {@linkcode BBoxComponents}
+   *
+   * @examplePrompt What is the bounding box of this shape?
+   * @examplePrompt How big is this object overall — give me its min and max extents
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const { min, max } = await snaptrude.core.geom.query.brep.getBoundingBox(brep)
+   *   console.log("size:", max.x - min.x, max.y - min.y, max.z - min.z)
+   * }
+   * ```
+   */
+  public abstract getBoundingBox(brep: BrepHandle): PluginApiReturn<BBoxComponents>
+
+  /**
+   * Test whether two breps are geometrically equal.
+   * @param brepA First brep
+   * @param brepB Second brep
+   * @returns `true` if the breps are equal, otherwise `false`
+   *
+   * @examplePrompt Are these two shapes geometrically identical?
+   * @examplePrompt Check whether these two objects have the same geometry
+   *
+   * # Example
+   * ```ts
+   * const [a, b] = await snaptrude.design.query.listMasses()
+   * const brepA = await snaptrude.design.query.geometry.getBrep(a)
+   * const brepB = await snaptrude.design.query.geometry.getBrep(b)
+   * if (brepA && brepB) {
+   *   const same = await snaptrude.core.geom.query.brep.isEqual(brepA, brepB)
+   * }
+   * ```
+   */
+  public abstract isEqual(brepA: BrepHandle, brepB: BrepHandle): PluginApiReturn<boolean>
+
+  /**
+   * Measures the minimum distance between two solids, with the closest witness
+   * point on each. Touching or overlapping solids report a distance of 0 with
+   * contact points.
+   *
+   * @param brepA First solid
+   * @param brepB Second solid
+   * @returns `{ distance, pointA, pointB }` — the minimum distance and the
+   *   closest points on `brepA` and `brepB` as {@linkcode Vec3Components}
+   * @throws OPERATION_FAILED if the kernel cannot compute the distance
+   *
+   * @examplePrompt What is the clearance between these two masses?
+   * @examplePrompt How far apart are the tower and the neighbouring building?
+   * @examplePrompt Find the closest points between these two solids
+   *
+   * # Example
+   * ```ts
+   * const [a, b] = await snaptrude.design.query.listMasses()
+   * const brepA = await snaptrude.design.query.geometry.getBrep(a)
+   * const brepB = await snaptrude.design.query.geometry.getBrep(b)
+   * if (brepA && brepB) {
+   *   const { distance, pointA, pointB } = await snaptrude.core.geom.query.brep.getDistance(brepA, brepB)
+   *   console.log("clearance:", distance)
+   * }
+   * ```
+   */
+  public abstract getDistance(
+    brepA: BrepHandle,
+    brepB: BrepHandle
+  ): PluginApiReturn<{ distance: number; pointA: Vec3Components; pointB: Vec3Components }>
+}
+
+const brepArg = z.object({ brep: BrepHandle })
+const brepEdgeArg = z.object({
+  brep: BrepHandle,
+  vertexIndexA: z.number(),
+  vertexIndexB: z.number(),
+})
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.listFaces}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepListFacesArgs = brepArg
+export type PluginGeomQueryBrepListFacesArgs = z.infer<typeof PluginGeomQueryBrepListFacesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.listEdges}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepListEdgesArgs = brepArg
+export type PluginGeomQueryBrepListEdgesArgs = z.infer<typeof PluginGeomQueryBrepListEdgesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.listVertices}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepListVerticesArgs = brepArg
+export type PluginGeomQueryBrepListVerticesArgs = z.infer<typeof PluginGeomQueryBrepListVerticesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.listHalfEdges}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepListHalfEdgesArgs = brepArg
+export type PluginGeomQueryBrepListHalfEdgesArgs = z.infer<
+  typeof PluginGeomQueryBrepListHalfEdgesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getEdge}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The brep to query |
+ * | `vertexIndexA` | `number` | First vertex index |
+ * | `vertexIndexB` | `number` | Second vertex index |
+ */
+export const PluginGeomQueryBrepGetEdgeArgs = brepEdgeArg
+export type PluginGeomQueryBrepGetEdgeArgs = z.infer<typeof PluginGeomQueryBrepGetEdgeArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.hasEdge}. `{ brep, vertexIndexA, vertexIndexB }` */
+export const PluginGeomQueryBrepHasEdgeArgs = brepEdgeArg
+export type PluginGeomQueryBrepHasEdgeArgs = z.infer<typeof PluginGeomQueryBrepHasEdgeArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.listEdgesBetween}. `{ brep, vertexIndexA, vertexIndexB }` */
+export const PluginGeomQueryBrepListEdgesBetweenArgs = brepEdgeArg
+export type PluginGeomQueryBrepListEdgesBetweenArgs = z.infer<
+  typeof PluginGeomQueryBrepListEdgesBetweenArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getEdgeCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The brep the edge belongs to |
+ * | `edge` | {@linkcode EdgeHandle} | The edge whose curve to read |
+ */
+export const PluginGeomQueryBrepGetEdgeCurveArgs = z.object({
+  brep: BrepHandle,
+  edge: EdgeHandle,
+})
+export type PluginGeomQueryBrepGetEdgeCurveArgs = z.infer<
+  typeof PluginGeomQueryBrepGetEdgeCurveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getVertexPosition}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The brep to query |
+ * | `vertex` | {@linkcode VertexHandle} | The vertex whose position to read |
+ */
+export const PluginGeomQueryBrepGetVertexPositionArgs = z.object({
+  brep: BrepHandle,
+  vertex: VertexHandle,
+})
+export type PluginGeomQueryBrepGetVertexPositionArgs = z.infer<
+  typeof PluginGeomQueryBrepGetVertexPositionArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.listVertexPositions}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepListVertexPositionsArgs = brepArg
+export type PluginGeomQueryBrepListVertexPositionsArgs = z.infer<
+  typeof PluginGeomQueryBrepListVertexPositionsArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getCentroid}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetCentroidArgs = brepArg
+export type PluginGeomQueryBrepGetCentroidArgs = z.infer<typeof PluginGeomQueryBrepGetCentroidArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getFaceCount}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetFaceCountArgs = brepArg
+export type PluginGeomQueryBrepGetFaceCountArgs = z.infer<typeof PluginGeomQueryBrepGetFaceCountArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getEdgeCount}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetEdgeCountArgs = brepArg
+export type PluginGeomQueryBrepGetEdgeCountArgs = z.infer<typeof PluginGeomQueryBrepGetEdgeCountArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getVertexCount}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetVertexCountArgs = brepArg
+export type PluginGeomQueryBrepGetVertexCountArgs = z.infer<
+  typeof PluginGeomQueryBrepGetVertexCountArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getHalfEdgeCount}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetHalfEdgeCountArgs = brepArg
+export type PluginGeomQueryBrepGetHalfEdgeCountArgs = z.infer<
+  typeof PluginGeomQueryBrepGetHalfEdgeCountArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryBrepApi.getBoundingBox}. `{ brep: BrepHandle }` */
+export const PluginGeomQueryBrepGetBoundingBoxArgs = brepArg
+export type PluginGeomQueryBrepGetBoundingBoxArgs = z.infer<
+  typeof PluginGeomQueryBrepGetBoundingBoxArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.isEqual}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brepA` | {@linkcode BrepHandle} | First brep |
+ * | `brepB` | {@linkcode BrepHandle} | Second brep |
+ */
+export const PluginGeomQueryBrepIsEqualArgs = z.object({
+  brepA: BrepHandle,
+  brepB: BrepHandle,
+})
+export type PluginGeomQueryBrepIsEqualArgs = z.infer<typeof PluginGeomQueryBrepIsEqualArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getDistance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brepA` | {@linkcode BrepHandle} | First solid |
+ * | `brepB` | {@linkcode BrepHandle} | Second solid |
+ */
+export const PluginGeomQueryBrepGetDistanceArgs = z.object({
+  brepA: BrepHandle,
+  brepB: BrepHandle,
+})
+export type PluginGeomQueryBrepGetDistanceArgs = z.infer<typeof PluginGeomQueryBrepGetDistanceArgs>