adapt brainrender-napari tutorial

docs/source/documentation/brainglobe-atlasapi/usage/command-line-interface.md

@@ -16,5 +16,7 @@ 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`.
+
+We also provide a [graphical user interface](/tutorials/manage-atlases-in-GUI) to download and update atlases, as part of the `brainrender-napari` package.
 

docs/source/tutorials/index.md

@@ -5,6 +5,13 @@
 ::::{grid} 1 2 2 3
 :gutter: 3
 
+:::{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 through napari
+:::
+
 :::{grid-item-card} {fas}`brain;sd-text-primary` Atlas visualisation
 :img-bottom: images/visualise-atlas-napari.png
 :link: visualise-atlas-napari
@@ -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

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).**

docs/source/tutorials/visualise-atlas-napari.md

@@ -8,39 +8,41 @@ 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 - well done! 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!

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)
+
+