@pluot/react 0.1.0

package/src/Pluot.jsx

@@ -0,0 +1,560 @@
+import React, { useLayoutEffect, useEffect, useEffectEvent, useRef, useState, useMemo, useReducer, useCallback } from "react";
+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';
+
+// 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."
+const { decompressFromUint8Array } = lzs;
+
+const DEFAULT_VIEW = new Float32Array([
+  1, 0, 0, 0,
+  0, 1, 0, 0,
+  0, 0, 1/200, 0,
+  0, 0, 0, 1,
+]);
+
+
+const DEFAULT_3D_VIEW = new Float32Array([
+  1, 0, 0, 0,
+  0, 1, 0, 0,
+  0, 0, 1, 0,
+  0, 0, -10, 1,
+]);
+
+function normalizePickingResult(data) {
+  const result = data;
+  if (data && Array.isArray(result.layer_results)) {
+    result.layer_results = result.layer_results.map(obj => ({
+      layer_id: obj.layer_id,
+      // This is needed because serde-wasm-bindgen
+      // converts Rust HashMap to JS Map.
+      info: Object.fromEntries(Array.from(obj.info)),
+    }));
+  }
+  return result;
+}
+
+
+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;
+
+  const width = Math.floor(widthProp);
+  const height = Math.floor(heightProp);
+
+  const isVector = format === "Vector";
+
+  const storeName = useMemo(() => {
+    if (storeNameProp) {
+      return storeNameProp;
+    }
+    // If store is a string, assume it is a URL and initialize a FetchStore here.
+    if (store) {
+      if (typeof store === 'string') {
+        return setStore(new FetchStore(store), plotId);
+      }
+      return setStore(store, plotId);
+    }
+    throw new Error("Either storeName or store must be provided.");
+  }, [storeNameProp, store]);
+
+  const [supportsWebGpu, supportsWebGpuMessage] = useMemo(checkWebGpuFeatureDetection, []);
+
+  const svgRef = useRef(null);
+  const canvasRef = useRef(null);
+  const cameraRef = 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);
+
+  // 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
+  //const backlogRef = useRef([]);
+  const [backlogIteration, incBacklogIteration] = useReducer(i => i + 1, 0);
+
+  const [isWasmReady, setIsWasmReady] = useState(false);
+  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]);
+
+  // The picking callback.
+  const pickFrame = useEffectEvent(async (screenCoordX, screenCoordY) => {
+    const renderParams = {
+      width,
+      height,
+      format: format,
+      margin_bottom: marginBottom,
+      margin_left: marginLeft,
+      margin_top: marginTop,
+      margin_right: marginRight,
+      device_pixel_ratio: window.devicePixelRatio,
+      aspect_ratio_mode: aspectRatioMode,
+      aspect_ratio_alignment_mode: aspectRatioAlignmentMode,
+      view_mode: viewMode,
+      pickable: false,
+      // Should see the latest viewMatrix here, since renderFrame is wrapped in useEffectEvent.
+      camera_view: viewMatrix,
+      plot_id: plotId,
+      plot_type: plotType,
+      store_name: storeName,
+      plot_params: plotParams,
+      // Reduce the timeout value to improve responsiveness during data loading (bailed-early renders)?
+      timeout: currentTimeout.current, // in ms // Note: will not have any effect when wait_for_store_gets is false.
+      wait_for_store_gets: false, // TODO: lift this value up to pass/use it in the window.zarr_ functions as well?
+      cache_enabled: true,
+      svg_compression_enabled: true,
+      svg_include_document: false,
+    };
+
+    const layerHeight = height - marginTop - marginBottom;
+
+    setPickingResult(normalizePickingResult(await pick_wasm(
+      renderParams,
+      // The coordinates are relative to the "layer" (the camera region), not the full width/height.
+      // We also need to flip the Y coordinate so that positive is up.
+      screenCoordX + marginLeft,
+      marginBottom + (layerHeight - screenCoordY)
+    )));
+  });
+
+
+  // The renderFrame callback.
+  // We use useEffectEvent because we want to "see"
+  // the latest values of viewMatrix, plotProps, etc.
+  const renderFrame = useEffectEvent(async () => {
+    isRenderingRef.current = true;
+    console.log('wasm.render');
+
+    const renderParams = {
+      width,
+      height,
+      format: format,
+      margin_bottom: marginBottom,
+      margin_left: marginLeft,
+      margin_top: marginTop,
+      margin_right: marginRight,
+      device_pixel_ratio: window.devicePixelRatio,
+      aspect_ratio_mode: aspectRatioMode,
+      aspect_ratio_alignment_mode: aspectRatioAlignmentMode,
+      view_mode: viewMode,
+      pickable: false,
+      // Should see the latest viewMatrix here, since renderFrame is wrapped in useEffectEvent.
+      camera_view: viewMatrix,
+      plot_id: plotId,
+      plot_type: plotType,
+      store_name: storeName,
+      plot_params: plotParams,
+      // Reduce the timeout value to improve responsiveness during data loading (bailed-early renders)?
+      timeout: currentTimeout.current, // in ms // Note: will not have any effect when wait_for_store_gets is false.
+      wait_for_store_gets: false, // TODO: lift this value up to pass/use it in the window.zarr_ functions as well?
+      cache_enabled: true,
+      svg_compression_enabled: true,
+      svg_include_document: false,
+    };
+
+    // Wrap render_wasm in try/catch, to handle Rust panics.
+    let arr;
+    try {
+      arr = await render_wasm(renderParams);
+
+      isRenderingRef.current = false;
+    } catch (error) {
+      console.error("Error during wasm.render_wasm:", error);
+      // Cleanup
+      isRenderingRef.current = false;
+      return;
+    }
+
+    if (isVector) {
+      // Format: Vector (render to SVG)
+      const gContents = decompressFromUint8Array(arr);
+
+      //console.log(gContents)
+
+      if (!svgRef.current) {
+        return;
+      }
+      svgRef.current.innerHTML = gContents;
+
+      // TODO: check for bailed early
+    } else {
+      // Format: Raster (render to canvas)
+      const canvas = canvasRef.current;
+      if (!canvas) {
+        return;
+      }
+      const ctx = canvas.getContext("2d");
+      if (!ctx) {
+        return;
+      }
+      // TODO: is there a more efficient way to do this?
+      // E.g., write to a webgl texture? or is this fast enough already?
+      const imageData = new ImageData(
+        new Uint8ClampedArray(arr.subarray(0, -1)),
+        width,
+        height,
+      );
+      ctx.putImageData(imageData, 0, 0);
+
+      const frameBailedEarly = arr.at(-1) === 1;
+      if (frameBailedEarly) {
+        currentTimeout.current = maxTimeout;
+        incBacklogIteration(); // Increment this to force a re-render.
+        setBailedEarly(true); // Update this to show the loading indicator.
+      } else {
+        // Successful render.
+        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);
+        if (storeUsed && storeUsed.clearCache && typeof storeUsed.clearCache === 'function') {
+          storeUsed.clearCache();
+        }
+      }
+    }
+    setDidFirstRender(true);
+  });
+
+  const throttledRender = useMemo(
+    () => throttle(
+      renderFrame,
+      16, // ~60fps
+      // When both leading and trailing are true (the default):
+      // - First call -> executes immediately (leading edge)
+      // - Calls during the wait window -> ignored, but the most recent one is remembered.
+      // - After the wait period expires -> the last remembered call is executed (trailing edge).
+      { leading: true, trailing: true }
+    ), []);
+
+  useEffect(() => {
+    return () => throttledRender.cancel();
+  }, [throttledRender]);
+
+  // TODO: use react-query?
+  useEffect(() => {
+    if (!isWasmReady) {
+      return;
+    }
+
+    // We want to allow for simultaneous renders, as this makes user interactions feel
+    // much smoother. However, we allow for users to opt-out, and we also
+    // need to prevent simultaneous renders prior to the first render, as the first
+    // render initializes cached values and stuff.
+    if (isRenderingRef.current && (!didFirstRender || bailedEarly || !allowSimultaneousRenders)) {
+      // Prevent multiple render calls prior to the first successful render.
+      return;
+    }
+
+    // Render on the next animation frame.
+    throttledRender();
+  }, [isWasmReady, didFirstRender, viewMatrix, backlogIteration, plotId, plotType, plotParams, storeName, format,
+    width, height, aspectRatioMode, aspectRatioAlignmentMode, marginLeft, marginRight, marginTop, marginBottom]);
+
+  return (
+    <>
+      <div style={{ width, height, position: "relative" }}>
+        {!supportsWebGpu ? (
+          <p>{supportsWebGpuMessage}</p>
+        ) : null}
+        <div
+          ref={cameraRef}
+          style={{
+            position: "absolute",
+            top: marginTop,
+            left: marginLeft,
+            width: width - marginLeft - marginRight,
+            height: height - marginTop - marginBottom,
+            border: `${debugMargins ? 1 : 0}px solid red`,
+          }}
+        />
+        {isVector ? (
+          <svg
+            ref={svgRef}
+            style={{ width, height, border: "1px solid black" }}
+            width={width}
+            height={height}
+            viewBox={`0 0 ${width} ${height}`}
+            xmlns="http://www.w3.org/2000/svg"
+          >
+          </svg>
+        ) : (
+          <canvas
+            ref={canvasRef}
+            style={{ width, height, border: "1px solid black" }}
+            width={width}
+            height={height}
+          />
+        )}
+      </div>
+      {bailedEarly ? (
+          <p>Loading...</p>
+        ) : null}
+      <button ref={tempButtonRef} style={{ display: 'none' }}>Try lookAt</button>
+      {pickingResult ? (
+        <pre>{JSON.stringify(pickingResult, null, 2)}</pre>
+      ) : null}
+    </>
+  );
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export * from '@pluot/core'; // Re-export everything from the vanilla JS package.
+export { Pluot } from "./Pluot.jsx";