@biongff/vizarr 0.3.0-dev.2025-11-12.283baee9

package/assets/logo-wide.svg

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 516.22 126.13">
+  <defs>
+    <style>
+      .cls-1, .cls-2, .cls-3, .cls-4 {
+        mix-blend-mode: multiply;
+      }
+
+      .cls-1, .cls-2, .cls-3, .cls-5, .cls-6, .cls-7 {
+        stroke-width: 0px;
+      }
+
+      .cls-1, .cls-7 {
+        fill: #ef4136;
+      }
+
+      .cls-2, .cls-5 {
+        fill: #27aae1;
+      }
+
+      .cls-3, .cls-6 {
+        fill: #39b54a;
+      }
+
+      .cls-8 {
+        isolation: isolate;
+      }
+    </style>
+  </defs>
+  <g class="cls-8">
+    <g id="Layer_2" data-name="Layer 2">
+      <g id="Layer_1-2" data-name="Layer 1">
+        <polygon class="cls-2" points="72.82 40.61 49.38 0 7.5 0 72.82 113.14 138.15 0 96.27 0 72.82 40.61"/>
+        <polygon class="cls-1" points="102.06 12.99 72.82 63.62 43.59 12.99 15 12.99 80.32 126.13 145.65 12.99 102.06 12.99"/>
+        <polygon class="cls-3" points="72.82 63.62 43.59 12.99 0 12.99 65.32 126.13 130.65 12.99 102.06 12.99 72.82 63.62"/>
+        <g class="cls-4">
+          <path class="cls-7" d="M160.22,17.14h13.85l-20.36,92.36h-13.85l20.36-92.36Z"/>
+          <path class="cls-7" d="M172.96,98.15l63.84-68.82h-48.6l2.63-12.19h67.44l-2.35,11.35-64.11,68.82h49.85l-2.77,12.19h-68.41l2.49-11.35Z"/>
+          <path class="cls-7" d="M318.91,90.39h-45.28l-11.63,19.11h-15.92l57.05-92.36h17.31l16.34,92.36h-14.54l-3.32-19.11ZM280.41,78.07h37.25l-7.89-48.47-29.36,48.47Z"/>
+          <path class="cls-7" d="M387.58,73.92h-18.14l-7.75,35.59h-13.85l20.36-92.36h35.59c13.85,0,26.86,9.28,26.86,24.65,0,17.03-11.91,29.63-28.94,31.43l15.37,36.28h-15.23l-14.26-35.59ZM416.11,43.04c0-8.03-7.2-13.71-14.68-13.71h-22.02l-7.2,32.4h23.26c13.16,0,20.63-8.31,20.63-18.69Z"/>
+          <path class="cls-7" d="M473.16,73.92h-18.14l-7.75,35.59h-13.85l20.36-92.36h35.59c13.85,0,26.86,9.28,26.86,24.65,0,17.03-11.91,29.63-28.94,31.43l15.37,36.28h-15.23l-14.26-35.59ZM501.68,43.04c0-8.03-7.2-13.71-14.68-13.71h-22.02l-7.2,32.4h23.26c13.16,0,20.63-8.31,20.63-18.69Z"/>
+        </g>
+        <g class="cls-4">
+          <path class="cls-5" d="M160.22,17.14h13.85l-20.36,92.36h-13.85l20.36-92.36Z"/>
+          <path class="cls-5" d="M172.96,98.15l63.84-68.82h-48.6l2.63-12.19h67.44l-2.35,11.35-64.11,68.82h49.85l-2.77,12.19h-68.41l2.49-11.35Z"/>
+          <path class="cls-5" d="M318.91,90.39h-45.28l-11.63,19.11h-15.92l57.05-92.36h17.31l16.34,92.36h-14.54l-3.32-19.11ZM280.41,78.07h37.25l-7.89-48.47-29.36,48.47Z"/>
+          <path class="cls-5" d="M387.58,73.92h-18.14l-7.75,35.59h-13.85l20.36-92.36h35.59c13.85,0,26.86,9.28,26.86,24.65,0,17.03-11.91,29.63-28.94,31.43l15.37,36.28h-15.23l-14.26-35.59ZM416.11,43.04c0-8.03-7.2-13.71-14.68-13.71h-22.02l-7.2,32.4h23.26c13.16,0,20.63-8.31,20.63-18.69Z"/>
+          <path class="cls-5" d="M473.16,73.92h-18.14l-7.75,35.59h-13.85l20.36-92.36h35.59c13.85,0,26.86,9.28,26.86,24.65,0,17.03-11.91,29.63-28.94,31.43l15.37,36.28h-15.23l-14.26-35.59ZM501.68,43.04c0-8.03-7.2-13.71-14.68-13.71h-22.02l-7.2,32.4h23.26c13.16,0,20.63-8.31,20.63-18.69Z"/>
+        </g>
+        <g class="cls-4">
+          <path class="cls-6" d="M160.22,17.14h13.85l-20.36,92.36h-13.85l20.36-92.36Z"/>
+          <path class="cls-6" d="M172.96,98.15l63.84-68.82h-48.6l2.63-12.19h67.44l-2.35,11.35-64.11,68.82h49.85l-2.77,12.19h-68.41l2.49-11.35Z"/>
+          <path class="cls-6" d="M318.91,90.39h-45.28l-11.63,19.11h-15.92l57.05-92.36h17.31l16.34,92.36h-14.54l-3.32-19.11ZM280.41,78.07h37.25l-7.89-48.47-29.36,48.47Z"/>
+          <path class="cls-6" d="M387.58,73.92h-18.14l-7.75,35.59h-13.85l20.36-92.36h35.59c13.85,0,26.86,9.28,26.86,24.65,0,17.03-11.91,29.63-28.94,31.43l15.37,36.28h-15.23l-14.26-35.59ZM416.11,43.04c0-8.03-7.2-13.71-14.68-13.71h-22.02l-7.2,32.4h23.26c13.16,0,20.63-8.31,20.63-18.69Z"/>
+          <path class="cls-6" d="M473.16,73.92h-18.14l-7.75,35.59h-13.85l20.36-92.36h35.59c13.85,0,26.86,9.28,26.86,24.65,0,17.03-11.91,29.63-28.94,31.43l15.37,36.28h-15.23l-14.26-35.59ZM501.68,43.04c0-8.03-7.2-13.71-14.68-13.71h-22.02l-7.2,32.4h23.26c13.16,0,20.63-8.31,20.63-18.69Z"/>
+        </g>
+      </g>
+    </g>
+  </g>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 145.65 126.13">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #ef4136;
+      }
+
+      .cls-1, .cls-2, .cls-3 {
+        mix-blend-mode: multiply;
+        stroke-width: 0px;
+      }
+
+      .cls-2 {
+        fill: #27aae1;
+      }
+
+      .cls-3 {
+        fill: #39b54a;
+      }
+
+      .cls-4 {
+        isolation: isolate;
+      }
+    </style>
+  </defs>
+  <g class="cls-4">
+    <g id="Layer_2" data-name="Layer 2">
+      <g id="Layer_1-2" data-name="Layer 1">
+        <polygon class="cls-2" points="72.82 40.61 49.38 0 7.5 0 72.82 113.14 138.15 0 96.27 0 72.82 40.61"/>
+        <polygon class="cls-1" points="102.06 12.99 72.82 63.62 43.59 12.99 15 12.99 80.32 126.13 145.65 12.99 102.06 12.99"/>
+        <polygon class="cls-3" points="72.82 63.62 43.59 12.99 0 12.99 65.32 126.13 130.65 12.99 102.06 12.99 72.82 63.62"/>
+      </g>
+    </g>
+  </g>
+</svg>

package/assets/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

package/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.7.3/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "useConst": "off",
+        "noParameterAssign": "off"
+      },
+      "suspicious": {
+        "noShadowRestrictedNames": "off"
+      }
+    }
+  },
+  "files": {
+    "ignore": ["python"]
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  }
+}

package/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🔬</text></svg>"
+    />
+    <link rel="alternate icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="A minimal, purely client-side program for viewing Zarr-based images." />
+    <title>vizarr</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <script type="module" src="/main.ts"></script>
+    <style>
+      html {
+        background-color: black;
+      }
+    </style>
+  </body>
+</html>

package/main.ts

@@ -0,0 +1,52 @@
+import debounce from "just-debounce-it";
+import * as vizarr from "./src/index";
+
+async function main() {
+  console.log(`vizarr v${vizarr.version}: https://github.com/hms-dbmi/vizarr`);
+  // biome-ignore lint/style/noNonNullAssertion: We know the element exists
+  const viewer = await vizarr.createViewer(document.querySelector("#root")!);
+  const url = new URL(window.location.href);
+
+  if (!url.searchParams.has("source")) {
+    return;
+  }
+
+  // see if we have initial viewState
+  const viewStateString = url.searchParams.get("viewState");
+  if (viewStateString) {
+    const viewState = JSON.parse(viewStateString);
+    viewer.setViewState(viewState);
+  }
+
+  // Add event listener to sync viewState as query param.
+  // Debounce to limit how quickly we are pushing to browser history
+  viewer.on(
+    "viewStateChange",
+    debounce((update: vizarr.ViewState) => {
+      const url = new URL(window.location.href);
+      url.searchParams.set("viewState", JSON.stringify(update));
+      window.history.replaceState(window.history.state, "", decodeURIComponent(url.href));
+    }, 200),
+  );
+
+  // parse image config
+  // @ts-expect-error - TODO: validate config
+  const config: vizarr.ImageLayerConfig = {};
+
+  for (const [key, value] of url.searchParams) {
+    // @ts-expect-error - TODO: validate config
+    config[key] = value;
+  }
+
+  // Make sure the source URL is decoded.
+  viewer.addImage(config);
+
+  const newLocation = decodeURIComponent(url.href);
+
+  // Only update history if the new location is different from the current
+  if (window.location.href !== newLocation) {
+    window.history.replaceState(window.history.state, "", newLocation);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@biongff/vizarr",
+  "version": "0.3.0-dev.2025-11-12.283baee9",
+  "type": "module",
+  "dependencies": {
+    "@deck.gl/core": "~9.0.0",
+    "@deck.gl/geo-layers": "~9.0.0",
+    "@deck.gl/layers": "~9.0.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@hms-dbmi/viv": "~0.17.2",
+    "@mui/icons-material": "^7.2.0",
+    "@mui/material": "^7.2.0",
+    "@vivjs/types": "~0.17.0",
+    "@zarrita/storage": "0.1.0",
+    "deck.gl": "~9.0.0",
+    "jotai": "^1.0.0",
+    "just-debounce-it": "^3.1.1",
+    "math.gl": "^4.1.0",
+    "p-map": "^7.0.3",
+    "quick-lru": "^7.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-is": "18.3.1",
+    "zarrita": "0.5.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.1",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^24.3.0",
+    "@types/react": "^18.3.10",
+    "@types/react-dom": "^18.2.18",
+    "@vitejs/plugin-react": "^4.3.4",
+    "semantic-release": "^25.0.2",
+    "typescript": "^5.8.2",
+    "vite": "^6.2.7"
+  },
+  "overrides": {
+    "react-is": "^18.3.1"
+  },
+  "prereleaseSha": "283baee9c93391f3d86fd39ddfce706d868be2e9",
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run check && vite build",
+    "preview": "vite preview",
+    "lint": "biome ci",
+    "fix": "biome check --write",
+    "check": "tsc"
+  }
+}

package/patches/@vivjs__loaders@0.17.2.patch

@@ -0,0 +1,13 @@
+diff --git a/dist/index.mjs b/dist/index.mjs
+index b709ea0b4eb932f46b304b4cd8d241ac09e37a8b..37788b9807822f2d4bc257a5079f534a1d34dea7 100644
+--- a/dist/index.mjs
++++ b/dist/index.mjs
+@@ -1,8 +1,6 @@
+ import { BaseDecoder, fromBlob, fromFile, fromUrl, GeoTIFFImage, addDecoder } from 'geotiff';
+-import { decompress } from 'lzw-tiff-decoder';
+ import quickselect from 'quickselect';
+ import * as z from 'zod';
+-import { KeyError, openGroup, HTTPStore } from 'zarr';
+ 
+ var __defProp$3 = Object.defineProperty;
+ var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;

package/python/.python-version

@@ -0,0 +1 @@
+3.13

package/python/README.md

@@ -0,0 +1,14 @@
+# vizarr
+
+```sh
+pip install vizarr
+```
+
+```python
+import vizarr
+import zarr
+
+viewer = vizarr.Viewer()
+viewer.add_image(source=zarr.open("path/to/ome.zarr"))
+viewer
+```

package/python/Untitled.ipynb

@@ -0,0 +1,40 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "20794451-c89f-497d-aa89-3c6a432326fc",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  },
+  "widgets": {
+   "application/vnd.jupyter.widget-state+json": {
+    "state": {},
+    "version_major": 2,
+    "version_minor": 0
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

package/python/deno.json

@@ -0,0 +1,22 @@
+{
+	"lock": false,
+	"compilerOptions": {
+		"checkJs": true,
+		"allowJs": true,
+		"lib": [
+			"ES2022",
+			"DOM",
+			"DOM.Iterable"
+		]
+	},
+	"fmt": {
+		"useTabs": true
+	},
+	"lint": {
+		"rules": {
+			"exclude": [
+				"prefer-const"
+			]
+		}
+	}
+}

package/python/notebooks/IDR_example.ipynb

@@ -0,0 +1,86 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Viewing an image from the IDR\n",
+    "\n",
+    "OME-NGFF is an open standard for imaging from the OME community. The Imaging Data Resource (IDR) provides serveral publically available images in this format."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install --quiet fsspec zarr requests aiohttp"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Open the remote zarr"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fsspec import get_mapper\n",
+    "import zarr\n",
+    "\n",
+    "# Create a remote mapping to the data\n",
+    "url = \"https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.1/6001240.zarr/\"\n",
+    "store = get_mapper(url)\n",
+    "z_grp = zarr.open(store, mode='r')\n",
+    "z_grp"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##  View with vizarr"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import vizarr\n",
+    "\n",
+    "viewer = vizarr.Viewer()\n",
+    "viewer.add_image(source=z_grp)\n",
+    "viewer"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

package/python/notebooks/README.md

@@ -0,0 +1,35 @@
+# Examples
+
+## Install Requirements
+
+The examples require the `vizarr` [anywidget](https://github.com/manzt/anywidget). If running locally, please install the following:
+
+```bash
+pip install vizarr
+```
+
+## Getting Started
+
+This example will work in the Jupyter, JupyterLab, VS Code, and more. We recommend trying our JupyterLab.
+
+```bash
+$ jupyter lab getting_started.ipynb
+```
+
+## Viewing an Image from the Imaging Data Resource
+
+OME-NGFF is an open standard for imaging from the OME community. The [Imaging Data Resource](https://idr.openmicroscopy.org) (IDR) 
+provides serveral images in this format which are publically available.
+
+```bash
+$ jupyter lab IDR_example.ipynb
+```
+
+## Display a Zoomable Mandelbrot Set
+
+This notebook a contains a `vizarr` example visualizing a generic multiscale Zarr. The first cells create the
+underlying generative Zarr store. It dynamically creates "chunks" at different zoom levels and associated array metadata.
+
+```bash
+$ jupyter lab mandelbrot.ipynb
+```

package/python/notebooks/create_fixture.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+import argparse
+import zarr
+import numpy as np
+import os
+import json
+from skimage import data
+from skimage.transform import pyramid_gaussian
+
+# Modified from https://github.com/ome/ome-zarr-py/blob/master/tests/create_test_data.py
+def create_ome_zarr(zarr_directory, dtype="f4"):
+
+    base = np.tile(data.astronaut(), (4, 4, 1))
+    gaussian = list(pyramid_gaussian(base, downscale=2, max_layer=3, channel_axis=-1))
+
+    pyramid = []
+    # convert each level of pyramid into 5D image (t, c, z, y, x)
+    for pixels in gaussian:
+        red = pixels[:, :, 0]
+        green = pixels[:, :, 1]
+        blue = pixels[:, :, 2]
+        # wrap to make 5D: (t, c, z, y, x)
+        pixels = np.array([np.array([red]), np.array([green]), np.array([blue])])
+        pixels = np.array([pixels]).astype(dtype)
+        pyramid.append(pixels)
+
+    store = zarr.DirectoryStore(zarr_directory)
+    grp = zarr.group(store, overwrite=True)
+    paths = []
+    for path, dataset in enumerate(pyramid):
+        grp.create_dataset(str(path), data=pyramid[path])
+        paths.append({"path": str(path)})
+
+    image_data = {
+        "id": 1,
+        "channels": [
+            {
+                "color": "FF0000",
+                "window": {"start": 0, "end": 1},
+                "label": "Red",
+                "active": True,
+            },
+            {
+                "color": "00FF00",
+                "window": {"start": 0, "end": 1},
+                "label": "Green",
+                "active": True,
+            },
+            {
+                "color": "0000FF",
+                "window": {"start": 0, "end": 1},
+                "label": "Blue",
+                "active": True,
+            },
+        ],
+        "rdefs": {
+            "model": "color",
+        },
+    }
+
+    multiscales = [
+        {
+            "version": "0.1",
+            "datasets": paths,
+        }
+    ]
+    grp.attrs["multiscales"] = multiscales
+    grp.attrs["omero"] = image_data
+
+
+if __name__ == "__main__":
+    create_ome_zarr("astronaut.zarr")