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 idetik = new Idetik({
  canvas: document.querySelector('canvas')!,
  viewports: [{
    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

QueueStats

A snapshot of the chunk request queue.

Property	Description
pending: number	Number of requests waiting to start.
running: number	Number of requests currently in flight.

ChunkStats

A snapshot of chunk demand and GPU residency.

Requested counts include prefetch. When the memory limit cannot hold every requested chunk, some are never fetched and resident stays below requested.

Property	Description
sources: readonly SourceChunkStats[]	Cache state per source.
viewports: readonly ViewportChunkStats[]	Loading progress per viewport. Viewports without chunked layers are omitted.

SourceChunkStats

Cache state for one source, combined across all of its views.

Property	Description
source: ChunkSource	The source the counts describe.
requested: number	Chunks requested by any view, visible or prefetch, at any LOD. A chunk requested by several views counts once. The budget may defer fetching.
resident: number	How many of requested are on the GPU and drawable.
timepoints: object	The same counts by timepoint index, the position along the source's time axis rather than the world t coordinate. A timepoint is fully loaded for every view of the source when its two counts are equal.
timepoints.requested: Uint32Array	requested[t] is the chunks requested at timepoint index t.
timepoints.resident: Uint32Array	resident[t] is how many of requested[t] are on the GPU.

ViewportChunkStats

Loading progress for one viewport, summed across its chunked layers.

Property	Description
viewportId: string	The viewport the counts describe.
requested: number	Visible and prefetch chunks at any LOD, including the fallback LOD drawn while the current one loads.
resident: number	How many of requested are on the GPU.
current: object	The same counts excluding fallback and prefetch: chunks visible at each layer's current LOD and timepoint. The viewport is fully drawn at its selected LOD when these are equal.
current.requested: number	Chunks visible at each layer's current LOD and timepoint.
current.resident: number	How many of requested are on the GPU.

Overlay

An object updated once per frame after all viewports have rendered.

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.memoryStats.cpuChunkCount} chunks`;
  },
};

idetik.addOverlay(chunkReadout);

Property	Description
update: (idetik) => void	Called once per rendered frame.

IdetikProps

Initialization properties for constructing an Idetik instance.

Property	Description
canvas: HTMLCanvasElement	The canvas element to render into.
viewports?: ViewportProps[]	Viewport definitions to create 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.

MemoryStats

A snapshot of the runtime's memory usage.

Property	Description
cpuChunkBytes: number	Bytes of chunk data held in CPU memory.
cpuChunkCount: number	Number of chunks held in CPU memory.
gpuTextureBytes: number	Bytes of texture data resident on the GPU.
gpuTextureCount: number	Number of textures resident on the GPU.
jsHeapUsedBytes?: number	Used JS heap in bytes.
jsHeapLimitBytes?: number	JS heap size limit in bytes.

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[];

Accessors

chunkQueueStats QueueStats

Counts of queued and in-flight chunk requests.

get chunkQueueStats(): QueueStats;

chunkStats ChunkStats

Chunk demand and GPU residency per source, by timepoint, and loading progress per viewport. Each read walks every view's chunk states and returns a new snapshot, so poll it at the rate you need rather than every frame.

get chunkStats(): ChunkStats;

memoryStats MemoryStats

A snapshot of current CPU/GPU/JS heap memory usage.

get memoryStats(): MemoryStats;

renderedObjects number

The number of objects drawn in the last rendered frame.

get renderedObjects(): number;

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;

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(props): Viewport;

Parameter	Description
props: ViewportProps	The viewport definition. The element defaults to the canvas and must be unique across viewports.

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.

start() Idetik

Starts the render loop and connects input handlers.

start(): Idetik;

stop() void

Stops the render loop and disconnects input handlers.

stop(): void;