@h5web/h5wasm

H5Web's H5Wasm Provider

H5Web is a collection of React components to visualize and explore data. It consists of two main packages:

• @h5web/lib: visualization components built with react-three-fiber.
• @h5web/app: a stand-alone, web-based viewer to explore HDF5 files.

@h5web/app exposes the HDF5 viewer component App, as well as the following built-in data providers:

• H5GroveProvider for use with H5Grove server implementations, like jupyterlab-h5web;
• HsdsProvider for use with HSDS;
• MockProvider for testing purposes.

This package, @h5web/h5wasm, provides one additional data provider, H5WasmProvider, that can read HDF5 files straight in the browser thanks to the h5wasm library.

Check out this code sandbox for a demonstration of how to set up @h5web/h5wasm and use the H5WasmProvider.

Getting started 🚀

npm install @h5web/app @h5web/h5wasm

import '@h5web/app/dist/styles.css';

import React, { useState } from 'react';
import type { ChangeEvent } from 'react';
import { App } from '@h5web/app';
import { H5WasmProvider } from '@h5web/h5wasm';

interface H5File {
  filename: string;
  buffer: ArrayBuffer;
}

function MyApp() {
  const [h5File, setH5File] = useState<H5File>();

  function handleFileInputChange(evt: ChangeEvent<HTMLInputElement>) {
    const file = evt.target.files?.[0];
    if (!file) {
      return;
    }

    /* `H5WasmProvider` expects an HDF5 file in the form of an `ArrayBuffer`.
     * The way you get this buffer is up to you. Here, we show a simple file picker
     * and use the FileReader API to process the selected file. */
    const reader = new FileReader();
    reader.addEventListener('load', () => {
      setH5File({
        filename: file.name,
        buffer: reader.result as ArrayBuffer,
      });
    });

    reader.readAsArrayBuffer(file);
  }

  if (!h5File) {
    return (
      <input
        aria-label="Pick HDF5 file"
        type="file"
        accept=".h5"
        onChange={handleFileInputChange}
      />
    );
  }

  return (
    <div style={{ height: '100vh' }}>
      <H5WasmProvider {...h5File}>
        <App />
      </H5WasmProvider>
    </div>
  );
}

export default MyApp;

If your bundler supports it (e.g. webpack 5), you may be able to shorten the stylesheet import path as follows:

import '@h5web/app/styles.css';

Caveats

Requires BigInt support

The h5wasm library uses the BigInt 123n notation, which is challenging to polyfill. This means that:

• your build tool must understand the BigInt notation (e.g. babel-plugin-syntax-bigint)
• your application will only run in browsers that support BigInt.

External links are not resolved

The provider doesn't know how to resolve links to groups and datasets contained in other HDF5 files. Such links will appear as unresolved entities in the viewer.

File size is limited

Since h5wasm requires the entire HDF5 file to be passed as a single ArrayBuffer, there's a limit to how big a file you can load. This limit depends on your browser, on your operating system, and on your machine's resources.

API reference

H5WasmProvider

• filename: string (required) - the name of the file
• buffer: ArrayBuffer (required) - the content of the file

<H5WasmProvider filename="foo.h5" buffer={buffer}>
  <App />
</H5WasmProvider>