@selvajs/visualization 1.0.0-beta.0

package/dist/render.d.cts

@@ -0,0 +1,430 @@
+import * as THREE from 'three';
+import { L as Look, a as LookPreset, M as MaterialAppearanceOptions } from './types-CdF9R3qA.cjs';
+export { b as LOOKS } from './types-CdF9R3qA.cjs';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+/**
+ * Errors for the visualization package. Replaces `@selvajs/compute`'s `RhinoComputeError`, which
+ * mis-named failures on paths (e.g. the plugin WebSocket) that never touch Rhino.Compute. `code`
+ * values match compute's so existing catch-sites keep working.
+ */
+declare const ErrorCodes: {
+    /** Structural check failed: bad magic bytes, out-of-window index, malformed metadata. */
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INVALID_STATE: "INVALID_STATE";
+    /** No `DecompressionStream`, no WebGL context, etc. */
+    readonly ENVIRONMENT_ERROR: "ENVIRONMENT_ERROR";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    /** Base64 input could not be decoded. */
+    readonly ENCODING_ERROR: "ENCODING_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+declare class VisualizationError extends Error {
+    readonly code: ErrorCode;
+    readonly context?: Record<string, unknown>;
+    readonly originalError?: Error;
+    constructor(message: string, code?: ErrorCode, options?: {
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+}
+
+/**
+ * Logging facility for the visualization package. Deliberately local rather than imported from
+ * `@selvajs/compute` (logging isn't a compute concern). Mirrors compute's logger shape so a host
+ * wanting one sink for both can call `setLogger(computeLogger.getLogger())`.
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+declare function getLogger(): Logger;
+declare function setLogger(logger: Logger | Console | null): void;
+declare function enableDebugLogging(): void;
+
+/** The look applied when the caller passes no `look` option. */
+declare const DEFAULT_LOOK: Look;
+/**
+ * Single source of truth for both `applyDefaults` (construction) and `setLook` (runtime), so the two
+ * can't drift.
+ *
+ * `ambientOcclusion: false` on every look: GTAO is a heavy full-screen pass, so it stays opt-in
+ * (`render.ambientOcclusion` or `setAmbientOcclusion(true)`) rather than costing every viewer 60fps.
+ */
+declare const LOOK_PRESETS: Record<Look, LookPreset>;
+/** Baked at parse time (not toggleable at runtime). */
+declare function materialAppearanceForLook(look: Look): MaterialAppearanceOptions;
+
+type CameraConfig = {
+    position?: THREE.Vector3;
+    fov?: number;
+    near?: number;
+    far?: number;
+    target?: THREE.Vector3;
+    /**
+     * Refit the near plane to the camera↔content gap every frame (default true) — recovers
+     * depth-buffer precision when zoomed out, preventing distant z-fighting. `near` is only ever
+     * raised, never lowered below the configured value.
+     */
+    dynamicNear?: boolean;
+};
+type LightingConfig = {
+    enableSunlight?: boolean;
+    sunlightIntensity?: number;
+    sunlightPosition?: THREE.Vector3;
+    ambientLightColor?: THREE.Color;
+    ambientLightIntensity?: number;
+    sunlightColor?: THREE.Color | number;
+    /**
+     * Direction-aware fill (sky color above, ground color below) so surfaces facing away from the
+     * sun don't collapse to black under a dark HDR. Default false — enabling it shifts the look.
+     */
+    enableHemisphereLight?: boolean;
+    /** Default white. */
+    hemisphereSkyColor?: THREE.Color | number;
+    /** Default a mid grey. */
+    hemisphereGroundColor?: THREE.Color | number;
+    /** Default 0.6. Only applies when {@link LightingConfig.enableHemisphereLight}. */
+    hemisphereIntensity?: number;
+};
+type EnvironmentConfig = {
+    hdrPath?: string;
+    backgroundColor?: THREE.Color | string;
+    enableEnvironmentLighting?: boolean;
+    /**
+     * Defaults to `(0, 0, 1)` — Rhino's Z-up, not Three's native Y-up — because geometry arrives in
+     * Rhino's frame and is never rotated on ingress. Everything orientation-dependent derives from
+     * this (view presets, default camera, sun, grid, floor, hemisphere light), but overriding it
+     * reorients the viewer only — it does NOT rotate incoming geometry.
+     */
+    sceneUp?: THREE.Vector3;
+    showEnvironment?: boolean;
+    /**
+     * Multiplier on the HDR's image-based lighting contribution — normalizes brightness across HDRs
+     * of differing exposure. Default 1 (unchanged look).
+     */
+    environmentIntensity?: number;
+};
+type FloorConfig = {
+    enabled?: boolean;
+    size?: number;
+    color?: THREE.Color | string;
+    roughness?: number;
+    metalness?: number;
+    receiveShadow?: boolean;
+};
+type RenderConfig = {
+    enableShadows?: boolean;
+    shadowMapSize?: number;
+    antialias?: boolean;
+    pixelRatio?: number;
+    toneMapping?: THREE.ToneMapping;
+    toneMappingExposure?: number;
+    preserveDrawingBuffer?: boolean;
+    /** Default false — switches rendering from `renderer.render` to an EffectComposer, which costs more. */
+    ambientOcclusion?: boolean;
+    /** AO strength 0–1 when {@link RenderConfig.ambientOcclusion} is on. Default 1. */
+    aoIntensity?: number;
+    /**
+     * DPR cap for AO buffers — AO is low-frequency, so sampling below display DPR is nearly invisible
+     * but much cheaper (a DPR-2 display would otherwise push 4× the pixels through GTAO's per-pixel
+     * sample loop). Default 1; only relevant when AO is enabled.
+     */
+    aoPixelRatio?: number;
+    /**
+     * Render only on change (camera motion, invalidate(), pointer input, resize) plus a ~500ms safety
+     * repaint, instead of every frame. Default true — cuts idle GPU/battery use. Set false to restore
+     * a continuous loop.
+     */
+    onDemand?: boolean;
+};
+
+/** Crisp boundary/crease edge overlays on meshes. See `addEdges`. */
+type EdgesConfig = {
+    /** Default false (opt-in). */
+    enabled?: boolean;
+    /** Omit (default) to derive each mesh's edge color from its own surface material, darkened by `darken`. */
+    color?: THREE.ColorRepresentation;
+    /** 0–1, default 0.75. Ignored when `color` is set. */
+    darken?: number;
+    /** CSS px. Default 1.5. */
+    width?: number;
+    /** Crease angle in degrees: keep edges where faces differ by more than this. Default 44. */
+    thresholdAngle?: number;
+    /** Fade an overlay out as its mesh shrinks on screen. Default true. */
+    distanceFade?: boolean;
+    /** Skip overlay extraction for meshes above this triangle count. Default 4M. */
+    maxTriangles?: number;
+    /** Overlays above this segment count render opaque (no distance fade). Default 2M. */
+    maxSegments?: number;
+    /** Meshes skipped for exceeding `maxTriangles` fall back to the screen-space edge-detection pass
+     * (constant cost regardless of triangle count). Default true. */
+    screenSpaceFallback?: boolean;
+};
+type ControlsConfig = {
+    enableDamping?: boolean;
+    dampingFactor?: number;
+    autoRotate?: boolean;
+    autoRotateSpeed?: number;
+    enableZoom?: boolean;
+    enablePan?: boolean;
+    minDistance?: number;
+    maxDistance?: number;
+};
+/** Infinite distance-fading reference grid. See `createGrid`. */
+type GridConfig = {
+    /** Default false (opt-in). */
+    enabled?: boolean;
+    /** World units (meters). Default 1. */
+    cellSize?: number;
+    /** Minor cells per major line. Default 10. */
+    majorEvery?: number;
+    cellColor?: THREE.ColorRepresentation;
+    majorColor?: THREE.ColorRepresentation;
+    /** World radius at which the grid fully fades. Default 100. */
+    fadeDistance?: number;
+    /**
+     * Axis the grid lies perpendicular to. Defaults to whichever axis `sceneUp` points along
+     * (`'z'` unless `sceneUp` is overridden); set explicitly to force an orientation that ignores it.
+     */
+    plane?: 'x' | 'y' | 'z';
+};
+/** Corner nav-cube/axis gizmo that snaps to preset views. See `createViewGizmo`. */
+type GizmoConfig = {
+    /** Default false (opt-in). */
+    enabled?: boolean;
+};
+/** Two-click distance measurement tool. See `createMeasureTool`. */
+type MeasureConfig = {
+    /** Default false. Only builds the tool; start measuring via `measureTool.setEnabled(true)` on the init result. */
+    enabled?: boolean;
+    /** Snap to a vertex within this many screen px. Default 12. */
+    snapPixels?: number;
+    /** Default yellow. */
+    color?: THREE.ColorRepresentation;
+    /** CSS class for the distance label. */
+    labelClassName?: string;
+    /** Scene is in meters; pass the response's `modelunits` to convert the label (e.g. "25.0 mm"). Default meters. Ignored if `format` is set. */
+    displayUnit?: string;
+    /** Receives the straight-line `distance` and per-axis `delta`. Default renders the total plus a Δx/Δy/Δz breakdown. */
+    format?: (distance: number, delta: THREE.Vector3) => string;
+};
+type ThreeInitializerOptions = {
+    sceneScale?: 'mm' | 'cm' | 'm' | 'inches' | 'feet';
+    /**
+     * Seeds lighting/material defaults (tone mapping, AO, IBL strength, hemisphere fill); explicit
+     * `lighting`/`environment`/`render` options still win. Does NOT touch edges/grid. Default
+     * 'technical'. Re-apply later via the init result's `setLook`.
+     */
+    look?: Look;
+    camera?: CameraConfig;
+    lighting?: LightingConfig;
+    environment?: EnvironmentConfig;
+    floor?: FloorConfig;
+    render?: RenderConfig;
+    controls?: ControlsConfig;
+    grid?: GridConfig;
+    gizmo?: GizmoConfig;
+    edges?: EdgesConfig;
+    measure?: MeasureConfig;
+    events?: EventConfig;
+    /**
+     * Called once at init with the GPU's max anisotropy. **Not needed for sharp textures** — the
+     * parse layer's texture cache subscribes to this value itself via a shared sink. This hook is
+     * only for hosts doing their own texture work on top.
+     */
+    onMaxAnisotropy?: (value: number) => void;
+};
+type EventConfig = {
+    onBackgroundClicked?: (event: {
+        x: number;
+        y: number;
+    }) => void;
+    onObjectSelected?: (object: THREE.Object3D) => void;
+    /** Receives the clicked mesh's `userData`; only fires for meshes with non-empty `userData`. */
+    onMeshMetadataClicked?: (metadata: Record<string, unknown>) => void;
+    onMeshDoubleClicked?: (object: THREE.Object3D) => void;
+    /** Default red (#ff0000). */
+    selectionColor?: THREE.Color | string;
+    /** Enable all event handlers (click/selection/metadata). Default true. */
+    enableEventHandlers?: boolean;
+    enableKeyboardControls?: boolean;
+    enableClickToFocus?: boolean;
+    /** Default true. */
+    enableDoubleClickZoom?: boolean;
+    onReady?: () => void;
+    /** Fires every animation frame, after controls update and before render. */
+    onFrame?: (delta: number) => void;
+};
+
+/**
+ * Runtime camera control: preset views, perspective⇄orthographic toggle, rotate lock.
+ *
+ * Centralized because projection switching swaps the camera object that OrbitControls drives, the
+ * render loop renders, resize reshapes, and the raycaster picks with — {@link getActiveCamera} is
+ * the one source of truth for all four call sites.
+ *
+ * Orthographic shadows perspective (same position/target, frustum derived from perspective FOV +
+ * distance) so switching doesn't visually jump.
+ */
+type ViewPreset = 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right' | 'iso';
+type CameraProjection = 'perspective' | 'orthographic';
+interface CameraController {
+    /** Swaps identity on {@link setProjection}. */
+    getActiveCamera(): THREE.Camera;
+    getProjection(): CameraProjection;
+    setProjection(projection: CameraProjection): void;
+    toggleProjection(): CameraProjection;
+    setView(preset: ViewPreset, animate?: boolean): void;
+    /**
+     * Frame current content from an explicit world-space direction (target → camera) instead of a
+     * named preset — used by the nav-cube, whose clicked axis is a world axis.
+     */
+    setViewDirection(direction: THREE.Vector3, animate?: boolean): void;
+    /** Frame a world-space box from the current view direction. No-op on an empty box. */
+    frameBounds(box: THREE.Box3, animate?: boolean): void;
+    setRotateEnabled(enabled: boolean): void;
+    isRotateEnabled(): boolean;
+    updateAspect(width: number, height: number): void;
+    /** Cancel any in-flight camera tween. Call on viewer teardown so ticks can't touch disposed controls. */
+    dispose(): void;
+}
+
+interface Grid {
+    /** Tagged `userData.id = 'grid'` so pick/fit code skips it. */
+    readonly object: THREE.Mesh;
+    /** Re-centers the fade on the camera so the grid feels infinite as you move. Call per frame. */
+    update(cameraPosition: THREE.Vector3): void;
+    /**
+     * Rescales cell spacing and fade radius to the content's extent, so a 3-unit or 3000-unit part
+     * both get sensible cells. No-op for empty/degenerate bounds.
+     */
+    fitToContent(bounds: THREE.Box3): void;
+    setVisible(visible: boolean): void;
+    dispose(): void;
+}
+
+/**
+ * Two-click distance measurement. Click a point, click a second, read the distance off a label on
+ * the connecting line; a third click starts fresh.
+ *
+ * Picking snaps to the nearest vertex of the struck triangle within {@link MeasureOptions.snapPixels}
+ * so measurements land exactly on vertices rather than wherever the ray happened to hit — a cheap
+ * local snap (three candidate vertices, no spatial index).
+ *
+ * Dormant until {@link MeasureTool.setEnabled}(true). While enabled it intercepts clicks (caller
+ * forwards them and swallows the event when {@link MeasureTool.handleClick} returns true) so
+ * measuring doesn't also select objects.
+ */
+interface MeasureTool {
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /** Returns true if the tool consumed the click (caller should not also select). */
+    handleClick(event: MouseEvent): boolean;
+    /** Preview the next snap point via a ghost marker. No-op when disabled; never consumes the event. */
+    handleMove(event: MouseEvent): void;
+    clear(): void;
+    dispose(): void;
+}
+
+/**
+ * Corner nav-cube/axis gizmo. Uses three's {@link ViewHelper} only as the rendered widget, NOT its
+ * click→animate behavior: ViewHelper's snap assumes Y-up and animates straight onto the up axis,
+ * which rolls the view and jitters the gizmo at the pole in our Z-up scene. Instead we hit-test the
+ * axis sprites ourselves and drive the viewer's up-aware camera controller, which snaps instantly
+ * with a pole nudge so the orbit basis never degenerates.
+ *
+ * A click frames the current orbit target (not the world origin), and flips the viewer back to
+ * perspective first if it's in orthographic mode (the cube is inherently a 3D-orientation tool).
+ *
+ * Caller contract (mirrors ViewHelper's own): call {@link ViewGizmo.render} *after* the main scene
+ * render each frame, and forward pointer clicks to {@link ViewGizmo.handleClick}.
+ */
+interface ViewGizmo {
+    render(renderer: THREE.WebGLRenderer): void;
+    /** Returns true if it hit the gizmo (and a view change started). */
+    handleClick(event: MouseEvent): boolean;
+    setVisible(visible: boolean): void;
+    isVisible(): boolean;
+    dispose(): void;
+}
+
+interface ThreeViewer {
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    controls: OrbitControls;
+    renderer: THREE.WebGLRenderer;
+    cameraController: CameraController;
+    grid: Grid | null;
+    gizmo: ViewGizmo | null;
+    /** Null unless `measure.enabled`; `setEnabled(true)` to use. */
+    measureTool: MeasureTool | null;
+    /**
+     * Attach edge overlays to meshes under `root` (no-op unless `edges.enabled`). Large-mesh
+     * extraction runs off-thread, so overlays may attach a beat later; meshes over
+     * `edges.maxTriangles` are skipped and (by default) covered by the screen-space edge fallback.
+     */
+    applyEdges: (root: THREE.Object3D) => void;
+    /**
+     * Prefer over calling `removeEdges` directly — also cancels in-flight async attaches and stands
+     * down the screen-space fallback if active.
+     */
+    clearEdges: (root: THREE.Object3D) => void;
+    /**
+     * Request a repaint from the on-demand render loop. Built-in setters and input invalidate
+     * automatically; call this after mutating the scene externally. No-op when `render.onDemand` is false.
+     */
+    invalidate: () => void;
+    setAmbientOcclusion: (enabled: boolean) => void;
+    /**
+     * Retunes lighting/material only (tone mapping, fill, IBL, AO) — never edges/grid. Overwrites
+     * any granular lighting dials set earlier.
+     */
+    setLook: (look: 'studio' | 'technical' | 'showcase') => void;
+    /**
+     * Raising `hemisphereIntensity` is the most effective way to lift shadowed/under-facing surfaces
+     * a dark HDR leaves black; a positive value lazily creates the hemisphere light if the viewer was
+     * built without one, `0` switches it off.
+     */
+    setFillLights: (opts: {
+        hemisphereIntensity?: number;
+        hemisphereSkyColor?: THREE.Color | number;
+        hemisphereGroundColor?: THREE.Color | number;
+        ambientIntensity?: number;
+    }) => void;
+    /**
+     * Normalizes IBL brightness across HDRs of differing exposure. Applies even before the HDR
+     * finishes decoding.
+     */
+    setEnvironmentIntensity: (intensity: number) => void;
+    setToneMappingExposure: (exposure: number) => void;
+    /** GTAO strength (0-1). No-op when ambient occlusion isn't active. */
+    setAoIntensity: (intensity: number) => void;
+    /** Feed into the batch parser's `material` option so freshly-loaded meshes match the active look. */
+    getMaterialAppearance: () => MaterialAppearanceOptions;
+    /** Call after loading or replacing geometry. No-op when sunlight/shadows are off. */
+    updateShadowBounds: () => void;
+    /** Call after loading or replacing geometry. No-op when the grid is off or empty. */
+    updateGridScale: () => void;
+    dispose: () => void;
+    fitToView: () => void;
+    clearSelection: () => void;
+    /**
+     * Tagged `userData.source = 'user'` so it survives `updateScene` solves instead of being cleared
+     * with compute content, and counts as normal content for fit-to-view framing.
+     */
+    addUserGeometry: (object: THREE.Object3D) => void;
+    removeUserGeometry: (object: THREE.Object3D) => void;
+    /** Removes and disposes everything added via `addUserGeometry`. */
+    clearUserGeometry: () => void;
+}
+
+declare const initThree: (canvas: HTMLCanvasElement, options?: ThreeInitializerOptions) => ThreeViewer;
+
+/** Replaces scene content with `meshes`, rescales the camera frustum to fit, and (first call only) positions the camera/controls. */
+declare function updateScene(scene: THREE.Scene, meshes: THREE.Object3D[], camera: THREE.PerspectiveCamera, controls: OrbitControls, initialPositionSet: boolean): void;
+
+export { type CameraConfig, type CameraController, type CameraProjection, type ControlsConfig, DEFAULT_LOOK, type EdgesConfig, type EnvironmentConfig, type ErrorCode, ErrorCodes, type EventConfig, type FloorConfig, type GizmoConfig, type Grid, type GridConfig, LOOK_PRESETS, type LightingConfig, type Logger, Look, LookPreset, MaterialAppearanceOptions, type MeasureConfig, type MeasureTool, type RenderConfig, type ThreeInitializerOptions, type ThreeViewer, type ViewGizmo, type ViewPreset, VisualizationError, enableDebugLogging, getLogger, initThree, materialAppearanceForLook, setLogger, updateScene };