@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/design/query/geometry/index.ts

@@ -0,0 +1,288 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  ComponentHandle,
+  BrepHandle,
+  ContourHandle,
+  CurveHandle,
+} from "../../../../handles"
+
+/**
+ * `snaptrude.design.query.geometry` — read the geometry of scene BIM entities.
+ *
+ * This is the bridge from the BIM/scene layer (`design.*`, keyed by
+ * {@linkcode ComponentHandle}) into the geometry kernel (`core.geom.query.*`,
+ * keyed by value/topology handles). {@linkcode PluginDesignQueryGeometryApi.getBrep}
+ * mints a {@linkcode BrepHandle} for a component's boundary-representation mesh;
+ * {@linkcode PluginDesignQueryGeometryApi.getBottomContour} mints a
+ * {@linkcode ContourHandle} for its footprint outline;
+ * {@linkcode PluginDesignQueryGeometryApi.getCenterline} mints a
+ * {@linkcode CurveHandle} for a wall's core curve.
+ * {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes} is the
+ * handle-free exception: it returns the triangulated render meshes as plain
+ * world-space arrays.
+ *
+ * Returned handles are session-ephemeral and go stale on undo/redo/re-topologize
+ * — re-fetch a fresh one after edits.
+ */
+export abstract class PluginDesignQueryGeometryApi {
+  constructor() {}
+
+  /**
+   * Get the boundary representation (B-rep) of a scene component — the solid
+   * geometry (faces, edges, vertices) behind a wall, slab, room or any other
+   * scene entity, as a reusable {@linkcode BrepHandle} for the
+   * `core.geom.query.brep.*` reads.
+   *
+   * @param component - The scene component to read
+   * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry
+   *
+   * @examplePrompt Get the 3D solid geometry of the selected wall
+   * @examplePrompt How many faces does this mass have?
+   * @examplePrompt Inspect the mesh of this slab so I can look at its faces and edges
+   * @examplePrompt Read the vertices of the selected column's geometry
+   *
+   * @example
+   * ```ts
+   * const brep = await snaptrude.design.query.geometry.getBrep(component)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   * }
+   * ```
+   */
+  public abstract getBrep(
+    component: ComponentHandle,
+  ): PluginApiReturn<BrepHandle | null>
+
+  /**
+   * Get the **bottom-face contour** of a component — the footprint outline (outer
+   * profile + holes) of its lowest horizontal face, as a reusable
+   * {@linkcode ContourHandle}.
+   *
+   * Extracted from the component's B-rep; robust to inverted face normals. Read
+   * its geometry via `snaptrude.core.geom.query.contour.*`, or feed it back into
+   * `design.create.*` / `core.geom.*`.
+   *
+   * @param component - The scene component to read
+   * @returns the footprint {@linkcode ContourHandle}, or `null` if the component
+   *   has no extractable bottom face (e.g. it carries no B-rep)
+   *
+   * @examplePrompt Get the footprint of the selected mass
+   * @examplePrompt What is the plan outline of this building volume?
+   * @examplePrompt Trace the base profile of this wall
+   * @examplePrompt Find the ground-level outline of the slab, including any openings
+   * @examplePrompt Work out the footprint area of the selected component
+   *
+   * @example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const contour = await snaptrude.design.query.geometry.getBottomContour(wall)
+   * if (contour) {
+   *   const area = await snaptrude.core.geom.query.contour.getArea(contour)
+   * }
+   * ```
+   */
+  public abstract getBottomContour(
+    component: ComponentHandle,
+  ): PluginApiReturn<ContourHandle | null>
+
+  /**
+   * Get the **centerline** (core curve) of a wall — the single curve running
+   * down the middle of the wall, as a reusable {@linkcode CurveHandle}
+   * (a `Line` for a straight wall, an `Arc` for a curved wall).
+   *
+   * For a parametric wall this is its stored core curve; otherwise it is
+   * derived from the wall's B-rep bottom face. Read its geometry via
+   * `snaptrude.core.geom.query.curve.*`, or feed it into `design.create.*`.
+   *
+   * Only walls have a centerline. As with all `get*` reads it never throws:
+   * a non-wall component, or a wall with no derivable centerline, yields `null`.
+   *
+   * @param component - The scene component to read (only walls yield a centerline)
+   * @returns the centerline {@linkcode CurveHandle}, or `null` if the component
+   *   is not a wall or the wall has no derivable centerline (e.g. it carries no
+   *   B-rep or has an unsupported profile)
+   *
+   * @examplePrompt Get the centerline of the selected wall
+   * @examplePrompt How long is this wall along its centre line?
+   * @examplePrompt Find the axis running down the middle of this wall
+   * @examplePrompt Give me the core curve of that curved wall
+   * @examplePrompt Where does the wall's centreline start and end?
+   *
+   * @example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const length = await snaptrude.core.geom.query.curve.getLength(centerline)
+   * }
+   * ```
+   */
+  public abstract getCenterline(
+    component: ComponentHandle,
+  ): PluginApiReturn<CurveHandle | null>
+
+  /**
+   * Get the **triangulated render meshes** of scene components as plain,
+   * serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0,
+   * x1, …]`) and triangle `indices` (three per triangle), one record per
+   * requested component.
+   *
+   * Unlike the other `geometry.*` reads this does NOT mint kernel handles — the
+   * raw arrays cross the boundary directly, ready for export, custom analysis,
+   * or feeding an external renderer. Positions are **always world-space**
+   * (instance/transform baked in; there is no local-coordinates mode) in plan
+   * units — no conversion needed. Raw doubles, unrounded.
+   *
+   * With `includeMaterialIds: true` each record also carries `materialIds`: one
+   * entry **per triangle** (`indices.length / 3` entries), the material *name*
+   * painted on that triangle, or `null` for unpainted/default faces.
+   *
+   * With `includeFaceIndices: true` each record also carries `faceIds`: one
+   * entry **per triangle** (input order), the B-rep face index owning that
+   * triangle (same ids as {@linkcode getBrep} faces), or `null` where there is
+   * no provenance. Non-B-rep meshes (Revit imports, generic models, furniture)
+   * yield all-`null` rather than an error.
+   *
+   * A resolvable component with no readable mesh geometry yields
+   * `{ id, positions: [], indices: [] }` — nothing is silently omitted.
+   *
+   * The call is capped at **500 000 triangles total**; over the cap it throws a
+   * `VALIDATION` error whose message includes the actual total — split the
+   * component list into smaller batches and call again.
+   *
+   * @param components - The scene components to triangulate
+   * @param options - `includeMaterialIds` adds the per-triangle material names;
+   *   `includeFaceIndices` adds the per-triangle B-rep face indices
+   * @returns `{ meshes }` — one {@linkcode PluginTriangulatedMesh} per requested
+   *   component, in input order
+   * @throws `HANDLE_INVALID` if any component handle is gone/forged;
+   *   `VALIDATION` if the combined mesh exceeds 500 000 triangles
+   *
+   * @examplePrompt Export the selected masses as a triangle mesh
+   * @examplePrompt Get the raw vertices and triangles of this wall in world coordinates
+   * @examplePrompt Give me the triangulated geometry of every space with its materials
+   * @examplePrompt Compute the surface area of this roof from its triangles
+   *
+   * @example
+   * ```ts
+   * const spaces = await snaptrude.design.query.listSpaces()
+   * const { meshes } = await snaptrude.design.query.geometry.getTriangulatedMeshes(spaces, {
+   *   includeMaterialIds: true,
+   * })
+   * for (const mesh of meshes) {
+   *   const triangleCount = mesh.indices.length / 3
+   *   console.log(mesh.id, triangleCount, mesh.materialIds?.[0])
+   * }
+   * ```
+   */
+  public abstract getTriangulatedMeshes(
+    components: ComponentHandle[],
+    options?: PluginDesignQueryGeometryGetTriangulatedMeshesArgs["options"],
+  ): PluginApiReturn<PluginDesignQueryGeometryGetTriangulatedMeshesResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBrep}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+export const PluginDesignQueryGeometryGetBrepArgs = z.object({
+  component: ComponentHandle,
+})
+
+export type PluginDesignQueryGeometryGetBrepArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetBrepArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBottomContour}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+export const PluginDesignQueryGeometryGetBottomContourArgs = z.object({
+  component: ComponentHandle,
+})
+
+export type PluginDesignQueryGeometryGetBottomContourArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetBottomContourArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getCenterline}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+export const PluginDesignQueryGeometryGetCenterlineArgs = z.object({
+  component: ComponentHandle,
+})
+
+export type PluginDesignQueryGeometryGetCenterlineArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetCenterlineArgs
+>
+
+/**
+ * One component's triangulated world-space mesh, as plain serializable arrays
+ * (no handles).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The component's id (its {@linkcode ComponentHandle} token) |
+ * | `positions` | `number[]` | Flat world-space vertex coordinates `[x0, y0, z0, x1, …]`, plan units, raw doubles |
+ * | `indices` | `number[]` | Triangle vertex indices, three per triangle, into `positions / 3` |
+ * | `materialIds` | `(string \| null)[]` _(optional)_ | One entry per triangle: the painted material's name, `null` for unpainted/default faces. Present only when requested via `includeMaterialIds` |
+ * | `faceIds` | `(number \| null)[]` _(optional)_ | One entry per triangle: the B-rep face index owning it (same ids as {@linkcode PluginDesignQueryGeometryApi.getBrep} faces), `null` where there is no provenance (non-B-rep mesh). Present only when requested via `includeFaceIndices` |
+ */
+export const PluginTriangulatedMesh = z.object({
+  id: z.string(),
+  positions: z.array(z.number()),
+  indices: z.array(z.number()),
+  materialIds: z.array(z.string().nullable()).optional(),
+  faceIds: z.array(z.number().nullable()).optional(),
+})
+
+export type PluginTriangulatedMesh = z.infer<typeof PluginTriangulatedMesh>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The scene components to triangulate |
+ * | `options.includeMaterialIds` | `boolean` _(optional)_ | Also return the per-triangle material names |
+ * | `options.includeFaceIndices` | `boolean` _(optional)_ | Also return the per-triangle B-rep face indices |
+ */
+export const PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.object({
+  components: z.array(ComponentHandle),
+  options: z
+    .object({
+      includeMaterialIds: z.boolean().optional(),
+      includeFaceIndices: z.boolean().optional(),
+    })
+    .optional(),
+})
+
+export type PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetTriangulatedMeshesArgs
+>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `meshes` | {@linkcode PluginTriangulatedMesh}`[]` | One record per requested component, in input order |
+ */
+export const PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.object({
+  meshes: z.array(PluginTriangulatedMesh),
+})
+
+export type PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.infer<
+  typeof PluginDesignQueryGeometryGetTriangulatedMeshesResult
+>

package/src/api/design/query/grids.ts

@@ -0,0 +1,197 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { CurveHandle, BBoxComponents } from "../../../handles"
+import { PluginReferenceLineStyle } from "../create"
+
+// ---------------------------------------------------------------------------
+// Records
+// ---------------------------------------------------------------------------
+
+/**
+ * Visual properties of grid lines — the group's defaults and any per-line
+ * overrides share this shape (values mirror the engine's `GridLineProps`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginReferenceLineStyle} | Line style (`"SOLID"` \| `"DASHED"` \| `"DOT_DASH"`) |
+ * | `weight` | `number` | Line weight |
+ * | `color` | `string` | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean` | Whether the start-end tag bubble is shown |
+ * | `showEnd` | `boolean` | Whether the end-end tag bubble is shown |
+ */
+export const PluginGridLineProps = z.object({
+  style: PluginReferenceLineStyle,
+  weight: z.number(),
+  color: z.string(),
+  showStart: z.boolean(),
+  showEnd: z.boolean(),
+})
+export type PluginGridLineProps = z.infer<typeof PluginGridLineProps>
+
+/**
+ * One grid line within a wing.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The line's geometry in **world space** (a line or arc; read coordinates via `core.geom.curve`) |
+ * | `tag` | `string` | The line's grid tag (e.g. `"A"`, `"3"`) |
+ * | `visible` | `boolean` | Persisted per-line visibility |
+ * | `props` | {@linkcode PluginGridLineProps} | **Effective** visual properties (group defaults merged with this line's overrides) |
+ * | `overrides` | `Partial<`{@linkcode PluginGridLineProps}`>`? | This line's raw overrides, when any exist |
+ */
+export const PluginGridLineRecord = z.object({
+  curve: CurveHandle,
+  tag: z.string(),
+  visible: z.boolean(),
+  props: PluginGridLineProps,
+  overrides: PluginGridLineProps.partial().optional(),
+})
+export type PluginGridLineRecord = z.infer<typeof PluginGridLineRecord>
+
+/**
+ * One wing of a grid — a family of parallel lines sharing a local frame.
+ * `spacing` and `span` are measured along the wing's local axes in
+ * Snaptrude units; line addresses used by mutating APIs are
+ * `{ wing, line }` index pairs into these arrays.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacing` | `number` | Nominal spacing between adjacent lines (Snaptrude units) |
+ * | `tagStart` | `string` | First tag of the wing's deterministic tag sequence |
+ * | `span` | `{ min: number; max: number }`? | Explicit family length along the wing's line axis, when baked |
+ * | `lines` | {@linkcode PluginGridLineRecord}`[]` | The wing's lines, in wing order (index = the `line` address) |
+ */
+export const PluginGridWingRecord = z.object({
+  spacing: z.number(),
+  tagStart: z.string(),
+  span: z.object({ min: z.number(), max: z.number() }).optional(),
+  lines: z.array(PluginGridLineRecord),
+})
+export type PluginGridWingRecord = z.infer<typeof PluginGridWingRecord>
+
+/**
+ * Per-storey 2D-plan visibility of a grid.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `activeStorey` | `number` | The storey the grid belongs to |
+ * | `disabledOnStoreys` | `number[]` | Storeys on whose 2D plan the grid is hidden |
+ */
+export const PluginGridStoreyVisibility = z.object({
+  activeStorey: z.number(),
+  disabledOnStoreys: z.array(z.number()),
+})
+export type PluginGridStoreyVisibility = z.infer<typeof PluginGridStoreyVisibility>
+
+// ---------------------------------------------------------------------------
+// get — args & result
+// ---------------------------------------------------------------------------
+
+/**
+ * Property names readable via {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"angle"` | World rotation about +Y, in **degrees** |
+ * | `"props"` | Group-level default line properties |
+ * | `"storeyVisibility"` | Active storey + storeys where the grid is hidden in 2D |
+ * | `"wings"` | Full wing/line structure with world-space curve handles |
+ * | `"bounds"` | World-space axis-aligned bounding box of the grid geometry |
+ */
+export const PluginGridGetProperty = z.enum([
+  "angle",
+  "props",
+  "storeyVisibility",
+  "wings",
+  "bounds",
+])
+export type PluginGridGetProperty = z.infer<typeof PluginGridGetProperty>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `gridId` | `string` | The grid group ID to query |
+ * | `properties` | {@linkcode PluginGridGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginGridGetArgs = z.object({
+  gridId: z.string(),
+  properties: z.array(PluginGridGetProperty),
+})
+export type PluginGridGetArgs = z.infer<typeof PluginGridGetArgs>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGridsApi.get} — only the requested
+ * properties are present.
+ */
+export const PluginGridGetResult = z
+  .object({
+    angle: z.number(),
+    props: PluginGridLineProps,
+    storeyVisibility: PluginGridStoreyVisibility,
+    wings: z.array(PluginGridWingRecord),
+    bounds: BBoxComponents,
+  })
+  .partial()
+export type PluginGridGetResult = z.infer<typeof PluginGridGetResult>
+
+// ---------------------------------------------------------------------------
+// Abstract API
+// ---------------------------------------------------------------------------
+
+/**
+ * `design.query.grids.*` — structural-grid-specific reads.
+ *
+ * A **grid** (grid group) is a structural/documentation grid: one or more
+ * *wings* (families of parallel lines with a shared local frame), each holding
+ * tagged grid *lines* (straight lines, or a lone arc). Enumerate grids with
+ * `design.query.listGrids`; read an individual grid's structure here.
+ *
+ * Lines have no stable identity of their own — mutating APIs address them
+ * positionally as `{ wing, line }` index pairs into the `wings` arrays
+ * returned by {@linkcode get}. Structural edits (adding/removing lines,
+ * count changes) re-index lines; re-query after mutating.
+ *
+ * Accessed via `snaptrude.design.query.grids`.
+ */
+export abstract class PluginDesignQueryGridsApi {
+  constructor() {}
+
+  /**
+   * Get properties of a grid by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. `wings` is the heavy
+   * read (it registers a world-space {@linkcode CurveHandle} per line);
+   * request it only when the geometry is needed.
+   *
+   * Units: `angle` is in **degrees** (positive = CCW about +Y); `spacing`,
+   * `span`, `bounds`, and curve coordinates are in **Snaptrude units**,
+   * world space.
+   *
+   * @param gridId - The unique grid group ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginGridGetProperty}.
+   * @returns A partial {@linkcode PluginGridGetResult} containing only the
+   *   requested properties
+   * @throws If the grid does not exist
+   *
+   * @examplePrompt What is the spacing of this grid?
+   * @examplePrompt Read the grid line tags on this structural grid
+   * @examplePrompt Get the geometry of every line in this grid
+   * @examplePrompt Which storeys is this grid hidden on?
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * const { wings } = await snaptrude.design.query.grids.get(grid, ["wings"])
+   * // wings[0].lines[0].curve is an opaque CurveHandle in world space;
+   * // read its coordinates via `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    gridId: string,
+    properties: z.infer<typeof PluginGridGetProperty>[],
+  ): PluginApiReturn<PluginGridGetResult>
+}