Browser-native digital pathology: WebAssembly + OpenSlide

Salik Syed

March 11, 2025

Background

OpenSlide is a popular open-source library that provides unified pixel-level file access to diverse Whole Slide Image (WSI) file formats. Originally developed at Carnegie Mellon University, its C library is widely used in digital pathology software including:

• VIPS image processing system
• QuPath open software for bioimage analysis
• Tia Computational Pathology Toolbox

Today, most browser-based slide image viewers require conversion to different formats, pre-rendering large tile archives or running server-side applications.

To enable portable and performant slide rendering in-browser, we ported OpenSlide to WebAssembly, allowing users to read files from local and remote sources (including cloud object storage) at near-native speeds without file conversion or server configuration.

  import { OpenSlide, OpenSlideImage } from "@conflux-xyz/openslide-wasm";

  async function run() {
    const ctx = await new OpenSlide();
    await ctx.initialize();
    const url = "https://your-bucket.s3.us-west-2.amazonaws.com/image.svs";
    const image = await ctx.open(url);
    const numLevels = image.getLevelCount();
    const dims = image.getLevelDimensions(0);
    const canvas = document.getElementById("image");
    const x = Math.floor(dims[0]/2);
    const y = Math.floor(dims[1]/2);
    // Read 512x512 tile of image as ARGB buffer
    const uint8buffer = image.readRegion(canvas, x, y, numLevels - 1, 512, 512);
  }

Motivation

At Conflux, we believe modern browser and edge applications have immense potential for delivering diagnostic and scientific insights from whole slide images and other high dimensional clinical data. ML runtimes like ONNX enable inference using WebGPU or WebAssembly, allowing a wide range of applications — including quality assessment, virtual staining, and biomarker imputation — to run directly in the browser, all without any sensitive data leaving the client machine. With WebGL-enabled browsers now rivaling traditional, rigid desktop slide visualization applications, pathologists can work more flexibly and efficiently. Both ML and visualization applications on the web hold tremendous promise, but to fully realize this potential, digital pathology images must be accessible within the browser. Recognizing the lack of existing tools for this purpose, we identified the need for a truly cross-format solution capable of handling a variety of digital pathology formats. Beyond the browser, OpenSlideWASM extends slide processing capabilities to serverless environments, edge computing on medical devices, native desktop and mobile applications via WASI, and secure multi-tenant pathology platforms, unlocking new possibilities for digital pathology workflows.

🚀

Try the In-Browser Demo

Compiling OpenSlide to Web Assembly

By leveraging Emscripten, an LLVM compiler toolchain, we compiled OpenSlide and its dependencies into WebAssembly, allowing us to call OpenSlide to parse images stored within the WASM filesystem or remotely (accessible via HTTP Range Request). For our build pipeline, we opted to manually flatten OpenSlide’s dependency graph—comprising 16 projects—and compile each one independently via a shell script, outputting to a common lib directory. Many dependencies required patches or minor modifications to remove system calls referenced in the code that are not supported in the WASM runtime. Additionally, we created a Docker container with all necessary build system dependencies pre-installed, streamlining the compilation process.

Extending OpenSlide's file loading for the web

OpenSlide wraps all file system API calls inside openslide-file.c, this allows us to intercept system calls (e.g fseek, fread, ftell) and translate them into fetch requests. For web based applications this is incredibly useful, as files are often not stored in the file system but rather on a remote web-server or blob store. HTTP Range Requests enable us to read portions of these large files incrementally. We used Emscripten's Asyncify API's to allow OpenSlideWASM to read data without downloading the entire file as long as the file is hosted on a server that supports such requests.

Pre-fetching data to reduce overhead

In the logs above we can see that there are a large number of 2-32 byte reads at various offsets throughout the file. Given that the HTTP headers themselves take several hundred bytes this creates an enormous amount of overhead for a tiny amount of data returned. Due to this we introduced a pre-fetching system that splits the file into 15kb logical chunks. Many of the tiny reads happen co-located within chunk regions so pre-fetching the data significantly reduces wasted bandwidth and reduces the total number of live fetches at any given time.

Using the API

We developed TypeScript wrappers around the raw OpenSlide C API calls, providing an object-oriented interface with two classes:

• OpenSlide: represents OpenSlide within the WASM runtime
• OpenSlideImage: corresponds to a C openslide_t * pointer.

Common OpenSlide operations can be performed as methods of OpenSlideImage:

class OpenSlideImage {
    getPropertyNames(): string[];
    getPropertyValue(name: string): string;
    getLevelCount(): number;
    getLevelDimensions(level: number): [number, number];
    readRegion(x: number, y: number, level: number, w: number, height: number) : UInt8Array;
    ...other methods
  }

We wrap raw C constructs with familiar async functions. Loading an image is as simple as calling await OpenSlide.open(...) with either a fetchable URL or a File object as the argument.

Looking Forward

• With OpenSlideWASM we are excited to further digital pathology by bringing a complex codebase to browser and edge-computing environments via the power of WebAssembly.
• We hope that packaging OpenSlide in WebAssembly will enable algorithm developers and researchers to deliver and share work while protecting sensitive data.
• This is just the first step and our roadmap includes support for all file formats (currently only SVS is supported) and all OpenSlide C API methods.

Want to collaborate or contribute?

We welcome feedback and are eager to collaborate on enhancing the performance, capabilities, and scope of OpenSlideWASM. If you are interested in our work, please reach out!