@biongff/vizarr 1.1.1 → 1.3.0

package/python/notebooks/create_fixture.py

@@ -1,72 +0,0 @@
-#!/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")

package/python/notebooks/getting_started.ipynb

@@ -1,217 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Hello, `vizarr`\n",
-    "\n",
-    "This example explains the basic usage of `vizarr` [anywidget](https://github.com/manzt/anywidget)."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Create a multiscale OME-Zarr\n",
-    "\n",
-    "The easiest way to use `vizarr` in a jupyter notebook is to have an OME-Zarr compliant image. OME-Zarr is a developing standard from the OME-Community and currently considered experimental as it is under active development. The specification can be found [here](https://ngff.openmicroscopy.org/specifications/index.html). \n",
-    " \n",
-    "Creating an OME-Zarr for your own images can be accomplished by using Bio-Formats, `bioformats2raw` with the `--file_type=zarr --dimension-order=XYZCT` options and adding `omero` metadata to the root attrs of the resulting multiscale group. \n",
-    "\n",
-    "For convenience, we have included a simple function to create a multiscale OME-Zarr below."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from create_fixture import create_ome_zarr\n",
-    "create_ome_zarr(\"astronaut.zarr\") # creates an example OME-Zarr in the current directory"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Open OME-Zarr in jupyter with `zarr-python`\n",
-    "\n",
-    "The root of an OME-Zarr is a group that aheres to the `multiscales` zarr extension (if pyramidal) and also contains `omero` metadata describing _how_ to render the image. Here we open the OME-Zarr as a `zarr.Group` using `zarr-python`. "
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import zarr\n",
-    "multiscale_astronaut = zarr.open(\"astronaut.zarr\", mode=\"r\") # open the zarr created above in jupyter kernel"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### View the image in `vizarr`\n",
-    "\n",
-    "The vizarr Python API allows basic viewing of large zarr datasets in computational notebooks. The `vizarr.Viewer` allows adding images to the view with the `.add_image` API. The `source` field must be a `zarr.Array` or `zarr.Group`. If the `zarr.Group` is for an OME-Zarr, `source` is the only required field. If it is an `zarr.Array` or `zarr.Group` that is not OME-Zarr, additional fields are required for rendering (described below)."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import vizarr\n",
-    "\n",
-    "viewer = vizarr.Viewer()\n",
-    "viewer.add_image(source=multiscale_astronaut, name=\"astronaut\")\n",
-    "viewer"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Create a generic array layer\n",
-    "\n",
-    "`vizarr` also supports custom `zarr.Array` and `zarr.Group`s, but requires additional metadata to render. Viewing a custom `zarr` has the following requirements:\n",
-    "\n",
-    "- The last two dimensions of the `zarr.Array` must be `YX`.\n",
-    "- If an `zarr.Array` has more than 2D dimensions, non-YX axis much have a `chunksize` of `1`.\n",
-    "- If a `zarr.Group` is provided, it must implement the `multiscales` specification and subresolution arrays must adhere to the same `zarr.Array` requirements outlined above."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import numpy as np\n",
-    "\n",
-    "# Create in-memory numpy array\n",
-    "arr = np.random.randint(0, 255, (1024, 1024), dtype=np.uint8)\n",
-    "\n",
-    "viewer.add_image(\n",
-    "    source=zarr.array(arr), # make sure it's a zarr\n",
-    "    opacity=0.5,   # optional, default 1\n",
-    "    name=\"noise\",  # optional, default image_x\n",
-    ")\n",
-    "\n",
-    "# view canvas above"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Use `channel_axis` to choose axis to additively blend\n",
-    "\n",
-    "Vizarr was designed to support viewing a subset of multiscale OME-Zarr images, but it can support blending 2D slices of generic `zarr.Array`s. For a `zarr.Array` with more than 2 dimensions, a `channel_axis` must be specified to tell vizarr which dimension to split into separate blended channels. \n",
-    "\n",
-    "Here we will load one of the sub-resolution `zarr.Array`s from the OME-Zarr we created and view it with Vizarr."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "z_arr = zarr.open('astronaut.zarr').get('2')\n",
-    "z_arr.shape"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The channel axis for an OME-Zarr is always `1`, but loading the image with a different channel axis will load a single plane."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "viewer = vizarr.Viewer()\n",
-    "viewer.add_image(source=z_arr, channel_axis=0)\n",
-    "viewer"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "You can specify other rendering properties to tell vizarr how to render the channels along the specified axis."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "viewer = vizarr.Viewer()\n",
-    "viewer.add_image(\n",
-    "    source=z_arr,\n",
-    "    name=\"CYM astronaut\", # Image name\n",
-    "    channel_axis=1, # size == 3, lists below must be of same length if provided\n",
-    "    colors=[\"#FFFF00\", \"#FF00FF\", \"#00FFFF\"],   # optional\n",
-    "    names=[\"yellow\", \"magenta\", \"cyan\"],        # optional, default channel_X\n",
-    "    visibilities=[True, False, True],           # optional, default True\n",
-    "    contrast_limits=[[0, 1] for _ in range(3)], # optional, but recommended\n",
-    ")\n",
-    "viewer"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "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.7"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}

package/python/notebooks/mandelbrot.ipynb

@@ -1,211 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Setup\n",
-    "\n",
-    "Before start, please make sure you have all the dependencies installed."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "!pip install --quiet vizarr zarr numba"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import zarr\n",
-    "import numcodecs\n",
-    "import numba\n",
-    "import numpy as np"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Zoomable Mandelbrot Set\n",
-    "\n",
-    "This notebook a contains `vizarr` example visualizing a generic multiscale zarr. The first cell contains code to create the underlying generatvie zarr store. It dynamically creates \"chunks\" at different zoom levels and associated array metadata."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "\n",
-    "def create_meta_store(levels: int, tilesize: int, compressor, dtype: str):\n",
-    "    store = dict()\n",
-    "    zarr.storage.init_group(store)\n",
-    "    \n",
-    "    datasets = [{\"path\": str(i)} for i in range(levels)]\n",
-    "    root_attrs = {\"multiscales\": [{\"datasets\": datasets, \"version\": \"0.1\"}]}\n",
-    "    store[\".zattrs\"] = zarr.util.json_dumps(root_attrs)\n",
-    "    \n",
-    "    base_width = tilesize * 2 ** levels\n",
-    "    for level in range(levels):\n",
-    "        width = int(base_width / 2 ** level)\n",
-    "        zarr.storage.init_array(\n",
-    "            store,\n",
-    "            path=str(level),\n",
-    "            shape=(width, width),\n",
-    "            chunks=(tilesize, tilesize),\n",
-    "            dtype=dtype,\n",
-    "            compressor=compressor,\n",
-    "        )\n",
-    "    return store\n",
-    "\n",
-    "\n",
-    "@numba.njit\n",
-    "def mandelbrot(out, from_x, from_y, to_x, to_y, grid_size, maxiter):\n",
-    "    step_x = (to_x - from_x) / grid_size\n",
-    "    step_y = (to_y - from_y) / grid_size\n",
-    "    creal = from_x\n",
-    "    cimag = from_y\n",
-    "    for i in range(grid_size):\n",
-    "        cimag = from_y\n",
-    "        for j in range(grid_size):\n",
-    "            nreal = real = imag = n = 0\n",
-    "            for _ in range(maxiter):\n",
-    "                nreal = real * real - imag * imag + creal\n",
-    "                imag = 2 * real * imag + cimag\n",
-    "                real = nreal\n",
-    "                if real * real + imag * imag > 4.0:\n",
-    "                    break\n",
-    "                n += 1\n",
-    "            out[j * grid_size + i] = n\n",
-    "            cimag += step_y\n",
-    "        creal += step_x\n",
-    "    return out\n",
-    "\n",
-    "\n",
-    "@numba.njit\n",
-    "def tile_bounds(level, x, y, max_level, min_coord=-2.5, max_coord=2.5):\n",
-    "    max_width = max_coord - min_coord\n",
-    "    tile_width = max_width / 2 ** (max_level - level)\n",
-    "    from_x = min_coord + x * tile_width\n",
-    "    to_x = min_coord + (x + 1) * tile_width\n",
-    "\n",
-    "    from_y = min_coord + y * tile_width\n",
-    "    to_y = min_coord + (y + 1) * tile_width\n",
-    "\n",
-    "    return from_x, from_y, to_x, to_y\n",
-    "\n",
-    "\n",
-    "class MandlebrotStore(zarr.storage.BaseStore):\n",
-    "    \n",
-    "    def __init__(self, levels, tilesize, maxiter=255, compressor=None):\n",
-    "        self.levels = levels\n",
-    "        self.tilesize = tilesize\n",
-    "        self.compressor = compressor\n",
-    "        self.dtype = np.dtype(np.uint8 if maxiter < 256 else np.uint16)\n",
-    "        self.maxiter = maxiter\n",
-    "        self._store = create_meta_store(levels, tilesize, compressor, self.dtype)\n",
-    "\n",
-    "    def __getitem__(self, key):\n",
-    "        if key in self._store:\n",
-    "            return self._store[key]\n",
-    "\n",
-    "        try:\n",
-    "            # Try parsing pyramidal coords\n",
-    "            level, chunk_key = key.split(\"/\")\n",
-    "            level = int(level)\n",
-    "            y, x = map(int, chunk_key.split(\".\"))\n",
-    "        except:\n",
-    "            raise KeyError\n",
-    "\n",
-    "        from_x, from_y, to_x, to_y = tile_bounds(level, x, y, self.levels)\n",
-    "        out = np.zeros(self.tilesize * self.tilesize, dtype=self.dtype)\n",
-    "        tile = mandelbrot(out, from_x, from_y, to_x, to_y, self.tilesize, self.maxiter)\n",
-    "        tile = tile.reshape(self.tilesize, self.tilesize)\n",
-    "\n",
-    "        if self.compressor:\n",
-    "            return self.compressor.encode(tile)\n",
-    "\n",
-    "        return tile.tobytes()\n",
-    "\n",
-    "    def __iter__(self):\n",
-    "        return iter(self._store)\n",
-    "        \n",
-    "    def __len__(self):\n",
-    "        return len(self._store)\n",
-    "\n",
-    "    def __delitem__(self, key):\n",
-    "        raise NotImplementedError(\"read-only store\")\n",
-    "        \n",
-    "    def __setitem__(self, key):\n",
-    "        raise NotImplementedError(\"read-only store\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Running vizarr\n",
-    "\n",
-    "Initalize the store implemented above, and open as a `zarr.Group` for vizarr. "
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Initialize the store\n",
-    "store = MandlebrotStore(levels=50, tilesize=512, compressor=numcodecs.Blosc())\n",
-    "# Wrap in a cache so that tiles don't need to be computed as often\n",
-    "store = zarr.LRUStoreCache(store, max_size=1e9)\n",
-    "\n",
-    "# This store implements the 'multiscales' zarr specfiication which is recognized by vizarr\n",
-    "grp = zarr.open(store, mode=\"r\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import vizarr\n",
-    "\n",
-    "viewer = vizarr.Viewer()\n",
-    "viewer.add_image(source=grp, name=\"mandelbrot\")\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/spatial_transformations.ipynb

@@ -1,139 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e9ac663e-a7ed-41c9-9050-2c69b89e7e74",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "!pip install --quiet zarr scikit-image"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "2c447021",
-   "metadata": {},
-   "source": [
-    "## Affine Transformations\n",
-    "\n",
-    "Spatial transformations are defined per image layer via a [4x4 transformation matrix](https://www.brainvoyager.com/bv/doc/UsersGuide/CoordsAndTransforms/SpatialTransformationMatrices.html) using the `model_matrix` property.\n",
-    "\n",
-    "This features is useful for pre-processing (e.g. flipping, rotating, scaling etc) your data, since these operations \n",
-    "are executed performantly on the GPU thanks to [Viv](https://github.com/hms-dbmi/viv).\n",
-    "\n",
-    "In this notebook we will load a simple OME-NGFF dataset from the `Getting Started` notebook and apply a simple rotation."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "31b069e3",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from create_fixture import create_ome_zarr\n",
-    "import zarr\n",
-    "import numpy as np\n",
-    "\n",
-    "import vizarr\n",
-    "\n",
-    "# creates an example OME-NGFF, see `getting_started.ipynb` for more details\n",
-    "create_ome_zarr(\"astronaut.zarr\") \n",
-    "\n",
-    "# Create a viewer\n",
-    "viewer = vizarr.Viewer()\n",
-    "\n",
-    "astronaut = {\n",
-    "    \"source\": zarr.open(\"astronaut.zarr\", mode=\"r\"),\n",
-    "    \"name\": \"astronaut\",\n",
-    "}\n",
-    "\n",
-    "noise = {\n",
-    "    \"source\": zarr.array(np.random.randint(0, 255, (1024, 1024), dtype=np.uint8)),\n",
-    "    \"opacity\": 0.8,\n",
-    "    \"name\": \"noise\",\n",
-    "}\n",
-    "\n",
-    "viewer.add_image(**astronaut)\n",
-    "viewer.add_image(**noise)\n",
-    "viewer"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "50cc6192",
-   "metadata": {},
-   "source": [
-    "### Apply translation and rotation to `noise` layer"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e967d280",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "M = np.eye(4)\n",
-    "\n",
-    "# rotation\n",
-    "theta = np.pi / 4\n",
-    "M[:3, :3] = np.array([\n",
-    "    [ np.cos(theta),  np.sin(theta), 0],\n",
-    "    [-np.sin(theta),  np.cos(theta), 0],\n",
-    "    [             0,              0, 1],\n",
-    "])\n",
-    "\n",
-    "# translation\n",
-    "M[:3,3] = np.array([512, 512, 0])\n",
-    "\n",
-    "M"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6ffbea5e",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "translated_noise = { **noise, **{\"model_matrix\": M.ravel().tolist() } } # need to ravel into 1D list\n",
-    "\n",
-    "v = vizarr.Viewer()\n",
-    "v.add_image(**astronaut)\n",
-    "v.add_image(**translated_noise)\n",
-    "v"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "ff64b992",
-   "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"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

package/python/pyproject.toml

@@ -1,18 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "vizarr"
-version = "0.1.1"
-dependencies = ["anywidget>=0.9.13", "zarr<3"]
-requires-python = ">=3.9"
-
-[dependency-groups]
-dev = ["watchfiles", "jupyterlab", "scikit-image"]
-
-[tool.hatch.build.targets.sdist]
-only-include = ["src"]
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/vizarr"]

package/python/src/vizarr/__init__.py

@@ -1,10 +0,0 @@
-import importlib.metadata
-
-try:
-    __version__ = importlib.metadata.version("vizarr")
-except importlib.metadata.PackageNotFoundError:
-    __version__ = "unknown"
-
-del importlib
-
-from ._widget import Viewer