@idetik/core 0.48.4 → 0.49.0

package/dist/index.d.ts

@@ -731,7 +731,7 @@ declare class Geometry extends Node {
     protected attributes_: GeometryAttribute[];
     protected vertexData_: Float32Array;
     protected indexData_: Uint32Array;
-    constructor(vertexData?: number[], indexData?: number[], primitive?: Primitive);
+    constructor(vertexData?: number[] | Float32Array, indexData?: number[] | Uint32Array, primitive?: Primitive);
     addAttribute(attr: GeometryAttribute): void;
     get vertexCount(): number;
     get stride(): number;
@@ -749,7 +749,7 @@ declare class WireframeGeometry extends Geometry {
     constructor(geometry: Geometry);
 }
 
-type Shader = "floatScalarImage" | "floatVolume" | "intLabelImage" | "intScalarImage" | "intVolume" | "labelImage" | "points" | "projectedLine" | "uintScalarImage" | "uintVolume" | "wireframe" | "meshDepth" | "pointsDepth" | "projectedLineDepth";
+type Shader = "floatScalarImage" | "floatVolume" | "intLabelImage" | "intScalarImage" | "intVolume" | "labelImage" | "mesh" | "points" | "projectedLine" | "uintScalarImage" | "uintVolume" | "wireframe" | "meshDepth" | "pointsDepth" | "projectedLineDepth";
 
 /**
  * A value convertible to {@link Color}.
@@ -919,6 +919,14 @@ declare abstract class RenderableObject extends Node {
      * changes.
      */
     get wireframeGeometry(): WireframeGeometry;
+    /**
+     * Releases GPU buffers for {@link geometry} and any cached
+     * {@link wireframeGeometry}. Layers call this when discarding a
+     * renderable. CPU geometry data remains available for reuse.
+     *
+     * @param dispose - The runtime callback that releases a geometry's GPU buffers.
+     */
+    disposeGeometry(dispose: (geometry: Geometry) => void): void;
     /** The assigned textures indexed by texture unit. */
     get textures(): Texture[];
     /**
@@ -1614,6 +1622,7 @@ declare abstract class Renderer {
     abstract get gpuTextureCount(): number;
     abstract uploadTexture(texture: Texture): void;
     abstract disposeTexture(texture: Texture): void;
+    abstract disposeGeometry(geometry: Geometry): void;
 }
 
 /** A snapshot of memory used by chunks, renderer textures, and the JS heap. */
@@ -1746,6 +1755,7 @@ type IdetikProps = {
 };
 type IdetikContext = {
     chunkManager: ChunkManager;
+    disposeGeometry: (geometry: Geometry) => void;
 };
 /**
  * The entry point of an Idetik application.
@@ -1883,6 +1893,55 @@ declare class Idetik {
     stop(): void;
 }
 
+/**
+ * Initialization properties for constructing a mesh source.
+ */
+type MeshSourceProps = {
+    /** The source URL passed to the mesh loader. */
+    url: string;
+};
+/**
+ * A source of static mesh geometry shared by one or more mesh layers.
+ *
+ * Geometry is loaded on the first call to {@link load} and retained by the
+ * source. Each layer's renderable references the same CPU arrays and uses
+ * separate GPU buffers. The loader currently returns placeholder box
+ * geometry without fetching the URL.
+ *
+ * ```ts
+ * const source = new MeshSource({
+ *   url: "https://example.com/mesh.glb",
+ * });
+ *
+ * const layer = new MeshLayer({
+ *   source,
+ *   color: Color.RED,
+ * });
+ * ```
+ *
+ * @group Data Loading
+ */
+declare class MeshSource {
+    /** The source URL passed to the mesh loader. */
+    readonly url: string;
+    private geometryPromise_?;
+    /**
+     * Creates a mesh source without loading its geometry.
+     *
+     * @param props - Initialization properties.
+     */
+    constructor({ url }: MeshSourceProps);
+    /**
+     * Returns the source's CPU geometry, loading it on the first call.
+     *
+     * Concurrent and subsequent calls share the same promise and geometry.
+     * A failed load clears the cached promise so a later call can retry.
+     *
+     * @returns A promise resolving to the geometry owned by this source.
+     */
+    load(): Promise<Geometry>;
+}
+
 /**The zarr.json attributes key*/
 declare const Image: z.ZodObject<{
     /**The versioned OME-Zarr Metadata namespace*/
@@ -2831,6 +2890,68 @@ declare class ImageLayer extends Layer implements ChannelsEnabled {
     private releaseAndRemoveChunks;
 }
 
+/**
+ * Initialization properties for constructing a mesh layer.
+ */
+type MeshLayerProps = {
+    /** The mesh source to load geometry from. */
+    source: MeshSource;
+    /** The mesh color. Alpha is ignored. Defaults to `Color.WHITE`. */
+    color?: ColorLike;
+    /** Ambient lighting contribution. Defaults to `0.25`. */
+    ambientStrength?: number;
+    /** Diffuse lighting contribution. Defaults to `0.75`. */
+    diffuseStrength?: number;
+};
+/**
+ * A layer that renders a static mesh with an opaque color and overhead lighting.
+ *
+ * Mesh layer loads its {@link MeshSource} when attached to a viewport and
+ * creates one {@link MeshRenderable}. The mesh writes scene depth so
+ * {@link VolumeLayer} can composite volume samples in front of its surface.
+ * Detaching the layer releases the renderable's GPU buffers while the
+ * source retains its CPU geometry for reuse.
+ *
+ * ```ts
+ * const source = new MeshSource({ url: "https://example.com/mesh.glb" });
+ *
+ * const layer = new MeshLayer({
+ *   source,
+ *   color: Color.RED,
+ *   ambientStrength: 0.25,
+ *   diffuseStrength: 0.75,
+ * });
+ *
+ * viewport.addLayer(layer);
+ * ```
+ *
+ * @see {@link MeshSource} for geometry loading and caching.
+ *
+ * @group Layers
+ */
+declare class MeshLayer extends Layer {
+    /** Identifies the layer type as `MeshLayer`. */
+    readonly type = "MeshLayer";
+    private readonly source_;
+    private readonly renderableProps_;
+    private version_;
+    /**
+     * Creates a mesh layer for the given source and appearance settings.
+     *
+     * @param props - Initialization properties.
+     */
+    constructor({ source, ...renderableProps }: MeshLayerProps);
+    /** @hidden */
+    protected attach(): void;
+    /** @hidden */
+    protected detach(context: IdetikContext): void;
+    /**
+     * Returns `false` because the mesh is static. Loading and readiness
+     * changes are handled when the layer is attached.
+     */
+    update(): boolean;
+}
+
 /**
  * Initialization properties for constructing a volume layer.
  */
@@ -3230,6 +3351,56 @@ declare class LabelLayer extends Layer {
     private releaseAndRemoveChunks;
 }
 
+/**
+ * Initialization properties for constructing a mesh renderable.
+ */
+type MeshRenderableProps = {
+    /** The mesh geometry with position and normal attributes. */
+    geometry: Geometry;
+    /** The mesh color. Alpha is ignored. Defaults to `Color.WHITE`. */
+    color?: ColorLike;
+    /** Ambient lighting contribution. Defaults to `0.25`. */
+    ambientStrength?: number;
+    /** Diffuse lighting contribution. Defaults to `0.75`. */
+    diffuseStrength?: number;
+};
+type UniformValues$1 = {
+    u_color: vec3;
+    u_ambientStrength: number;
+    u_diffuseStrength: number;
+};
+/**
+ * An opaque mesh shaded with ambient light and a fixed overhead light.
+ *
+ * Normals are transformed to world space for diffuse shading. The mesh
+ * also writes depth so it can occlude other layers. {@link MeshLayer}
+ * creates one instance after its source has loaded.
+ *
+ * Vertex and index arrays are kept by reference in a separate geometry
+ * object, allowing each renderable to use its own GPU buffers without
+ * copying the source's CPU data.
+ *
+ * @group Renderables
+ */
+declare class MeshRenderable extends RenderableObject {
+    /** The mesh color. Alpha is ignored. Defaults to `Color.WHITE`. */
+    color: Color;
+    /** Ambient lighting contribution. Defaults to `0.25`. */
+    ambientStrength: number;
+    /** Diffuse lighting contribution. Defaults to `0.75`. */
+    diffuseStrength: number;
+    /**
+     * Creates a mesh renderable for the given geometry and appearance settings.
+     *
+     * @param props - Initialization properties.
+     */
+    constructor({ geometry, color, ambientStrength, diffuseStrength, }: MeshRenderableProps);
+    /** Identifies the renderable type as `MeshRenderable`. */
+    get type(): string;
+    /** Returns the color and lighting strength uniforms for the mesh shader. */
+    getUniforms(): UniformValues$1;
+}
+
 /**
  * Initialization properties for constructing an image renderable.
  */
@@ -3680,5 +3851,5 @@ declare class OrbitControls implements CameraControls {
     private cutoffLowVelocity;
 }
 
-export { AxesLayer, Box2, Box3, Camera, Color, Frustum, Idetik, ImageLayer, ImageRenderable, LabelImageRenderable, LabelLayer, Layer, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, PointsRenderable, ProjectedLineRenderable, RenderableObject, Stats, TrsTransform, Viewport, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
-export type { AxesLayerProps, BlendMode, CameraControls, CameraType, ChannelProps, ChunkStats, ColorLike, FileSystemOmeZarrImageSourceProps, HttpOmeZarrImageSourceProps, IdetikProps, ImageLayerProps, ImageRenderableProps, ImageSourcePolicy, ImageSourcePolicyProps, LabelColorMap, LabelColorMapProps, LabelImageRenderableProps, LabelLayerProps, LayerProps, LayerState, MemoryStats, OrbitControlsProps, OrthographicCameraFrame, OrthographicCameraProps, Overlay, PanZoomControlsProps, PerspectiveCameraProps, PointPickingResult, PointProps, PriorityCategory, ProjectedLineRenderableProps, QueueStats, RuntimeStats, SliceCoordinates, SliceOrientation, SourceChunkStats, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportChunkStats, ViewportProps, VolumeLayerProps, VolumeRenderableProps };
+export { AxesLayer, Box2, Box3, Camera, Color, Frustum, Idetik, ImageLayer, ImageRenderable, LabelImageRenderable, LabelLayer, Layer, MeshLayer, MeshRenderable, MeshSource, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, PointsRenderable, ProjectedLineRenderable, RenderableObject, Stats, TrsTransform, Viewport, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
+export type { AxesLayerProps, BlendMode, CameraControls, CameraType, ChannelProps, ChunkStats, ColorLike, FileSystemOmeZarrImageSourceProps, HttpOmeZarrImageSourceProps, IdetikProps, ImageLayerProps, ImageRenderableProps, ImageSourcePolicy, ImageSourcePolicyProps, LabelColorMap, LabelColorMapProps, LabelImageRenderableProps, LabelLayerProps, LayerProps, LayerState, MemoryStats, MeshLayerProps, MeshRenderableProps, MeshSourceProps, OrbitControlsProps, OrthographicCameraFrame, OrthographicCameraProps, Overlay, PanZoomControlsProps, PerspectiveCameraProps, PointPickingResult, PointProps, PriorityCategory, ProjectedLineRenderableProps, QueueStats, RuntimeStats, SliceCoordinates, SliceOrientation, SourceChunkStats, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportChunkStats, ViewportProps, VolumeLayerProps, VolumeRenderableProps };