python/notebooks/getting_started.ipynb

{
 "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://github.com/ome/omero-ms-zarr/blob/master/spec.md). \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": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "run_vizarr([astronaut_img, noise])"
   ]
  },
  {
   "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"
   ]
  }
 ],
 "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": 4
}