[Feature]:Atlas-Registered Dataset Browsing and Visualization

[HARSHDIPSAHA]

Is your feature request related to a problem? Please describe.

The BrainGlobe brainrender tool is widely used to visualize brain data in a common coordinate space defined by a "brain atlas" (referred to as "atlas-registered" data). However, brainrender is inaccessible to people without programming skills. The brainrender-napari tool aims to make brainrender functionality available to more people through a plugin for the popular open-source graphical image viewer napari.

Although brainrender and brainrender-napari share some functionality, publicly available atlas-registered data is not yet available in brainrender-napari. Users currently cannot browse, download, or visualize atlas-registered datasets (such as neuron morphologies from Allen Brain Atlas, Janelia MouseLight, or NeuroMorpho.Org) directly within the napari interface, which limits the tool's utility for researchers who want to explore and visualize publicly available neuroanatomical data without writing Python code.

Describe the solution you'd like

A Python implementation of a napari widget that allows users to:

1. Browse and Search Public Databases(inspiration and use of https://github.com/brainglobe/morphapi):

   • Search for atlas-registered datasets from multiple sources:
     • Allen Brain Atlas (mouse neurons)
     • Janelia MouseLight
     • NeuroMorpho.Org
   • Filter datasets by species, brain structure, cell type, and other metadata
   • Display search results in an interactive table with dataset information

2. Download Datasets:

   • Download datasets directly from external APIs with progress tracking
   • Support for multiple data formats (SWC, NRRD, image files)
   • Automatic metadata extraction and storage
   • Track downloaded vs. available datasets with visual indicators

3. Visualize Datasets in napari:

   • Automatically load and visualize downloaded datasets as appropriate napari layer types:
     • Points layers for cell positions or individual points
     • Shapes/Paths layers for connected neuron morphologies (streamlines)
     • Image/Volume layers for volumetric data (projection densities, etc.)
   • Maintain all original brainrender-napari features

4. User Interface:

• Integrated widget accessible from napari's plugin menu
• Clean separation between database search and dataset management
• Visual feedback for download progress and visualization status
• Contextual help and informative messages

Describe alternatives you've considered

1. Static Example Files: Instead of dynamic API integration, I considered providing static example files for testing. However, this approach is limiting and doesn't scale to the thousands of publicly available datasets.

2. Manual Dataset Registration: We could require users to manually register datasets with metadata files. However, this adds friction and doesn't leverage existing database APIs that already have rich metadata.

Additional context

Implementation Details

Key Components:

• BrainrenderDatasetWidget: Main widget integrating database search and dataset management
• DatabaseSearchWidget: UI for searching external databases with filtering capabilities
• DatasetManagerView: Interactive table for browsing downloaded and available datasets
• morphapi_integration.py: Integration layer for Allen Brain Atlas, MouseLight, and NeuroMorpho.Org APIs
• visualize_datasets.py: Utilities for converting downloaded datasets into napari layers with proper coordinate handling
• download_datasets.py: Dataset management, download orchestration, and file format handling

Technical Challenges Addressed:

1. File Format Detection: Some APIs return files with incorrect extensions (e.g., JPEG files with .nrrd extension). Implemented robust format detection by reading file headers.

2. Layer Visibility and Ordering: Ensured that when datasets are loaded before or after atlas layers, all layers remain visible and properly ordered (reference background → annotation → dataset layers).

3. 3D Rotation Visibility: Configured layers with out_of_slice_display=True to ensure neurons remain visible during 3D rotation and zoom operations with touchpad gestures.

Preserved Original Features:

• All original brainrender-napari functionality remains intact
• Structure label tooltips on hover/zoom
• 3D view toggle (2D/3D display switching)
• Atlas region mesh visualization
• Additional reference image support
• Layer controls and visibility toggles

Testing:

• Unit tests for dataset table models, search results models, download utilities, and visualization functions
• Integration tests for widget initialization and user interactions
• Coordinate transformation validation tests
• File format detection tests

Dependencies Added:

• morphapi: For programmatic access to neuron morphology databases
• requests: For API interactions
• pandas: For data handling in search results

Use Cases

1. Exploratory Analysis: Researchers can quickly browse and visualize neuron morphologies from different brain regions to understand spatial distributions.

2. Teaching and Demonstration: Educators can download and visualize example datasets to demonstrate neuroanatomical concepts without programming.

3. Data Validation: Users can compare their own data with publicly available datasets by loading both in the same napari viewer.

Future Enhancements

Currenlty i am uploading the neuron in the napari space itself and the user can drag it and fit it inside brain atlas, but I am not sure how to do this manually,it would be great if i get direction on this.

---

[HARSHDIPSAHA]

@adamltyson @alessandrofelder @IgorTatarnikov please review, so that i can work more on it and make changes in this feature.

[adamltyson]

Hi @HARSHDIPSAHA, this is definately on our roadmap, but it's not something we want to implement just yet. Our current plan is to create a Data API to access this data in a more streamlined way, and then brainrender and brainrender-napari can depend on that. For this reason, this feature isn't a priority yet.