@idetik/core 0.36.0 → 0.36.2

package/README.md

@@ -1,149 +1,93 @@
-# Idetik
+<h1 align="center">Idetik</h1>
 
-A layer-based library for interactive visualization of large bioimaging data, with first-class support for OME-Zarr.
+<p align="center">Build interactive viewers for massive bioimaging data in the browser</p>
 
-## Project Status
-
-This project is under active development and not yet stable. We welcome bug reports and new ideas, but are not prepared to review or accept major contributions at this time.
-
-## Reporting Security Issues
-
-If you believe you have found a security issue, please responsibly disclose via the process in our [Security Policy](SECURITY.md).
-
-## Getting started (development)
-
-1. Install the development version of node.
-
-   If you use `nvm` to manage node versions, you can run:
-
-   `nvm use`
-
-   Otherwise, manually install the version of node specified in `.nvmrc`.
-
-2. Install the dependencies required by this project (from within this directory):
-
-   `npm install`
-
-   Re-run this command any time the dependencies listed in [package.json](package.json) change, such
-   as after checking out a different revision or pulling changes.
+<div align="center">
 
-3. To run a local server for development purposes (from the repo root):
+![ci-badge](https://github.com/chanzuckerberg/idetik/actions/workflows/lint-test-build.yml/badge.svg)
+[![npm-badge](https://img.shields.io/npm/v/%40idetik%2Fcore.svg)](https://www.npmjs.com/package/@idetik/core)
+[![docs-badge](https://img.shields.io/badge/docs-online-blue.svg)](https://chanzuckerberg.github.io/idetik/)
 
-   `npm run examples`
+</div>
 
-   This will start a server on <http://localhost:5173>. The examples under [examples/](examples/)
-   are for local development and testing only; they are not deployed.
+## Overview
 
-4. To run the unit test suite (headless Chrome using playwright), run:
+Idetik is a high-performance library for exploring multi-dimensional OME-Zarr datasets right in the browser. It is not a viewer but a framework for building viewers. Define viewports with your own cameras, controls, and layers, and point them at any local or remote store with no conversion step. Chunks are streamed based on what the camera needs at the current zoom and nothing more, with preconfigured policies for smooth temporal playback. When the built-in pieces aren't enough, subclass layers to render your own data, add custom input handlers, or plug in your own data loader.
 
-   `npm test` or `npm run test-with-coverage` to generate a coverage report.
+#### Documentation
 
-   By default, the test runner will watch for changes to the source files and re-run the tests
-   automatically, so you can leave it running while you work. To run the tests once and exit, use
-   `npm run test -- --run`.
+- Guide: https://chanzuckerberg.github.io/idetik/guide/getting-started
+- API reference: https://chanzuckerberg.github.io/idetik/api/
 
-5. To build the library for publishing:
+## Installation
 
-   `npm run build`
+Idetik is published to npm as [@idetik/core](https://www.npmjs.com/package/@idetik/core):
 
-   This bundles the library and emits type declarations to `dist/`. Use `npm run compile` to
-   type-check and emit declarations only (no bundle).
+```bash
+npm install @idetik/core
+```
 
-6. To build the examples as a static site (e.g. to verify the production build):
+## Minimal Example
 
-   `npm run build:examples`
+This example displays a single slice from [Zebrahub](https://zebrahub.sf.czbiohub.org/), a terabyte-scale light-sheet time-lapse of a developing zebrafish, hosted as OME-Zarr on a public server. Idetik fetches only the chunks the view needs so you can pan and zoom through the full-resolution image without downloading the dataset.
 
-   Output is written to `examples/dist/`.
+```typescript
+import {
+  Idetik,
+  ImageLayer,
+  OmeZarrImageSource,
+  OrthographicCamera,
+  PanZoomControls,
+} from '@idetik/core'
 
-7. To work on the documentation site:
+const url = 'https://public.czbiohub.org/royerlab/zebrahub/imaging/single-objective/ZSNS001.ome.zarr/';
+const source = await OmeZarrImageSource.fromHttp({url});
 
-   - `npm run docs:dev` — start the VitePress dev server on <http://localhost:5174>
-   - `npm run docs:build` — build the static docs site to `.vitepress/dist/` (also generates the
-     API reference from TypeScript/JSDoc via TypeDoc)
-   - `npm run docs:preview` — build, then locally serve the production docs
+const layer = new ImageLayer({
+  source,
+  sliceCoords: { t: 400, z: 278, c: [0] }, // one slice: mid time-lapse, mid-stack
+  channelProps: [{ visible: true, contrastLimits: [0, 60] }],
+});
 
-   The docs site is deployed to GitHub Pages automatically on push to `main`.
+// frame the camera to the image's physical extent.
+const { x, y } = source.getDimensions()
+const camera = new OrthographicCamera({
+  left: 0, right: x.lods[0].size * x.lods[0].scale,
+  top: 0, bottom: y.lods[0].size * y.lods[0].scale
+});
 
-8. See [package.json](package.json) for other available commands.
+const idetik = new Idetik({
+  canvas: document.querySelector('canvas')!,
+  viewports: [{
+    camera,
+    layers: [layer],
+    cameraControls: new PanZoomControls(camera)
+  }],
+});
 
-## Release
+idetik.start();
+```
 
-We maintain the [@idetik/core](https://www.npmjs.com/package/@idetik/core?activeTab=readme) package on npm.
-
-### Automatic Release Process (Recommended)
-
-We use [semantic-release](https://github.com/semantic-release/semantic-release) to automatically handle versioning, changelog generation, npm publishing, and GitHub releases.
-
-#### How It Works
-
-1. **Use Conventional Commits**: When creating PRs, ensure your PR title follows the [Conventional Commits](https://www.conventionalcommits.org/) format:
-   - `feat: add new feature` → triggers a **minor** version bump (e.g., 0.1.0 → 0.2.0)
-   - `fix: resolve bug` → triggers a **patch** version bump (e.g., 0.1.0 → 0.1.1)
-   - `feat!: breaking change` or `BREAKING CHANGE:` in commit footer → triggers a **minor** version bump while in `0.x` (e.g., 0.1.0 → 0.2.0)
-   - `refactor:`, `perf:`, `chore:`, `revert:` → triggers a **patch** version bump
-   - `docs:`, `style:`, `test:`, `ci:`, `build:` → no release
-
-   While the project is in `0.x`, breaking changes bump the **minor** version (see [.releaserc.json](.releaserc.json)); `1.0.0` will be cut deliberately.
-
-2. **PR Title Validation**: Our CI automatically validates PR titles to ensure they follow the conventional commit format.
-
-3. **Merge to Main**: When your PR is merged to `main`, the release workflow automatically:
-   - Analyzes commits since the last release
-   - Determines the version bump
-   - Updates the version in `package.json`
-   - Generates/updates `CHANGELOG.md`
-   - Publishes to npm as `@idetik/core`
-   - Creates a GitHub release with release notes
-   - Tags the release (e.g., `v0.2.0`)
-
-4. **No Manual Intervention Required**: The entire process is automatic once merged to `main`.
-
-#### Pre-requirements
+## Project Status
 
-- For GH Actions:
-    - Set up "trusted publishing" for the repo/package pair on npm (uses OIDC to authenticate when publishing)
-    - Use `actions/create-github-app-token` to generate a GH token so `semantic-release` can comment
-      on the PR after release
-- For manual releases:
-    - Set `NPM_TOKEN` env var with an npm token with publish access to `@idetik` scope
-    - You must be a member of the [idetik developer team](https://www.npmjs.com/settings/idetik/teams/team/developers/users) on NPM
+This project is under active development. We welcome bug reports and new ideas but are not prepared to review or accept major contributions at this time.
 
-### Manual Release Process (Fallback)
+## Getting Help
 
-If you need to manually release (e.g., if the automated process fails), follow these steps:
+If you run into problems, please [open an issue on GitHub](https://github.com/chanzuckerberg/idetik/issues). If possible include:
 
-1. **Bump the version**:
-   ```shell
-   git switch -c your-name/prerelease-X-Y-Z
-   npm version [major|minor|patch]  # Choose appropriate bump
-   npm install  # Updates package-lock.json
-   npm run build
-   ```
+- A clear description of the problem and steps to reproduce
+- Expected vs. actual behavior
+- Your environment (OS, browser, version)
 
-2. **Create and merge PR**:
-   - Create a PR with your changes
-   - Get it approved and merge to `main`
+If you believe you have found a security issue, we would appreciate notification. Please email security@biohub.org.
 
-3. **Publish to npm**:
-   ```shell
-   git checkout main
-   git pull
-   npm login
-   npm run pub
-   ```
+## Code of Conduct
 
-4. **Tag the release**:
-   ```shell
-   git tag vX.Y.Z  # Use the version number from package.json
-   git push origin --tags
-   ```
+This project adheres to the Contributor Covenant [code of conduct](https://www.contributor-covenant.org/version/3/0/code_of_conduct/). By participating you are expected to uphold this code. Please report unacceptable behavior to opensource@biohub.org.
 
-5. **Create GitHub release**:
-   - Go to the [Releases page](https://github.com/chanzuckerberg/idetik/releases)
-   - Click "Create a new release"
-   - Select the tag you just created
-   - Add release notes describing the changes
+## License
 
-## Code of Conduct
+Licensed under the [MIT License](LICENSE).
 
-This project adheres to the Contributor Covenant [code of conduct](https://www.contributor-covenant.org/version/3/0/code_of_conduct/). By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.
+Copyright (c) 2026-present Chan Zuckerberg Biohub, Inc.

package/dist/index.d.ts

@@ -313,6 +313,57 @@ declare class Box3 {
     applyTransform(matrix: mat4): void;
 }
 
+declare class Frustum {
+    private readonly planes_;
+    constructor(m: mat4);
+    setWithViewProjection(m: mat4): void;
+    intersectsWithBox3(box: Box3): boolean;
+}
+
+declare class TrsTransform {
+    private dirty_;
+    private matrix_;
+    private rotation_;
+    private translation_;
+    private scale_;
+    addRotation(q: quat): void;
+    setRotation(q: quat): void;
+    get rotation(): gl_matrix.vec4;
+    addTranslation(vec: vec3): void;
+    setTranslation(vec: vec3): void;
+    get translation(): vec3;
+    addScale(vec: vec3): void;
+    setScale(vec: vec3): void;
+    targetTo(target: vec3): void;
+    get scale(): vec3;
+    get matrix(): mat4;
+    get inverse(): mat4;
+    private computeMatrix;
+}
+
+type CameraType = "OrthographicCamera" | "PerspectiveCamera";
+declare abstract class Camera extends Node {
+    private readonly transform_;
+    protected projectionMatrix_: mat4;
+    protected near_: number;
+    protected far_: number;
+    protected abstract updateProjectionMatrix(): void;
+    abstract get type(): CameraType;
+    update(): void;
+    get projectionMatrix(): mat4;
+    get transform(): TrsTransform;
+    get viewMatrix(): mat4;
+    get right(): vec3;
+    get up(): vec3;
+    getViewProjection(): mat4;
+    get frustum(): Frustum;
+    abstract setAspectRatio(aspectRatio: number): void;
+    abstract zoom(factor: number): void;
+    pan(vec: vec3): void;
+    get position(): vec3;
+    clipToWorld(position: vec3): vec3;
+}
+
 type Primitive = "triangles" | "points" | "lines";
 type GeometryAttributeType = "position" | "normal" | "uv" | "next_position" | "previous_position" | "direction" | "color" | "size" | "marker";
 type GeometryAttribute = {
@@ -344,27 +395,6 @@ declare class WireframeGeometry extends Geometry {
     constructor(geometry: Geometry);
 }
 
-declare class TrsTransform {
-    private dirty_;
-    private matrix_;
-    private rotation_;
-    private translation_;
-    private scale_;
-    addRotation(q: quat): void;
-    setRotation(q: quat): void;
-    get rotation(): gl_matrix.vec4;
-    addTranslation(vec: vec3): void;
-    setTranslation(vec: vec3): void;
-    get translation(): vec3;
-    addScale(vec: vec3): void;
-    setScale(vec: vec3): void;
-    targetTo(target: vec3): void;
-    get scale(): vec3;
-    get matrix(): mat4;
-    get inverse(): mat4;
-    private computeMatrix;
-}
-
 type Shader = "floatScalarImage" | "floatVolume" | "intLabelImage" | "intScalarImage" | "intVolume" | "labelImage" | "points" | "projectedLine" | "uintScalarImage" | "uintVolume" | "wireframe";
 
 /** @group Layer Configuration */
@@ -429,34 +459,6 @@ declare abstract class RenderableObject extends Node {
     getUniforms(): Record<string, unknown>;
 }
 
-declare class Frustum {
-    private readonly planes_;
-    constructor(m: mat4);
-    setWithViewProjection(m: mat4): void;
-    intersectsWithBox3(box: Box3): boolean;
-}
-
-type CameraType = "OrthographicCamera" | "PerspectiveCamera";
-declare abstract class Camera extends RenderableObject {
-    protected projectionMatrix_: mat4;
-    protected near_: number;
-    protected far_: number;
-    protected abstract updateProjectionMatrix(): void;
-    abstract get type(): CameraType;
-    update(): void;
-    get projectionMatrix(): mat4;
-    get viewMatrix(): mat4;
-    get right(): vec3;
-    get up(): vec3;
-    getViewProjection(): mat4;
-    get frustum(): Frustum;
-    abstract setAspectRatio(aspectRatio: number): void;
-    abstract zoom(factor: number): void;
-    pan(vec: vec3): void;
-    get position(): vec3;
-    clipToWorld(position: vec3): vec3;
-}
-
 declare class Plane {
     normal: vec3;
     signedDistance: number;
@@ -500,7 +502,68 @@ declare class EventDispatcher {
     private readonly handleEvent;
 }
 
-type OrthographicCameraProps = {
+/** @group Layers */
+type LayerState = "initialized" | "loading" | "ready";
+type BlendMode = "none" | "normal" | "additive" | "subtractive" | "multiply" | "premultiplied";
+type StateChangeCallback = (newState: LayerState, prevState?: LayerState) => void;
+interface LayerProps {
+    opacity?: number;
+    blendMode?: BlendMode;
+}
+/**
+ * Abstract base class for everything that can be added to a viewport.
+ *
+ * A `Layer` owns a set of renderable objects and contributes them to the scene
+ * each frame. Subclasses (e.g. {@link ImageLayer}, {@link VolumeLayer},
+ * {@link LabelLayer}) implement {@link Layer.update} to build or refresh those
+ * objects for the current view, and may override the `attach`/`detach` hooks to
+ * acquire and release resources when the layer joins or leaves a viewport.
+ *
+ * Layers carry shared presentation state — {@link Layer.opacity} and blend mode —
+ * and expose a lifecycle {@link LayerState} (`initialized` → `loading` → `ready`)
+ * that observers can subscribe to. A layer instance may be attached to only one
+ * viewport at a time.
+ *
+ * @group Layers
+ */
+declare abstract class Layer {
+    abstract readonly type: string;
+    private readonly coverageGroups_;
+    private state_;
+    private attached_;
+    private readonly callbacks_;
+    private opacity_;
+    blendMode: BlendMode;
+    constructor({ opacity, blendMode }?: LayerProps);
+    get opacity(): number;
+    set opacity(value: number);
+    abstract update(viewport?: Viewport): void;
+    onEvent(_: EventContext): void;
+    onAttached(context: IdetikContext): void;
+    onDetached(context: IdetikContext): void;
+    protected attach(_context: IdetikContext): void;
+    protected detach(_context: IdetikContext): void;
+    get coverageGroups(): ReadonlyMap<number | null, readonly RenderableObject[]>;
+    get state(): LayerState;
+    addStateChangeCallback(callback: StateChangeCallback): void;
+    removeStateChangeCallback(callback: StateChangeCallback): void;
+    protected setState(newState: LayerState): void;
+    protected addObject(object: RenderableObject, coverageGroup?: number | null): void;
+    protected clearObjects(): void;
+    /**
+     * Get uniforms for shader program. Override in derived classes that need custom uniforms.
+     * @returns Object containing uniform name-value pairs
+     */
+    getUniforms(): Record<string, unknown>;
+}
+
+type OrthographicCameraFrame = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+type OrthographicCameraProps = OrthographicCameraFrame & {
     near?: number;
     far?: number;
     orientation?: SliceOrientation;
@@ -529,17 +592,14 @@ declare class OrthographicCamera extends Camera {
     /**
      * Creates an orthographic camera framing the given world-space rectangle.
      *
-     * @param left - Left edge of the view frame, in world units.
-     * @param right - Right edge of the view frame, in world units.
-     * @param top - Top edge of the view frame, in world units.
-     * @param bottom - Bottom edge of the view frame, in world units.
-     * @param options - Near/far clipping plane distances (default `-1e6` and
-     *   `1e6`) and the slice orientation the camera faces (default `"XY"`).
+     * @param props - The view frame edges in world units, near/far clipping
+     *   plane distances (default `-1e6` and `1e6`), and the slice orientation
+     *   the camera faces (default `"XY"`).
      */
-    constructor(left: number, right: number, top: number, bottom: number, options?: OrthographicCameraProps);
+    constructor(props: OrthographicCameraProps);
     get viewportSize(): [number, number];
     setAspectRatio(aspectRatio: number): void;
-    setFrame(left: number, right: number, bottom: number, top: number): void;
+    setFrame({ left, right, top, bottom }: OrthographicCameraFrame): void;
     get type(): CameraType;
     get orientation(): SliceOrientation;
     /**
@@ -612,84 +672,6 @@ declare class Viewport {
     private updateAspectRatio;
 }
 
-/** @group Layers */
-type LayerState = "initialized" | "loading" | "ready";
-type BlendMode = "none" | "normal" | "additive" | "subtractive" | "multiply" | "premultiplied";
-type StateChangeCallback = (newState: LayerState, prevState?: LayerState) => void;
-interface LayerProps {
-    opacity?: number;
-    blendMode?: BlendMode;
-}
-/**
- * Abstract base class for everything that can be added to a viewport.
- *
- * A `Layer` owns a set of renderable objects and contributes them to the scene
- * each frame. Subclasses (e.g. {@link ImageLayer}, {@link VolumeLayer},
- * {@link LabelLayer}) implement {@link Layer.update} to build or refresh those
- * objects for the current view, and may override the `attach`/`detach` hooks to
- * acquire and release resources when the layer joins or leaves a viewport.
- *
- * Layers carry shared presentation state — {@link Layer.opacity} and blend mode —
- * and expose a lifecycle {@link LayerState} (`initialized` → `loading` → `ready`)
- * that observers can subscribe to. A layer instance may be attached to only one
- * viewport at a time.
- *
- * @group Layers
- */
-declare abstract class Layer {
-    abstract readonly type: string;
-    private readonly coverageGroups_;
-    private state_;
-    private attached_;
-    private readonly callbacks_;
-    private opacity_;
-    blendMode: BlendMode;
-    constructor({ opacity, blendMode }?: LayerProps);
-    get opacity(): number;
-    set opacity(value: number);
-    abstract update(viewport?: Viewport): void;
-    onEvent(_: EventContext): void;
-    onAttached(context: IdetikContext): void;
-    onDetached(context: IdetikContext): void;
-    protected attach(_context: IdetikContext): void;
-    protected detach(_context: IdetikContext): void;
-    get coverageGroups(): ReadonlyMap<number | null, readonly RenderableObject[]>;
-    get state(): LayerState;
-    addStateChangeCallback(callback: StateChangeCallback): void;
-    removeStateChangeCallback(callback: StateChangeCallback): void;
-    protected setState(newState: LayerState): void;
-    protected addObject(object: RenderableObject, coverageGroup?: number | null): void;
-    protected clearObjects(): void;
-    /**
-     * Get uniforms for shader program. Override in derived classes that need custom uniforms.
-     * @returns Object containing uniform name-value pairs
-     */
-    getUniforms(): Record<string, unknown>;
-}
-
-declare abstract class Renderer {
-    private readonly canvas_;
-    private width_;
-    private height_;
-    protected renderedObjects_: number;
-    protected abstract resize(width: number, height: number): void;
-    protected abstract renderObject(layer: Layer, object: RenderableObject, camera: Camera): void;
-    protected abstract clear(): void;
-    constructor(canvas: HTMLCanvasElement);
-    beginFrame(): void;
-    abstract render(viewport: Viewport): void;
-    updateSize(): void;
-    private updateRendererSize;
-    protected get canvas(): HTMLCanvasElement;
-    get width(): number;
-    get height(): number;
-    get renderedObjects(): number;
-    abstract get gpuTextureBytes(): number;
-    abstract get gpuTextureCount(): number;
-    abstract uploadTexture(texture: Texture): void;
-    abstract disposeTexture(texture: Texture): void;
-}
-
 /** @group Runtime */
 type Overlay = {
     update(idetik: Idetik): void;
@@ -754,7 +736,7 @@ declare class Idetik {
      *
      * @example
      * // Single viewport (element defaults to canvas)
-     * const camera = new OrthographicCamera(0, 1024, 0, 1024);
+     * const camera = new OrthographicCamera({ left: 0, right: 1024, top: 0, bottom: 1024 });
      * const idetik = new Idetik({
      *   canvas: document.querySelector('canvas')!,
      *   viewports: [{
@@ -786,7 +768,7 @@ declare class Idetik {
      *
      * @throws {Error} If viewports have duplicate IDs or shared elements
      */
-    constructor(params: IdetikProps, renderer?: Renderer);
+    constructor(params: IdetikProps);
     get chunkQueueStats(): QueueStats;
     get memoryStats(): MemoryStats;
     get renderedObjects(): number;
@@ -1497,7 +1479,7 @@ interface PointPickingResult {
 type ImageLayerProps = LayerProps & {
     source: ChunkSource;
     sliceCoords: SliceCoordinates;
-    policy: ImageSourcePolicy;
+    policy?: ImageSourcePolicy;
     orientation?: SliceOrientation;
     channelProps?: ChannelProps[];
     onPickValue?: (info: PointPickingResult) => void;
@@ -1581,7 +1563,7 @@ declare class ImageLayer extends Layer implements ChannelsEnabled {
 type VolumeLayerProps = {
     source: ChunkSource;
     sliceCoords: SliceCoordinates;
-    policy: ImageSourcePolicy;
+    policy?: ImageSourcePolicy;
     channelProps?: ChannelProps[];
 };
 /** @group Layers */
@@ -1666,7 +1648,7 @@ declare class LabelImageRenderable extends RenderableObject {
 type LabelLayerProps = LayerProps & {
     source: ChunkSource;
     sliceCoords: SliceCoordinates;
-    policy: ImageSourcePolicy;
+    policy?: ImageSourcePolicy;
     orientation?: SliceOrientation;
     colorMap?: LabelColorMapProps;
     onPickValue?: (info: PointPickingResult) => void;
@@ -1726,6 +1708,12 @@ declare class LabelLayer extends Layer {
     private releaseAndRemoveChunks;
 }
 
+type ImageRenderableProps = {
+    width: number;
+    height: number;
+    texture: Texture;
+    channelProps?: ChannelProps[];
+};
 type UniformValues = {
     u_color: vec3;
     u_imageSampler: number;
@@ -1738,7 +1726,7 @@ type UniformValues = {
 declare class ImageRenderable extends RenderableObject {
     private channels_;
     worldToTexCoord: mat4;
-    constructor(width: number, height: number, texture: Texture, channels?: ChannelProps[]);
+    constructor({ width, height, texture, channelProps, }: ImageRenderableProps);
     get type(): string;
     setChannelProps(channels: ChannelProps[]): void;
     setChannelProperty<K extends keyof ChannelProps>(channelIndex: number, property: K, value: Required<ChannelProps>[K]): void;
@@ -1785,13 +1773,16 @@ declare class ProjectedLineRenderable extends RenderableObject {
     };
 }
 
+type VolumeRenderableProps = {
+    channelProps?: ChannelProps[];
+};
 /** @group Renderable Objects */
 declare class VolumeRenderable extends RenderableObject {
     voxelScale: vec3;
     private channels_;
     private loadedChannels_;
     private readonly channelToTextureIndex_;
-    constructor();
+    constructor({ channelProps }?: VolumeRenderableProps);
     get type(): string;
     updateVolumeWithChunk(chunk: Chunk): void;
     private addChannelTexture;
@@ -1818,7 +1809,7 @@ type PerspectiveCameraProps = {
 declare class PerspectiveCamera extends Camera {
     private fov_;
     private aspectRatio_;
-    constructor(options?: PerspectiveCameraProps);
+    constructor(props?: PerspectiveCameraProps);
     setAspectRatio(aspectRatio: number): void;
     get type(): CameraType;
     get fov(): number;