brainglobe / brainrender-napari

A napari plugin to render BrainGlobe atlases and associated data as layers.

BrainGlobe

General information, resources, high-level issues and dicussions for the BrainGlobe project. For more details see brainglobe.info. For developer meeting summaries, see the Discussions tab - developer meetings are open to anyone, join the Zulip chat to participate.

brainrender-napari's Issues

[Feature] Incorporate developer and user docs for brainrender napari in the main website

Make need for slow downloading of a non-local atlas explicit to the user with a "Download" button

Related issues #5 #7 #13

Make it clearer what the `Structures` part of the widget does.

Once you know what it does, it's intuitive, but when you first use it it's not clear that it adds 3D meshes on top of the existing images (these are only really obvious in 3D).

[BUG] mesh default colouring mostly shows as white

Describe the bug
Almost all mesh-adding to napari results in a white-coloured mesh.

To Reproduce
Add meshes to napari via the atlas viewer widget.

Expected behaviour
Default colour specified in structures.json should propagate to napari mesh vertex colouring when a mesh is added.

Additional context
This happens because we are missing a conversion from RGB (in structures.json) to rgb (what napari expects).

Windows tests are super slow suddenly.

Something is wrong with them (Linux and Mac tests take < 10mins, but Windows takes 1h+!)
Opening this so we can merge PRs that pass all tests other than the Windows one in good conscience, because we'll remember to address this.

Beautify the way atlas metadata is displayed in viewer widget

Currently it's a QTextEdit of the string representation of the BrainGlobeAtlas and it looks awful :)

[BUG] Structure view doesn't show after atlas is newly downloaded.

Should just be a matter of calling refresh() in the on_downloaded function somewhere.

Nicer UI for downloading atlases

There should be a progress bar and the opportunity to cancel the download (instead of having to confirm it).
Could part of this be moved into bg_atlasapi ? Maybe with a yield statement giving updates that can be shown in the progress bar here?

Related: brainglobe/brainglobe-atlasapi#121

Investigate replacing derived classes with Qt standards

Currently, all of our model/view/item classes are derived from a Qt abstract class.
We could maybe replace some with Qt standard concrete implementations instead of rolling our own.

Beautify acronym-name structure toggle

see initial attempt at this in https://github.com/brainglobe/brainrender-napari/tree/complex-structure-tree-view

[BUG] hacky tooltip can persist sometimes

Describe the bug
Moving the mouse too quickly can leave the hacky tooltip from #85 lying around.

Additional context
Maybe fixable by adding a callback to any layer (selection) change to hide all tooltips

Expose setting the colour of the structure mesh to the user

Downloading a new atlas via the Atlas viewer should not block napari viewer.

Initial user feedback

This issue will be addressed when we've

• asked users at SWC and other friends to try brainrender-napari 0.0.1 and the relevant tutorial on the website.
• taken their feedback and organised it into new issues

User instructions about basic brainrender-napari UI functionality

We should have an intuitive way for users to find out they can double-click on the atlas table view and structure tree view to add things to napari. Maybe an info logo to hover over? More/alternative suggestions welcome!

#49 (comment)

Cache atlas details

It's a bit laggy moving from one atlas to another. I guess this is because the atlas class needs to be initiated. Until bg-atlasapi V2 is complete, it would be useful to cache atlas details to speed things up.

Ideas for the integration of BrainGlobe atlases within napari

Currently BrainGlobe atlases are used by napari plugins (e.g. brainreg, brainreg-segment), but these are not accessible by napari plugins directly (only by using bg-atlasapi in the plugin code). It would be useful to be able to load, visualise and manipulate these atlases for many reasons, e.g.:

• To visualise atlas data
• To use the atlases as a target for third party registration libraries
• To define coordinate spaces for other analysis tools

As a first pass, my idea is to create a napari plugin that will include some of the functionality of the brainglobe atlas API and CLI, including:

• Query available atlases
• Inspect atlas metadata
• Load (and visualise) atlases

bg-atlasapi represents atlases as an abstract object. It would also be useful to do the same within napari. i.e. represent all the information within an atlas object as a "thing". It won't be a new layer type, but as close to this as possible (layer group?).

A sketch of my idea:

cc @alessandrofelder @dstansby

Separate render settings from napari atlas representation

See #31 (comment) and https://github.com/brainglobe/brainrender/blob/master/brainrender/settings.py

[Feature] Make downloading an atlas robust

While an atlas is being downloaded, double-clicking on said atlas should not break anything. I'm not sure it does currently, but I think it might?

Describe the solution you'd like
Full robustness and good UI for this. Maybe disabling and greying out the row of the atlas currently being download. Related to #62

Describe alternatives you've considered
None yet, but open to suggestions

Additional context
Continuation of #7

Discuss and design sorting behaviour and user options of atlas table view

Atlas Viewer widget currently does not sort or allow the user to sort in any way. Order is just what BG atlas API gives.

Inside napari, the plugin should be named "brainrender"

"Brainrender napari" is unnecessary in the napari plugin menu

Filter by species widget?

Would it be useful for users to filter the tableview in the viewer widget by species?

[Feature] Add robustness to tests (mesh extents relative to annotations)

This issue will be addressed when we have tests that check that mesh and annotations image extents in napari world coords roughly match.

See brainglobe/brainglobe-atlasapi#231 for difficulties encountered.

Display more columns in Atlas table view

bg-atlas API shows more info when calling show_atlases but this info is generated on the fly by the function, and not accessible directly elsewhere (so maybe that should be refactored before tackling this). That info should also be displayed and kept up-to-date in the Atlas viewer's table view.

Add to napari hub collection

Once this plugin is released (and the name decided #40), this plugin should be added to the BrainGlobe collection on the napari hub. It can be added here.

[meta-issue] waiting on napari

A place to track where we are waiting on changes in napari

• ability to add group layers (see lower left corner of image in #1)
• ability to add custom viewer tooltips (see #85 )
• ability to add callbacks to layer deletion (should be possible via napari/napari#5967, but not in a stable release at time of writing) so we can reset hacky tooltips (may not be needed if we get custom viewer tooltips earlier) - see #88

Think about exposing a Python API

As this package accrues more and more features, it would be useful to be able to build up a scene without necessarily using the GUI. I think two features would be useful to think about:

• Expose a Python API
• Provide functionality to save the current state of the scene e.g. layers loaded
  • Potentially also export a script to recreate the scene

comprehensive typehints

How to best let (advanced) users customise user data and config locations?

IIUC there are currently several ways to customise where downloaded atlases are stored

• by passing brainglobe_dir as an argument to the BrainGlobeAtlas constructor
• by passing config_dir as an argument to the BrainGlobeAtlas constructor
• by setting the BRAINGLOBE_CONFIG_DIR environmental variable and storing a config file there.

This has some consequences that can

• if both brainglobe_dir and config_dir are passed, brainglobe_dir takes precendence (I think, but this is undocumented!)
• if brainglobe_dir is passed to BrainGlobeAtlas() (and therefore an atlas is downloaded), that atlas will not be part of the output of get_downloaded_versions().
• it's unclear how widgets should best deal with customisable user data and config folders.

Additionally, code interacting with the bg_atlasapi API will need to remember to pass the right arguments, making this susceptible to having to change things in many different places if bg_atlasapi changes.

• we should also think about, and document, backwards compatibility and/or migration if we do decide on a new way of doing this.

This is possibly a more-fleshed-out duplicate of brainglobe/brainglobe-atlasapi#150 and should replace it in that repo?

Allow user to hover over a brain region and see the metadata.

This is currently implemented within brainreg-segment:

https://github.com/brainglobe/brainreg-segment/blob/a84d4b2fab53c256590b79d57beb1eac5810ef0f/brainreg_segment/segment.py#L91-L105

Ideally this would:

1. use tooltips instead (brainglobe/brainglobe-segmentation#89)
2. Be visible regardless of what layers are added/visible (as long as one is!), not just the annotations layer

I think for 1. the metadata would have to be added to the annotation layer itself

Rename brainglobe-napari > brainrender-napari

Simplify widget visuals

pin to newest napari RC

This would help fix the problem described in #31 (comment) (but would we then have to pin the entirety of brainglobe and is that a good idea?

Avoid tests messing with user installation of BG

For the tests, maybe the brainglobe atlas directory should be set to somewhere in tmp_dir?

The syntax is:

atlas = BrainGlobeAtlas("atlas_name", brainglobe_dir="/path/to/dir")

We could therefore pass brainglobe_dir as a fixture to the relevant methods during tests so that the tests don't interfere with any existing brainglobe installation. We could even detect being in a GitHub actions environment and pass None in this case to test everything in the default location.

Implement logic to deal with new atlas versions

This issue will be addressed once

• the atlas table view widget shows the columns drawn in the top right of image below (re-used from #1 )
• tests have been added that check the updating-an-atlas functionality

brainrender widget should have brainglobe logo at top

Cache atlases in GHA workflow

• at least some of them, so we test that widget triggers download on at least one.
• will help with accelerating tests.

Decide on naming.

brainrender is pretty popular, has a published paper, and Fede has spent a long time working on it. For this reason I think the napari port of BrainGlobe's 3D visualisation should keep the brainrender name. I can see two options:

• Rename this plugin to brainrender-napari and any other (non-visualisation) functionality lives elsewhere
• Keep the brainrender-napari name as a general plugin, but make sure there's a widget or something that is specifically named brainrender.

Any thoughts @alessandrofelder

[Feature] Add robustness to tests (anisotropic atlas)

This issue will be addressed when we add tests around the scale of an anisotropic atlas to test_napari_atlas_representation.py.
The spinal cord atlas is anisotropic, but there seem to be some issues around its orientation. See brainglobe/brainglobe-atlasapi#231

Split `test_napari_atlas_representation.test_add_to_viewer` into several tests

Remove metadata caching in favour of atlas API calls

Depends on brainglobe/brainglobe-atlasapi#149 being addressed.

See also #13.

Toggle between name and acronyms in structure tree view

Add more than just annotations image in Atlas viewer

Version 0.0 just adds the annotations image but more layers are needed for a full atlas.

Make plugin robust to lack of internet connection

Currently opening this widget offline crashes, because get_all_atlases_lastversions() errors without an internet connection. We should be robust to this case, and display a warning and local versions of downloaded atlases instead!

Avoid duplication of napari layers when visualising atlases

Version 0.0 of the atlas viewer will just add another layer:

We could either replace the layer, or do some fancy checking of whether replacing the layer is needed in the first place.

Move setup.cfg to pyproject.toml

Follow NIU cookiecutter as far as possible!

[BUG] Clicking on name of structure causes crash

Describe the bug
Trying to add a structure via its name instead of its acronym crashes

To Reproduce

• open brainrender napari
• select a downloaded atlas
• check "show structure names" checkbox
• double-click on name column somewhere

Expected behaviour

Log file
n/a

Computer used (please complete the following information):
not relevant here

Additional context
Fix is to change StructureView.selected_structure_name() to return the data in sibling index at column 0

Refactor internal structure of AtlasViewerWidget

Maybe AtlasTableView or a general BG table view deserve their own class.

Use the NIU python cookiecutter format

https://github.com/neuroinformatics-unit/python-cookiecutter

Integrate napari layer group into atlas viewer plugin

Currently, we just add each part of the atlas we are interested in as a separate layer to napari. In the future, the napari representation of a BG Atlas should be a layer group containing all the layers of one atlas together.