@vitessce/heatmap 2.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/Heatmap.js

@@ -0,0 +1,689 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* eslint-disable react/display-name */
+import React, { useRef, useState, useCallback, useMemo, useEffect, useReducer, forwardRef, } from 'react';
+import uuidv4 from 'uuid/v4';
+import { deck, luma, HeatmapCompositeTextLayer, PixelatedBitmapLayer, PaddedExpressionHeatmapBitmapLayer, HeatmapBitmapLayer, TILE_SIZE, MAX_ROW_AGG, MIN_ROW_AGG, COLOR_BAR_SIZE, AXIS_MARGIN, DATA_TEXTURE_SIZE, PIXELATED_TEXTURE_PARAMETERS, } from '@vitessce/gl';
+import range from 'lodash/range';
+import clamp from 'lodash/clamp';
+import isEqual from 'lodash/isEqual';
+import { getLongestString, DEFAULT_GL_OPTIONS, createDefaultUpdateCellsHover, createDefaultUpdateGenesHover, createDefaultUpdateTracksHover, createDefaultUpdateViewInfo, copyUint8Array, getDefaultColor, } from '@vitessce/utils';
+import { layerFilter, getAxisSizes, mouseToHeatmapPosition, heatmapToMousePosition, mouseToCellColorPosition, } from './utils';
+import HeatmapWorkerPool from './HeatmapWorkerPool';
+// Only allocate the memory once for the container
+const paddedExpressionContainer = new Uint8Array(DATA_TEXTURE_SIZE * DATA_TEXTURE_SIZE);
+/**
+ * Should the "padded" implementation
+ * be used? Only works if the number of heatmap values is
+ * <=  4096^2 = ~16 million.
+ * @param {number|null} dataLength The number of heatmap values.
+ * @returns {boolean} Whether the more efficient implementation should be used.
+ */
+function shouldUsePaddedImplementation(dataLength) {
+    return dataLength <= DATA_TEXTURE_SIZE ** 2;
+}
+/**
+ * A heatmap component for cell x gene matrices.
+ * @param {object} props
+ * @param {string} props.uuid The uuid of this component,
+ * used by tooltips to determine whether to render a tooltip or
+ * a crosshair.
+ * @param {string} props.theme The current theme name.
+ * @param {object} props.viewState The viewState for
+ * DeckGL.
+ * @param {function} props.setViewState The viewState setter
+ * for DeckGL.
+ * @param {number} props.width The width of the canvas.
+ * @param {number} props.height The height of the canvas.
+ * @param {object} props.expressionMatrix An object { rows, cols, matrix },
+ * where matrix is a flat Uint8Array, rows is a list of cell ID strings,
+ * and cols is a list of gene ID strings.
+ * @param {Map} props.cellColors Map of cell ID to color. Optional.
+ * If defined, the key ordering is used to order the cell axis of the heatmap.
+ * @param {array} props.cellColorLabels array of labels to place beside cell color
+ * tracks. Only works for transpose=true.
+ * @param {function} props.clearPleaseWait The clear please wait callback,
+ * called when the expression matrix has loaded (is not null).
+ * @param {function} props.setCellHighlight Callback function called on
+ * hover with the cell ID. Optional.
+ * @param {function} props.setGeneHighlight Callback function called on
+ * hover with the gene ID. Optional.
+ * @param {function} props.updateViewInfo Callback function that gets called with an
+ * object { uuid, project() } where project is a function that maps (cellId, geneId)
+ * to canvas (x,y) coordinates. Used to show tooltips. Optional.
+ * @param {boolean} props.transpose By default, false.
+ * @param {string} props.variablesTitle By default, 'Genes'.
+ * @param {string} props.observationsTitle By default, 'Cells'.
+ * @param {number} props.useDevicePixels By default, 1. Higher values
+ * e.g. 2 increase text sharpness.
+ * @param {boolean} props.hideObservationLabels By default false.
+ * @param {boolean} props.hideVariableLabels By default false.
+ * @param {string} props.colormap The name of the colormap function to use.
+ * @param {array} props.colormapRange A tuple [lower, upper] to adjust the color scale.
+ * @param {function} props.setColormapRange The setter function for colormapRange.
+ */
+const Heatmap = forwardRef((props, deckRef) => {
+    const { uuid, theme, viewState: rawViewState, setViewState, width: viewWidth, height: viewHeight, expressionMatrix: expression, cellColors, cellColorLabels = [''], colormap, colormapRange, clearPleaseWait, setComponentHover, setCellHighlight = createDefaultUpdateCellsHover('Heatmap'), setGeneHighlight = createDefaultUpdateGenesHover('Heatmap'), setTrackHighlight = createDefaultUpdateTracksHover('Heatmap'), updateViewInfo = createDefaultUpdateViewInfo('Heatmap'), setIsRendering = () => { }, transpose = false, variablesTitle = 'Genes', observationsTitle = 'Cells', variablesDashes = true, observationsDashes = true, useDevicePixels = 1, hideObservationLabels = false, hideVariableLabels = false, } = props;
+    const viewState = {
+        ...rawViewState,
+        target: (transpose ? [rawViewState.target[1], rawViewState.target[0]] : rawViewState.target),
+        minZoom: 0,
+    };
+    const axisLeftTitle = (transpose ? variablesTitle : observationsTitle);
+    const axisTopTitle = (transpose ? observationsTitle : variablesTitle);
+    const workerPool = useMemo(() => new HeatmapWorkerPool(), []);
+    useEffect(() => {
+        if (clearPleaseWait && expression) {
+            clearPleaseWait('expression-matrix');
+        }
+    }, [clearPleaseWait, expression]);
+    const tilesRef = useRef();
+    const dataRef = useRef();
+    const [axisLeftLabels, setAxisLeftLabels] = useState([]);
+    const [axisTopLabels, setAxisTopLabels] = useState([]);
+    const [numCellColorTracks, setNumCellColorTracks] = useState([]);
+    // Since we are storing the tile data in a ref,
+    // and updating it asynchronously when the worker finishes,
+    // we need to tie it to a piece of state through this iteration value.
+    const [tileIteration, incTileIteration] = useReducer(i => i + 1, 0);
+    // We need to keep a backlog of the tasks for the worker thread,
+    // since the array buffer can only be held by one thread at a time.
+    const [backlog, setBacklog] = useState([]);
+    // Store a reference to the matrix Uint8Array in the dataRef,
+    // since we need to access its array buffer to transfer
+    // it back and forth from the worker thread.
+    useEffect(() => {
+        // Store the expression matrix Uint8Array in the dataRef.
+        if (expression && expression.matrix
+            && !shouldUsePaddedImplementation(expression.matrix.length)) {
+            dataRef.current = copyUint8Array(expression.matrix);
+        }
+    }, [dataRef, expression]);
+    // Check if the ordering of axis labels needs to be changed,
+    // for example if the cells "selected" (technically just colored)
+    // have changed.
+    useEffect(() => {
+        if (!expression) {
+            return;
+        }
+        const newCellOrdering = (!cellColors || cellColors.size === 0
+            ? expression.rows
+            : Array.from(cellColors.keys()));
+        const oldCellOrdering = (transpose ? axisTopLabels : axisLeftLabels);
+        if (!isEqual(oldCellOrdering, newCellOrdering)) {
+            if (transpose) {
+                setAxisTopLabels(newCellOrdering);
+            }
+            else {
+                setAxisLeftLabels(newCellOrdering);
+            }
+        }
+    }, [expression, cellColors, axisTopLabels, axisLeftLabels, transpose]);
+    // Set the genes ordering.
+    useEffect(() => {
+        if (!expression) {
+            return;
+        }
+        if (transpose) {
+            setAxisLeftLabels(expression.cols);
+        }
+        else {
+            setAxisTopLabels(expression.cols);
+        }
+    }, [expression, transpose]);
+    const [longestCellLabel, longestGeneLabel] = useMemo(() => {
+        if (!expression) {
+            return ['', ''];
+        }
+        return [
+            getLongestString(expression.rows),
+            getLongestString([...expression.cols, ...cellColorLabels]),
+        ];
+    }, [expression, cellColorLabels]);
+    // Creating a look up dictionary once is faster than calling indexOf many times
+    // i.e when cell ordering changes.
+    const expressionRowLookUp = useMemo(() => {
+        const lookUp = new Map();
+        if (expression?.rows) {
+            // eslint-disable-next-line no-return-assign
+            expression.rows.forEach((cell, j) => (lookUp.set(cell, j)));
+        }
+        return lookUp;
+    }, [expression]);
+    const width = axisTopLabels.length;
+    const height = axisLeftLabels.length;
+    const [axisOffsetLeft, axisOffsetTop] = getAxisSizes(transpose, longestGeneLabel, longestCellLabel, hideObservationLabels, hideVariableLabels);
+    const [gl, setGlContext] = useState(null);
+    const offsetTop = axisOffsetTop + COLOR_BAR_SIZE * (transpose ? numCellColorTracks : 0);
+    const offsetLeft = axisOffsetLeft + COLOR_BAR_SIZE * (transpose ? 0 : numCellColorTracks);
+    const matrixWidth = viewWidth - offsetLeft;
+    const matrixHeight = viewHeight - offsetTop;
+    const matrixLeft = -matrixWidth / 2;
+    const matrixRight = matrixWidth / 2;
+    const matrixTop = -matrixHeight / 2;
+    const matrixBottom = matrixHeight / 2;
+    const xTiles = Math.ceil(width / TILE_SIZE);
+    const yTiles = Math.ceil(height / TILE_SIZE);
+    const widthRatio = 1 - (TILE_SIZE - (width % TILE_SIZE)) / (xTiles * TILE_SIZE);
+    const heightRatio = 1 - (TILE_SIZE - (height % TILE_SIZE)) / (yTiles * TILE_SIZE);
+    const tileWidth = (matrixWidth / widthRatio) / (xTiles);
+    const tileHeight = (matrixHeight / heightRatio) / (yTiles);
+    const scaleFactor = 2 ** viewState.zoom;
+    const cellHeight = (matrixHeight * scaleFactor) / height;
+    const cellWidth = (matrixWidth * scaleFactor) / width;
+    // Get power of 2 between 1 and 16,
+    // for number of cells to aggregate together in each direction.
+    const aggSizeX = clamp(2 ** Math.ceil(Math.log2(1 / cellWidth)), MIN_ROW_AGG, MAX_ROW_AGG);
+    const aggSizeY = clamp(2 ** Math.ceil(Math.log2(1 / cellHeight)), MIN_ROW_AGG, MAX_ROW_AGG);
+    const [targetX, targetY] = viewState.target;
+    // Emit the viewInfo object on viewState updates
+    // (used by tooltips / crosshair elements).
+    useEffect(() => {
+        updateViewInfo({
+            uuid,
+            project: (cellId, geneId) => {
+                const colI = transpose ? axisTopLabels.indexOf(cellId) : axisTopLabels.indexOf(geneId);
+                const rowI = transpose ? axisLeftLabels.indexOf(geneId) : axisLeftLabels.indexOf(cellId);
+                return heatmapToMousePosition(colI, rowI, {
+                    offsetLeft,
+                    offsetTop,
+                    targetX: viewState.target[0],
+                    targetY: viewState.target[1],
+                    scaleFactor,
+                    matrixWidth,
+                    matrixHeight,
+                    numRows: height,
+                    numCols: width,
+                });
+            },
+        });
+    }, [uuid, updateViewInfo, transpose, axisTopLabels, axisLeftLabels, offsetLeft,
+        offsetTop, viewState, scaleFactor, matrixWidth, matrixHeight, height, width]);
+    // Listen for viewState changes.
+    // Do not allow the user to zoom and pan outside of the initial window.
+    const onViewStateChange = useCallback(({ viewState: nextViewState }) => {
+        const { zoom: nextZoom } = nextViewState;
+        const nextScaleFactor = 2 ** nextZoom;
+        const minTargetX = nextZoom === 0 ? 0 : -(matrixRight - (matrixRight / nextScaleFactor));
+        const maxTargetX = -1 * minTargetX;
+        const minTargetY = nextZoom === 0 ? 0 : -(matrixBottom - (matrixBottom / nextScaleFactor));
+        const maxTargetY = -1 * minTargetY;
+        // Manipulate view state if necessary to keep the user in the window.
+        const nextTarget = [
+            clamp(nextViewState.target[0], minTargetX, maxTargetX),
+            clamp(nextViewState.target[1], minTargetY, maxTargetY),
+        ];
+        setViewState({
+            zoom: nextZoom,
+            target: (transpose ? [nextTarget[1], nextTarget[0]] : nextTarget),
+        });
+    }, [matrixRight, matrixBottom, transpose, setViewState]);
+    // If `expression` or `cellOrdering` have changed,
+    // then new tiles need to be generated,
+    // so add a new task to the backlog.
+    useEffect(() => {
+        if (!expression || !expression.matrix || expression.matrix.length < DATA_TEXTURE_SIZE ** 2) {
+            return;
+        }
+        // Use a uuid to give the task a unique ID,
+        // to help identify where in the list it is located
+        // after the worker thread asynchronously sends the data back
+        // to this thread.
+        if (axisTopLabels && axisLeftLabels && xTiles && yTiles) {
+            setBacklog(prev => [...prev, uuidv4()]);
+        }
+    }, [dataRef, expression, axisTopLabels, axisLeftLabels, xTiles, yTiles]);
+    // When the backlog has updated, a new worker job can be submitted if:
+    // - the backlog has length >= 1 (at least one job is waiting), and
+    // - buffer.byteLength is not zero, so the worker does not currently "own" the buffer.
+    useEffect(() => {
+        if (backlog.length < 1 || shouldUsePaddedImplementation(dataRef.current.length)) {
+            return;
+        }
+        const curr = backlog[backlog.length - 1];
+        if (dataRef.current
+            && dataRef.current.buffer.byteLength && expressionRowLookUp.size > 0
+            && !shouldUsePaddedImplementation(dataRef.current.length)) {
+            const { cols, matrix } = expression;
+            const promises = range(yTiles).map(i => range(xTiles).map(async (j) => workerPool.process({
+                curr,
+                tileI: i,
+                tileJ: j,
+                tileSize: TILE_SIZE,
+                cellOrdering: transpose ? axisTopLabels : axisLeftLabels,
+                cols,
+                transpose,
+                data: matrix.buffer.slice(),
+                expressionRowLookUp,
+            })));
+            const process = async () => {
+                const tiles = await Promise.all(promises.flat());
+                tilesRef.current = tiles.map(i => i.tile);
+                incTileIteration();
+                dataRef.current = new Uint8Array(tiles[0].buffer);
+                const { curr: currWork } = tiles[0];
+                setBacklog((prev) => {
+                    const currIndex = prev.indexOf(currWork);
+                    return prev.slice(currIndex + 1, prev.length);
+                });
+            };
+            process();
+        }
+    }, [axisLeftLabels, axisTopLabels, backlog, expression, transpose,
+        xTiles, yTiles, workerPool, expressionRowLookUp]);
+    useEffect(() => {
+        setIsRendering(backlog.length > 0);
+    }, [backlog, setIsRendering]);
+    // Create the padded expression matrix for holding data which can then be bound to the GPU.
+    const paddedExpressions = useMemo(() => {
+        const cellOrdering = transpose ? axisTopLabels : axisLeftLabels;
+        if (expression?.matrix && cellOrdering.length
+            && gl && shouldUsePaddedImplementation(expression.matrix.length)) {
+            let newIndex = 0;
+            for (let cellOrderingIndex = 0; cellOrderingIndex < cellOrdering.length; cellOrderingIndex += 1) {
+                const cell = cellOrdering[cellOrderingIndex];
+                newIndex = transpose ? cellOrderingIndex : newIndex;
+                const cellIndex = expressionRowLookUp.get(cell);
+                for (let geneIndex = 0; geneIndex < expression.cols.length; geneIndex += 1) {
+                    const index = cellIndex * expression.cols.length + geneIndex;
+                    paddedExpressionContainer[newIndex % (DATA_TEXTURE_SIZE * DATA_TEXTURE_SIZE)] = expression.matrix[index];
+                    newIndex = transpose ? newIndex + cellOrdering.length : newIndex + 1;
+                }
+            }
+        }
+        return gl ? new luma.Texture2D(gl, {
+            data: paddedExpressionContainer,
+            mipmaps: false,
+            parameters: PIXELATED_TEXTURE_PARAMETERS,
+            // Each color contains a single luminance value.
+            // When sampled, rgb are all set to this luminance, alpha is 1.0.
+            // Reference: https://luma.gl/docs/api-reference/webgl/texture#texture-formats
+            format: luma.GL.LUMINANCE,
+            dataFormat: luma.GL.LUMINANCE,
+            type: luma.GL.UNSIGNED_BYTE,
+            width: DATA_TEXTURE_SIZE,
+            height: DATA_TEXTURE_SIZE,
+        }) : paddedExpressionContainer;
+    }, [
+        transpose,
+        axisTopLabels,
+        axisLeftLabels,
+        expression,
+        expressionRowLookUp,
+        gl,
+    ]);
+    // Update the heatmap tiles if:
+    // - new tiles are available (`tileIteration` has changed), or
+    // - the matrix bounds have changed, or
+    // - the `aggSizeX` or `aggSizeY` have changed, or
+    // - the cell ordering has changed.
+    const heatmapLayers = useMemo(() => {
+        const usePaddedExpressions = expression?.matrix
+            && shouldUsePaddedImplementation(expression?.matrix.length);
+        if ((!tilesRef.current || backlog.length) && !usePaddedExpressions) {
+            return [];
+        }
+        if (usePaddedExpressions) {
+            const cellOrdering = transpose ? axisTopLabels : axisLeftLabels;
+            // eslint-disable-next-line no-inner-declarations, no-shadow
+            function getLayer(i, j) {
+                const { cols } = expression;
+                return new PaddedExpressionHeatmapBitmapLayer({
+                    id: `heatmapLayer-${i}-${j}`,
+                    image: paddedExpressions,
+                    bounds: [
+                        matrixLeft + j * tileWidth,
+                        matrixTop + i * tileHeight,
+                        matrixLeft + (j + 1) * tileWidth,
+                        matrixTop + (i + 1) * tileHeight,
+                    ],
+                    tileI: i,
+                    tileJ: j,
+                    numXTiles: xTiles,
+                    numYTiles: yTiles,
+                    origDataSize: transpose
+                        ? [cols.length, cellOrdering.length]
+                        : [cellOrdering.length, cols.length],
+                    aggSizeX,
+                    aggSizeY,
+                    colormap,
+                    colorScaleLo: colormapRange[0],
+                    colorScaleHi: colormapRange[1],
+                    updateTriggers: {
+                        image: [axisLeftLabels, axisTopLabels],
+                        bounds: [tileHeight, tileWidth],
+                    },
+                });
+            }
+            const layers = range(yTiles * xTiles).map(index => getLayer(Math.floor(index / xTiles), index % xTiles));
+            return layers;
+        }
+        function getLayer(i, j, tile) {
+            return new HeatmapBitmapLayer({
+                id: `heatmapLayer-${tileIteration}-${i}-${j}`,
+                image: tile,
+                bounds: [
+                    matrixLeft + j * tileWidth,
+                    matrixTop + i * tileHeight,
+                    matrixLeft + (j + 1) * tileWidth,
+                    matrixTop + (i + 1) * tileHeight,
+                ],
+                aggSizeX,
+                aggSizeY,
+                colormap,
+                colorScaleLo: colormapRange[0],
+                colorScaleHi: colormapRange[1],
+                updateTriggers: {
+                    image: [axisLeftLabels, axisTopLabels],
+                    bounds: [tileHeight, tileWidth],
+                },
+            });
+        }
+        const layers = tilesRef.current.map((tile, index) => getLayer(Math.floor(index / xTiles), index % xTiles, tile));
+        return layers;
+    }, [expression, backlog.length, transpose, axisTopLabels, axisLeftLabels, yTiles, xTiles,
+        paddedExpressions, matrixLeft, tileWidth, matrixTop, tileHeight,
+        aggSizeX, aggSizeY, colormap, colormapRange, tileIteration]);
+    const axisLeftDashes = (transpose ? variablesDashes : observationsDashes);
+    const axisTopDashes = (transpose ? observationsDashes : variablesDashes);
+    // Map cell and gene names to arrays with indices,
+    // to prepare to render the names in TextLayers.
+    const axisTopLabelData = useMemo(() => axisTopLabels.map((d, i) => [i, (axisTopDashes ? `- ${d}` : d)]), [axisTopLabels, axisTopDashes]);
+    const axisLeftLabelData = useMemo(() => axisLeftLabels.map((d, i) => [i, (axisLeftDashes ? `${d} -` : d)]), [axisLeftLabels, axisLeftDashes]);
+    const cellColorLabelsData = useMemo(() => cellColorLabels.map((d, i) => [i, d && (transpose ? `${d} -` : `- ${d}`)]), [cellColorLabels, transpose]);
+    const hideTopLabels = (transpose ? hideObservationLabels : hideVariableLabels);
+    const hideLeftLabels = (transpose ? hideVariableLabels : hideObservationLabels);
+    // Generate the axis label, axis title, and loading indicator text layers.
+    const textLayers = [
+        new HeatmapCompositeTextLayer({
+            axis: 'left',
+            id: 'axisLeftCompositeTextLayer',
+            targetX,
+            targetY,
+            scaleFactor,
+            axisLeftLabelData,
+            matrixTop,
+            height,
+            matrixHeight,
+            cellHeight,
+            cellWidth,
+            axisTopLabelData,
+            matrixLeft,
+            width,
+            matrixWidth,
+            viewHeight,
+            viewWidth,
+            theme,
+            axisLeftTitle,
+            axisTopTitle,
+            axisOffsetLeft,
+            axisOffsetTop,
+            hideTopLabels,
+            hideLeftLabels,
+            transpose,
+        }),
+        new HeatmapCompositeTextLayer({
+            axis: 'top',
+            id: 'axisTopCompositeTextLayer',
+            targetX,
+            targetY,
+            scaleFactor,
+            axisLeftLabelData,
+            matrixTop,
+            height,
+            matrixHeight,
+            cellHeight,
+            cellWidth,
+            axisTopLabelData,
+            matrixLeft,
+            width,
+            matrixWidth,
+            viewHeight,
+            viewWidth,
+            theme,
+            axisLeftTitle,
+            axisTopTitle,
+            axisOffsetLeft,
+            axisOffsetTop,
+            cellColorLabelsData,
+            hideTopLabels,
+            hideLeftLabels,
+            transpose,
+        }),
+        new HeatmapCompositeTextLayer({
+            axis: 'corner',
+            id: 'cellColorLabelCompositeTextLayer',
+            targetX,
+            targetY,
+            scaleFactor,
+            axisLeftLabelData,
+            matrixTop,
+            height,
+            matrixHeight,
+            cellHeight,
+            cellWidth,
+            axisTopLabelData,
+            matrixLeft,
+            width,
+            matrixWidth,
+            viewHeight,
+            viewWidth,
+            theme,
+            axisLeftTitle,
+            axisTopTitle,
+            axisOffsetLeft,
+            axisOffsetTop,
+            cellColorLabelsData,
+            hideTopLabels,
+            hideLeftLabels,
+            transpose,
+        }),
+    ];
+    useEffect(() => {
+        setNumCellColorTracks(cellColorLabels.length);
+    }, [cellColorLabels]);
+    // Create the left color bar with a BitmapLayer.
+    // TODO: find a way to do aggregation for this as well.
+    const cellColorsTilesList = useMemo(() => {
+        if (!cellColors) {
+            return null;
+        }
+        let cellId;
+        let offset;
+        let color;
+        let rowI;
+        const cellOrdering = (transpose ? axisTopLabels : axisLeftLabels);
+        const colorBarTileWidthPx = (transpose ? TILE_SIZE : 1);
+        const colorBarTileHeightPx = (transpose ? 1 : TILE_SIZE);
+        const result = range(numCellColorTracks).map((track) => {
+            const trackResult = range((transpose ? xTiles : yTiles)).map((i) => {
+                const tileData = new Uint8ClampedArray(TILE_SIZE * 1 * 4);
+                range(TILE_SIZE).forEach((tileY) => {
+                    rowI = (i * TILE_SIZE) + tileY; // the row / cell index
+                    if (rowI < cellOrdering.length) {
+                        cellId = cellOrdering[rowI];
+                        color = cellColors.get(cellId);
+                        offset = (transpose ? tileY : (TILE_SIZE - tileY - 1)) * 4;
+                        if (color) {
+                            // allows color to be [R, G, B] or array of arrays of [R, G, B]
+                            if (typeof color[0] !== 'number')
+                                color = color[track] ?? getDefaultColor(theme);
+                            const [rValue, gValue, bValue] = color;
+                            tileData[offset + 0] = rValue;
+                            tileData[offset + 1] = gValue;
+                            tileData[offset + 2] = bValue;
+                            tileData[offset + 3] = 255;
+                        }
+                    }
+                });
+                return new ImageData(tileData, colorBarTileWidthPx, colorBarTileHeightPx);
+            });
+            return trackResult;
+        });
+        return result;
+    }, [cellColors, transpose, axisTopLabels, axisLeftLabels,
+        numCellColorTracks, xTiles, yTiles, theme]);
+    const cellColorsLayersList = useMemo(() => {
+        if (!cellColorsTilesList) {
+            return [];
+        }
+        const result = cellColorsTilesList.map((cellColorsTiles, track) => (cellColorsTiles
+            ? cellColorsTiles.map((tile, i) => new PixelatedBitmapLayer({
+                id: `${(transpose ? 'colorsTopLayer' : 'colorsLeftLayer')}-${track}-${i}-${uuidv4()}`,
+                image: tile,
+                bounds: (transpose ? [
+                    matrixLeft + i * tileWidth,
+                    -matrixHeight / 2,
+                    matrixLeft + (i + 1) * tileWidth,
+                    matrixHeight / 2,
+                ] : [
+                    -matrixWidth / 2,
+                    matrixTop + i * tileHeight,
+                    matrixWidth / 2,
+                    matrixTop + (i + 1) * tileHeight,
+                ]),
+            }))
+            : []));
+        return (result);
+    }, [cellColorsTilesList, matrixTop, matrixLeft, matrixHeight,
+        matrixWidth, tileWidth, tileHeight, transpose]);
+    const layers = heatmapLayers
+        .concat(textLayers)
+        .concat(...cellColorsLayersList);
+    // Set up the onHover function.
+    function onHover(info, event) {
+        if (!expression) {
+            return;
+        }
+        const { x: mouseX, y: mouseY } = event.offsetCenter;
+        const [trackColI, trackI] = mouseToCellColorPosition(mouseX, mouseY, {
+            axisOffsetTop,
+            axisOffsetLeft,
+            offsetTop,
+            offsetLeft,
+            colorBarSize: COLOR_BAR_SIZE,
+            numCellColorTracks,
+            transpose,
+            targetX,
+            targetY,
+            scaleFactor,
+            matrixWidth,
+            matrixHeight,
+            numRows: height,
+            numCols: width,
+        });
+        if (trackI === null || trackColI === null) {
+            setTrackHighlight(null);
+        }
+        else {
+            const obsI = expression.rows.indexOf(axisTopLabels[trackColI]);
+            const cellIndex = expression.rows[obsI];
+            setTrackHighlight([cellIndex, trackI, mouseX, mouseY]);
+        }
+        const [colI, rowI] = mouseToHeatmapPosition(mouseX, mouseY, {
+            offsetLeft,
+            offsetTop,
+            targetX,
+            targetY,
+            scaleFactor,
+            matrixWidth,
+            matrixHeight,
+            numRows: height,
+            numCols: width,
+        });
+        if (colI === null) {
+            if (transpose) {
+                setCellHighlight(null);
+            }
+            else {
+                setGeneHighlight(null);
+            }
+        }
+        if (rowI === null) {
+            if (transpose) {
+                setGeneHighlight(null);
+            }
+            else {
+                setCellHighlight(null);
+            }
+        }
+        const obsI = expression.rows.indexOf(transpose
+            ? axisTopLabels[colI]
+            : axisLeftLabels[rowI]);
+        const varI = expression.cols.indexOf(transpose
+            ? axisLeftLabels[rowI]
+            : axisTopLabels[colI]);
+        const obsId = expression.rows[obsI];
+        const varId = expression.cols[varI];
+        if (setComponentHover) {
+            setComponentHover();
+        }
+        setCellHighlight(obsId || null);
+        setGeneHighlight(varId || null);
+    }
+    const cellColorsViews = useMemo(() => {
+        const result = range(numCellColorTracks).map((track) => {
+            let view;
+            if (transpose) {
+                view = new deck.OrthographicView({
+                    id: `colorsTop-${track}`,
+                    controller: true,
+                    x: offsetLeft,
+                    y: axisOffsetTop + track * COLOR_BAR_SIZE,
+                    width: matrixWidth,
+                    height: COLOR_BAR_SIZE - AXIS_MARGIN,
+                });
+            }
+            else {
+                view = new deck.OrthographicView({
+                    id: `colorsLeft-${track}`,
+                    controller: true,
+                    x: axisOffsetLeft + track * COLOR_BAR_SIZE,
+                    y: offsetTop,
+                    width: COLOR_BAR_SIZE - AXIS_MARGIN,
+                    height: matrixHeight,
+                });
+            }
+            return view;
+        });
+        return result;
+    }, [numCellColorTracks, transpose, offsetLeft, axisOffsetTop,
+        matrixWidth, axisOffsetLeft, offsetTop, matrixHeight]);
+    return (_jsx(deck.DeckGL, { id: `deckgl-overlay-${uuid}`, ref: deckRef, onWebGLInitialized: setGlContext, views: [
+            // Note that there are multiple views here,
+            // but only one viewState.
+            new deck.OrthographicView({
+                id: 'heatmap',
+                controller: true,
+                x: offsetLeft,
+                y: offsetTop,
+                width: matrixWidth,
+                height: matrixHeight,
+            }),
+            new deck.OrthographicView({
+                id: 'axisLeft',
+                controller: false,
+                x: 0,
+                y: offsetTop,
+                width: axisOffsetLeft,
+                height: matrixHeight,
+            }),
+            new deck.OrthographicView({
+                id: 'axisTop',
+                controller: false,
+                x: offsetLeft,
+                y: 0,
+                width: matrixWidth,
+                height: axisOffsetTop,
+            }),
+            new deck.OrthographicView({
+                id: 'cellColorLabel',
+                controller: false,
+                x: (transpose ? 0 : axisOffsetLeft),
+                y: (transpose ? axisOffsetTop : 0),
+                width: (transpose ? axisOffsetLeft : COLOR_BAR_SIZE * numCellColorTracks),
+                height: (transpose ? COLOR_BAR_SIZE * numCellColorTracks : axisOffsetTop),
+            }),
+            ...cellColorsViews,
+        ], layers: layers, layerFilter: layerFilter, getCursor: interactionState => (interactionState.isDragging ? 'grabbing' : 'default'), glOptions: DEFAULT_GL_OPTIONS, onViewStateChange: onViewStateChange, viewState: viewState, onHover: onHover, useDevicePixels: useDevicePixels }));
+});
+export default Heatmap;

package/dist/Heatmap.test.fixtures.js

@@ -0,0 +1,20 @@
+export const expressionMatrix = {
+    rows: ['cell-0', 'cell-1', 'cell-2', 'cell-3', 'cell-4'],
+    cols: ['gene-0', 'gene-1', 'gene-2', 'gene-3'],
+    // "An image with an 'F' on it has a clear direction so it's easy to tell
+    // if it's turned or flipped etc when we use it as a texture."
+    // - https://webglfundamentals.org/webgl/lessons/webgl-3d-textures.html
+    matrix: Uint8Array.from([
+        0, 255, 255, 0,
+        0, 255, 0, 0,
+        0, 255, 255, 0,
+        0, 255, 0, 0,
+        0, 255, 0, 0,
+    ]),
+};
+export const cellColors = new Map([
+    ['cell-1', [0, 0, 255]],
+    ['cell-0', [0, 0, 255]],
+    ['cell-3', [255, 0, 0]],
+    ['cell-2', [255, 0, 0]],
+]);

package/dist/Heatmap.test.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* eslint-disable func-names */
+import '@testing-library/jest-dom';
+import { cleanup, render } from '@testing-library/react';
+import { afterEach } from 'vitest';
+import Heatmap from './Heatmap';
+import { expressionMatrix, cellColors } from './Heatmap.test.fixtures';
+afterEach(() => {
+    cleanup();
+});
+describe('<Heatmap/>', () => {
+    it('renders a DeckGL element', function () {
+        const { container } = render(_jsx(Heatmap, { uuid: "heatmap-0", theme: "dark", width: 100, height: 100, colormap: "plasma", colormapRange: [0.0, 1.0], expressionMatrix: expressionMatrix, cellColors: cellColors, transpose: true, viewState: { zoom: 0, target: [0, 0] } }));
+        expect(container.querySelectorAll('#deckgl-overlay-heatmap-0-wrapper').length).toEqual(1);
+    });
+});

package/dist/HeatmapOptions.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback } from 'react';
+import debounce from 'lodash/debounce';
+import Slider from '@material-ui/core/Slider';
+import TableCell from '@material-ui/core/TableCell';
+import TableRow from '@material-ui/core/TableRow';
+import { usePlotOptionsStyles, OptionsContainer, OptionSelect } from '@vitessce/vit-s';
+import { GLSL_COLORMAPS } from '@vitessce/gl';
+export default function HeatmapOptions(props) {
+    const { geneExpressionColormap, setGeneExpressionColormap, geneExpressionColormapRange, setGeneExpressionColormapRange, } = props;
+    const classes = usePlotOptionsStyles();
+    function handleGeneExpressionColormapChange(event) {
+        setGeneExpressionColormap(event.target.value);
+    }
+    function handleColormapRangeChange(event, value) {
+        setGeneExpressionColormapRange(value);
+    }
+    const handleColormapRangeChangeDebounced = useCallback(debounce(handleColormapRangeChange, 5, { trailing: true }), [handleColormapRangeChange]);
+    return (_jsxs(OptionsContainer, { children: [_jsxs(TableRow, { children: [_jsx(TableCell, { className: classes.labelCell, htmlFor: "gene-expression-colormap-select", children: "Gene Expression Colormap" }), _jsx(TableCell, { className: classes.inputCell, children: _jsx(OptionSelect, { className: classes.select, value: geneExpressionColormap, onChange: handleGeneExpressionColormapChange, inputProps: {
+                                id: 'gene-expression-colormap-select',
+                            }, children: GLSL_COLORMAPS.map(cmap => (_jsx("option", { value: cmap, children: cmap }, cmap))) }) })] }), _jsxs(TableRow, { children: [_jsx(TableCell, { className: classes.labelCell, children: "Gene Expression Colormap Range" }), _jsx(TableCell, { className: classes.inputCell, children: _jsx(Slider, { classes: { root: classes.slider, valueLabel: classes.sliderValueLabel }, value: geneExpressionColormapRange, onChange: handleColormapRangeChangeDebounced, "aria-labelledby": "gene-expression-colormap-range-slider", valueLabelDisplay: "auto", step: 0.005, min: 0.0, max: 1.0 }) })] })] }));
+}

package/dist/HeatmapSubscriber.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState, useCallback, useMemo, } from 'react';
+import plur from 'plur';
+import { TitleInfo, useDeckCanvasSize, useGetObsInfo, useReady, useUrls, useObsSetsData, useObsFeatureMatrixData, useMultiObsLabels, useFeatureLabelsData, useCoordination, useLoaders, useSetComponentHover, useSetComponentViewInfo, registerPluginViewType, } from '@vitessce/vit-s';
+import { capitalize, commaNumber, getCellColors } from '@vitessce/utils';
+import { mergeObsSets } from '@vitessce/sets';
+import { COMPONENT_COORDINATION_TYPES, ViewType } from '@vitessce/constants-internal';
+import Heatmap from './Heatmap';
+import HeatmapTooltipSubscriber from './HeatmapTooltipSubscriber';
+import HeatmapOptions from './HeatmapOptions';
+/**
+ * @param {object} props
+ * @param {number} props.uuid The unique identifier for this component.
+ * @param {object} props.coordinationScopes The mapping from coordination types to coordination
+ * scopes.
+ * @param {function} props.removeGridComponent The callback function to pass to TitleInfo,
+ * to call when the component has been removed from the grid.
+ * @param {string} props.title The component title.
+ * @param {boolean} props.transpose Whether to
+ * render as cell-by-gene or gene-by-cell.
+ * @param {boolean} props.disableTooltip Whether to disable the
+ * tooltip on mouse hover.
+ */
+export function HeatmapSubscriber(props) {
+    const { uuid, coordinationScopes, removeGridComponent, theme, transpose, observationsLabelOverride, variablesLabelOverride, disableTooltip = false, title = 'Heatmap', } = props;
+    const loaders = useLoaders();
+    const setComponentHover = useSetComponentHover();
+    const setComponentViewInfo = useSetComponentViewInfo(uuid);
+    // Get "props" from the coordination space.
+    const [{ dataset, obsType, featureType, featureValueType, heatmapZoomX: zoomX, heatmapTargetX: targetX, heatmapTargetY: targetY, featureSelection: geneSelection, obsHighlight: cellHighlight, featureHighlight: geneHighlight, obsSetSelection: cellSetSelection, obsSetColor: cellSetColor, additionalObsSets: additionalCellSets, featureValueColormap: geneExpressionColormap, featureValueColormapRange: geneExpressionColormapRange, }, { setHeatmapZoomX: setZoomX, setHeatmapZoomY: setZoomY, setHeatmapTargetX: setTargetX, setHeatmapTargetY: setTargetY, setObsHighlight: setCellHighlight, setFeatureHighlight: setGeneHighlight, setObsSetSelection: setCellSetSelection, setObsSetColor: setCellSetColor, setFeatureValueColormapRange: setGeneExpressionColormapRange, setFeatureValueColormap: setGeneExpressionColormap, }] = useCoordination(COMPONENT_COORDINATION_TYPES[ViewType.HEATMAP], coordinationScopes);
+    const observationsLabel = observationsLabelOverride || obsType;
+    const observationsPluralLabel = plur(observationsLabel);
+    const variablesLabel = variablesLabelOverride || featureType;
+    const variablesPluralLabel = plur(variablesLabel);
+    const observationsTitle = capitalize(observationsPluralLabel);
+    const variablesTitle = capitalize(variablesPluralLabel);
+    const [isRendering, setIsRendering] = useState(false);
+    const [urls, addUrl] = useUrls(loaders, dataset);
+    const [width, height, deckRef] = useDeckCanvasSize();
+    // Get data from loaders using the data hooks.
+    const [obsLabelsTypes, obsLabelsData] = useMultiObsLabels(coordinationScopes, obsType, loaders, dataset, addUrl);
+    // TODO: support multiple feature labels using featureLabelsType coordination values.
+    const [{ featureLabelsMap }, featureLabelsStatus] = useFeatureLabelsData(loaders, dataset, addUrl, false, {}, {}, { featureType });
+    const [{ obsIndex, featureIndex, obsFeatureMatrix }, matrixStatus] = useObsFeatureMatrixData(loaders, dataset, addUrl, true, {}, {}, { obsType, featureType, featureValueType });
+    const [{ obsSets: cellSets, obsSetsMembership }, obsSetsStatus] = useObsSetsData(loaders, dataset, addUrl, false, { setObsSetSelection: setCellSetSelection, setObsSetColor: setCellSetColor }, { obsSetSelection: cellSetSelection, obsSetColor: cellSetColor }, { obsType });
+    const isReady = useReady([
+        featureLabelsStatus,
+        matrixStatus,
+        obsSetsStatus,
+    ]);
+    const mergedCellSets = useMemo(() => mergeObsSets(cellSets, additionalCellSets), [cellSets, additionalCellSets]);
+    const cellColors = useMemo(() => getCellColors({
+        // Only show cell set selection on heatmap labels.
+        cellColorEncoding: 'cellSetSelection',
+        geneSelection,
+        cellSets: mergedCellSets,
+        cellSetSelection,
+        cellSetColor,
+        obsIndex,
+        theme,
+    }), [mergedCellSets, geneSelection, theme,
+        cellSetColor, cellSetSelection, obsIndex]);
+    const getObsInfo = useGetObsInfo(observationsLabel, obsLabelsTypes, obsLabelsData, obsSetsMembership);
+    const getFeatureInfo = useCallback((featureId) => {
+        if (featureId) {
+            return { [`${capitalize(variablesLabel)} ID`]: featureId };
+        }
+        return null;
+    }, [variablesLabel]);
+    const expressionMatrix = useMemo(() => {
+        if (obsIndex && featureIndex && obsFeatureMatrix) {
+            return {
+                rows: obsIndex,
+                cols: (featureLabelsMap
+                    ? featureIndex.map(key => featureLabelsMap.get(key) || key)
+                    : featureIndex),
+                matrix: obsFeatureMatrix.data,
+            };
+        }
+        return null;
+    }, [obsIndex, featureIndex, obsFeatureMatrix, featureLabelsMap]);
+    const cellsCount = obsIndex ? obsIndex.length : 0;
+    const genesCount = featureIndex ? featureIndex.length : 0;
+    const setTrackHighlight = useCallback(() => {
+        // No-op, since the default handler
+        // logs in the console on every hover event.
+    }, []);
+    const cellColorLabels = useMemo(() => ([
+        `${capitalize(observationsLabel)} Set`,
+    ]), [observationsLabel]);
+    const selectedCount = cellColors.size;
+    return (_jsxs(TitleInfo, { title: title, info: `${commaNumber(cellsCount)} ${plur(observationsLabel, cellsCount)} × ${commaNumber(genesCount)} ${plur(variablesLabel, genesCount)},
+             with ${commaNumber(selectedCount)} ${plur(observationsLabel, selectedCount)} selected`, urls: urls, theme: theme, removeGridComponent: removeGridComponent, isReady: isReady && !isRendering, options: (_jsx(HeatmapOptions, { geneExpressionColormap: geneExpressionColormap, setGeneExpressionColormap: setGeneExpressionColormap, geneExpressionColormapRange: geneExpressionColormapRange, setGeneExpressionColormapRange: setGeneExpressionColormapRange })), children: [_jsx(Heatmap, { ref: deckRef, transpose: transpose, viewState: { zoom: zoomX, target: [targetX, targetY] }, setViewState: ({ zoom, target }) => {
+                    setZoomX(zoom);
+                    setZoomY(zoom);
+                    setTargetX(target[0]);
+                    setTargetY(target[1]);
+                }, colormapRange: geneExpressionColormapRange, setColormapRange: setGeneExpressionColormapRange, height: height, width: width, theme: theme, uuid: uuid, expressionMatrix: expressionMatrix, cellColors: cellColors, colormap: geneExpressionColormap, setIsRendering: setIsRendering, setCellHighlight: setCellHighlight, setGeneHighlight: setGeneHighlight, setTrackHighlight: setTrackHighlight, setComponentHover: () => {
+                    setComponentHover(uuid);
+                }, updateViewInfo: setComponentViewInfo, observationsTitle: observationsTitle, variablesTitle: variablesTitle, variablesDashes: false, observationsDashes: false, cellColorLabels: cellColorLabels, useDevicePixels: true }), !disableTooltip && (_jsx(HeatmapTooltipSubscriber, { parentUuid: uuid, width: width, height: height, transpose: transpose, getObsInfo: getObsInfo, getFeatureInfo: getFeatureInfo, obsHighlight: cellHighlight, featureHighlight: geneHighlight }))] }));
+}
+export function register() {
+    registerPluginViewType(ViewType.HEATMAP, HeatmapSubscriber, COMPONENT_COORDINATION_TYPES[ViewType.HEATMAP]);
+}

package/dist/HeatmapTooltipSubscriber.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { Tooltip2D, TooltipContent } from '@vitessce/tooltip';
+import { useComponentHover, useComponentViewInfo } from '@vitessce/vit-s';
+export default function HeatmapTooltipSubscriber(props) {
+    const { parentUuid, width, height, transpose, getObsInfo, getFeatureInfo, obsHighlight, featureHighlight, } = props;
+    const sourceUuid = useComponentHover();
+    const viewInfo = useComponentViewInfo(parentUuid);
+    const [cellInfo, cellCoord] = (obsHighlight && getObsInfo ? ([
+        getObsInfo(obsHighlight),
+        (viewInfo && viewInfo.project
+            ? viewInfo.project(obsHighlight, null)[(transpose ? 0 : 1)]
+            : null),
+    ]) : ([null, null]));
+    const [geneInfo, geneCoord] = (featureHighlight && getFeatureInfo ? ([
+        getFeatureInfo(featureHighlight),
+        (viewInfo && viewInfo.project
+            ? viewInfo.project(null, featureHighlight)[(transpose ? 1 : 0)]
+            : null),
+    ]) : ([null, null]));
+    const x = (transpose ? cellCoord : geneCoord);
+    const y = (transpose ? geneCoord : cellCoord);
+    return ((cellInfo || geneInfo ? (_jsx(Tooltip2D, { x: x, y: y, parentUuid: parentUuid, parentWidth: width, parentHeight: height, sourceUuid: sourceUuid, children: _jsx(TooltipContent, { info: { ...geneInfo, ...cellInfo } }) })) : null));
+}

package/dist/HeatmapWorkerPool.js

@@ -0,0 +1,49 @@
+import { HeatmapWorker } from '@vitessce/workers';
+import { Pool } from '@vitessce/utils';
+// Reference: https://github.com/developit/jsdom-worker/issues/14#issuecomment-1268070123
+function createWorker() {
+    return new HeatmapWorker();
+}
+/**
+ * Pool for workers to decode chunks of the images.
+ * This is a line-for-line copy of GeoTIFFs old implementation: https://github.com/geotiffjs/geotiff.js/blob/v1.0.0-beta.6/src/pool.js
+ */
+export default class HeatmapPool extends Pool {
+    constructor() {
+        super(createWorker);
+    }
+    /**
+     * Process each heatmap tile
+     * @param {object} params The arguments passed to the heatmap worker.
+     * @param {string} params.curr The current task uuid.
+     * @param {number} params.xTiles How many tiles required in the x direction?
+     * @param {number} params.yTiles How many tiles required in the y direction?
+     * @param {number} params.tileSize How many entries along each tile axis?
+     * @param {string[]} params.cellOrdering The current ordering of cells.
+     * @param {string[]} params.rows The name of each row (cell ID).
+     * Does not take transpose into account (always cells).
+     * @param {string[]} params.cols The name of each column (gene ID).
+     * Does not take transpose into account (always genes).
+     * @param {ArrayBuffer} params.data The array buffer.
+     * Need to transfer back to main thread when done.
+     * @param {boolean} params.transpose Is the heatmap transposed?
+     * @returns {array} [message, transfers]
+     * @returns {Promise.<ArrayBuffer>} the decoded result as a `Promise`
+     */
+    async process(args) {
+        const currentWorker = await this.waitForWorker();
+        return new Promise((resolve, reject) => {
+            currentWorker.onmessage = (event) => {
+                // this.workers.push(currentWorker);
+                this.finishTask(currentWorker);
+                resolve(event.data);
+            };
+            currentWorker.onerror = (error) => {
+                // this.workers.push(currentWorker);
+                this.finishTask(currentWorker);
+                reject(error);
+            };
+            currentWorker.postMessage(['getTile', args], [args.data]);
+        });
+    }
+}

package/dist/heatmap.worker.js

@@ -0,0 +1,56 @@
+/* eslint-disable no-restricted-globals */
+import { getCellByGeneTile, getGeneByCellTile } from './utils';
+/**
+ * Map a gene expression matrix onto multiple square array tiles,
+ * taking into account the ordering/selection of cells.
+ * @param {object} params
+ * @param {string} params.curr The current task uuid.
+ * @param {number} params.xTiles How many tiles required in the x direction?
+ * @param {number} params.yTiles How many tiles required in the y direction?
+ * @param {number} params.tileSize How many entries along each tile axis?
+ * @param {string[]} params.cellOrdering The current ordering of cells.
+ * @param {string[]} params.cols The name of each column (gene ID).
+ * Does not take transpose into account (always genes).
+ * @param {ArrayBuffer} params.data The array buffer.
+ * Need to transfer back to main thread when done.
+ * @param {boolean} params.transpose Is the heatmap transposed?
+ * @param {boolean} params.expressionRowLookUp A lookup table for the array index of a given cell.
+ * This is needed for performance reasons instead of calling `indexOf` repeatedly.
+ * @returns {array} [message, transfers]
+ */
+function getTile({ curr, tileI, tileJ, tileSize, cellOrdering, cols, data, transpose, expressionRowLookUp, }) {
+    const view = new Uint8Array(data);
+    const numGenes = cols.length;
+    const numCells = cellOrdering.length;
+    const getTileFunction = (transpose ? getGeneByCellTile : getCellByGeneTile);
+    const result = getTileFunction(view, {
+        tileSize,
+        tileI,
+        tileJ,
+        numCells,
+        numGenes,
+        cellOrdering,
+        expressionRowLookUp,
+    });
+    return [{ tile: result, buffer: data, curr }, [data]];
+}
+/**
+ * Worker message passing logic.
+ */
+if (typeof self !== 'undefined') {
+    const nameToFunction = {
+        getTile,
+    };
+    self.addEventListener('message', (event) => {
+        try {
+            if (Array.isArray(event.data)) {
+                const [name, args] = event.data;
+                const [message, transfers] = nameToFunction[name](args);
+                self.postMessage(message, transfers);
+            }
+        }
+        catch (e) {
+            console.warn(e);
+        }
+    });
+}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { HeatmapSubscriber, register } from './HeatmapSubscriber';
+export { default as Heatmap } from './Heatmap';

package/dist/utils.js

@@ -0,0 +1,181 @@
+import clamp from 'lodash/clamp';
+import { AXIS_LABEL_TEXT_SIZE, AXIS_FONT_FAMILY, AXIS_PADDING, AXIS_MIN_SIZE, AXIS_MAX_SIZE, } from '@vitessce/gl';
+/**
+ * Called before a layer is drawn to determine whether it should be rendered.
+ * Reference: https://deck.gl/docs/api-reference/core/deck#layerfilter
+ * @param {object} params A viewport, layer pair.
+ * @param {object} params.layer The layer to check.
+ * @param {object} params.viewport The viewport to check.
+ * @returns {boolean} Should this layer be rendered in this viewport?
+ */
+export function layerFilter({ layer, viewport }) {
+    if (viewport.id === 'axisLeft') {
+        return layer.id.startsWith('axisLeft');
+    }
+    if (viewport.id === 'axisTop') {
+        return layer.id.startsWith('axisTop');
+    }
+    if (viewport.id === 'cellColorLabel') {
+        return layer.id.startsWith('cellColorLabel');
+    }
+    if (viewport.id === 'heatmap') {
+        return layer.id.startsWith('heatmap');
+    }
+    if (viewport.id.startsWith('colorsLeft')) {
+        const matches = viewport.id.match(/-(\d)/);
+        if (matches)
+            return layer.id.startsWith(`colorsLeftLayer-${matches[1]}`);
+    }
+    if (viewport.id.startsWith('colorsTop')) {
+        const matches = viewport.id.match(/-(\d)/);
+        if (matches)
+            return layer.id.startsWith(`colorsTopLayer-${matches[1]}`);
+    }
+    return false;
+}
+/**
+ * Uses canvas.measureText to compute and return the width of the given text
+ * of given font in pixels.
+ *
+ * @param {String} text The text to be rendered.
+ * @param {String} font The css font descriptor that text is to be rendered
+ * with (e.g. "bold 14px verdana").
+ *
+ * @see https://stackoverflow.com/questions/118241/calculate-text-width-with-javascript/21015393#21015393
+ */
+function getTextWidth(text, font) {
+    // re-use canvas object for better performance
+    const canvas = getTextWidth.canvas || (getTextWidth.canvas = document.createElement('canvas'));
+    const context = canvas.getContext('2d');
+    context.font = font;
+    const metrics = context.measureText(text);
+    return metrics.width;
+}
+/**
+ * Get the size of the left and top heatmap axes,
+ * taking into account the maximum label string lengths.
+ * @param {boolean} transpose Is the heatmap transposed?
+ * @param {String} longestGeneLabel longest gene label
+ * @param {String} longestCellLabel longest cell label
+ * @param {boolean} hideObservationLabels are cell labels hidden?
+ * @param {boolean} hideVariableLabels are gene labels hidden?
+ * Increases vertical space for heatmap
+ * @returns {number[]} [axisOffsetLeft, axisOffsetTop]
+ */
+export function getAxisSizes(transpose, longestGeneLabel, longestCellLabel, hideObservationLabels, hideVariableLabels) {
+    const font = `${AXIS_LABEL_TEXT_SIZE}pt ${AXIS_FONT_FAMILY}`;
+    const geneLabelMaxWidth = hideVariableLabels
+        ? 0 : getTextWidth(longestGeneLabel, font) + AXIS_PADDING;
+    const cellLabelMaxWidth = hideObservationLabels
+        ? 0 : getTextWidth(longestCellLabel, font) + AXIS_PADDING;
+    const axisOffsetLeft = clamp((transpose ? geneLabelMaxWidth : cellLabelMaxWidth), AXIS_MIN_SIZE, AXIS_MAX_SIZE);
+    const axisOffsetTop = clamp((transpose ? cellLabelMaxWidth : geneLabelMaxWidth), AXIS_MIN_SIZE, AXIS_MAX_SIZE);
+    return [axisOffsetLeft, axisOffsetTop];
+}
+/**
+ * Convert a mouse coordinate (x, y) to a heatmap coordinate (col index, row index).
+ * @param {number} mouseX The mouse X of interest.
+ * @param {number} mouseY The mouse Y of interest.
+ * @param {object} param2 An object containing current sizes and scale factors.
+ * @returns {number[]} [colI, rowI]
+ */
+export function mouseToHeatmapPosition(mouseX, mouseY, { offsetLeft, offsetTop, targetX, targetY, scaleFactor, matrixWidth, matrixHeight, numRows, numCols, }) {
+    // TODO: use linear algebra
+    const viewMouseX = mouseX - offsetLeft;
+    const viewMouseY = mouseY - offsetTop;
+    if (viewMouseX < 0 || viewMouseY < 0) {
+        // The mouse is outside the heatmap.
+        return [null, null];
+    }
+    // Determine the rowI and colI values based on the current viewState.
+    const bboxTargetX = targetX * scaleFactor + matrixWidth * scaleFactor / 2;
+    const bboxTargetY = targetY * scaleFactor + matrixHeight * scaleFactor / 2;
+    const bboxLeft = bboxTargetX - matrixWidth / 2;
+    const bboxTop = bboxTargetY - matrixHeight / 2;
+    const zoomedOffsetLeft = bboxLeft / (matrixWidth * scaleFactor);
+    const zoomedOffsetTop = bboxTop / (matrixHeight * scaleFactor);
+    const zoomedViewMouseX = viewMouseX / (matrixWidth * scaleFactor);
+    const zoomedViewMouseY = viewMouseY / (matrixHeight * scaleFactor);
+    const zoomedMouseX = zoomedOffsetLeft + zoomedViewMouseX;
+    const zoomedMouseY = zoomedOffsetTop + zoomedViewMouseY;
+    const rowI = Math.floor(zoomedMouseY * numRows);
+    const colI = Math.floor(zoomedMouseX * numCols);
+    return [colI, rowI];
+}
+/**
+ * Convert a heatmap coordinate (col index, row index) to a mouse coordinate (x, y).
+ * @param {number} colI The column index of interest.
+ * @param {number} rowI The row index of interest.
+ * @param {object} param2 An object containing current sizes and scale factors.
+ * @returns {number[]} [x, y]
+ */
+export function heatmapToMousePosition(colI, rowI, { offsetLeft, offsetTop, targetX, targetY, scaleFactor, matrixWidth, matrixHeight, numRows, numCols, }) {
+    // TODO: use linear algebra
+    let zoomedMouseY = null;
+    let zoomedMouseX = null;
+    if (rowI !== null) {
+        const minY = -matrixHeight * scaleFactor / 2;
+        const maxY = matrixHeight * scaleFactor / 2;
+        const totalHeight = maxY - minY;
+        const minInViewY = (targetY * scaleFactor) - (matrixHeight / 2);
+        const maxInViewY = (targetY * scaleFactor) + (matrixHeight / 2);
+        const inViewHeight = maxInViewY - minInViewY;
+        const normalizedRowY = (rowI + 0.5) / numRows;
+        const globalRowY = minY + (normalizedRowY * totalHeight);
+        if (minInViewY <= globalRowY && globalRowY <= maxInViewY) {
+            zoomedMouseY = offsetTop + ((globalRowY - minInViewY) / inViewHeight) * matrixHeight;
+        }
+    }
+    if (colI !== null) {
+        const minX = -matrixWidth * scaleFactor / 2;
+        const maxX = matrixWidth * scaleFactor / 2;
+        const totalWidth = maxX - minX;
+        const minInViewX = (targetX * scaleFactor) - (matrixWidth / 2);
+        const maxInViewX = (targetX * scaleFactor) + (matrixWidth / 2);
+        const inViewWidth = maxInViewX - minInViewX;
+        const normalizedRowX = (colI + 0.5) / numCols;
+        const globalRowX = minX + (normalizedRowX * totalWidth);
+        if (minInViewX <= globalRowX && globalRowX <= maxInViewX) {
+            zoomedMouseX = offsetLeft + ((globalRowX - minInViewX) / inViewWidth) * matrixWidth;
+        }
+    }
+    return [zoomedMouseX, zoomedMouseY];
+}
+/**
+ * Convert a mouse coordinate (x, y) to a heatmap color bar coordinate (cell index, track index).
+ * @param {number} mouseX The mouse X of interest.
+ * @param {number} mouseY The mouse Y of interest.
+ * @param {object} param2 An object containing current sizes and scale factors.
+ * @returns {number[]} [cellI, trackI]
+ */
+export function mouseToCellColorPosition(mouseX, mouseY, { axisOffsetTop, axisOffsetLeft, offsetTop, offsetLeft, colorBarSize, numCellColorTracks, transpose, targetX, targetY, scaleFactor, matrixWidth, matrixHeight, numRows, numCols, }) {
+    const cellPosition = transpose ? mouseX - offsetLeft : mouseY - offsetTop;
+    const trackPosition = transpose ? mouseY - axisOffsetTop : mouseX - axisOffsetLeft;
+    const tracksWidth = numCellColorTracks * colorBarSize;
+    // outside of cell color tracks
+    if (cellPosition < 0 || trackPosition < 0 || trackPosition >= tracksWidth) {
+        return [null, null];
+    }
+    // Determine the trackI and cellI values based on the current viewState.
+    const trackI = Math.floor(trackPosition / colorBarSize);
+    let cellI;
+    if (transpose) {
+        const viewMouseX = mouseX - offsetLeft;
+        const bboxTargetX = targetX * scaleFactor + matrixWidth * scaleFactor / 2;
+        const bboxLeft = bboxTargetX - matrixWidth / 2;
+        const zoomedOffsetLeft = bboxLeft / (matrixWidth * scaleFactor);
+        const zoomedViewMouseX = viewMouseX / (matrixWidth * scaleFactor);
+        const zoomedMouseX = zoomedOffsetLeft + zoomedViewMouseX;
+        cellI = Math.floor(zoomedMouseX * numCols);
+        return [cellI, trackI];
+    }
+    // Not transposed
+    const viewMouseY = mouseY - axisOffsetTop;
+    const bboxTargetY = targetY * scaleFactor + matrixHeight * scaleFactor / 2;
+    const bboxTop = bboxTargetY - matrixHeight / 2;
+    const zoomedOffsetTop = bboxTop / (matrixHeight * scaleFactor);
+    const zoomedViewMouseY = viewMouseY / (matrixHeight * scaleFactor);
+    const zoomedMouseY = zoomedOffsetTop + zoomedViewMouseY;
+    cellI = Math.floor(zoomedMouseY * numRows);
+    return [cellI, trackI];
+}

package/dist/utils.test.js

@@ -0,0 +1,71 @@
+import { mouseToHeatmapPosition, heatmapToMousePosition } from './utils';
+describe('heatmap tooltip utils', () => {
+    it('transforms mouse coordinates to row and column indices when zoomed out', () => {
+        const mouseX = 35;
+        const mouseY = 78;
+        const [colI, rowI] = mouseToHeatmapPosition(mouseX, mouseY, {
+            offsetLeft: 10,
+            offsetTop: 10,
+            targetX: 0,
+            targetY: 0,
+            scaleFactor: 1,
+            matrixWidth: 100,
+            matrixHeight: 100,
+            numRows: 5,
+            numCols: 4,
+        });
+        expect(colI).toEqual(1);
+        expect(rowI).toEqual(3);
+    });
+    it('transforms mouse coordinates to row and column indices when zoomed in', () => {
+        const mouseX = 35;
+        const mouseY = 78;
+        const [colI, rowI] = mouseToHeatmapPosition(mouseX, mouseY, {
+            offsetLeft: 10,
+            offsetTop: 10,
+            targetX: 21,
+            targetY: -11,
+            scaleFactor: 4,
+            matrixWidth: 100,
+            matrixHeight: 100,
+            numRows: 5,
+            numCols: 4,
+        });
+        expect(colI).toEqual(2);
+        expect(rowI).toEqual(2);
+    });
+    it('transforms row and column indices when zoomed out', () => {
+        const colI = 1;
+        const rowI = 3;
+        const [mouseX, mouseY] = heatmapToMousePosition(colI, rowI, {
+            offsetLeft: 10,
+            offsetTop: 10,
+            targetX: 0,
+            targetY: 0,
+            scaleFactor: 1,
+            matrixWidth: 100,
+            matrixHeight: 100,
+            numRows: 5,
+            numCols: 4,
+        });
+        expect(mouseX).toEqual(47.5);
+        expect(mouseY).toEqual(80);
+    });
+    it('transforms row and column indices when zoomed in', () => {
+        const colI = 2;
+        const rowI = 2;
+        const [mouseX, mouseY] = heatmapToMousePosition(colI, rowI, {
+            offsetLeft: 10,
+            offsetTop: 10,
+            targetX: 21,
+            targetY: -11,
+            scaleFactor: 4,
+            matrixWidth: 100,
+            matrixHeight: 100,
+            numRows: 5,
+            numCols: 4,
+        });
+        expect(mouseX).toEqual(26);
+        expect(mouseY).toEqual(104);
+    });
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vitessce/heatmap",
+  "version": "2.0.0-beta.0",
+  "author": "Gehlenborg Lab",
+  "homepage": "http://vitessce.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vitessce/vitessce.git"
+  },
+  "license": "MIT",
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@material-ui/core": "~4.12.3",
+    "@vitessce/constants-internal": "2.0.0-beta.0",
+    "@vitessce/gl": "2.0.0-beta.0",
+    "@vitessce/sets": "2.0.0-beta.0",
+    "@vitessce/tooltip": "2.0.0-beta.0",
+    "@vitessce/utils": "2.0.0-beta.0",
+    "@vitessce/vit-s": "2.0.0-beta.0",
+    "@vitessce/workers": "2.0.0-beta.0",
+    "lodash": "^4.17.21",
+    "plur": "^5.1.0",
+    "uuid": "^3.3.2"
+  },
+  "devDependencies": {
+    "react": "^18.0.0",
+    "vite": "^3.0.0",
+    "vitest": "^0.23.4"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0"
+  },
+  "scripts": {
+    "start": "tsc --watch",
+    "build": "tsc",
+    "test": "pnpm exec vitest --run -r ../../../ --dir ."
+  }
+}