workflows/neuroglancer_notebook/neuroglancer-nb-workflow.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6df0e9b5-5c9b-4b20-9064-3f381fbeb2cb",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:25:02.532910Z",
     "start_time": "2024-03-29T17:25:02.529856Z"
    }
   },
   "source": [
    "# Neuroglancer App for Jupyter Notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b74f52e-efb2-493b-bf79-d37689c777db",
   "metadata": {},
   "source": [
    "[Neuroglancer](https://github.com/google/neuroglancer) by Google is a WebGL-based viewer for volumetric data. It is capable of displaying arbitrary (non axis-aligned) cross-sectional views of volumetric data, as well as 3-D meshes and line-segment based models (skeletons). It is commonly used to display massive datasets from electron microscopy in the field of neuroscience.\n",
    "\n",
    "Although neuroglancer provides a powerful browser-based tool for exploring very large volumes, it only provides a standalone application. However, researchers often utilize Jupyter Notebook to conduct reproducible research and encapsulate visualizations alongside code and text. Using [Panel](https://panel.holoviz.org/), we can provide access to the neuroglancer interface within the context of a research notebook.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "509b8b2079ffb9b3",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:27:21.640552Z",
     "start_time": "2024-03-29T17:27:20.750243Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "import neuroglancer\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9a5c51b-4936-46f1-a4c9-d1d976aaf6a6",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:38:20.342922Z",
     "start_time": "2024-03-29T17:38:20.339991Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Define the NeuroglancerNB Class\n",
    "> TODO: get this merged into Neuroglancer, or importable as a Panel extension"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fc000270015e8e33",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:48:55.453528Z",
     "start_time": "2024-03-29T17:48:55.439687Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "class NeuroglancerNB(pn.viewable.Viewer):\n",
    "    \"\"\"\n",
    "    A HoloViz Panel app for visualizing and interacting with Neuroglancer viewers\n",
    "    within a Jupyter Notebook.\n",
    "\n",
    "    This app supports loading from a parameterized Neuroglancer URL or an existing\n",
    "    `neuroglancer.viewer.Viewer` instance.\n",
    "    \"\"\"\n",
    "    \n",
    "    DEMO_URL = 'https://neuroglancer-demo.appspot.com/#!%7B%22dimensions%22:%7B%22x%22:%5B6.000000000000001e-9%2C%22m%22%5D%2C%22y%22:%5B6.000000000000001e-9%2C%22m%22%5D%2C%22z%22:%5B3.0000000000000004e-8%2C%22m%22%5D%7D%2C%22position%22:%5B5029.42333984375%2C6217.5849609375%2C1182.5%5D%2C%22crossSectionScale%22:3.7621853549999242%2C%22projectionOrientation%22:%5B-0.05179581791162491%2C-0.8017329573631287%2C0.0831851214170456%2C-0.5895944833755493%5D%2C%22projectionScale%22:4699.372698097029%2C%22layers%22:%5B%7B%22type%22:%22image%22%2C%22source%22:%22precomputed://gs://neuroglancer-public-data/kasthuri2011/image%22%2C%22tab%22:%22source%22%2C%22name%22:%22original-image%22%7D%2C%7B%22type%22:%22image%22%2C%22source%22:%22precomputed://gs://neuroglancer-public-data/kasthuri2011/image_color_corrected%22%2C%22tab%22:%22source%22%2C%22name%22:%22corrected-image%22%7D%2C%7B%22type%22:%22segmentation%22%2C%22source%22:%22precomputed://gs://neuroglancer-public-data/kasthuri2011/ground_truth%22%2C%22tab%22:%22source%22%2C%22selectedAlpha%22:0.63%2C%22notSelectedAlpha%22:0.14%2C%22segments%22:%5B%223208%22%2C%224901%22%2C%2213%22%2C%224965%22%2C%224651%22%2C%222282%22%2C%223189%22%2C%223758%22%2C%2215%22%2C%224027%22%2C%223228%22%2C%22444%22%2C%223207%22%2C%223224%22%2C%223710%22%5D%2C%22name%22:%22ground_truth%22%7D%5D%2C%22layout%22:%224panel%22%7D'\n",
    "\n",
    "    def __init__(self, source=None, aspect_ratio=2.75, show_state=False, **params):\n",
    "\n",
    "        \"\"\"\n",
    "        Args:\n",
    "            source (str or neuroglancer.viewer.Viewer, optional): Source for the initial state of the viewer,\n",
    "                which can be a URL string or an existing neuroglancer.viewer.Viewer instance.\n",
    "                If None, a new viewer will be initialized without a predefined state.\n",
    "            aspect_ratio (float, optional): The width to height ratio for the window-responsive Neuroglancer viewer.\n",
    "                Default is 2.75.\n",
    "            show_state (bool, optional): Provides a collapsable card widget under the viewer that displays the viewer's\n",
    "                Useful for debugging. Default is False.\n",
    "        \"\"\"\n",
    "            \n",
    "        super().__init__(**params)\n",
    "        self.source_not_provided = False if source else True\n",
    "        self.show_state = show_state\n",
    "        self.viewer = source if isinstance(source, neuroglancer.viewer.Viewer) else neuroglancer.Viewer()\n",
    "        self._setup_ui_components(aspect_ratio=aspect_ratio)    \n",
    "        self._configure_viewer()\n",
    "        self._setup_callbacks()\n",
    "        \n",
    "        # If source is provided and not a Viewer, assume it's a URL\n",
    "        if source and not isinstance(source, neuroglancer.viewer.Viewer):\n",
    "            self._initialize_viewer_from_url(source)\n",
    "\n",
    "    def _initialize_viewer_from_url(self, source:str):\n",
    "        self.url_input.value = source\n",
    "        self._load_state_from_url(source)\n",
    "\n",
    "    def _setup_ui_components(self, aspect_ratio):\n",
    "        self.url_input = pn.widgets.TextInput(placeholder=\"Enter a Neuroglancer URL and click Load\", name='Input URL', width=700)\n",
    "        self.load_button = pn.widgets.Button(name=\"Load\", button_type=\"primary\", width=75)\n",
    "        self.demo_button = pn.widgets.Button(name=\"Demo\", button_type=\"warning\", width=75)\n",
    "        self.json_pane = pn.pane.JSON({}, theme='light', depth=2, name='Viewer State', height=600, width=400)\n",
    "        self.shareable_url_pane = pn.pane.Markdown(\"**Shareable URL:**\")\n",
    "        self.local_url_pane = pn.pane.Markdown(\"**Local URL:**\")\n",
    "        self.iframe = pn.pane.HTML(sizing_mode='stretch_both', aspect_ratio=aspect_ratio, min_height=500, styles={\"resize\": \"both\", \"overflow\": \"hidden\"})\n",
    "\n",
    "    def _configure_viewer(self):\n",
    "        self._update_local_url()\n",
    "        self._update_iframe_with_local_url()\n",
    "\n",
    "    def _setup_callbacks(self):\n",
    "        self.load_button.on_click(self._on_load_button_clicked)\n",
    "        self.demo_button.on_click(self._on_demo_button_clicked)\n",
    "        self.viewer.shared_state.add_changed_callback(self._on_viewer_state_changed)\n",
    "\n",
    "    def _on_demo_button_clicked(self, event):\n",
    "        self.url_input.value = self.DEMO_URL\n",
    "        self._load_state_from_url(self.url_input.value)\n",
    "\n",
    "    def _on_load_button_clicked(self, event):\n",
    "        self._load_state_from_url(self.url_input.value)\n",
    "\n",
    "    def _load_state_from_url(self, url):\n",
    "        try:\n",
    "            new_state = self._parse_state_from_url(url)\n",
    "            self.viewer.set_state(new_state)\n",
    "        except Exception as e:\n",
    "            print(f\"Error loading Neuroglancer state: Please {e}\")\n",
    "\n",
    "    def _parse_state_from_url(self, url):\n",
    "        return neuroglancer.parse_url(url)\n",
    "\n",
    "    def _on_viewer_state_changed(self):\n",
    "        self._update_shareable_url()\n",
    "        self._update_json_pane()\n",
    "\n",
    "    def _update_shareable_url(self):\n",
    "        shareable_url = neuroglancer.to_url(self.viewer.state)\n",
    "        self.shareable_url_pane.object = self._generate_dropdown_markup(\"Shareable URL\", shareable_url)\n",
    "\n",
    "    def _update_local_url(self):\n",
    "        self.local_url_pane.object = self._generate_dropdown_markup(\"Local URL\", self.viewer.get_viewer_url())\n",
    "\n",
    "    def _update_iframe_with_local_url(self):\n",
    "        iframe_style = 'frameborder=\"0\" scrolling=\"no\" marginheight=\"0\" marginwidth=\"0\" style=\"width:100%; height:100%; min-width:500px; min-height:500px;\"'\n",
    "        self.iframe.object = f'<iframe src=\"{self.viewer.get_viewer_url()}\" {iframe_style}\"></iframe>'\n",
    "\n",
    "    def _update_json_pane(self):\n",
    "        self.json_pane.object = self.viewer.state.to_json()\n",
    "\n",
    "    def _generate_dropdown_markup(self, title, url):\n",
    "        return f\"\"\"\n",
    "            <details>\n",
    "                <summary><b>{title}:</b></summary>\n",
    "                <a href=\"{url}\" target=\"_blank\">{url}</a>\n",
    "            </details>\n",
    "        \"\"\"\n",
    "\n",
    "    def __panel__(self):\n",
    "        controls_layout = pn.Column(\n",
    "            pn.Row(self.demo_button, self.load_button),\n",
    "            pn.Row(self.url_input), visible=self.source_not_provided)\n",
    "        links_layout = pn.Column(self.local_url_pane, self.shareable_url_pane)\n",
    "        return pn.Column(\n",
    "            controls_layout,\n",
    "            links_layout,\n",
    "            self.iframe,\n",
    "            pn.Card(self.json_pane, title='State', collapsed=True, visible=self.show_state)\n",
    "        )\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac3c7976-b7b0-48ee-9735-9a72d851f39f",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Workflow 1: Launch new viewer and load state from URL\n",
    "\n",
    "To launch an empty viewer, simply omit the `source` input. You can then use the GUI to insert and load from a parametrized URL to set the state of the new viewer. Click the demo button to insert an example URL. You can find other demo links on the [neuroglancer repo](https://github.com/google/neuroglancer#examples)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a878765526558df",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:44:36.223839Z",
     "start_time": "2024-03-29T17:44:36.126429Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "NeuroglancerNB(show_state=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "65b223af-20e0-4957-8cbc-41e05516aa73",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:48:56.655478Z",
     "start_time": "2024-03-29T17:48:56.653461Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Workflow 2: Display Pre-specified Viewer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfe5d277ca4b472a",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "Provide an pre-specified neuroglancer viewer object as `source` to display that viewer in a notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a885a79c4875a5a8",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-29T17:48:44.411475Z",
     "start_time": "2024-03-29T17:48:44.407740Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "viewer = neuroglancer.Viewer()\n",
    "\n",
    "with viewer.txn() as s:\n",
    "    s.layers[\"image\"] = neuroglancer.ImageLayer(\n",
    "        source=\"precomputed://gs://neuroglancer-janelia-flyem-hemibrain/emdata/clahe_yz/jpeg\",\n",
    "    )\n",
    "    s.layers[\"segmentation\"] = neuroglancer.SegmentationLayer(\n",
    "        source=\"precomputed://gs://neuroglancer-janelia-flyem-hemibrain/v1.1/segmentation\",\n",
    "    )\n",
    "\n",
    "NeuroglancerNB(source=viewer, show_state=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "585ff5de-8fa3-45e4-a22d-1f2706ab748a",
   "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
}