@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/dist/api/analysis/heatmaps.d.ts

@@ -0,0 +1,658 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+import { ComponentHandle, Vec3Components } from "../../handles";
+/**
+ * Analysis heatmaps — render plugin-computed scalar data as a heatmap.
+ *
+ * Unlike the built-in studies ({@linkcode PluginAnalysisSunlightHoursApi},
+ * {@linkcode PluginAnalysisIlluminanceApi}) where the host computes the
+ * values, here the **plugin brings its own numbers** and the host renders
+ * them. Two render modes:
+ *
+ * - {@linkcode PluginAnalysisHeatmapsApi.renderSpaces} — one flat colour per
+ *   space, painted on the space's top face (occupancy, energy use, any
+ *   per-room metric).
+ * - {@linkcode PluginAnalysisHeatmapsApi.renderGrid} — a coloured grid mesh
+ *   from point samples in world coordinates (wind, noise, microclimate — any
+ *   field sampled over an area).
+ * - {@linkcode PluginAnalysisHeatmapsApi.renderField} — arbitrary planar
+ *   polygon cells (or pre-tessellated meshes), one scalar value each — for
+ *   non-square analysis meshes straight from a solver.
+ *
+ * Shared semantics:
+ *
+ * - **Named overlays** — every render call targets a named overlay
+ *   (`options.name`; a shared default overlay when omitted). Rendering an
+ *   existing name replaces that overlay only; the newly rendered overlay
+ *   becomes the visible one — **exactly one overlay is visible at a time**.
+ *   Up to 16 overlays can be registered; manage them (list / show / hide /
+ *   remove) via {@linkcode PluginAnalysisHeatmapsApi.overlays}.
+ * - **Legend** — the host renders a legend card from
+ *   {@linkcode PluginAnalysisHeatmapOptions} (title, unit, min/max, colour
+ *   segments). Values outside `[min, max]` **clamp to the end colours** and
+ *   the legend shows `<` / `>` markers at the clamped ends.
+ * - **Hover tooltip** — pass `options.hover: true` to any render call and,
+ *   while that overlay is visible, hovering a cell shows a tooltip with the
+ *   cell's `value` (and its `meta` payload, when the cell carries one).
+ * - **Ephemeral** — the heatmap is a transient overlay: never persisted,
+ *   never saved with views, and auto-cleared when a scene-mutating edit
+ *   invalidates it. Re-render after changing the model.
+ *
+ * Accessed via `snaptrude.analysis.heatmaps`.
+ */
+export declare abstract class PluginAnalysisHeatmapsApi {
+    /**
+     * Manage the named heatmap overlays created by the render calls —
+     * list / show / hide / remove. See
+     * {@linkcode PluginAnalysisHeatmapOverlaysApi}.
+     */
+    abstract overlays: PluginAnalysisHeatmapOverlaysApi;
+    constructor();
+    /**
+     * Render a per-space heatmap — one flat colour per space's top face.
+     *
+     * Each entry maps a space to a scalar value; the value is mapped through
+     * the colour ramp (see {@linkcode PluginAnalysisHeatmapOptions}) and the
+     * space's top face is painted that single flat colour. Renders into the
+     * overlay named `options.name` (the default overlay when omitted),
+     * replacing that overlay only and making it the visible one. Spaces whose top
+     * face is not flat (pitched/sloped tops) are **skipped with a console
+     * warning** — the rest of the heatmap still renders.
+     *
+     * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+     * and is never persisted or saved with views.
+     *
+     * @param entries - One {@linkcode PluginAnalysisHeatmapSpaceEntry} per
+     *   space: the space's handle and its scalar value.
+     * @param options - {@linkcode PluginAnalysisHeatmapOptions} — legend
+     *   title/unit, explicit min/max range (auto-derived from the data when
+     *   omitted), and the colour ramp.
+     * @returns A {@linkcode PluginAnalysisHeatmapsRenderResult} —
+     *   `{ success: true }` once the heatmap is rendered.
+     * @throws When `entries` is empty or a handle does not resolve to a space.
+     * @throws When no space had a flat top face to paint (every entry was
+     *   skipped).
+     * @throws When `options.min` is greater than `options.max`.
+     * @throws When a colour in `options.colors` is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Color each room by its occupancy count
+     * @examplePrompt Show my energy simulation results as a heatmap per space
+     * @examplePrompt Paint the rooms red to blue by temperature
+     *
+     * # Example
+     * ```ts
+     * const spaces = await snaptrude.design.query.listSpaces()
+     * await snaptrude.analysis.heatmaps.renderSpaces(
+     *   spaces.map((space) => ({ space, value: occupancy[space] ?? 0 })),
+     *   { title: "Occupancy", unit: "people", min: 0, max: 50 },
+     * )
+     * ```
+     */
+    abstract renderSpaces(entries: PluginAnalysisHeatmapSpaceEntry[], options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
+    /**
+     * Render a grid heatmap — a coloured mesh from point samples.
+     *
+     * Each cell is a scalar sample at a **world-coordinate** position
+     * (**y is up** — a ground-level field sits at `y = 0`); the host builds
+     * one square cell of edge `cellSize` per sample — in the same Snaptrude
+     * internal units as `position` (convert real-world lengths via
+     * {@linkcode PluginUnitsApi.convert}) — coloured by mapping the value
+     * through the colour ramp
+     * (see {@linkcode PluginAnalysisHeatmapOptions}). This is the mode for
+     * field data — wind, noise, microclimate — sampled over an area. Renders
+     * into the overlay named `options.name` (the default overlay when
+     * omitted), replacing that overlay only and making it the visible one.
+     *
+     * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+     * and is never persisted or saved with views.
+     *
+     * @param cells - One {@linkcode PluginAnalysisHeatmapGridCell} per
+     *   sample: a world-coordinate `position` (y up) and its scalar `value`.
+     * @param cellSize - Edge length of each (square) cell, in the same
+     *   Snaptrude internal units as `position` (see
+     *   {@linkcode PluginUnitsApi.convert}). Must be a positive, finite number.
+     * @param options - {@linkcode PluginAnalysisHeatmapOptions} — legend
+     *   title/unit, explicit min/max range (auto-derived from the data when
+     *   omitted), and the colour ramp.
+     * @returns A {@linkcode PluginAnalysisHeatmapsRenderResult} —
+     *   `{ success: true }` once the heatmap is rendered.
+     * @throws When `cells` is empty or `cellSize` is not a positive, finite number.
+     * @throws When `options.min` is greater than `options.max`.
+     * @throws When a colour in `options.colors` is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Overlay my CFD wind simulation results on the site
+     * @examplePrompt Render a noise-level grid around the building
+     * @examplePrompt Show these sampled microclimate values as a colored grid
+     *
+     * # Example
+     * ```ts
+     * // World coordinates are y-up: a ground-level field varies in x/z at y = 0.
+     * await snaptrude.analysis.heatmaps.renderGrid(
+     *   samples.map((s) => ({ position: { x: s.x, y: 0, z: s.z }, value: s.windSpeed })),
+     *   2, // 2-unit square cells
+     *   { title: "Wind speed", unit: "m/s", colors: ["#0000ff", "#00ff00", "#ff0000"] },
+     * )
+     * ```
+     */
+    abstract renderGrid(cells: PluginAnalysisHeatmapGridCell[], cellSize: number, options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
+    /**
+     * Render a grid heatmap on an **arbitrarily oriented plane** — a façade,
+     * a section cut, any flat surface.
+     *
+     * The same point-sample model as
+     * {@linkcode PluginAnalysisHeatmapsApi.renderGrid}, generalised: cells lie
+     * on the plane whose direction is given by `normal` (for a façade, the
+     * outward wall normal). Each cell is a square of edge `cellSize` centred
+     * on its **world-coordinate** `position` and oriented in that plane; the
+     * host derives the in-plane axes from the normal and offsets each cell a
+     * hair along it so the heatmap never z-fights the surface it annotates.
+     * Cell positions should lie on (or very near) the surface being
+     * annotated — the host does not project them. Renders into the overlay
+     * named `options.name` (the default overlay when omitted), replacing
+     * that overlay only and making it the visible one.
+     *
+     * This is the mode for per-façade data — solar irradiance, glare, panel
+     * yield, wind pressure — sampled over a vertical or sloped face. For
+     * horizontal ground fields prefer
+     * {@linkcode PluginAnalysisHeatmapsApi.renderGrid}, which is this call
+     * with `normal = { x: 0, y: 1, z: 0 }`.
+     *
+     * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+     * and is never persisted or saved with views.
+     *
+     * @param cells - One {@linkcode PluginAnalysisHeatmapGridCell} per
+     *   sample: a world-coordinate `position` on the surface plane (y up)
+     *   and its scalar `value`.
+     * @param cellSize - Edge length of each (square) cell, in the same
+     *   Snaptrude internal units as `position` (see
+     *   {@linkcode PluginUnitsApi.convert}). Must be a positive, finite number.
+     * @param normal - The plane's normal direction as `{ x, y, z }` (for a
+     *   façade, the outward wall normal — read it via
+     *   `core.geom.query.face.getNormal` on the wall's face). Any non-zero
+     *   length; the host normalises it.
+     * @param options - {@linkcode PluginAnalysisHeatmapOptions} — legend
+     *   title/unit, explicit min/max range (auto-derived from the data when
+     *   omitted), and the colour ramp.
+     * @returns A {@linkcode PluginAnalysisHeatmapsRenderResult} —
+     *   `{ success: true }` once the heatmap is rendered.
+     * @throws When `cells` is empty, `cellSize` is not a positive finite
+     *   number, or `normal` has zero length.
+     * @throws When `options.min` is greater than `options.max`.
+     * @throws When a colour in `options.colors` is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Paint the solar irradiance results on the south façade
+     * @examplePrompt Show my daylight values as a heatmap on this wall
+     * @examplePrompt Render panel-level PV yield on the building face
+     * @examplePrompt Overlay wind pressure on the tower's west elevation
+     *
+     * # Example
+     * ```ts
+     * // Samples lie on a wall plane facing +X; colour each 1-unit cell by irradiance.
+     * await snaptrude.analysis.heatmaps.renderSurfaceGrid(
+     *   samples.map((s) => ({ position: { x: wallX, y: s.y, z: s.z }, value: s.irradiance })),
+     *   1,
+     *   { x: 1, y: 0, z: 0 }, // façade normal
+     *   { title: "Irradiance", unit: "kWh/m²", colors: ["#0000ff", "#ffff00", "#ff0000"] },
+     * )
+     * ```
+     */
+    abstract renderSurfaceGrid(cells: PluginAnalysisHeatmapGridCell[], cellSize: number, normal: Vec3Components, options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
+    /**
+     * Render a heatmap from **arbitrary cell geometry** — planar polygons or
+     * pre-tessellated meshes, one scalar value each.
+     *
+     * The free-form sibling of the grid calls: instead of square cells, each
+     * {@linkcode PluginAnalysisHeatmapFieldCell} brings its own footprint in
+     * **world coordinates** (y up) — either a planar `polygon` ring (3+
+     * points, any orientation; the host triangulates it) or a pre-tessellated
+     * `vertices` + `indices` mesh (triangle list). This is the mode for
+     * analysis meshes straight from a solver: FEA/CFD cells, Voronoi regions,
+     * per-panel façade patches — anything not on a square grid. Each cell's
+     * `value` is mapped through the colour scale
+     * (see {@linkcode PluginAnalysisHeatmapOptions}, including
+     * `options.scale`); an optional `meta` payload is stored with the overlay
+     * for later features. Renders into the overlay named `options.name` (the
+     * default overlay when omitted), replacing that overlay only and making
+     * it the visible one.
+     *
+     * Degenerate polygon cells (collinear points, zero area) are **skipped
+     * with a console warning** — the rest of the heatmap still renders.
+     *
+     * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+     * and is never persisted or saved with views.
+     *
+     * @param cells - One {@linkcode PluginAnalysisHeatmapFieldCell} per cell:
+     *   a planar `polygon` ring OR a `vertices`/`indices` triangle mesh, plus
+     *   its scalar `value` and optional `meta`.
+     * @param options - {@linkcode PluginAnalysisHeatmapOptions} — legend
+     *   title/unit, min/max range, colour ramp, and the colour `scale`
+     *   (bands / threshold / categorical).
+     * @returns A {@linkcode PluginAnalysisHeatmapsRenderResult} —
+     *   `{ success: true }` once the heatmap is rendered.
+     * @throws When `cells` is empty, a polygon has fewer than 3 points, a
+     *   pre-tessellated cell's `indices` length is not a multiple of 3, or an
+     *   index is out of range of its `vertices`.
+     * @throws When every polygon cell was degenerate (nothing renderable).
+     * @throws When a `categorical` scale has no class for a cell's value.
+     * @throws When `options.min` is greater than `options.max`, or a colour
+     *   is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Overlay my FEA stress results on their solver mesh
+     * @examplePrompt Color these Voronoi regions by footfall
+     * @examplePrompt Paint each façade panel polygon by its PV yield
+     * @examplePrompt Render pass/fail daylight compliance per zone polygon
+     *
+     * # Example
+     * ```ts
+     * // Two triangular cells at ground level, coloured pass/fail at 300 lux.
+     * await snaptrude.analysis.heatmaps.renderField(
+     *   [
+     *     { polygon: [{ x: 0, y: 0, z: 0 }, { x: 4, y: 0, z: 0 }, { x: 0, y: 0, z: 4 }], value: 420 },
+     *     { polygon: [{ x: 4, y: 0, z: 4 }, { x: 0, y: 0, z: 4 }, { x: 4, y: 0, z: 0 }], value: 180 },
+     *   ],
+     *   { title: "Daylight", unit: "lux", scale: { type: "threshold", threshold: 300 } },
+     * )
+     * ```
+     */
+    abstract renderField(cells: PluginAnalysisHeatmapFieldCell[], options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
+    /**
+     * Clear every plugin heatmap overlay from the scene.
+     *
+     * Removes **all** registered overlays (equivalent to
+     * {@linkcode PluginAnalysisHeatmapOverlaysApi.removeAll}) and closes the
+     * legend. A no-op (returns `false`) when no plugin heatmap exists. Does
+     * not touch the built-in study heatmaps (`sunlightHours` /
+     * `illuminance`) — they have their own `reset`.
+     *
+     * @returns `true` when at least one overlay was cleared, `false` when
+     *   none existed.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Clear my custom heatmap
+     * @examplePrompt Remove the wind overlay from the model
+     * @examplePrompt Reset the plugin heatmap view
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.reset()
+     * ```
+     */
+    abstract reset(): PluginApiReturn<boolean>;
+    /**
+     * Is a plugin heatmap currently showing?
+     *
+     * `true` between a successful render and the next
+     * {@linkcode PluginAnalysisHeatmapsApi.reset} — or the scene-mutating
+     * edit that auto-clears it (heatmaps are ephemeral).
+     *
+     * @returns `true` when a plugin heatmap is rendered on the scene.
+     *
+     * @examplePrompt Is my heatmap still showing?
+     * @examplePrompt Check whether the custom heatmap is active
+     * @examplePrompt Do I need to re-render the wind overlay?
+     *
+     * # Example
+     * ```ts
+     * if (!(await snaptrude.analysis.heatmaps.isActive())) {
+     *   await snaptrude.analysis.heatmaps.renderGrid(cells, 2)
+     * }
+     * ```
+     */
+    abstract isActive(): PluginApiReturn<boolean>;
+}
+/**
+ * Heatmap overlay management — the named overlays created by the
+ * `analysis.heatmaps` render calls.
+ *
+ * Every render call registers (or replaces) an overlay under
+ * `options.name` — a shared default overlay when omitted. Overlays are
+ * in-session only: never persisted, never saved with views, and **all**
+ * of them are cleared together when a scene-mutating edit invalidates
+ * them. At most 16 overlays can be registered at once, and **exactly one
+ * overlay is visible at a time** — showing one hides the others, and the
+ * legend always describes the visible overlay.
+ *
+ * Accessed via `snaptrude.analysis.heatmaps.overlays`.
+ */
+export declare abstract class PluginAnalysisHeatmapOverlaysApi {
+    constructor();
+    /**
+     * List the registered heatmap overlays.
+     *
+     * Returns every overlay's `name`, `kind` (which render call produced
+     * it: `"spaces"`, `"grid"`, `"surfaceGrid"` or `"field"`) and whether it is the
+     * currently visible one. At most one overlay has `visible: true`.
+     *
+     * @returns A {@linkcode PluginAnalysisHeatmapOverlaysListResult} —
+     *   `{ overlays: [{ name, visible, kind }] }`, empty when nothing is
+     *   registered.
+     *
+     * @examplePrompt Which heatmap overlays do I have?
+     * @examplePrompt List my rendered analysis overlays
+     * @examplePrompt Check which heatmap is currently visible
+     *
+     * # Example
+     * ```ts
+     * const { overlays } = await snaptrude.analysis.heatmaps.overlays.list()
+     * const visible = overlays.find((o) => o.visible)
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginAnalysisHeatmapOverlaysListResult>;
+    /**
+     * Make a registered overlay the visible one.
+     *
+     * Enables the named overlay's meshes, hides whichever overlay was
+     * visible before, and swaps the legend to the shown overlay's. A no-op
+     * returning `false` when no overlay of that name exists.
+     *
+     * @param name - The overlay's name (`options.name` at render time).
+     * @returns `true` when the overlay is now visible, `false` when no
+     *   overlay of that name exists.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Switch back to my wind heatmap
+     * @examplePrompt Show the occupancy overlay
+     * @examplePrompt Flip between my two analysis overlays
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.overlays.show("wind")
+     * ```
+     */
+    abstract show(name: string): PluginApiReturn<boolean>;
+    /**
+     * Hide an overlay without removing it.
+     *
+     * Disables the named overlay's meshes; when it was the visible one its
+     * legend closes too (nothing visible → no legend). The overlay stays
+     * registered and can be brought back with
+     * {@linkcode PluginAnalysisHeatmapOverlaysApi.show}. A no-op returning
+     * `false` when no overlay of that name exists.
+     *
+     * @param name - The overlay's name (`options.name` at render time).
+     * @returns `true` when the overlay exists (and is now hidden), `false`
+     *   when no overlay of that name exists.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Hide the wind overlay but keep it around
+     * @examplePrompt Temporarily hide my heatmap
+     * @examplePrompt Turn off the occupancy colours without deleting them
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.overlays.hide("wind")
+     * ```
+     */
+    abstract hide(name: string): PluginApiReturn<boolean>;
+    /**
+     * Remove an overlay — dispose its meshes and forget it.
+     *
+     * Frees the overlay's slot toward the 16-overlay cap; when it was the
+     * visible one its legend closes. A no-op returning `false` when no
+     * overlay of that name exists.
+     *
+     * @param name - The overlay's name (`options.name` at render time).
+     * @returns `true` when the overlay was removed, `false` when no overlay
+     *   of that name exists.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Delete the wind overlay
+     * @examplePrompt Remove my occupancy heatmap for good
+     * @examplePrompt Free up an overlay slot
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.overlays.remove("wind")
+     * ```
+     */
+    abstract remove(name: string): PluginApiReturn<boolean>;
+    /**
+     * Remove every registered overlay and close the legend.
+     *
+     * The bulk form of {@linkcode PluginAnalysisHeatmapOverlaysApi.remove};
+     * `analysis.heatmaps.reset()` is this call under its historical name.
+     *
+     * @returns The number of overlays removed (`0` when none existed).
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Clear all my heatmap overlays
+     * @examplePrompt Remove every analysis overlay from the scene
+     * @examplePrompt Start over with a clean set of overlays
+     *
+     * # Example
+     * ```ts
+     * const removed = await snaptrude.analysis.heatmaps.overlays.removeAll()
+     * ```
+     */
+    abstract removeAll(): PluginApiReturn<number>;
+}
+/**
+ * One space's entry in {@linkcode PluginAnalysisHeatmapsApi.renderSpaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | Handle of the space to colour |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ */
+export declare const PluginAnalysisHeatmapSpaceEntry: z.ZodObject<{
+    space: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    value: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapSpaceEntry = z.infer<typeof PluginAnalysisHeatmapSpaceEntry>;
+/**
+ * One grid sample in {@linkcode PluginAnalysisHeatmapsApi.renderGrid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `position` | `{ x, y, z }` | Cell centre in **world coordinates** (y is up) |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ * | `meta` | `unknown \| undefined` | Optional payload stored with the overlay — shown in the hover tooltip when `options.hover` is on |
+ */
+export declare const PluginAnalysisHeatmapGridCell: z.ZodObject<{
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    value: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapGridCell = z.infer<typeof PluginAnalysisHeatmapGridCell>;
+/**
+ * One cell in {@linkcode PluginAnalysisHeatmapsApi.renderField} — either a
+ * planar polygon ring the host triangulates, or a pre-tessellated triangle
+ * mesh. All coordinates are **world coordinates** (y up).
+ *
+ * Polygon form:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `polygon` | `{ x, y, z }[]` | Planar ring of 3+ points (any orientation; no self-intersections) |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ * | `meta` | `unknown \| undefined` | Optional payload stored with the overlay |
+ *
+ * Pre-tessellated form:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `vertices` | `{ x, y, z }[]` | Mesh vertices (3+) |
+ * | `indices` | `number[]` | Triangle list into `vertices` — length a multiple of 3, every index in range |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ * | `meta` | `unknown \| undefined` | Optional payload stored with the overlay |
+ */
+export declare const PluginAnalysisHeatmapFieldCell: z.ZodUnion<readonly [z.ZodObject<{
+    polygon: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>>;
+    value: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    vertices: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>>;
+    indices: z.ZodArray<z.ZodNumber>;
+    value: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>]>;
+export type PluginAnalysisHeatmapFieldCell = z.infer<typeof PluginAnalysisHeatmapFieldCell>;
+/**
+ * The colour scale for a heatmap render — how values become colours and how
+ * the legend reads. Three kinds (discriminated by `type`):
+ *
+ * - **`bands`** — the default: the colour ramp quantised into `count`
+ *   discrete bands (2–64, default 11). The rendered mesh and legend always
+ *   use discrete bands; "continuous" is simply a high `count`.
+ * - **`threshold`** — binary pass/fail at a cut-off `threshold`: values
+ *   `>= threshold` get `passColor`, the rest `failColor`; the legend shows
+ *   the two labelled swatches.
+ * - **`categorical`** — exact-match classes: every cell value must equal
+ *   one class's `value` (anything else is a validation error); the legend
+ *   shows one labelled swatch per class.
+ *
+ * | Kind | Property | Type | Description |
+ * |---|---|---|---|
+ * | `bands` | `count` | `number \| undefined` | Number of discrete bands, 2–64 (default 11) |
+ * | `threshold` | `threshold` | `number` | Values `>= threshold` pass |
+ * | `threshold` | `passColor` | `string \| undefined` | Hex colour for passing values (host default green) |
+ * | `threshold` | `failColor` | `string \| undefined` | Hex colour for failing values (host default red) |
+ * | `threshold` | `passLabel` | `string \| undefined` | Legend label for the pass swatch (default `≥ threshold`) |
+ * | `threshold` | `failLabel` | `string \| undefined` | Legend label for the fail swatch (default `< threshold`) |
+ * | `categorical` | `classes` | `{ value, label, color }[]` | Exact-match classes: scalar `value`, legend `label`, hex `color` |
+ */
+export declare const PluginAnalysisHeatmapScale: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"bands">;
+    count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"threshold">;
+    threshold: z.ZodNumber;
+    passColor: z.ZodOptional<z.ZodString>;
+    failColor: z.ZodOptional<z.ZodString>;
+    passLabel: z.ZodOptional<z.ZodString>;
+    failLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"categorical">;
+    classes: z.ZodArray<z.ZodObject<{
+        value: z.ZodNumber;
+        label: z.ZodString;
+        color: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+export type PluginAnalysisHeatmapScale = z.infer<typeof PluginAnalysisHeatmapScale>;
+/**
+ * Display options shared by both heatmap render modes.
+ *
+ * The colour ramp maps values to colours: `colors` is an **ordered list of
+ * hex colour stops, low → high** (e.g. `["#0000ff", "#ff0000"]`). When
+ * omitted, the host's default blue → cyan → green → yellow → red ramp is used. Values outside
+ * `[min, max]` clamp to the end colours; the legend marks the clamped ends
+ * with `<` / `>`. `min`/`max` are auto-derived from the data when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Overlay name to render into (see {@linkcode PluginAnalysisHeatmapOverlaysApi}); a shared default overlay when omitted |
+ * | `title` | `string \| undefined` | Legend title |
+ * | `unit` | `string \| undefined` | Unit label shown on the legend (e.g. `"m/s"`) |
+ * | `min` | `number \| undefined` | Value mapped to the first colour stop; data minimum when omitted |
+ * | `max` | `number \| undefined` | Value mapped to the last colour stop; data maximum when omitted |
+ * | `colors` | `string[] \| undefined` | Ordered 6-digit hex colour stops (e.g. `"#0000ff"`), low → high; host blue → cyan → green → yellow → red default |
+ * | `scale` | {@linkcode PluginAnalysisHeatmapScale}` \| undefined` | Colour scale: discrete `bands` (count 2–64, default 11), binary `threshold`, or exact-match `categorical` |
+ * | `hover` | `boolean \| undefined` | Show a tooltip with the hovered cell's `value` (+ its `meta`, when given) while this overlay is visible. Default `false` |
+ */
+export declare const PluginAnalysisHeatmapOptions: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    colors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scale: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"bands">;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"threshold">;
+        threshold: z.ZodNumber;
+        passColor: z.ZodOptional<z.ZodString>;
+        failColor: z.ZodOptional<z.ZodString>;
+        passLabel: z.ZodOptional<z.ZodString>;
+        failLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"categorical">;
+        classes: z.ZodArray<z.ZodObject<{
+            value: z.ZodNumber;
+            label: z.ZodString;
+            color: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], "type">>;
+    hover: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapOptions = z.infer<typeof PluginAnalysisHeatmapOptions>;
+/**
+ * Result of {@linkcode PluginAnalysisHeatmapsApi.renderSpaces} /
+ * {@linkcode PluginAnalysisHeatmapsApi.renderGrid} — render failures throw,
+ * so a returned value always carries `success: true`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `true` | The heatmap is rendered on the scene |
+ */
+export declare const PluginAnalysisHeatmapsRenderResult: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapsRenderResult = z.infer<typeof PluginAnalysisHeatmapsRenderResult>;
+/**
+ * One overlay row in {@linkcode PluginAnalysisHeatmapOverlaysApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The overlay's name (`options.name` at render time) |
+ * | `visible` | `boolean` | Whether this is the (single) visible overlay |
+ * | `kind` | `"spaces" \| "grid" \| "surfaceGrid" \| "field"` | Which render call produced it |
+ */
+export declare const PluginAnalysisHeatmapOverlayInfo: z.ZodObject<{
+    name: z.ZodString;
+    visible: z.ZodBoolean;
+    kind: z.ZodEnum<{
+        spaces: "spaces";
+        grid: "grid";
+        surfaceGrid: "surfaceGrid";
+        field: "field";
+    }>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapOverlayInfo = z.infer<typeof PluginAnalysisHeatmapOverlayInfo>;
+/**
+ * Result of {@linkcode PluginAnalysisHeatmapOverlaysApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `overlays` | {@linkcode PluginAnalysisHeatmapOverlayInfo}`[]` | Every registered overlay; at most one has `visible: true` |
+ */
+export declare const PluginAnalysisHeatmapOverlaysListResult: z.ZodObject<{
+    overlays: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        visible: z.ZodBoolean;
+        kind: z.ZodEnum<{
+            spaces: "spaces";
+            grid: "grid";
+            surfaceGrid: "surfaceGrid";
+            field: "field";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapOverlaysListResult = z.infer<typeof PluginAnalysisHeatmapOverlaysListResult>;
+//# sourceMappingURL=heatmaps.d.ts.map

package/dist/api/analysis/heatmaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmaps.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/heatmaps.ts"],"names":[],"mappings":"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"}