Idetik

The entry point of an Idetik application.

An Idetik instance owns the renderer and the chunk manager and drives the render loop for the viewports it is given. Each viewport pairs a camera and its controls with a stack of layers and draws into a region of the shared canvas. Layers in all viewports stream chunks through the same manager under a single memory budget.

const source = await OmeZarrImageSource.fromHttp({ url });

const layer = new ImageLayer({
  source,
  sliceCoords: { t: 0, z: 0, c: [0] },
});

const camera = new OrthographicCamera({
  left: 0,
  right: 1024,
  top: 0,
  bottom: 1024,
});

const canvas = document.querySelector<HTMLCanvasElement>('canvas')!;
const idetik = new Idetik({
  canvas,
  viewports: [new Viewport({
    domElement: canvas,
    camera,
    layers: [layer],
    cameraControls: new PanZoomControls(camera),
  })],
});

idetik.start();

Constructor

Creates an Idetik runtime for the given canvas.

new Idetik(params): Idetik;

Parameter	Description
params: IdetikProps	Initialization properties.

Types

Overlay

An object updated once per animation frame after any drawing.

Overlays drive HUD elements that live outside the canvas such as scale bars, time indicators, or memory readouts.

const chunkReadout: Overlay = {
  update(idetik) {
    div.textContent = `${idetik.stats.memory.cpuChunkCount} chunks`;
  },
};

idetik.addOverlay(chunkReadout);

Property	Description
update: (idetik) => void	Called every animation frame, including when drawing is skipped.

IdetikProps

Property	Description
canvas: HTMLCanvasElement	The canvas element to render into.
viewports?: Viewport[]	Viewports to render at startup.
overlays?: Overlay[]	Overlays to run each frame.
showStats?: boolean	Shows an FPS meter. Defaults to false.
memoryLimitMB?: number	Memory budget for chunk data. Defaults to 2048.
maxConcurrentRequests?: number	Max in-flight chunk requests. Defaults to 8.
maxGpuUploadsPerUpdate?: number	Max GPU texture uploads per frame. Defaults to 4.

Properties

canvas

The canvas element the renderer draws into.

readonly canvas: HTMLCanvasElement;

overlays

The registered overlays that update once per frame in order.

readonly overlays: Overlay[];

stats

Runtime, memory, queue, chunk, and rendered-object statistics.

readonly stats: Stats;

autoDraw

Whether the loop draws on its own when something changed. When false, the loop still updates every frame but only draws on requestRender or captureFrameBlob.

autoDraw: boolean = true;

Accessors

width number

The width of the rendering surface in pixels.

get width(): number;

height number

The height of the rendering surface in pixels.

get height(): number;

viewports readonly Viewport[]

The viewports in render order.

get viewports(): readonly Viewport[];

running boolean

Whether the render loop is running.

get running(): boolean;

isSettled boolean

Whether the scene has come to rest: no layers loading, no chunk requests queued or in flight, no loaded chunks awaiting GPU upload, and no camera controls moving.

Chunks that do not fit the memory limit are never requested and so do not prevent settling.

get isSettled(): boolean;

Methods

getViewport() Viewport | undefined

Finds a viewport by its id.

getViewport(id): Viewport | undefined;

Parameter	Description
id: string	The id given in the viewport's definition.

addViewport() Viewport

Adds a viewport at runtime.

addViewport(viewport): Viewport;

Parameter	Description
viewport: Viewport	The viewport to add.

removeViewport() boolean

Removes a previously added viewport.

removeViewport(viewport): boolean;

Parameter	Description
viewport: Viewport	The viewport to remove.

addOverlay() void

Registers an overlay that updates once per frame.

addOverlay(overlay): void;

Parameter	Description
overlay: Overlay	The overlay to add.

removeOverlay() boolean

Removes a previously added overlay.

removeOverlay(overlay): boolean;

Parameter	Description
overlay: Overlay	The overlay to remove.

setMemoryLimitMB() void

Sets the memory budget for chunk data at runtime.

setMemoryLimitMB(memoryLimitMB): void;

Parameter	Description
memoryLimitMB: number	The new budget in megabytes.

requestRender() void

Explicitly requests a draw on the next animation frame while running, even if no internal state has changed.

requestRender(): void;

captureFrameBlob() Promise<Blob>

Requests a draw and encodes the canvas right after it, in the same frame, before the browser composites it.

captureFrameBlob(options?): Promise<Blob>;

Parameter	Description
options?: CaptureFrameBlobOptions	Image type and quality, as for canvas.toBlob. Defaults to PNG.

settled() Promise<void>

Resolves at the end of the first frame in which the scene isSettled.

A chunk that fails to load is retried indefinitely, so bound the wait, e.g. with Promise.race and a timeout. Combined with autoDraw, this renders a scene exactly once, after everything visible has loaded:

idetik.autoDraw = false;
idetik.start();
await idetik.settled();
const blob = await idetik.captureFrameBlob({ type: "image/webp" });

settled(): Promise<void>;

start() Idetik

Starts the render loop and connects input handlers.

start(): Idetik;

stop() void

Stops the render loop and disconnects input handlers.

stop(): void;