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

package/.gitattributes

@@ -0,0 +1 @@
+*ipynb linguist-vendored

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Report a problem with the software
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**  
+A clear and concise description of what the bug is.
+
+**To Reproduce**  
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+**Expected behavior**  
+A clear and concise description of what you expected to happen.
+
+**Screenshots (if applicable)**  
+If applicable, add screenshots to help explain the problem.
+
+**Environment (please complete the following information):**
+
+- OS: [e.g., Windows, macOS, Linux]
+- Python/Node/Django/etc. version: [e.g., Python 3.9]
+- Browser (if applicable): [e.g., Chrome, Firefox]
+
+**Additional context**  
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/documentation_update.md

@@ -0,0 +1,16 @@
+---
+name: Documentation Update
+about: Request changes or improvements to the documentation
+title: "[Docs] "
+labels: documentation
+assignees: ""
+---
+
+**What needs updating?**  
+Describe what section of the documentation needs improvement.
+
+**Where should this be updated?**  
+Provide links or file paths if possible.
+
+**Additional context**  
+Add any other relevant context about the documentation request.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+**Is your feature request related to a problem? Please describe.**  
+A clear and concise description of what the problem is.
+
+**Describe the solution you'd like**  
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**  
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**  
+Add any other context or screenshots about the feature request here.

package/.github/ISSUE_TEMPLATE/maintenance.md

@@ -0,0 +1,19 @@
+---
+name: Maintenance Task
+about: Request or propose refactoring, dependency updates, or tooling improvements
+title: "[Maintenance] "
+labels: maintenance, refactor
+assignees: ""
+---
+
+**Describe the task**  
+What needs to be maintained, refactored, or updated?
+
+**Reason for change**  
+Why is this maintenance needed (e.g., outdated dependency, code clarity, build speed)?
+
+**Proposed approach**  
+How might this be done?
+
+**Additional context**  
+Any links, dependencies, or related issues.

package/.github/ISSUE_TEMPLATE/optimisation_request.md

@@ -0,0 +1,23 @@
+---
+name: Optimisation Request
+about: Suggest a performance or efficiency improvement
+title: "[Optimisation] "
+labels: optimisation, enhancement
+assignees: ""
+---
+
+**Is your optimisation request related to a specific problem?**  
+A clear and concise description of the inefficiency or area for improvement.
+
+**Describe the proposed solution**  
+A clear and concise description of how the optimisation could be achieved.  
+(For example: refactoring code, reducing memory usage, improving response time, etc.)
+
+**Current performance**  
+(Optional) If available, provide benchmarks, logs, or profiling data showing current performance.
+
+**Expected performance improvement**  
+(Optional) If possible, describe the expected impact of the optimisation.
+
+**Additional context**  
+Add any other context or references (e.g., related issues, profiling tools used).

package/.github/ISSUE_TEMPLATE/support_request.md

@@ -0,0 +1,25 @@
+---
+name: Support Request
+about: Ask for help with using or configuring the software
+title: "[Support] "
+labels: question, support
+assignees: ""
+---
+
+**What are you trying to do?**  
+Describe your goal clearly.
+
+**What have you tried so far?**  
+List steps or commands you've already attempted.
+
+**What issue are you encountering?**  
+Include error messages, logs, or unexpected behaviour.
+
+**Environment:**
+
+- OS: [e.g., Windows, macOS, Linux]
+- Software version: [e.g., 1.2.3]
+- Runtime version: [e.g., Python 3.11]
+
+**Additional context:**  
+Add any relevant details, such as configuration files or links to documentation you’ve followed.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+# Description
+
+Give a brief summary of changes...
+
+Fixes # (issue)  
+Related to # (if applicable)
+
+## Type of change
+
+- [ ] 🐛 Bug fix (non-breaking change that resolves an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] ⚡ Optimisation (non-breaking improvement to performance or efficiency)
+- [ ] 🧩 Documentation (adds or improves documentation)
+- [ ] 🧱 Maintenance (refactor, dependency update, CI/CD, etc.)
+- [ ] 🔥 Breaking change (fix or feature that causes existing functionality to change)
+
+## Checklist
+
+- [ ] All tests pass (eg. `npm test`)
+- [ ] Pre-commit hooks run successfully (eg. `pre-commit run --all-files`)
+- [ ] Documentation updated (if required)

package/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+
+  # Maintain dependencies for npm
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"

package/.github/workflows/build_and_deploy.yml

@@ -0,0 +1,29 @@
+name: Build and Deploy
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: true
+      - run: |
+          pnpm build
+          touch dist/.nojekyll
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: dist
+          CLEAN: true
+          CLEAN_EXCLUDE: '["v0.1", "v0.2", "v0.3"]' # Manually add endpoints to keep

package/.github/workflows/npm-publish-dev.yml

@@ -0,0 +1,49 @@
+name: publish-dev
+# Publishes a pre-release (dev) version of the package to npmjs.org
+# whenever changes are pushed to the "dev" branch.
+
+on:
+  push:
+    branches: [dev]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install pnpm
+        run: npm install -g pnpm@9
+
+      - name: Update prerelease version
+        id: pre-release-version
+        uses: adobe/update-prerelease-npm-version@v1.0.0
+        with:
+          pre-release-tag: "dev"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build package
+        run: pnpm run build
+
+      - name: Configure npm authentication
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm publish --tag dev --access public --no-git-checks

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,20 @@
+name: publish
+# This workflow publishes the package to npmjs.org whenever a release is published.
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install pnpm
+        run: npm install -g pnpm@9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run Semantic Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: pnpm exec semantic-release

package/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Node CI
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: true
+      - run: pnpm check
+      - run: pnpm lint

package/.releaserc.json

@@ -0,0 +1,29 @@
+{
+  "branches": ["main"],
+  "repositoryUrl": "https://github.com/BioNGFF/vizarr.git",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md",
+        "changelogTitle": "# Changelog"
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "npmPublish": false
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "package-lock.json", "CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    ["@semantic-release/github", { "releaseNameTemplate": "<%= nextRelease.version %>" }]
+  ]
+}

package/CITATION.cff

@@ -0,0 +1,56 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using these metadata."
+authors:
+  - given-names: "Trevor"
+    family-names: "Manz"
+    affiliation: "Harvard Medical School"
+  - given-names: "Will"
+    family-names: "Moore"
+    affiliation: "Open Microscopy Environment"
+title: "Vizarr"
+url: "https://github.com/hms-dbmi/vizarr"
+preferred-citation:
+  type: article
+  title: "Viv: multiscale visualization of high-resolution multiplexed bioimaging data on the web"
+  authors:
+    - given-names: "Trevor"
+      family-names: "Manz"
+      orcid: "https://orcid.org/0000-0001-7694-5164"
+      affiliation: "Harvard Medical School"
+    - given-names: "Ilan"
+      family-names: "Gold"
+      orcid: "https://orcid.org/0000-0002-5823-1026"
+      affiliation: "Harvard Medical School"
+    - given-names: "Nathan Heath"
+      family-names: "Patterson"
+      affiliation: "Vanderbilt University"
+      orcid: "https://orcid.org/0000-0002-0064-1583"
+    - given-names: "Chuck"
+      family-names: "McCallum"
+      affiliation: "Harvard Medical School"
+      orcid: "https://orcid.org/0000-0003-4039-9768"
+    - given-names: "Mark S."
+      family-names: "Keller"
+      affiliation: "Harvard Medical School"
+      orcid: "https://orcid.org/0000-0003-3003-874X"
+    - given-names: "Bruce W."
+      family-names: "Herr"
+      name-suffix: "II"
+      affiliation: "Indiana University"
+      orcid: "https://orcid.org/0000-0002-6703-7647"
+    - given-names: "Kay"
+      family-names: "Börner"
+      affiliation: "Indiana University"
+      orcid: "https://orcid.org/0000-0002-3321-6137"
+    - given-names: "Jeffrey M."
+      family-names: "Spraggins"
+      affiliation: "Vanderbilt University"
+      orcid: "https://orcid.org/0000-0001-9198-5498"
+    - given-names: "Nils"
+      family-names: "Gehlenborg"
+      affiliation: "Harvard Medical School"
+      orcid: "https://orcid.org/0000-0003-0327-8297"
+  doi: "10.1038/s41592-022-01482-7"
+  journal: "Nature Methods"
+  month: 5
+  year: 2022

package/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+## Feedback and Contribution
+
+Thanks for your interest in `vizarr`! I welcome any input, feedback, bug reports, and contributions. 
+Please do not hesitate to reach out if you have any questions!
+
+### Setting up a development environment
+
+In order to make changes to `vizarr`, you will need to fork the repository. Clone your fork
+of the repository to your local machine and change directories:
+
+```bash
+git clone https://github.com/your-username/vizarr.git
+cd vizarr
+``` 
+
+Set the `upstream` remote to the base `vizarr` repository:
+
+```bash
+git remote add upstream https://github.com/hms-dbmi/vizarr.git
+```
+
+Install the dependencies to develop and build `vizarr` via `pnpm`.
+
+```bash
+pnpm install 
+```
+
+> Note: You need to have [Node.js](https://nodejs.org/en/) (v20.0 or later) to build
+> and develop `vizarr`. I recommend using [`nvm`](https://github.com/nvm-sh/nvm) or
+> [`fnm`](https://github.com/Schniz/fnm) to manage different version of Node.js
+> on your machine.
+
+### Running the development server
+
+```bash
+pnpm dev
+```
+
+The `dev` command will start a development server on `http://localhost:5173`
+which you can navigate to in your web browser. You can "live" edit the contents
+of any of the files within `src/` or `public/` when running this server;
+changes are reflected instantly in the browser. Stop the development server
+when you are done making changes.
+
+- `src/` - contains all TypeScript source code
+- `public/` - contains all static assets required for the site
+
+Have a look at the other `script` commands in `package.json` for the project. These are standard to any JS
+build and can be executed by running `pnpm <command>`.
+
+### Making changes
+
+Create a new feature branch:
+
+```bash
+git checkout main -b your-feature-branch-name
+```
+
+Add and commit your changed files.
+
+### Sharing your changes
+
+Update your remote branch:
+
+```bash
+git push -u origin your-feature-branch-name
+```
+
+You can then make a pull-request to `vizarr`'s `main` branch. When making a
+pull-request, your code will be checked for linting with `biome`. Please run
+`pnpm fix` to automatically format your code when making a pull-request.
+
+
+### (Note to self) Building and publishing `vizarr`
+
+Build a production version of the site:
+
+```bash
+pnpm version [<new version> | major | minor | patch]
+pnpm publish
+```
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Trevor Manz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+<h1>
+<p align="center">
+  <img src="./assets/logo-wide.svg" alt="vizarr" width="200">
+</h1>
+<samp>
+  <p align="center">
+    <span>view multiscale zarr images online and in notebooks</span>
+      <br>
+      <br>
+      <a href="https://hms-dbmi.github.io/vizarr/?source=https://minio-dev.openmicroscopy.org/idr/v0.3/idr0062-blin-nuclearsegmentation/6001240.zarr">standalone app</a> .
+      <a href="./python/notebooks/getting_started.ipynb">python api</a> .
+      <a href="https://colab.research.google.com/github/hms-dbmi/vizarr/blob/main/python/notebooks/mandelbrot.ipynb">open in colab</a>
+  </p>
+</samp>
+</p>
+
+## About 
+
+**Vizarr** is a minimal, purely client-side program for viewing zarr-based images.
+
+- ⚡ **GPU accelerated rendering** with [Viv](https://github.com/hms-dbmi/viv)
+- 💻 Purely **client-side** zarr access with [zarrita.js](https://github.com/manzt/zarrita.js)
+- 🌎 A **standalone [web app](https://hms-dbmi/vizarr)** for viewing entirely in the browser.
+- 🐍 An [anywidget](https://github.com/manzt/anywidget) **Python API** for
+  programmatic control in notebooks.
+- 📦 Supports any `zarr-python` [store](https://zarr.readthedocs.io/en/stable/api/storage.html)
+  as a backend.
+
+<p align="center">
+  <img src="./assets/screenshot.png" alt="Multiscale OME-Zarr in Jupyter Notebook with Vizarr" width="500">
+</p>
+
+## Getting started
+
+**Vizarr**  provides two primary interfaces for interacting with the core viewer:
+
+### 1. Standalone Web App
+
+You can use the standalone web app by copying and pasting a URL to a Zarr store as the `?source` query parameter in the [web app](https://hms-dbmi.github.io/vizarr).
+
+For example, to view [this dataset](https://minio-dev.openmicroscopy.org/idr/v0.3/idr0062-blin-nuclearsegmentation/6001240.zarr) from the IDR, navigate to the following URL:
+
+```
+https://hms-dbmi.github.io/vizarr/?source=https://minio-dev.openmicroscopy.org/idr/v0.3/idr0062-blin-nuclearsegmentation/6001240.zarr
+```
+
+### 2. Python API
+
+The Python API is an [anywidget](https://github.com/manzt/anywidget), allowing programatic control of the viewer in computational notebooks like Jupyter, JupyterLab, Colab, and VS Code. The easiest way to get started is to open a Zarr store and load it into the viewer.
+
+```python
+import vizarr
+import zarr
+
+store = zarr.open("./path/to/ome.zarr")
+viewer = vizarr.Viewer()
+viewer.add_image(store)
+viewer
+```
+
+To learn more, see the [getting started](./python/notebooks/getting_started.ipynb) notebook.
+
+## Data types
+
+**Vizarr** supports viewing 2D slices of n-Dimensional Zarr arrays, allowing
+users to choose a single channel or blended composites of multiple channels
+during analysis. It has special support for the developing OME-NGFF format for
+multiscale and multimodal images. Currently, Viv supports `int8`, `int16`,
+`int32`, `uint8`, `uint16`, `uint32`, `float32`, `float64` arrays, but
+contributions are welcome to support more np.dtypes!
+
+## Limitations
+
+`vizarr` was built to support the registration use case above where multiple, pyramidal OME-Zarr images
+are viewed within a Jupyter Notebook. Support for other Zarr arrays is supported but not as well tested. 
+More information regarding the viewing of generic Zarr arrays can be found in the example notebooks.
+
+## Citation
+
+If you are using Vizarr in your research, please cite our paper:
+
+> Trevor Manz, Ilan Gold, Nathan Heath Patterson, Chuck McCallum, Mark S Keller, Bruce W Herr II, Katy Börner, Jeffrey M Spraggins, Nils Gehlenborg,
+> "[Viv: multiscale visualization of high-resolution multiplexed bioimaging data on the web](https://www.nature.com/articles/s41592-022-01482-7)."
+> **Nature Methods** (2022), [doi:10.31219/10.1038/s41592-022-01482-7](https://doi.org/10.1038/s41592-022-01482-7)
+