@snaptrude/plugin-core 0.9.16 → 0.9.18-voids-20261016.1

package/src/api/presentation/sections.ts

@@ -0,0 +1,420 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+import { Vec3Components } from "../../handles"
+
+/** A point on the plan: world `x` and `z` in babylon units. */
+export const PluginSectionPoint = z
+  .object({ x: z.number().finite(), z: z.number().finite() })
+  .strict()
+export type PluginSectionPoint = z.infer<typeof PluginSectionPoint>
+
+/**
+ * A section: a line drawn on the plan that cuts the model and looks one way
+ * along it.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sectionId` | `string` | The section's id |
+ * | `name` | `string` | Its name in the Views panel ("Section 1") |
+ * | `tagLabel` | `string` | What its heads are marked with on the plan ("A") |
+ * | `buildingId` | `string` | The building it belongs to |
+ * | `start` | {@linkcode PluginSectionPoint} | First head on the plan |
+ * | `end` | {@linkcode PluginSectionPoint} | Second head on the plan |
+ * | `isFlipped` | `boolean` | Looks the other way along the line |
+ * | `depth` | `number` | How far behind the line the view keeps, babylon units |
+ * | `base` | `number` | Bottom of the slice, world Y |
+ * | `top` | `number` | Top of the slice, world Y |
+ * | `isHidden` | `boolean` | The line is hidden on the plan |
+ * | `isLocked` | `boolean` | Geometry edits are refused |
+ * | `isActive` | `boolean` | It is the section view open now |
+ */
+export const PluginSection = z.object({
+  sectionId: z.string(),
+  name: z.string(),
+  tagLabel: z.string(),
+  buildingId: z.string(),
+  start: PluginSectionPoint,
+  end: PluginSectionPoint,
+  isFlipped: z.boolean(),
+  depth: z.number(),
+  base: z.number(),
+  top: z.number(),
+  isHidden: z.boolean(),
+  isLocked: z.boolean(),
+  isActive: z.boolean(),
+})
+export type PluginSection = z.infer<typeof PluginSection>
+
+export const PluginSectionIdArgs = z
+  .object({ sectionId: z.string().min(1) })
+  .strict()
+export type PluginSectionIdArgs = z.infer<typeof PluginSectionIdArgs>
+
+/**
+ * Options for {@linkcode PluginPresentationSectionsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Name in the Views panel (default: the next "Section N") |
+ * | `tagLabel` | `string \| undefined` | Head mark on the plan (default: the next free mark) |
+ * | `depth` | `number \| undefined` | How far behind the line the view keeps (default: to the far side of the model) |
+ * | `base` | `number \| undefined` | Bottom of the slice, world Y (default: the building's base) |
+ * | `top` | `number \| undefined` | Top of the slice, world Y (default: the building's top) |
+ * | `buildingId` | `string \| undefined` | Building it belongs to (default: the active one) |
+ * | `isActive` | `boolean \| undefined` | Open the section view once created (default `false`) |
+ */
+export const PluginSectionCreateOptions = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    tagLabel: z.string().trim().min(1).optional(),
+    depth: z.number().finite().positive().optional(),
+    base: z.number().finite().optional(),
+    top: z.number().finite().optional(),
+    buildingId: z.string().min(1).optional(),
+    isActive: z.boolean().optional(),
+  })
+  .strict()
+export type PluginSectionCreateOptions = z.infer<
+  typeof PluginSectionCreateOptions
+>
+
+export const PluginSectionCreateArgs = z
+  .object({
+    start: PluginSectionPoint,
+    end: PluginSectionPoint,
+    options: PluginSectionCreateOptions.optional(),
+  })
+  .strict()
+export type PluginSectionCreateArgs = z.infer<typeof PluginSectionCreateArgs>
+
+/**
+ * The fields to change in {@linkcode PluginPresentationSectionsApi.update};
+ * omitted fields keep their value.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Name in the Views panel |
+ * | `tagLabel` | `string \| undefined` | Head mark on the plan |
+ * | `start` | {@linkcode PluginSectionPoint} `\| undefined` | First head |
+ * | `end` | {@linkcode PluginSectionPoint} `\| undefined` | Second head |
+ * | `isFlipped` | `boolean \| undefined` | Look the other way; without `depth`, the depth re-spans the model the new way |
+ * | `depth` | `number \| undefined` | View depth behind the line, > 0 |
+ * | `base` | `number \| undefined` | Bottom of the slice, world Y |
+ * | `top` | `number \| undefined` | Top of the slice, world Y; above `base` |
+ * | `isHidden` | `boolean \| undefined` | Hide the line on the plan |
+ */
+export const PluginSectionPatch = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    tagLabel: z.string().trim().min(1).optional(),
+    start: PluginSectionPoint.optional(),
+    end: PluginSectionPoint.optional(),
+    isFlipped: z.boolean().optional(),
+    depth: z.number().finite().positive().optional(),
+    base: z.number().finite().optional(),
+    top: z.number().finite().optional(),
+    isHidden: z.boolean().optional(),
+  })
+  .strict()
+export type PluginSectionPatch = z.infer<typeof PluginSectionPatch>
+
+export const PluginSectionUpdateArgs = PluginSectionIdArgs.extend({
+  patch: PluginSectionPatch,
+})
+export type PluginSectionUpdateArgs = z.infer<typeof PluginSectionUpdateArgs>
+
+/**
+ * Options for {@linkcode PluginPresentationSectionsApi.getCut}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `maxSegmentsPerElement` | `number \| undefined` | Outline segments to return per element, 0 to 2000 (default 0: none) |
+ */
+export const PluginSectionCutOptions = z
+  .object({
+    maxSegmentsPerElement: z.number().int().min(0).max(2000).optional(),
+  })
+  .strict()
+export type PluginSectionCutOptions = z.infer<typeof PluginSectionCutOptions>
+
+export const PluginSectionCutArgs = PluginSectionIdArgs.extend({
+  options: PluginSectionCutOptions.optional(),
+})
+export type PluginSectionCutArgs = z.infer<typeof PluginSectionCutArgs>
+
+/**
+ * A rect on the cutting plane. `u` runs along the line from the first head
+ * (0) to the second (the line's length); `v` is world Y.
+ */
+export const PluginSectionExtent = z.object({
+  uMin: z.number(),
+  uMax: z.number(),
+  vMin: z.number(),
+  vMax: z.number(),
+})
+export type PluginSectionExtent = z.infer<typeof PluginSectionExtent>
+
+/**
+ * One element a section cuts.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `entityId` | `string` | The element's component id (a `ComponentHandle`) |
+ * | `type` | `string` | Its component type ("wall", "slab", "mass", …) |
+ * | `area` | `number` | Cut area inside the section's extents, square babylon units |
+ * | `perimeter` | `number` | Length of the cut outline inside the extents, babylon units |
+ * | `extent` | {@linkcode PluginSectionExtent} | Where the cut lies on the plane |
+ * | `isHatched` | `boolean` | `false` for masses and voids, which the drawing leaves unfilled |
+ * | `isOpening` | `boolean` | Doors and windows, which the drawing fills white |
+ * | `segments` | `[u0, v0, u1, v1][]` | Cut outline segments, when asked for |
+ * | `droppedSegmentCount` | `number` | Segments not returned because of `maxSegmentsPerElement` |
+ */
+export const PluginSectionCutElement = z.object({
+  entityId: z.string(),
+  type: z.string(),
+  area: z.number(),
+  perimeter: z.number(),
+  extent: PluginSectionExtent,
+  isHatched: z.boolean(),
+  isOpening: z.boolean(),
+  segments: z.array(z.tuple([z.number(), z.number(), z.number(), z.number()])),
+  droppedSegmentCount: z.number().int(),
+})
+export type PluginSectionCutElement = z.infer<typeof PluginSectionCutElement>
+
+/**
+ * What a section cuts, from {@linkcode PluginPresentationSectionsApi.getCut}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sectionId` | `string` | The section |
+ * | `origin` | `{ x, y, z }` | World point at `u = 0, v = 0`: the first head, at Y 0 |
+ * | `uAxis` | `{ x, y, z }` | Unit direction of `u`: from the first head to the second |
+ * | `normal` | `{ x, y, z }` | Unit direction the section looks |
+ * | `extent` | {@linkcode PluginSectionExtent} | The cut rect: `u` 0 to the line's length, `v` base to top |
+ * | `elements` | {@linkcode PluginSectionCutElement}`[]` | What it cuts, largest area first |
+ * | `candidateCount` | `number` | Meshes near the plane that were tested |
+ * | `durationInMs` | `number` | Time the query took |
+ */
+export const PluginSectionCut = z.object({
+  sectionId: z.string(),
+  origin: Vec3Components,
+  uAxis: Vec3Components,
+  normal: Vec3Components,
+  extent: PluginSectionExtent,
+  elements: z.array(PluginSectionCutElement),
+  candidateCount: z.number().int(),
+  durationInMs: z.number(),
+})
+export type PluginSectionCut = z.infer<typeof PluginSectionCut>
+
+/**
+ * Sections: lines on the plan that cut the model, each with its own section
+ * view.
+ *
+ * A section is a cutting plane through its line, vertical, looking one way
+ * along it; its view keeps `depth` behind the line, between `base` and `top`.
+ * Create, read, edit and delete sections (`create`, `list`, `get`, `update`,
+ * `delete`), open one's view (`setActive`, `getActive`), and ask what it cuts
+ * (`getCut`): which elements the plane passes through, with the area, outline
+ * and extent of each cut. `getCut` is computed from the model, needs no open
+ * view and changes nothing.
+ *
+ * Writes are write-gated and each call is one undo step. Geometry edits
+ * (`start`, `end`, `isFlipped`, `depth`, `base`, `top`) are refused on a locked
+ * section; names, marks and hiding are not, and repeating a locked section's
+ * geometry unchanged is not a geometry edit. View-only collaborators cannot
+ * write.
+ *
+ * Positions are world coordinates in internal `babylon` units (1 unit =
+ * 0.254 m, Y up); a section's heads are plan points `{ x, z }`. Accessed via
+ * `snaptrude.presentation.sections`.
+ */
+export abstract class PluginPresentationSectionsApi {
+  constructor() {}
+
+  /**
+   * List the project's sections, in Views panel order.
+   *
+   * @returns Every {@linkcode PluginSection} (`[]` when there are none).
+   *
+   * @examplePrompt Which sections are there?
+   * @examplePrompt List the section lines in this project
+   * @examplePrompt Is there a section through the stair?
+   *
+   * # Example
+   * ```ts
+   * const sections = await snaptrude.presentation.sections.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginSection[]>
+
+  /**
+   * Get one section by id.
+   *
+   * @param sectionId - The section's id
+   * @returns The {@linkcode PluginSection}, or `null` when there is none with that id.
+   *
+   * @examplePrompt Where does Section A run?
+   * @examplePrompt How deep is this section?
+   *
+   * # Example
+   * ```ts
+   * const section = await snaptrude.presentation.sections.get(sectionId)
+   * console.log(section?.start, section?.end)
+   * ```
+   */
+  public abstract get(sectionId: string): PluginApiReturn<PluginSection | null>
+
+  /**
+   * Get the section whose view is open.
+   *
+   * @returns The open {@linkcode PluginSection}, or `null` when no section view is open.
+   *
+   * @examplePrompt Which section am I looking at?
+   *
+   * # Example
+   * ```ts
+   * const open = await snaptrude.presentation.sections.getActive()
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginSection | null>
+
+  /**
+   * Open a section's view, or close the open one with `null`. Opening frames
+   * the section's saved camera, or a straight-on view when it has none.
+   * Closing returns to 3D; with no section view open, `null` does nothing. Not
+   * an edit: nothing is added to the undo history.
+   *
+   * @param sectionId - The section to open, or `null` to close the section view
+   * @returns The open {@linkcode PluginSection}, or `null` after closing.
+   * @throws HANDLE_INVALID when there is no section with that id.
+   *
+   * @examplePrompt Open Section A
+   * @examplePrompt Show me the section through the atrium
+   * @examplePrompt Close the section view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.sections.setActive(section.sectionId)
+   * await snaptrude.presentation.sections.setActive(null)
+   * ```
+   */
+  public abstract setActive(
+    sectionId: string | null,
+  ): PluginApiReturn<PluginSection | null>
+
+  /**
+   * Draw a section line from `start` to `end` on the plan. The section looks
+   * along the line's direction turned a quarter turn — a line drawn toward +x
+   * looks toward +z; flip it with `update(id, { isFlipped: true })`. Its slice
+   * defaults to the building's full height and its depth to the far side of
+   * the model. Write-gated; one undo step.
+   *
+   * @param start - First head, a plan point `{ x, z }`
+   * @param end - Second head; must differ from `start`
+   * @param options - Name, mark, depth, slice, building and whether to open it ({@linkcode PluginSectionCreateOptions})
+   * @returns The new {@linkcode PluginSection}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. VALIDATION when
+   *   `start` and `end` coincide or `top` is not above `base`. PRECONDITION_FAILED
+   *   when the project is view-only or has no model to cut.
+   *
+   * @examplePrompt Cut a section through the middle of the building, east to west
+   * @examplePrompt Add a section across the stair core
+   * @examplePrompt Draw a longitudinal section and open it
+   *
+   * # Example
+   * ```ts
+   * const section = await snaptrude.presentation.sections.create(
+   *   { x: -40, z: 10 },
+   *   { x: 40, z: 10 },
+   *   { name: "Longitudinal", isActive: true },
+   * )
+   * ```
+   */
+  public abstract create(
+    start: PluginSectionPoint,
+    end: PluginSectionPoint,
+    options?: PluginSectionCreateOptions,
+  ): PluginApiReturn<PluginSection>
+
+  /**
+   * Change a section. Only the given fields change; the whole patch is one
+   * undo step. Flipping without a `depth` carries the depth to the far side of
+   * the model in the new direction, as `create` does. Write-gated.
+   *
+   * @param sectionId - The section's id
+   * @param patch - The fields to change ({@linkcode PluginSectionPatch})
+   * @returns The updated {@linkcode PluginSection}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no section with that id. VALIDATION when the heads coincide or `top`
+   *   is not above `base`. PRECONDITION_FAILED when the project is view-only, or the
+   *   patch changes a locked section's geometry.
+   *
+   * @examplePrompt Make Section A look the other way
+   * @examplePrompt Only show the ground floor in this section
+   * @examplePrompt Rename the section to "Through atrium"
+   * @examplePrompt Move the section line 5 m north
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.sections.update(sectionId, {
+   *   isFlipped: true,
+   *   depth: 60,
+   * })
+   * ```
+   */
+  public abstract update(
+    sectionId: string,
+    patch: PluginSectionPatch,
+  ): PluginApiReturn<PluginSection>
+
+  /**
+   * Delete a section. Closes its view first if it is open. Write-gated; one
+   * undo step.
+   *
+   * @param sectionId - The section's id
+   * @returns `true` once it has been deleted.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no section with that id. PRECONDITION_FAILED when the project is view-only.
+   *
+   * @examplePrompt Delete Section B
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.sections.delete(sectionId)
+   * ```
+   */
+  public abstract delete(sectionId: string): PluginApiReturn<boolean>
+
+  /**
+   * What a section cuts: every element its cutting plane passes through within
+   * the section's extents, with the cut's area, outline length and extent on
+   * the plane, largest first. Computed from the model, not from the drawing, so
+   * it needs no open view and works however the section is shown; furniture is
+   * left out, as in the drawing, and so is anything hidden in the model. Areas are exact for closed solids. Repeated
+   * calls reuse the cuts of elements that have not changed. Read-only.
+   *
+   * @param sectionId - The section's id
+   * @param options - Whether to return outline segments ({@linkcode PluginSectionCutOptions})
+   * @returns The {@linkcode PluginSectionCut}.
+   * @throws HANDLE_INVALID when there is no section with that id.
+   *
+   * @examplePrompt Which walls does Section A cut?
+   * @examplePrompt How thick is the slab where the section crosses it?
+   * @examplePrompt Does this section go through the stair?
+   * @examplePrompt What is the floor-to-floor height in this section?
+   *
+   * # Example
+   * ```ts
+   * const cut = await snaptrude.presentation.sections.getCut(sectionId)
+   * const walls = cut.elements.filter((element) => element.type === "wall")
+   * const thickest = walls[0]
+   * console.log(thickest.extent.uMax - thickest.extent.uMin)
+   * ```
+   */
+  public abstract getCut(
+    sectionId: string,
+    options?: PluginSectionCutOptions,
+  ): PluginApiReturn<PluginSectionCut>
+}