adapt brainrender-napari tutorial (#225)

* minimal docs update for splitting atlas vis and version management * minimal improvements to brainrender-napari docs * quick and dirty script to autogenerate br-napari tutorial screenshots but good to get into version control as a start * improve download tutorial icon * Apply suggestions from code review Co-authored-by: Adam Tyson <[email protected]> * move download tutorial to end --------- Co-authored-by: Adam Tyson <[email protected]>
brainglobe · Jul 30, 2024 · b0be0a7 · b0be0a7
1 parent 2bca572
commit b0be0a7
Show file tree

Hide file tree

Showing 13 changed files with 157 additions and 12 deletions.
diff --git a/docs/source/documentation/brainglobe-atlasapi/usage/command-line-interface.md b/docs/source/documentation/brainglobe-atlasapi/usage/command-line-interface.md
@@ -16,5 +16,9 @@ To update an atlas to a newer version, use `brainglobe update`, e.g.:
 brainglobe update -a allen_mouse_25um
 ```
 
-Further instructions can be found by running `brainglobe --help`
+Further instructions can be found by running `brainglobe --help`.
+
+:::{hint}
+We also provide a [graphical user interface](/tutorials/manage-atlases-in-GUI) to download and update atlases, as part of the `brainrender-napari` package.
+:::
 
diff --git a/docs/source/tutorials/images/atlas-versions.png b/docs/source/tutorials/images/atlas-versions.png
diff --git a/docs/source/tutorials/images/brainrender-napari/add-region-brainrender-napari.png b/docs/source/tutorials/images/brainrender-napari/add-region-brainrender-napari.png
diff --git a/docs/source/tutorials/images/brainrender-napari/added-brainrender-napari.png b/docs/source/tutorials/images/brainrender-napari/added-brainrender-napari.png
diff --git a/...tutorials/images/brainrender-napari/additional-reference-brainrender-napari.png b/...tutorials/images/brainrender-napari/additional-reference-brainrender-napari.png
diff --git a/...rce/tutorials/images/brainrender-napari/atlas-download-progress-in-terminal.png b/...rce/tutorials/images/brainrender-napari/atlas-download-progress-in-terminal.png
diff --git a/docs/source/tutorials/images/brainrender-napari/open-manager-widget.png b/docs/source/tutorials/images/brainrender-napari/open-manager-widget.png
diff --git a/docs/source/tutorials/images/brainrender-napari/plugin-menu-brainrender-napari.png b/docs/source/tutorials/images/brainrender-napari/plugin-menu-brainrender-napari.png
diff --git a/...urce/tutorials/images/brainrender-napari/toggle-ndisplay-brainrender-napari.png b/...urce/tutorials/images/brainrender-napari/toggle-ndisplay-brainrender-napari.png
diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md
@@ -46,6 +46,13 @@ Detecting cells in 3D with cellfinder in napari
 :link-type: doc
 Retraining the cellfinder cell classification network in napari
 :::
+
+:::{grid-item-card} {fas}`brain;sd-text-primary` Atlas download
+:img-bottom: images/atlas-versions.png
+:link: manage-atlases-in-GUI
+:link-type: doc
+Download an atlas with napari
+:::
 ::::
 
 ## Specific applications
@@ -81,6 +88,7 @@ Whole brain cell detection and registration
 :caption: Index
 :hidden:
 visualise-atlas-napari
+manage-atlases-in-GUI
 tutorial-whole-brain-registration
 segmenting-1d-tracks
 segmenting-3d-structures

diff --git a/docs/source/tutorials/manage-atlases-in-GUI.md b/docs/source/tutorials/manage-atlases-in-GUI.md
@@ -0,0 +1,25 @@
+# Download an atlas through napari
+
+In this tutorial, you will use `brainrender-napari`'s Atlas Manager widget to download a BrainGlobe atlas through a series of simple clicks. The [`mpin_zfish_1um` zebrafish brain atlas](https://doi.org/10.1016/j.neuron.2019.04.034) will serve as an example. 
+
+:::{note}
+You will need `napari` installed on your computer - please follow [`napari`'s installation instructions to do so](https://napari.org/stable/tutorials/fundamentals/installation.html).
+:::
+
+1. Open `napari`.
+2. Install `brainrender-napari` by selecting `Plugins > Install/Uninstall plugins` and searching for `brainrender-napari` in the searchbox. Then click on the `Install` button.
+3. Open the Atlas Manager widget by selecting `Plugins > Brainrender > Manage atlas versions` in the napari menu bar near the top left of the window. 
+![brainrender widget](./images/brainrender-napari/open-manager-widget.png)
+
+**The Atlas Manager widget appears on the right hand side of the window.**
+
+1. In the widget's `Atlas Manager` section, double-click the row which contains the `mpin_zfish_1um` atlas (you may have to scroll down slightly). The plugin will prompt you to download it (click yes). It may take a long time
+(depending on your internet speed) so please be patient. 
+
+:::{note}
+We are working on providing a progress indicator in `napari` - in the meantime, you can see download progress in the terminal from which you launched napari.
+:::
+
+![atlas manager dialog](./images/brainrender-napari/atlas-download-progress-in-terminal.png)
+
+**You have downloaded the zebrafish atlas - you can visualise it in napari by following our [atlas visualisation tutorial](./visualise-atlas-napari).**
diff --git a/docs/source/tutorials/visualise-atlas-napari.md b/docs/source/tutorials/visualise-atlas-napari.md
@@ -8,39 +8,42 @@ You will need `napari` installed on your computer - please follow [`napari`'s in
 
 1. Open `napari`.
 2. Install `brainrender-napari` by selecting `Plugins > Install/Uninstall plugins` and searching for `brainrender-napari` in the searchbox. Then click on the `Install` button.
-3. Open the `brainrender` widget by selecting `Plugins > Brainrender (brainrender-napari)` in the napari menu bar near the top left of the window. 
+
+:::{note}
+If you've not used BrainGlobe atlases before, you will need to download those you need. You can do this through the [command line](/documentation/brainglobe-atlasapi/usage/command-line-interface), or by following our (very short) ["Download an atlas in napari" tutorial](./manage-atlases-in-GUI).
+:::
+
+
+3. Open the `brainrender` widget by selecting `Plugins > brainrender > Brainrender` in the napari menu bar near the top left of the window. 
 ![brainrender widget](./images/brainrender-napari/plugin-menu-brainrender-napari.png)
 
-**The brainrender widget appears on the right hand side of the window.**
+**The brainrender widget appears on the right hand side of the window, listing all atlases you have downloaded**
 
-4. In the `brainrender` widget's `Atlas table view` section, double-click the row which contains the `mpin_zfish_1um` atlas (you may have to scroll down slightly).
+4. In the `brainrender` widget's `Atlas Viewer` section, double-click the row which contains the `mpin_zfish_1um` atlas (you may have to scroll down slightly, if you've downloaded many atlases).
 
 ![brainrender widget with added annotations](./images/brainrender-napari/added-brainrender-napari.png)
 
-**You have now added the annotations image and the default reference image to napari: They appear as layers in the napari layers list on the lower left of the window. A `3D Atlas region meshes` section appears below the `Atlas table view` section.**
-
-:::{note}
-If you haven't downloaded the atlas before, the plugin will prompt you to download it (click yes). It may take a long time
-(depending on your internet speed) so please be patient. Once downloaded, double-click again to view the atlas.
-:::
+**You have now added the annotations image and the default reference image to napari: They appear as layers in the napari layers list on the lower left of the window. A `3D Atlas region meshes` section appears below the `Atlas Viewer` section.**
 
 5. Toggle the napari display from 2D to 3D by pressing the button with the square icon on the lower left of the window.
 
 ![brainrender widget with 3d display](./images/brainrender-napari/toggle-ndisplay-brainrender-napari.png)
 
 **The annotations image should now be displayed in 3D.**
+
 6. Navigate the brain region tree in the `3D Atlas region meshes` section by opening "forebrain". Double-click on `telencephalon`.
 
 ![brainrender widget with region mesh](./images/brainrender-napari/add-region-brainrender-napari.png)
 
  **You have now added a 3D atlas region mesh layer, which appears as a mesh in the viewer and as a new layer in the layers list.**
-7. Back in the "Atlas table view" section, right-click on the `mpin_zfish_1um` row. In the menu that appears, select `GAD1b`.
+
+7. Back in the "Atlas Viewer" section, right-click on the `mpin_zfish_1um` row. In the menu that appears, select `GAD1b`.
 
 ![brainrender widget with additional reference](./images/brainrender-napari/additional-reference-brainrender-napari.png)
 
 **You have now added an additional reference image, which appears as a grey scale image in the viewer and as a new layer in the layers list.**
 
-You have now added all possible kinds of BrainGlobe atlas components (annotations image, reference image, 3D atlas region mesh, additional reference) to napari - well done! You can now add any of the other atlases listed in the `Atlas table view` if you like (note that not all atlases have additional references!). 
+You have now added all possible kinds of BrainGlobe atlas components (annotations image, reference image, 3D atlas region mesh, additional reference) to napari! You can now add any of the other atlases listed in the `Atlas Viewer` section if you like (note that not all atlases have additional references!). 
 
 :::{note}
 Hover over any of the elements in the `brainrender` widget to get additional hints about how to use them!

diff --git a/scripts/brainrender_napari_tutorial_screenshots.py b/scripts/brainrender_napari_tutorial_screenshots.py
@@ -0,0 +1,105 @@
+import napari
+from skimage.io import imsave
+from skimage.draw import disk
+import pytest
+import numpy as np
+import shutil
+from pathlib import Path
+
+VIEWPORT_WIDTH = 1400
+VIEWPORT_HEIGHT = 700
+
+COMPARE_OR_REGENERATE = "REGENERATE"
+RELATIVE_PATH_FOR_SCREENSHOTS = Path("./docs/source/tutorials/images/brainrender-napari/")    
+
+@pytest.fixture
+def standard_size_viewer(qtbot):
+    viewer = napari.Viewer()
+    viewer.window.resize(VIEWPORT_WIDTH, VIEWPORT_HEIGHT)
+    yield viewer
+    viewer.close()
+
+@pytest.fixture
+def take_viewer_screenshot(qtbot):
+    def _take_viewer_screenshot(viewer, path):
+        qtbot.wait(2000) # figure out how replace with qtbot.wait_exposed instead
+        screenshot = viewer.window.screenshot()
+        # hackily stick in a green point (or later, a cursor) at (x,y) with:
+        # screenshot[y, x] = [0, 255, 0, 255]
+        imsave(path, screenshot)
+    return _take_viewer_screenshot
+
+@pytest.fixture
+def clean_atlas_manager_widget(tmp_path, standard_size_viewer, take_viewer_screenshot):
+    """Returns an inner function that
+    - opens the brainglobe-segmentation widget
+    - configures the widget so an example project is loaded in atlas space
+    - saves a screenshot after each of the above steps
+    - returns the viewer and the widget
+    """
+    def _clean_atlas_manager_widget():
+        viewer = standard_size_viewer
+        _, atlas_manager_widget = viewer.window.add_plugin_dock_widget(
+            plugin_name="brainrender-napari", 
+            widget_name="Manage atlas versions"
+        )
+        atlas_manager_widget.viewer = viewer
+        viewer.show()
+
+        screenshot_file = RELATIVE_PATH_FOR_SCREENSHOTS / "open-manager-widget.png"
+        take_viewer_screenshot(viewer, screenshot_file)
+        return viewer, atlas_manager_widget
+
+    return _clean_atlas_manager_widget
+
+@pytest.fixture
+def clean_brainrender_widget(tmp_path, standard_size_viewer, take_viewer_screenshot):
+    """Returns an inner function that
+    - opens the brainglobe-segmentation widget
+    - configures the widget so an example project is loaded in atlas space
+    - saves a screenshot after each of the above steps
+    - returns the viewer and the widget
+    """
+    def _clean_brainrender_widget():
+        viewer = standard_size_viewer
+        _, brainrender_widget = viewer.window.add_plugin_dock_widget(
+            plugin_name="brainrender-napari", 
+            widget_name="Brainrender"
+        )
+        brainrender_widget.viewer = viewer
+        viewer.show()
+
+        screenshot_file = RELATIVE_PATH_FOR_SCREENSHOTS / "plugin-menu-brainrender-napari.png"
+        take_viewer_screenshot(viewer, screenshot_file)
+        return viewer, brainrender_widget
+
+    return _clean_brainrender_widget
+
+def test_manager_widget(tmp_path, take_viewer_screenshot, clean_atlas_manager_widget):
+    viewer, atlas_manager_widget = clean_atlas_manager_widget()
+
+def test_brainrender_widget(qtbot, tmp_path, take_viewer_screenshot, clean_brainrender_widget):
+    viewer, brainrender_widget = clean_brainrender_widget() # has already taken basic screenshot
+    fish_index = brainrender_widget.atlas_viewer_view.model().index(5,0) # fish is 5th row (some rows are hidden but still count!)
+    brainrender_widget.atlas_viewer_view.setCurrentIndex(fish_index)
+    brainrender_widget.atlas_viewer_view.doubleClicked.emit(fish_index)
+    screenshot_file = RELATIVE_PATH_FOR_SCREENSHOTS / "added-brainrender-napari.png"
+    take_viewer_screenshot(viewer, screenshot_file)
+
+    viewer.dims.ndisplay = 3
+    screenshot_file = RELATIVE_PATH_FOR_SCREENSHOTS / "toggle-ndisplay-brainrender-napari.png"
+    take_viewer_screenshot(viewer, screenshot_file)
+
+    root_index = brainrender_widget.structure_view.model().index(0,0)
+    forebrain_index = brainrender_widget.structure_view.model().index(0,0, root_index) 
+    telencephalon_index = brainrender_widget.structure_view.model().index(1,0, forebrain_index)
+    brainrender_widget.structure_view.setCurrentIndex(telencephalon_index)
+    brainrender_widget.structure_view.doubleClicked.emit(telencephalon_index)
+    screenshot_file = RELATIVE_PATH_FOR_SCREENSHOTS / "add-region-brainrender-napari.png"
+    take_viewer_screenshot(viewer, screenshot_file)
+
+    brainrender_widget.atlas_viewer_view.additional_reference_requested.emit("GAD1b")
+    screenshot_file = RELATIVE_PATH_FOR_SCREENSHOTS / "additional-reference-brainrender-napari.png"
+    take_viewer_screenshot(viewer, screenshot_file)
+
+