Extend heatmap into 3D surface with framing and height scale

apps/demo/src/DemoApp.tsx

@@ -9,10 +9,6 @@ import MockApp from './MockApp';
 // Split H5Wasm demo into its own bundle, and load it only when the demo is first visited
 const H5WasmApp = lazy(async () => import('./h5wasm/H5WasmApp'));
 
-const query = new URLSearchParams(document.location.search);
-// @ts-expect-error - Untyped global flag
-globalThis.H5WEB_EXPERIMENTAL = query.has('experimental');
-
 function DemoApp() {
   return (
     <Suspense fallback={null}>

apps/storybook/src/SurfaceVis.stories.tsx

@@ -1,46 +1,95 @@
 import { getDomain, mockValues, SurfaceVis } from '@h5web/lib';
 import { assertDefined } from '@h5web/shared/guards';
+import { COLOR_SCALE_TYPES, ScaleType } from '@h5web/shared/vis-models';
 import { createArrayFromView } from '@h5web/shared/vis-utils';
-import { extend, type Object3DNode, useThree } from '@react-three/fiber';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import ndarray from 'ndarray';
 
 import preview from '../.storybook/preview';
 import FillHeight from './decorators/FillHeight';
 
-extend({ OrbitControls });
-declare module '@react-three/fiber' {
-  interface ThreeElements {
-    orbitControls: Object3DNode<OrbitControls, typeof OrbitControls>;
-  }
-}
-
 const dataArray = createArrayFromView(mockValues.fourD().pick(0, 0));
 const domain = getDomain(dataArray.data);
 assertDefined(domain);
 
+const [rows, cols] = dataArray.shape;
+const abscissas = Float32Array.from({ length: cols }, (_, i) => -2 + i * 0.1);
+const ordinates = Float32Array.from({ length: rows }, (_, i) => i ** 1.5);
+
+const withHoles = ndarray(
+  Float32Array.from(dataArray.data, (val, i) =>
+    i % cols > cols / 3 && i % cols < cols / 2 ? Number.NaN : val,
+  ),
+  dataArray.shape,
+);
+
 const meta = preview.meta({
-  title: 'Experimental/SurfaceVis',
+  title: 'Visualizations/SurfaceVis',
   component: SurfaceVis,
   decorators: [FillHeight],
+  args: {
+    dataArray,
+    domain,
+  },
   argTypes: {
     dataArray: { control: false },
+    scaleType: {
+      control: { type: 'inline-radio' },
+      options: COLOR_SCALE_TYPES,
+    },
+    heightScale: {
+      control: { type: 'range', min: 0.05, max: 2, step: 0.05 },
+    },
   },
 });
 
-export const Default = meta.story({
-  render: (args) => (
-    <SurfaceVis {...args}>
-      <Controls />
-    </SurfaceVis>
-  ),
+export const Default = meta.story();
+
+export const AxisValues = meta.story({
   args: {
-    dataArray,
-    domain,
+    title: 'With axis values',
+    abscissaParams: { value: abscissas },
+    ordinateParams: { value: ordinates },
   },
 });
 
-function Controls() {
-  const camera = useThree((state) => state.camera);
-  const domElement = useThree((state) => state.gl.domElement);
-  return <orbitControls args={[camera, domElement]} />;
+// Positive data spanning five orders of magnitude: three Gaussian peaks over a low background
+function peak(x: number, y: number, params: [number, number, number, number]) {
+  const [cx, cy, amp, width] = params;
+  return amp * Math.exp(-((x - cx) ** 2 + (y - cy) ** 2) / (2 * width ** 2));
 }
+
+const peaksArray = ndarray(
+  Float32Array.from({ length: 80 * 120 }, (_, i) => {
+    const x = (i % 120) / 120;
+    const y = Math.floor(i / 120) / 80;
+    return (
+      1e-4 +
+      peak(x, y, [0.3, 0.4, 1, 0.08]) +
+      peak(x, y, [0.7, 0.6, 0.05, 0.06]) +
+      peak(x, y, [0.55, 0.2, 0.003, 0.05])
+    );
+  }),
+  [80, 120],
+);
+
+export const LogScale = meta.story({
+  args: {
+    title: 'Peaks (log scale)',
+    dataArray: peaksArray,
+    domain: getDomain(peaksArray.data, { scaleType: ScaleType.Log }),
+    scaleType: ScaleType.Log,
+  },
+});
+
+export const NaNHoles = meta.story({
+  name: 'With NaN',
+  args: {
+    dataArray: withHoles,
+  },
+});
+
+export const Downsampled = meta.story({
+  args: {
+    maxVertices: 1000,
+  },
+});

apps/storybook/src/Utilities.mdx

@@ -500,7 +500,7 @@ writing your own geometries:
 - `ErrorBarsGeometry`, used in [`ErrorBars`](https://h5web-docs.panosc.eu/?path=/docs/building-blocks-errorbars--docs)
 - `ErrorCapsGeometry`, used in [`ErrorBars`](https://h5web-docs.panosc.eu/?path=/docs/building-blocks-errorbars--docs)
 - `ScatterPointsGeometry`, used in [`ScatterPoints`](https://h5web-docs.panosc.eu/?path=/docs/visualizations-scattervis--docs) (undocumented)
-- `SurfaceMeshGeometry`, used in [`SurfaceMesh`](https://h5web-docs.panosc.eu/?path=/docs/experimental-surfacevis--docs) (experimental)
+- `SurfaceMeshGeometry`, used in [`SurfaceMesh`](https://h5web-docs.panosc.eu/?path=/docs/visualizations-surfacevis--docs)
 
 ### Constants
 

packages/app/src/__tests__/HeatmapSurface.browser.test.ts

@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, expect, test } from 'vitest';
+import { page } from 'vitest/browser';
+
+import { getSelectedVisTab, getVisTabs, renderApp } from '../test-utils';
+import { Vis } from '../vis-packs/core/visualizations';
+import { NxDataVis } from '../vis-packs/nexus/visualizations';
+
+function surfaceBtn() {
+  return page.getByRole('button', { name: 'Show as 3D surface' });
+}
+
+function heightSlider() {
+  return page.getByRole('slider', { name: 'Height scale' });
+}
+
+function resetViewBtn() {
+  return page.getByRole('button', { name: 'Reset view' });
+}
+
+/* Each switch between heatmap and surface creates a new WebGL context, which takes ~0.7 s with
+ * SwiftShader on an idle machine (profiled: `getContext` dominates; geometry, labels and React work
+ * take a few ms) and more when many test files create contexts in parallel, as in CI.
+ * ("THREE.WebGLRenderer: Context Lost." is R3F disposing the previous canvas on unmount.) */
+const SURFACE_TEST_TIMEOUT = 20_000;
+
+/* In 3D, the toolbar gets wider (height slider), so at the default 1920px viewport
+ * it re-measures after the switch and moves its last controls (Flip Y, Keep ratio, Grid) into the
+ * "More controls" menu. Querying those controls during that re-layout made tests flaky (the button
+ * would detach and the locator would wait until timeout). Use a viewport wide enough for the whole
+ * 3D toolbar to fit, so no control moves. */
+beforeEach(async () => {
+  await page.viewport(2560, 1080);
+});
+
+afterEach(async () => {
+  await page.viewport(1920, 1080);
+});
+
+test(
+  'extend heatmap into 3D surface and back',
+  async () => {
+    const { user } = await renderApp('/arrays/twoD');
+
+    expect(getVisTabs()).toEqual([Vis.Matrix, Vis.Line, Vis.Heatmap]);
+    expect(getSelectedVisTab()).toBe(Vis.Heatmap);
+    expect(surfaceBtn()).toHaveAttribute('aria-pressed', 'false');
+    expect(heightSlider()).not.toBeInTheDocument();
+
+    await user.click(surfaceBtn());
+
+    // Same vis tab, same dataset, now rendered as a surface
+    expect(getSelectedVisTab()).toBe(Vis.Heatmap);
+    expect(surfaceBtn()).toHaveAttribute('aria-pressed', 'true');
+    await expect
+      .element(page.getByRole('figure', { name: 'twoD' }))
+      .toBeVisible();
+    await expect.element(resetViewBtn()).toBeVisible();
+    expect(heightSlider()).toHaveValue('0.5');
+
+    await user.click(surfaceBtn());
+
+    expect(surfaceBtn()).toHaveAttribute('aria-pressed', 'false');
+    expect(resetViewBtn()).not.toBeInTheDocument();
+    expect(heightSlider()).not.toBeInTheDocument();
+  },
+  SURFACE_TEST_TIMEOUT,
+);
+
+test(
+  'carry heatmap settings over to 3D surface',
+  async () => {
+    const { user } = await renderApp('/arrays/twoD');
+
+    await user.click(page.getByRole('button', { name: 'Invert' }));
+    await user.click(page.getByRole('button', { name: 'Keep ratio' }));
+
+    await user.click(surfaceBtn());
+    await expect.element(resetViewBtn()).toBeVisible();
+
+    expect(page.getByRole('button', { name: 'Invert' })).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    );
+    expect(page.getByRole('button', { name: 'Keep ratio' })).toHaveAttribute(
+      'aria-pressed',
+      'false',
+    );
+  },
+  SURFACE_TEST_TIMEOUT,
+);
+
+test(
+  'keep settings changed in 3D when going back to heatmap',
+  async () => {
+    const { user } = await renderApp('/arrays/twoD');
+
+    await user.click(surfaceBtn());
+    await user.click(page.getByRole('button', { name: 'Flip X' }));
+    await user.click(surfaceBtn());
+
+    expect(resetViewBtn()).not.toBeInTheDocument();
+    expect(page.getByRole('button', { name: 'Flip X' })).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    );
+  },
+  SURFACE_TEST_TIMEOUT,
+);
+
+test(
+  'keep current slice and 3D mode when switching',
+  async () => {
+    const { user, selectExplorerNode } = await renderApp('/arrays/threeD');
+
+    const d0Slider = page.getByRole('slider', { name: 'D0' });
+    await user.type(d0Slider, '{ArrowUp}');
+    expect(d0Slider).toHaveValue(1);
+
+    await user.click(surfaceBtn());
+    await expect.element(resetViewBtn()).toBeVisible();
+    expect(d0Slider).toHaveValue(1);
+
+    // 3D mode is remembered when selecting another dataset
+    await selectExplorerNode('twoD');
+    expect(surfaceBtn()).toHaveAttribute('aria-pressed', 'true');
+    await expect
+      .element(page.getByRole('figure', { name: 'twoD' }))
+      .toBeVisible();
+    await expect.element(resetViewBtn()).toBeVisible();
+  },
+  SURFACE_TEST_TIMEOUT,
+);
+
+test(
+  'show interactions help for 3D surface',
+  async () => {
+    const { user } = await renderApp('/arrays/twoD');
+    await user.click(surfaceBtn());
+
+    await user.click(page.getByRole('button', { name: 'Show help' }));
+    expect(page.getByText('Rotate')).toBeVisible();
+    expect(page.getByText('Select to zoom')).not.toBeInTheDocument();
+  },
+  SURFACE_TEST_TIMEOUT,
+);
+
+test('offer 3D surface for NeXus images but not for complex heatmaps', async () => {
+  const { selectNexusExplorerNode } = await renderApp('/nexus/image');
+
+  expect(getSelectedVisTab()).toBe(NxDataVis.NxHeatmap);
+  expect(surfaceBtn()).toBeVisible();
+
+  await selectNexusExplorerNode('image_complex');
+  expect(getSelectedVisTab()).toBe(NxDataVis.NxHeatmap);
+  expect(surfaceBtn()).not.toBeInTheDocument();
+});
+
+test(
+  'fall back to heatmap for slices with a single row or column',
+  async () => {
+    const { user, selectExplorerNode } = await renderApp('/arrays/twoD');
+    await user.click(surfaceBtn());
+    await expect.element(resetViewBtn()).toBeVisible();
+
+    // 1 x 10 dataset: no surface can be built
+    await selectExplorerNode('twoD_negative');
+    expect(surfaceBtn()).not.toBeInTheDocument();
+    expect(resetViewBtn()).not.toBeInTheDocument();
+    await expect
+      .element(page.getByRole('figure', { name: 'twoD_negative' }))
+      .toBeVisible();
+  },
+  SURFACE_TEST_TIMEOUT,
+);
+
+test(
+  'show 3D surface of NeXus image with descending axes',
+  async () => {
+    const { user } = await renderApp('/nexus/descending-axes');
+    await user.click(surfaceBtn());
+
+    await expect.element(resetViewBtn()).toBeVisible();
+    expect(surfaceBtn()).toHaveAttribute('aria-pressed', 'true');
+  },
+  SURFACE_TEST_TIMEOUT,
+);