@pluot/react 0.1.0 → 0.1.2

package/dist-tsc/Pluot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pluot.d.ts","sourceRoot":"","sources":["../src/Pluot.jsx"],"names":[],"mappings":"AAgDA,uCA+fC"}
+{"version":3,"file":"Pluot.d.ts","sourceRoot":"","sources":["../src/Pluot.jsx"],"names":[],"mappings":"AAiDA,uCAgZC"}

package/dist-tsc/Pluot.js

@@ -4,7 +4,7 @@ import { mat4, vec4 } from "gl-matrix";
 import lzs from "lz-string";
 import { isEqual, throttle } from "lodash-es";
 import { FetchStore } from 'zarrita';
-import { initialize, getIsWasmReady, render_wasm, pick_wasm, setStore, getStore, create2dCamera, create3dCamera, getBounds, getCameraMatrixFromBounds, checkWebGpuFeatureDetection, } from '@pluot/core';
+import { initialize, getIsWasmReady, render_wasm, pick_wasm, setStore, getStore, getBounds, getCameraMatrixFromBounds, checkWebGpuFeatureDetection, onMouseMove2d, onWheel2d, onMouseMove3d, onWheel3d, } from '@pluot/core';
 // Needed due to "SyntaxError: Named export 'decompressFromUint8Array' not found.
 // The requested module 'lz-string' is a CommonJS module,
 // which may not support all module.exports as named exports."
@@ -37,7 +37,31 @@ export function Pluot(props) {
     const { width: widthProp, height: heightProp, plotId, plotType, store, storeName: storeNameProp, plotParams, viewMode = "2d", marginBottom = 100.0, marginLeft = 100.0, marginTop = 100.0, marginRight = 100.0, aspectRatioMode = "Contain", // "Ignore", "Contain", "Cover"
     aspectRatioAlignmentMode = "Start", // "Center", "Start", "End"
     format = "Raster", // "Raster", "Vector"
-    minTimeout = 32, maxTimeout = 32, allowSimultaneousRenders = true, debugMargins = false, } = props;
+    minTimeout = 32, maxTimeout = 5000, allowSimultaneousRenders = true, debugMargins = false, cameraMatrix: controlledCameraMatrix = null, setCameraMatrix: setControlledCameraMatrix = null, enablePicking = true, backgroundColor = undefined, } = props;
+    // If cameraMatrix is not provided, then we manage the camera matrix internally.
+    const [uncontrolledCameraMatrix, setUncontrolledCameraMatrix] = useState(
+    // Note: We use an initializer function here to avoid
+    // sharing the same Float32Array among multiple Pluot
+    // component instances that may be rendered on the same page.
+    () => Float32Array.from(
+    // If the cameraMatrix prop was provided, use that for the initial camera matrix;
+    // otherwise use the default matrix.
+    controlledCameraMatrix === null
+        ? (viewMode === "2d" ? DEFAULT_VIEW : DEFAULT_3D_VIEW)
+        : controlledCameraMatrix));
+    // Decide which camera matrix and setter to use.
+    // If the user provides the cameraMatrix prop but NOT the setCameraMatrix setter,
+    // then interpret the prop as the "initial" camera settings, but still treat as uncontrolled.
+    const isControlledCamera = typeof setControlledCameraMatrix === "function";
+    // Alternatively, if the user provides the setCameraMatrix setter, but NOT
+    // the cameraMatrix, interpret this as they want to use the default camera
+    // value initially, but they still want a controlled camera matrix.
+    const cameraMatrix = isControlledCamera && controlledCameraMatrix !== null
+        ? controlledCameraMatrix
+        : uncontrolledCameraMatrix;
+    const setCameraMatrix = isControlledCamera
+        ? setControlledCameraMatrix
+        : setUncontrolledCameraMatrix;
     const width = Math.floor(widthProp);
     const height = Math.floor(heightProp);
     const isVector = format === "Vector";
@@ -57,11 +81,11 @@ export function Pluot(props) {
     const [supportsWebGpu, supportsWebGpuMessage] = useMemo(checkWebGpuFeatureDetection, []);
     const svgRef = useRef(null);
     const canvasRef = useRef(null);
-    const cameraRef = useRef(null);
+    const cameraElementRef = useRef(null);
     const tempButtonRef = useRef(null);
     // We may want to update these things without triggering a re-render.
     const isRenderingRef = useRef(false);
-    const currentTimeout = useRef(maxTimeout);
+    const currentTimeout = useRef(minTimeout);
     // TODO: do we want to use the backlog approach or not?
     // (Similar to the one used in the Vitessce heatmap)
     // Reference: https://github.com/vitessce/vitessce/blob/71f17fb605768e0428fb15ed87b3ea34bcbb4803/packages/view-types/heatmap/src/Heatmap.js#L368
@@ -71,195 +95,41 @@ export function Pluot(props) {
     const [didFirstRender, setDidFirstRender] = useState(false);
     const [bailedEarly, setBailedEarly] = useState(true);
     const [pickingResult, setPickingResult] = useState(null);
-    // TODO: handle a viewMatrix that is provided and set via props,
-    // to enable usage as a controlled component
-    // (e.g., for linked views with shared cameras).
-    const [viewMatrix, setViewMatrix] = useState(
-    // Note: We use an initializer function here to avoid
-    // sharing the same Float32Array among multiple Pluot
-    // component instances that may be rendered on the same page.
-    () => new Float32Array(DEFAULT_VIEW));
     useLayoutEffect(() => {
         initialize().then(() => setIsWasmReady(getIsWasmReady()));
     }, []);
-    useEffect(() => {
-        // Reset view matrix on plot change.
-        // Create a new Float32Array to avoid sharing a mutable array
-        // among multiple Pluot component instances.
-        setViewMatrix(new Float32Array(viewMode === "2d" ? DEFAULT_VIEW : DEFAULT_3D_VIEW));
-        //viewMatrixRef.current = new Float32Array(DEFAULT_VIEW);
-    }, [plotId, viewMode]);
-    // Set up the camera.
-    useEffect(() => {
-        // Set up the camera.
-        const cameraEl = cameraRef.current;
-        if (!cameraEl) {
-            return () => { };
-        }
-        let dispose = () => { };
-        // Create a 2D camera for handling zoom and pan.
-        if (viewMode === "2d") {
-            function onCameraEvent(camera, event) {
-                camera.tick();
-                // Reference: https://github.com/flekschas/regl-scatterplot/blob/17a650c352fad313d1574472b2fdc5f58b9e1eca/src/index.js#L1648
-                setViewMatrix(prev => {
-                    // Since camera events happen even on mousemove events that do not change the matrix,
-                    // we check for equality here to avoid unnecessary state updates and plot re-renders.
-                    if (isEqual(prev, camera.view)) {
-                        return prev;
-                    }
-                    return mat4.clone(camera.view);
-                });
-                currentTimeout.current = minTimeout;
-            }
-            const camera = create2dCamera(cameraEl, {
-                isFixed: false,
-                distance: 0.0,
-                //target: [0.0, 0.0],
-                //viewCenter: [0.5, 0.5], // Should this be used when the coordinate system is (0 to 1) rather than (-1 to 1)?
-                viewCenter: [0.0, 0.0],
-                defaultMouseDownMoveAction: "pan",
-                onKeyDown: (event) => {
-                    onCameraEvent(camera, event);
-                },
-                onKeyUp: (event) => {
-                    onCameraEvent(camera, event);
-                },
-                onMouseDown: (event) => {
-                    onCameraEvent(camera, event);
-                },
-                onMouseUp: (event) => {
-                    onCameraEvent(camera, event);
-                },
-                onMouseMove: (event) => {
-                    onCameraEvent(camera, event);
-                },
-                onWheel: (event) => {
-                    onCameraEvent(camera, event);
-                },
-                aspectRatioMode: aspectRatioMode,
-                aspectRatioAlignmentMode: aspectRatioAlignmentMode,
-            });
-            // Set the initial view matrix.
-            // We need to ensure we create a new copy of the array.
-            camera.setView(new Float32Array(viewMatrix));
-            const tempHandler = e => {
-                // camera.setScaleBounds([[xScaleMin, xScaleMax], [yScaleMin, yScaleMax]])
-                //camera.lookAt([2.0, 2.0], 2.0);
-                //onCameraEvent(camera, null);
-                // Only zoom/pan the X axis; keep Y unchanged
-                const nextCameraMatrix = getCameraMatrixFromBounds({ yMin: 0.0, yMax: 100.0 }, new Float32Array(viewMatrix), {
-                    width,
-                    height,
-                    aspectRatioMode,
-                    aspectRatioAlignmentMode,
-                    margins: {
-                        marginTop,
-                        marginBottom,
-                        marginLeft,
-                        marginRight
-                    },
-                });
-                console.log("done", nextCameraMatrix);
-                camera.setView(nextCameraMatrix);
-                onCameraEvent(camera, null);
-            };
-            tempButtonRef.current.addEventListener('click', tempHandler);
-            // Set up an onClick handler.
-            //
-            const clickHandler = (event) => {
-                pickFrame(event.offsetX, event.offsetY);
-            };
-            cameraEl.addEventListener("click", clickHandler);
-            dispose = () => {
-                camera.dispose();
-                cameraEl.removeEventListener("click", clickHandler);
-                tempButtonRef.current.removeEventListener('click', tempHandler);
-            };
-        }
-        else if (viewMode === "3d") {
-            function onCameraEvent(camera, event) {
-                camera.tick();
-                // Note: the 3D camera stores the matrix in camera.matrix (not camera.view).
-                setViewMatrix(prev => {
-                    // Since camera events happen even on mousemove events that do not change the matrix,
-                    // we check for equality here to avoid unnecessary state updates and plot re-renders.
-                    if (isEqual(prev, camera.matrix)) {
-                        return prev;
-                    }
-                    return mat4.clone(camera.matrix);
-                });
-            }
-            const camera = create3dCamera(cameraEl, {
-                mode: "orbit",
-                zoomSpeed: -5,
-            });
-            // TODO:
-            // - fork 3d-view-controls and remove usage of "global" - then clean up vite config.
-            // - define a camera.dispsose option.
-            // Reference: https://github.com/flekschas/dom-2d-camera/blob/cd59ea035a0ea72c2c0535fa3721f8127946576c/src/index.js#L237C3-L315C71
-            const keyUpHandler = (event) => {
-                // TODO
-            };
-            const keyDownHandler = (event) => {
-                // TODO
-            };
-            const mouseUpHandler = (event) => {
-                // TODO
-            };
-            const mouseDownHandler = (event) => {
-                // TODO
-            };
-            // TODO: use react state?
-            var lastX = 0;
-            var lastY = 0;
-            // Reference: https://github.com/mikolalysenko/3d-view/blob/8269e02337bba1923173a750aa7f3f0f76c91ba5/example/minimal.js#L67
-            const mouseMoveHandler = (event) => {
-                /*
-                var dx = (event.clientX - lastX) / width;
-                var dy = -(event.clientY - lastY) / height;
-                if (event.which === 1) {
-                  if (event.shiftKey) {
-                    //zoom
-                    camera.rotate(now(), 0, 0, dx);
-                  } else {
-                    //rotate
-                    camera.rotate(now(), dx, dy);
-                  }
-                } else if (event.which === 3) {
-                  //pan
-                  camera.pan(now(), dx, dy);
-                }
-                lastX = event.clientX;
-                lastY = event.clientY;
-                */
-                onCameraEvent(camera, event);
-            };
-            const wheelHandler = (event) => {
-                //camera.pan(now(), 0, 0, event.deltaY);
-                onCameraEvent(camera, event);
-            };
-            cameraEl.addEventListener("keydown", keyDownHandler);
-            cameraEl.addEventListener("keyup", keyUpHandler);
-            cameraEl.addEventListener("mousedown", mouseDownHandler);
-            cameraEl.addEventListener("mouseup", mouseUpHandler);
-            cameraEl.addEventListener("mousemove", mouseMoveHandler);
-            cameraEl.addEventListener("wheel", wheelHandler);
-            dispose = () => {
-                cameraEl.removeEventListener("keydown", keyDownHandler);
-                cameraEl.removeEventListener("keyup", keyUpHandler);
-                cameraEl.removeEventListener("mousedown", mouseDownHandler);
-                cameraEl.removeEventListener("mouseup", mouseUpHandler);
-                cameraEl.removeEventListener("mousemove", mouseMoveHandler);
-                cameraEl.removeEventListener("wheel", wheelHandler);
-            };
-            //camera.matrix = new Float32Array(viewMatrix);
-        }
-        else {
-            throw new Error("Unknown mode found.");
-        }
-        return dispose;
-    }, [cameraRef, viewMode, aspectRatioMode, aspectRatioAlignmentMode, width, height, marginLeft, marginRight, marginTop, marginBottom]);
+    const wheelHandler = useEffectEvent((event) => {
+        const onWheel = viewMode === "3d" ? onWheel3d : onWheel2d;
+        const nextCameraMatrix = onWheel({
+            width,
+            height,
+            aspectRatioMode,
+            aspectRatioAlignmentMode,
+            margins: {
+                marginTop,
+                marginBottom,
+                marginLeft,
+                marginRight,
+            },
+        }, cameraMatrix, event);
+        setCameraMatrix(nextCameraMatrix);
+    });
+    const mouseMoveHandler = useEffectEvent((event) => {
+        const onMouseMove = viewMode === "3d" ? onMouseMove3d : onMouseMove2d;
+        const nextCameraMatrix = onMouseMove({
+            width,
+            height,
+            aspectRatioMode,
+            aspectRatioAlignmentMode,
+            margins: {
+                marginTop,
+                marginBottom,
+                marginLeft,
+                marginRight,
+            },
+        }, cameraMatrix, event);
+        setCameraMatrix(nextCameraMatrix);
+    });
     // The picking callback.
     const pickFrame = useEffectEvent(async (screenCoordX, screenCoordY) => {
         const renderParams = {
@@ -276,7 +146,7 @@ export function Pluot(props) {
             view_mode: viewMode,
             pickable: false,
             // Should see the latest viewMatrix here, since renderFrame is wrapped in useEffectEvent.
-            camera_view: viewMatrix,
+            camera_view: cameraMatrix,
             plot_id: plotId,
             plot_type: plotType,
             store_name: storeName,
@@ -294,6 +164,28 @@ export function Pluot(props) {
         // We also need to flip the Y coordinate so that positive is up.
         screenCoordX + marginLeft, marginBottom + (layerHeight - screenCoordY))));
     });
+    // Set up the camera and picking handlers.
+    useEffect(() => {
+        const cameraEl = cameraElementRef.current;
+        if (!cameraEl) {
+            return () => { };
+        }
+        // Create a 2D camera for handling zoom and pan.
+        cameraEl.addEventListener("mousemove", mouseMoveHandler);
+        cameraEl.addEventListener("wheel", wheelHandler);
+        // Set up an onClick handler for picking.
+        const clickHandler = (event) => {
+            if (enablePicking) {
+                pickFrame(event.offsetX, event.offsetY);
+            }
+        };
+        cameraEl.addEventListener("click", clickHandler);
+        return () => {
+            cameraEl.removeEventListener("mousemove", mouseMoveHandler);
+            cameraEl.removeEventListener("wheel", wheelHandler);
+            cameraEl.removeEventListener("click", clickHandler);
+        };
+    }, [viewMode, enablePicking]);
     // The renderFrame callback.
     // We use useEffectEvent because we want to "see"
     // the latest values of viewMatrix, plotProps, etc.
@@ -314,7 +206,7 @@ export function Pluot(props) {
             view_mode: viewMode,
             pickable: false,
             // Should see the latest viewMatrix here, since renderFrame is wrapped in useEffectEvent.
-            camera_view: viewMatrix,
+            camera_view: cameraMatrix,
             plot_id: plotId,
             plot_type: plotType,
             store_name: storeName,
@@ -364,12 +256,17 @@ export function Pluot(props) {
             ctx.putImageData(imageData, 0, 0);
             const frameBailedEarly = arr.at(-1) === 1;
             if (frameBailedEarly) {
-                currentTimeout.current = maxTimeout;
+                // We multiply the current timeout by two to implement an exponential backoff
+                // while the Rust side is bailing early.
+                // A downstream useEffect restarts the exponential backoff from scratch
+                // if any other plotting parameters change.
+                currentTimeout.current = Math.min(currentTimeout.current * 2, maxTimeout);
                 incBacklogIteration(); // Increment this to force a re-render.
                 setBailedEarly(true); // Update this to show the loading indicator.
             }
             else {
                 // Successful render.
+                currentTimeout.current = minTimeout;
                 setBailedEarly(false); // Update this to hide the loading indicator.
                 // Clear the LRU cache for the store (via its store_name) corresponding to the rendered plot.
                 const storeUsed = getStore(renderParams.store_name);
@@ -389,6 +286,15 @@ export function Pluot(props) {
     useEffect(() => {
         return () => throttledRender.cancel();
     }, [throttledRender]);
+    // Reset the backoff timeout whenever plot parameters change so the next
+    // sequence of bailed-early renders starts from the minimum again.
+    useEffect(() => {
+        currentTimeout.current = minTimeout;
+    }, [plotId, plotType, plotParams, storeName, format,
+        width, height, aspectRatioMode, aspectRatioAlignmentMode,
+        marginLeft, marginRight, marginTop, marginBottom,
+        cameraMatrix,
+    ]);
     // TODO: use react-query?
     useEffect(() => {
         if (!isWasmReady) {
@@ -404,9 +310,9 @@ export function Pluot(props) {
         }
         // Render on the next animation frame.
         throttledRender();
-    }, [isWasmReady, didFirstRender, viewMatrix, backlogIteration, plotId, plotType, plotParams, storeName, format,
+    }, [isWasmReady, didFirstRender, cameraMatrix, backlogIteration, plotId, plotType, plotParams, storeName, format,
         width, height, aspectRatioMode, aspectRatioAlignmentMode, marginLeft, marginRight, marginTop, marginBottom]);
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { style: { width, height, position: "relative" }, children: [!supportsWebGpu ? (_jsx("p", { children: supportsWebGpuMessage })) : null, _jsx("div", { ref: cameraRef, style: {
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { style: { width, height, position: "relative", backgroundColor }, children: [!supportsWebGpu ? (_jsx("p", { children: supportsWebGpuMessage })) : null, _jsx("div", { ref: cameraElementRef, style: {
                             position: "absolute",
                             top: marginTop,
                             left: marginLeft,

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@pluot/react",
   "private": false,
-  "version": "0.1.0",
-  "description": "",
+  "version": "0.1.2",
+  "description": "React component for visualization with Pluot",
   "license": "Apache-2.0",
+  "author": "Mark Keller",
+  "homepage": "https://pluot.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keller-mark/pluot.git"
+  },
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -30,7 +36,7 @@
     "mouse-wheel": "^1.0.2",
     "lz-string": "^1.5.0",
     "lodash-es": "^4.17.23",
-    "@pluot/core": "0.1.0"
+    "@pluot/core": "0.1.2"
   },
   "devDependencies": {
     "vitest": "^3.2.4",