@snaptrude/plugin-core 0.3.0 → 0.6.0

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

@@ -0,0 +1,210 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { HalfEdgeHandle, VertexHandle, EdgeHandle, FaceHandle } from "../../../../handles"
+
+/**
+ * Half-edge queries — walk and read a single BREP half-edge (all-handle model, §11).
+ * A {@linkcode HalfEdgeHandle} is minted by walking from a brep/face/edge/vertex
+ * handle; it is session-ephemeral and goes stale on undo/redo/re-topologize.
+ *
+ * The kind token is all-lowercase `"halfedge"` (§6.1 — no camelCase namespaces).
+ * Traversals (`getNext`/`getPrev`/`getFlip`) return `null` on a boundary or a
+ * malformed chain rather than throwing (§6, reads never throw).
+ *
+ * Accessed via `snaptrude.core.geom.query.halfedge`.
+ */
+export abstract class PluginGeomQueryHalfEdgeApi {
+  constructor() {}
+
+  /**
+   * Get the next half-edge around the face loop.
+   * @param halfEdge The half-edge to walk from
+   * @returns The next half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a malformed chain
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const [he] = await snaptrude.core.geom.query.face.listHalfEdges(face)
+   *   const next = await snaptrude.core.geom.query.halfedge.getNext(he)
+   *   if (next) {
+   *     const vertex = await snaptrude.core.geom.query.halfedge.getVertex(next)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getNext(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the previous half-edge around the face loop.
+   * @param halfEdge The half-edge to walk from
+   * @returns The previous half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a malformed chain
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const prev = await snaptrude.core.geom.query.halfedge.getPrev(he)
+   *   if (prev) {
+   *     const edge = await snaptrude.core.geom.query.halfedge.getEdge(prev)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getPrev(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the flip (opposite) half-edge of the shared edge.
+   * @param halfEdge The half-edge to flip
+   * @returns The flip half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a boundary
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const flip = await snaptrude.core.geom.query.halfedge.getFlip(he)
+   *   if (flip) {
+   *     // cross the shared edge into the neighbouring face
+   *     const neighbourFace = await snaptrude.core.geom.query.halfedge.getFace(flip)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getFlip(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the tail vertex of a half-edge.
+   * @param halfEdge The half-edge to read
+   * @returns The vertex as a {@linkcode VertexHandle}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const vertex = await snaptrude.core.geom.query.halfedge.getVertex(he)
+   *   const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, vertex)
+   * }
+   * ```
+   */
+  public abstract getVertex(halfEdge: HalfEdgeHandle): PluginApiReturn<VertexHandle>
+
+  /**
+   * Get the edge of a half-edge.
+   * @param halfEdge The half-edge to read
+   * @returns The edge as an {@linkcode EdgeHandle}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const edge = await snaptrude.core.geom.query.halfedge.getEdge(he)
+   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
+   * }
+   * ```
+   */
+  public abstract getEdge(halfEdge: HalfEdgeHandle): PluginApiReturn<EdgeHandle>
+
+  /**
+   * Get the face of a half-edge.
+   * @param halfEdge The half-edge to read
+   * @returns The face as a {@linkcode FaceHandle}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const face = await snaptrude.core.geom.query.halfedge.getFace(he)
+   *   const index = await snaptrude.core.geom.query.face.getIndex(face)
+   * }
+   * ```
+   */
+  public abstract getFace(halfEdge: HalfEdgeHandle): PluginApiReturn<FaceHandle>
+
+  /**
+   * Test whether a half-edge lies on the brep boundary (has no flip).
+   * @param halfEdge The half-edge to test
+   * @returns `true` if on the boundary, otherwise `false`
+   *
+   * # 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)
+   *   let boundary = 0
+   *   for (const he of halfEdges) {
+   *     if (await snaptrude.core.geom.query.halfedge.isOnBoundary(he)) boundary++
+   *   }
+   *   console.log("boundary half-edges:", boundary)
+   * }
+   * ```
+   */
+  public abstract isOnBoundary(halfEdge: HalfEdgeHandle): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a half-edge is the forward (primary) half-edge of its edge —
+   * i.e. `edge.getHalfEdge() === thisHalfEdge`.
+   * @param halfEdge The half-edge to test
+   * @returns `true` if forward, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const forward = await snaptrude.core.geom.query.halfedge.isForward(he)
+   *   console.log(forward ? "primary half-edge" : "flip half-edge")
+   * }
+   * ```
+   */
+  public abstract isForward(halfEdge: HalfEdgeHandle): PluginApiReturn<boolean>
+}
+
+const heArg = z.object({ halfEdge: HalfEdgeHandle })
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getNext}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetNextArgs = heArg
+export type PluginGeomQueryHalfEdgeGetNextArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetNextArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getPrev}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetPrevArgs = heArg
+export type PluginGeomQueryHalfEdgeGetPrevArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetPrevArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getFlip}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetFlipArgs = heArg
+export type PluginGeomQueryHalfEdgeGetFlipArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetFlipArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getVertex}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetVertexArgs = heArg
+export type PluginGeomQueryHalfEdgeGetVertexArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetVertexArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getEdge}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetEdgeArgs = heArg
+export type PluginGeomQueryHalfEdgeGetEdgeArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetEdgeArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getFace}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetFaceArgs = heArg
+export type PluginGeomQueryHalfEdgeGetFaceArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetFaceArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.isOnBoundary}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeIsOnBoundaryArgs = heArg
+export type PluginGeomQueryHalfEdgeIsOnBoundaryArgs = z.infer<
+  typeof PluginGeomQueryHalfEdgeIsOnBoundaryArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.isForward}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeIsForwardArgs = heArg
+export type PluginGeomQueryHalfEdgeIsForwardArgs = z.infer<typeof PluginGeomQueryHalfEdgeIsForwardArgs>

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

@@ -0,0 +1,63 @@
+import { PluginGeomQueryCurveApi } from "./curve"
+import { PluginGeomQueryArcApi } from "./arc"
+import { PluginGeomQueryCircleApi } from "./circle"
+import { PluginGeomQueryProfileApi } from "./profile"
+import { PluginGeomQueryContourApi } from "./contour"
+import { PluginGeomQueryBrepApi } from "./brep"
+import { PluginGeomQueryFaceApi } from "./face"
+import { PluginGeomQueryEdgeApi } from "./edge"
+import { PluginGeomQueryHalfEdgeApi } from "./halfedge"
+import { PluginGeomQueryVertexApi } from "./vertex"
+
+/**
+ * Geometry-kernel query namespace — read geometry, topology, and relationships as
+ * plain values / child handles (all-handle model, §11). No query mutates its inputs.
+ *
+ * - {@linkcode PluginGeomQueryApi.curve} — shared line/arc queries + two-curve relationships
+ * - {@linkcode PluginGeomQueryApi.arc} — arc-specific reads
+ * - {@linkcode PluginGeomQueryApi.circle} — circle-specific reads
+ * - {@linkcode PluginGeomQueryApi.profile} — profile reads
+ * - {@linkcode PluginGeomQueryApi.contour} — contour reads (outer profile + holes)
+ * - {@linkcode PluginGeomQueryApi.brep} — BREP mesh topology + geometry
+ * - {@linkcode PluginGeomQueryApi.face} — BREP face reads
+ * - {@linkcode PluginGeomQueryApi.edge} — BREP edge reads
+ * - {@linkcode PluginGeomQueryApi.halfedge} — BREP half-edge walks
+ * - {@linkcode PluginGeomQueryApi.vertex} — BREP vertex reads
+ *
+ * Accessed via `snaptrude.core.geom.query`.
+ */
+export abstract class PluginGeomQueryApi {
+  /** Shared curve queries (line or arc) and relationships. See {@linkcode PluginGeomQueryCurveApi}. */
+  public abstract curve: PluginGeomQueryCurveApi
+  /** Arc-specific queries. See {@linkcode PluginGeomQueryArcApi}. */
+  public abstract arc: PluginGeomQueryArcApi
+  /** Circle-specific queries. See {@linkcode PluginGeomQueryCircleApi}. */
+  public abstract circle: PluginGeomQueryCircleApi
+  /** Profile queries. See {@linkcode PluginGeomQueryProfileApi}. */
+  public abstract profile: PluginGeomQueryProfileApi
+  /** Contour queries. See {@linkcode PluginGeomQueryContourApi}. */
+  public abstract contour: PluginGeomQueryContourApi
+  /** BREP mesh topology + geometry queries. See {@linkcode PluginGeomQueryBrepApi}. */
+  public abstract brep: PluginGeomQueryBrepApi
+  /** BREP face queries. See {@linkcode PluginGeomQueryFaceApi}. */
+  public abstract face: PluginGeomQueryFaceApi
+  /** BREP edge queries. See {@linkcode PluginGeomQueryEdgeApi}. */
+  public abstract edge: PluginGeomQueryEdgeApi
+  /** BREP half-edge walks. See {@linkcode PluginGeomQueryHalfEdgeApi}. */
+  public abstract halfedge: PluginGeomQueryHalfEdgeApi
+  /** BREP vertex queries. See {@linkcode PluginGeomQueryVertexApi}. */
+  public abstract vertex: PluginGeomQueryVertexApi
+
+  constructor() {}
+}
+
+export * from "./curve"
+export * from "./arc"
+export * from "./circle"
+export * from "./profile"
+export * from "./contour"
+export * from "./brep"
+export * from "./face"
+export * from "./edge"
+export * from "./halfedge"
+export * from "./vertex"