documentation of exported functions and types

packages/dzi/src/renderer.ts

@@ -11,14 +11,26 @@ import { buildTileRenderer } from './tile-renderer';
 
 export type RenderSettings = {
     camera: {
+        /**
+         * a region of a dzi image, expressed as a relative parameter (eg. [0,0],[1,1] means the whole image)
+         */
         view: box2D;
+        /**
+         * the resolution of the output screen on which to project the region of source pixels given by view
+         */
         screenSize: vec2;
     };
 };
 
 type GpuProps = {
     pixels: CachedTexture;
 };
+/**
+ * 
+ * @param regl a valid REGL context (https://github.com/regl-project/regl)
+ * @returns an object which can fetch tiles from a DeepZoomImage, determine the visibility of those tiles given a simple camera, and render said tiles
+ * using regl (which uses webGL)
+ */
 export function buildDziRenderer(regl: REGL.Regl): Renderer<DziImage, DziTile, RenderSettings, GpuProps> {
     const renderCmd = buildTileRenderer(regl, { enable: false });
     const fetchDziTile = (
@@ -45,7 +57,7 @@ export function buildDziRenderer(regl: REGL.Regl): Renderer<DziImage, DziTile, R
         };
     };
     return {
-        destroy: () => {}, // no private resources to destroy
+        destroy: () => { }, // no private resources to destroy
         cacheKey: (item, _requestKey, _data, _settings) => `${item.url}`,
         fetchItemContent: fetchDziTile,
         getVisibleItems: (dzi, settings) => {
@@ -68,7 +80,13 @@ export function buildDziRenderer(regl: REGL.Regl): Renderer<DziImage, DziTile, R
         },
     };
 }
-
+/**
+ * 
+ * @param regl  a valid REGL context (https://github.com/regl-project/regl)
+ * @returns a function which creates a "Frame" of actions. each action represents loading
+ * and subsequently rendering a tile of the image as requested via its configuration -
+ * @see RenderSettings
+ */
 export function buildAsyncDziRenderer(regl: REGL.Regl) {
     return buildAsyncRenderer(buildDziRenderer(regl));
 }

packages/omezarr/src/sliceview/loader.ts

@@ -67,6 +67,19 @@ function getVisibleTilesInLayer(
     });
     return visibleTiles;
 }
+/**
+ * get tiles of the omezarr image which are visible (intersect with @param camera.veiw). 
+ * @param camera an object describing the current view: the region of the omezarr, and the resolution at which it 
+ * will be displayed.
+ * @param plane the plane (eg. 'xy') from which to draw tiles
+ * @param planeIndex the index of the plane along the orthagonal axis (if plane is xy, then the planes are slices along the Z axis)
+ * note that not all ome-zarr LOD layers can be expected to have the same number of slices! an index which exists at a high LOD may not
+ * exist at a low LOD.
+ * @param dataset the omezarr iamge to pull tiles from
+ * @param tileSize the size of the tiles, in pixels. it is recommended to use a size that agrees with the chunking used in the dataset, however,
+ * other utilities in this library will stitch togeather chunks to satisfy the requested tile size.
+ * @returns an array of objects representing tiles (bounding information, etc) which are visible from the given dataset.
+ */
 export function getVisibleTiles(
     camera: {
         view: box2D;
@@ -98,7 +111,15 @@ export function getVisibleTiles(
     }
     return getVisibleTilesInLayer(camera, plane, planeIndex, dataset, tileSize, layerIndex);
 }
-
+/**
+ * a function which returns a promise of float32 data from the requested region of an omezarr dataset.
+ * Note that omezarr decoding can be slow - consider wrapping this function in a web-worker (or a pool of them)
+ * to improve performance (note also that the webworker message passing will need to itself be wrapped in promises)
+ * @param metadata an omezarr object
+ * @param r a slice request @see getSlice
+ * @param layerIndex an index into the LOD pyramid of the given ZarrDataset.
+ * @returns the requested voxel information from the given layer of the given dataset.
+ */
 export const defaultDecoder = (metadata: ZarrDataset, r: ZarrRequest, layerIndex: number): Promise<VoxelTileImage> => {
     return getSlice(metadata, r, layerIndex).then((result: { shape: number[]; buffer: Chunk<'float32'> }) => {
         const { shape, buffer } = result;

packages/omezarr/src/sliceview/tile-renderer.ts

@@ -7,16 +7,22 @@ import REGL, { type Framebuffer2D } from 'regl';
 
 type Props = {
     target: Framebuffer2D | null;
-    tile: vec4;
-    view: vec4;
-    Rgamut: vec2;
-    Ggamut: vec2;
-    Bgamut: vec2;
+    tile: vec4; // [minx,miny,maxx,maxy] representing the bounding box of the tile we're rendering
+    view: vec4; // [minx,miny,maxx,maxy] representing the camera in the same space as the tile's bounding box
+    Rgamut: vec2; // [min,max] RedOut = RedChannelValue-Rgamut.min/(Rgamut.max-Rgamut.min)
+    Ggamut: vec2; // [min,max] GreenOut = GreenChannelValue-Ggamut.min/(Ggamut.max-Ggamut.min)
+    Bgamut: vec2; // [min,max] BlueOut = BlueChannelValue-Bgamut.min/(Bgamut.max-Bgamut.min)
     R: REGL.Texture2D;
     G: REGL.Texture2D;
     B: REGL.Texture2D;
 };
-
+/**
+ * 
+ * @param regl an active REGL context
+ * @returns a function (regl command) which renders 3 individual channels as the RGB
+ * components of an image. Each channel is mapped to the output RGB space via the given Gamut.
+ * the rendering is done in the given target buffer (or null for the screen).
+ */
 export function buildTileRenderer(regl: REGL.Regl) {
     const cmd = regl<
         {

packages/scatterbrain/src/abstract/types.ts

@@ -13,21 +13,67 @@ export type CachedVertexBuffer = {
 export type ReglCacheEntry = CachedTexture | CachedVertexBuffer;
 
 export type Renderer<Dataset, Item, Settings, GpuData extends Record<string, ReglCacheEntry>> = {
+    /**
+     * a function which returns items from the given dataset - this is the place to express spatial indexing
+     * or any other filtering that may be appropriate
+     * @param data the dataset to pull items from
+     * @param settings the settings that determine what items are appropriate
+     * @returns a list of the requested items, whatever they may be
+     */
     getVisibleItems: (data: Dataset, settings: Settings) => Array<Item>;
+    /**
+     * fetch raw, expensive-to-load content (an "Item" is a placeholder for that content)
+     * @param item An item to fetch content for
+     * @param dataset the dataset which owns the given item
+     * @param settings 
+     * @param signal an AbortSignal that allows the fetching of content to be cancelled
+     * @returns a map of meaningful names (eg. position, color, amplitude, etc) to functions that promise raw content, like pixels or other raw, renderable information.
+     * expect that the functions returned in this way have closures over the other arguments to this function -
+     * that is to say, DONT mutate them (make them Readonly if possible)
+     */
     fetchItemContent: (
         item: Item,
         dataset: Dataset,
         settings: Settings,
         signal?: AbortSignal
     ) => Record<string, () => Promise<ReglCacheEntry>>;
+    /**
+     * 
+     * @param cacheData the results of fetching all the content for an Item
+     * @returns true if the content matches the expectations of our rendering function
+     */
     isPrepared: (cacheData: Record<string, ReglCacheEntry | undefined>) => cacheData is GpuData;
+    /**
+     * actually render the content of an item
+     * @param target REGL framebuffer to render to (null is the canvas to which regl is bound - it is shared and mutable!)
+     * @param item the item describing the content to render
+     * @param data the dataset which owns the item
+     * @param settings the configuration of the current rendering task
+     * @param gpuData the data as fetched and uploaded to the GPU @see fetchItemContent and validated by @see isPrepared
+     * @returns void - this function will render (mutate!) the content (pixels!) of the target
+     */
     renderItem: (
         target: REGL.Framebuffer2D | null,
         item: Item,
         data: Dataset,
         settings: Settings,
         gpuData: GpuData
     ) => void;
+    /**
+     * compute a unique (but please not random!) string that the cache system can use to identify the content
+     * associated with this {item, settings, data}
+     * @param item the item we're caching the data for
+     * @param requestKey a key of gpuData (TODO: make this fact official via Typescript if possible)
+     * @param data the dataset that owns the given item
+     * @param settings the configuration of the current rendering task 
+     * @returns a string, suitable for use in a cache
+     */
     cacheKey: (item: Item, requestKey: string, data: Dataset, settings: Settings) => string;
+    /**
+     * in some cases, rendering may rely on non-item-specific rendering resources (lookup tables, buffers, etc)
+     * this function is the place to release those
+     * @param regl the regl context (the same that was used to create this renderer)
+     * @returns 
+     */
     destroy: (regl: REGL.Regl) => void;
 };