Skip to content

Latest commit

 

History

History
246 lines (182 loc) · 12.6 KB

README.md

File metadata and controls

246 lines (182 loc) · 12.6 KB

Developer docs

Decision trees

Compute operations:

  • Has GPU?
    • Yes: Perform compute operations on GPU via WGPU
    • No: Perform compute operations on CPU via CPU fallbacks

Picking operations:

  • Has GPU?
    • Yes: Perform picking operations on GPU via WGPU. May require a bitmap-based render pass to obtain the picking buffer.
    • No: Perform picking operations on CPU via CPU fallbacks

Rendering operations:

  • Graphics output format?
    • Vector: Check per-layer graphics output format
      • Layer specifies bitmap rendering: Has GPU?
        • Yes: Perform bitmap rendering operations on GPU via WGPU
        • No: Perform bitmap rendering operations on CPU via CPU fallbacks
      • Layer specifies vector rendering: Perform vector rendering operations on CPU
    • Bitmap: Has GPU?
      • Yes: Perform bitmap rendering operations on GPU via WGPU
      • No: Perform bitmap rendering operations on CPU via CPU fallbacks

Non-goals

  • Window/Canvas/Eventloop management via Rust. This should be handled by the parent/calling code. The Rust code should be concerned with returning the rendered bytes, which can be written to HTML Canvas or saved to a file by the calling library. This both reduces the scope and decouples the plotting from any particular GUI framework. However, it does complicate certain things, like rendering while asynchronously loading data.
  • Coordinated multiple views. This can be achieved via the parent/calling library, for example, by wrapping with use-coordination or your favorite state management library.
  • WebGL fallbacks via the webgl feature of WGPU. Why not: this both increases the WASM bundle size in order to include the shader translation code paths, and it requires providing the compatible_surface parameter when initializing the WGPU Instance (which conflicts with our first non-goal of avoiding canvas management).
    • As a workaround, environments that do not support WebGPU can either use the slower SVG-based rendering, or future CPU-based raster rendering (#157).
    • Alternatively, tell the user to use a different browser/platform, or just be patient and wait for WebGPU support to become more widespread.
      • WebGPU is available in all major browsers already (implementation status, web.dev article).
        • Caveat: WebGPU is only available in Safari on macOS Tahoe 26 and above. According to one April 2026 estimate of macOS version market share, approximately ~70% of macOS users are running Tahoe or later. Until certain design issues are resolved by Apple, I suspect that a subset of users will resist upgrading to Tahoe for as long as possible.

Repository organization

This repository is organized as a monorepo.

Rust

The repo contains a cargo workspace, in order to support both development of the pluot core crate and the example crates in ./examples which depend on pluot and have their own additional dependencies.

The core Rust/WGPU plotting code is located in the crates directory. Rust-associated files also include:

  • Cargo.toml (workspace-level)
  • crates/pluot/Cargo.toml
  • crates/pluot_core/Cargo.toml
  • crates/pluot_zarr/Cargo.toml
  • rust-toolchain.toml
  • .cargo
  • crates/pluot_core/tests: Plain Rust unit tests
  • target (generated by cargo)
  • Cargo.lock (generated by cargo)

JavaScript

The repository contains JavaScript bindings in the form of an NPM package (containing a React component that loads the WASM bundle) and web apps for a demo site and documentation site. The NPM packages are managed by a PNPM workspace.

JavaScript code is located in the bindings-js directory. JavaScript-associated files also include:

  • package.json
  • pnpm-workspace.yaml
  • tsconfig.json
  • vitest.config.js
  • vitest.setup.js
  • node_modules (generated by pnpm)
  • crates/pluot/pkg (generated by wasm-pack)
  • pnpm-lock.yaml (generated by pnpm)
  • dev-docs/webgpu-playground: Plain HTML files for quickly checking concepts and syntax in WebGPU shader code.

Python

The repository contains Python bindings in the form of a Python package. Python code is located in the bindings-python directory. Python-associated files also include:

  • pyproject.toml
  • bindings-python/notebooks: Testing the Python bindings via Jupyter/Marimo notebooks
  • data: Code to download/generate data for testing
  • .venv (generated by uv)
  • uv.lock (generated by uv)

Principles

The Rust code should only be concerned with rendering a single plot, and should not care (or as minimally as possible) whether the caller is intending to use the result in a static or interactive context. It should be fast enough for this not to matter.

The WASM and JS bundle sizes should be relatively small, as we want to prioritize web-based usage from the outset.

The frontend/client should never "touch" the data. In other words, it should never execute a for loop over the data (for rendering purposes). The frontend/client does, however, need to register data-loading functions that will be called by the Rust code to retrieve data.

The frontend will specify visual properties and data-related properties and expressions, for example colormaps, viewState (zoom/pan), data filtering expressions via parameters. The data filtering operations themselves will always be performed in Rust.

Challenges

  • Keeping the bundle size small.
    • Prevents using certain Rust dependencies, such as for text rendering, requiring new minimal implementations.
    • Prevents using WebGL fallbacks, as this also increases the bundle size significantly. However, we could explore progressively loading a larger bundle in this situation.
  • WebGPU not yet available in all contexts.
    • Safari and Firefox on macOS versions prior to Tahoe
    • CI machines that lack a GPU
  • Compilation for web targets with Rust dependencies that have C subdependencies that assume C libraries like stdlib.h and string.h.
    • Prevents using certain Zarr (de)compression algorithms that are implemented in C
  • Challenges using multi-threaded and concurrenct Rust programs in WASM contexts.
  • Need to port low-level plotting logic (e.g., from D3).
  • Supporting both raster and vector formats. In some cases, plot rendering logic may need to be implemented twice, once for each type of output.
  • Efficient rendering while providing high-level APIs.
  • Caching intermediate values to improve performance in the interactive case.
  • Rendering something before all data has been loaded.
  • Extensibility, enabling implementation of new plot types outside the pluot crate.

Troubleshooting Rust compilation

brew install cmake # for zfp-sys for zarrs
brew install llvm # for zstd for zarrs

# In ~/.zshrc
# For rust compilation of zstd for zarrs
# Reference: https://github.com/gyscos/zstd-rs/issues/93#issuecomment-1058772951
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
export CC=/opt/homebrew/opt/llvm/bin/clang
export AR=/opt/homebrew/opt/llvm/bin/llvm-ar

On macOS, if you run into an Xcode SDK conflict (e.g., during snappy_src compilation), try setting the SDKROOT environment variable to ensure that C and C++ system headers come from the same CommandLineTools SDK version:

export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.1.sdk

Publishing to crates io

cargo login
cargo publish --dry-run
cargo publish

# JS
pnpm run build
pnpm run bundle
npm login
pnpm publish --filter='./bindings-js/**' --filter='./crates/pluot/pkg' --no-git-checks --provenance --access public

# Python
uv run maturin build --release
uv run twine upload target/wheels/*

Testing local widget package in marimo-wasm notebooks

Notebooks exported with marimo export html-wasm install their dependencies in the browser via micropip, so by default pluot_widget comes from PyPI rather than from the local checkout. To test local changes, build a wheel into a public/ folder next to the notebook (marimo copies this folder into the export) and point the notebook's script metadata at it.

The widget's JS bundle does not include react, react-dom, or @pluot/react; it loads them from CDNs at runtime (see bindings-python/pluot_widget/js/deps.ts). By default this is the published @pluot/react version matching the one in node_modules, so testing local @pluot/react changes also requires bundling it and passing its URL via custom_js_url.

# 1. Build the widget JS and the wheel into the notebook's public/ folder (its contents are git-ignored).
#    The hatch build hook skips the JS build when static/widget.js already exists, so rebuild it explicitly after changing js/.
pnpm -C bindings-python/pluot_widget run build
rm -rf bindings-python/notebooks/public
uv build bindings-python/pluot_widget --wheel -o bindings-python/notebooks/public

# 2. (Only to test local @pluot/react changes) Bundle @pluot/react and copy it next to the wheel.
#    The bundle keeps react external, so it shares the widget's React instance.
pnpm run build-tsc
pnpm -C bindings-js/react run bundle
mkdir -p bindings-python/notebooks/public/pluot-react
cp bindings-js/react/dist/*.js bindings-python/notebooks/public/pluot-react/

http-server --cors='*' --port 8001 -c-1 ./bindings-python/notebooks

Then, in the notebook's PEP 723 script metadata, replace the pluot_widget dependency with a URL to the wheel. marimo passes name @ <url> requirements to micropip as-is.

# /// script
# dependencies = [
#     "pluot_widget @ http://localhost:8001/public/pluot_widget-0.1.23-py3-none-any.whl"
# ]
# ///

If you did step 2, also pass the bundle's URL to the widget:

PluotWasmWidget(
    ...,
    custom_js_url="http://localhost:8001/public/pluot-react/index.js",
)

In a separate terminal, while the above http-server is still serving the notebooks directory:

# 3. Export and serve. The port must match the one in the wheel URL. -c-1 disables caching.
rm -rf output_dir
uv run marimo export html-wasm bindings-python/notebooks/widget_on_molab.mo.py -o output_dir --mode edit
http-server --cors='*' --port 8000 -c-1 ./output_dir

Notes:

  • The wheel's own dependencies (e.g., pluot_core) are still resolved from PyPI, so changes to those packages must be published (or built into public/ and referenced the same way).
  • Rebuilt wheels keep the same version number, so hard-refresh the browser after each rebuild.
  • Python-side logs written to sys.__stderr__ appear in the browser console, since the Pyodide kernel runs in a web worker.
  • Pyodide cannot start threads, so code paths that rely on zarr's sync() fail in this context even though they work in regular marimo.
  • React is loaded as a production build from the CDN by default. Pass js_dev_mode=True to the widget to load development builds for React dev warnings.
  • Revert the dependency to plain pluot_widget and remove custom_js_url before committing the notebook.

Memory usage of PluotWasmWidget in marimo-wasm notebooks

Issue: rendering the widget in a marimo-wasm notebook appeared to grow browser memory by ~2 GB.

Profiling: exported notebook variants (marimo export html-wasm) were loaded in headless Chrome and measured with performance.measureUserAgentSpecificMemory(). The page was served with COOP/COEP headers to enable that API, which also counts the Pyodide worker. Process RSS was too noisy to rely on (1.2–2.7 GB across identical runs).

Root cause: the Python dependencies are not the problem. The cost comes from passing the 16.6 MB _esm bundle (WASM inlined as base64) through Python:

  • A few non-ASCII characters make CPython store it at 2 bytes/char (31.7 MB).
  • marimo then encodes it, hashes it, and wraps it in a base64 data: URL, since virtual files are unsupported under Pyodide.
  • Pyodide's heap grows to hold these copies and never shrinks.

marimo/anywidget passes an http(s) _esm URL through as-is, which avoids the need to store large JS strings on the Python side.

Potential solutions:

  • Publish the full widget ESM to NPM and load via a CDN URL
  • Load only react, react-dom and @pluot/react via CDN URL