Skip to content
Snippets Groups Projects
Commit 8f322592 authored by Xiao Gui's avatar Xiao Gui
Browse files

WIP: docs structure

parent 303efaab
No related branches found
No related tags found
No related merge requests found
Showing
with 184 additions and 29 deletions
# Annotating Structures in the Brain
(TBD)
<!--
- accessible via the tool menu
- allows to annotate points and polylines
- when authenticated, they are preserved of the logged in user
- annotations can be downloaded as json, and imported in siibra-python for programmatic workflows
-->
# Differential Gene Expression Analysis
(TBD)
<!--
short description of siibra-jugex plugin with links to other resources
-->
# Superimposing Local Files
siibra-explorer experimentally supports overlaying spatial features on top of existing atlas. They are never uploaded to any server, and are processed locally on your computer/browser.
!!! info
As the files never leave your browser, URL sharing will not include superimposed file.
!!! warning
Modern browser impose severe limitations on the amount of resources browser can request. As a result, loading local files may fail based on the spec of your machine (better spec, particularly RAM, reduces the likelihood of failure), size of the file (smaller file reduces the likelihood of failure), amidst other potential factors.
To start, navigate to the atlas/template/parcellation map o your choice, then drag and drop the file you would like to super impose.
## NIFTI
siibra-explorer carries out a number of verification/normalization steps to ensure the volume is displayed correctly:
- `FLOAT64` is currently not supported by the underlying view engine, siibra-explorer will inform the user if the nifti uses `FLOAT64` datatype
- `dim4`, if set to > 1, indicates a time series. Since times series is not yet supported by the underlying view engine, siibra-explorer will inform the user
- `dim4`, if set to 0, will be set to 1
- `xyzt_unit`, if unset, will be set to mm, sec
- the volume will be normalized between min and max
- the affine of the volume is handled by the underlying view engine, neuroglancer
## SWC
SWC files are plain text files encoding the structure of one (or more) neurons. One of the difficulty of overlaying SWC files on top of atlases is the lack of standardization of space (voxel vs physical, different MNI152 spaces etc).
Whilst siibra-explorer makes a best attempt at parsing the SWC file, it is likely that some SWC may still be parsed poorly. Feel free to contact us to have it rectified.
## JSON (Pointclouds)
Pointclouds generated by the Nutil workflow in JSON format can be visualized in siibra-explorer. Pointcloud JSON file must be in CCF v3 (or, in Nutil parlance, ABA) space.
# Exploring 3D Parcellation Maps
Based on the displayed reference template and brain parcellation, siibra-explorer provides functionalities for downloading the volumes, browsing brain region hierarchies, and retrieving various data features, such as regional distributions of cells and neurotransmitters structural, or/and functional connectivity between brain regions.
Depending on the type of the selected reference template, the view differs.
## Navigation Volumetric Maps
In the case of a volumetric template, siibra-explorer combines a rotatable 3D surface view of a brain volume with three planar views of orthogonal image planes (coronal, sagittal, horizontal). It can visualize very large brain volumes in the terabyte range.
![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/julichbrain_bigbrain_4panel.png)
Each planar view allows zooming (`[mouse-wheel]`) and panning (`[mouse-drag]`), and can be maximized to full screen (`[mouse-over]` then `<click>` on `[ ]` icon) to behave like a 2D image viewer. You can select arbitrary non-orthogonal cutting planes (`<shift> + [mouse-drag]`), so that cortical layers may be inspected in their optimal 3D orientation when browsing a microscopic brain volume.
![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/julichbrain_bigbrain_coronal.png)
Users can explore the reference atlas at higher resolution (if available) by zooming in on the planar views.
Independent of the available resolution of the volumetric reference atlas, the resolution of the 3D view is locked to always show the whole brain and provide the 3D topographical context.
## Navigating surface maps
In the case of a surface template, siibra-explorer shows a single view presenting the surface of the reference template.
![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/julichbrain_fsaverage.png)
# Finding Multimodal Data
The viewer links many multimodal datasets to locations in the brain. You can discover such dasets by selecting brain regions or navigating the 3D view.
## Datasets Linked to Regions
(TBD)
## Datasets Linked to the View
(TBD)
<!--
- when no region is selected, siibra searches for image data anchored to the current referee space and viewport
- when zooming in, list is filtered
- may take a little delay on slow internet connections, since it updates whenever the view is changed
- open the spatial feature panel to see bounding boxes and select anchored image datasets
-->
../../common/helpOnePager.md
\ No newline at end of file
# Looking Up Coordinates in Reference Space
Use `<right click>` to access extended information for a specific 3D coordinate. siibra-explorer can lookup the values of all statistical maps in the current parcellations.
![](https://data-proxy.ebrains.eu/api/v1/buckets/reference-atlas-data/static/point_assignment.png)
# Selecting Brain Regions
(TBD)
<!--
Finding and selecting regions
- by clicking regions in volume or surface
- by navigating the regiontree
- if available, statistical map of selected region will be loaded
- result: sidepanel
- allows to navigate to the region
- provides link to original dataset of the statistical map, if applicable
- provides list of datasets anchored to the region
- provides connectivity browser
- Disclaimer: multi-region selections not yet possible
-->
# Selecting Parcellation Maps
(TBD)
# Storing and Sharing 3D Views
## Bookmarks
Any views in siibra-explorer can be shared via their URLs. You can use any native share functionality offered by your browser, or manually copy the URL.
!!! info
Automatic markdown renderer such as rocketchat can interfere with the rendering of the URL. To circumvent the issue, it is recommended that you generate a sane URL, or use a `code` block to escape markup
## sane URL
Whilst sharing views with URLs are convenient, full URLs are lengthy, fail to be recitable or memorable. While you can use any URL shortener, siibra-explorer provide a URL shortener. To access this service, expand navigation panel, click share icon and click `Create custom URL`.
!!! warning
Links generated by unauthenticated users will expire automatically after 72 hours. To circumvent the expiry, ensure you are logged in using an ebrains user account. Links generated by an authenticated user does not expire.
## Taking Screenshots
Whilst you can use any browser level or OS level screenshot tool, siibra-explorer also offers a screenshot tool. To access the screenshot tool, click `Plugin`, then select `Screenshot`.
!!! info
Screenshot taken by the built in screenshot tool hides all UIs.
......@@ -10,6 +10,6 @@ div.autodoc-members {
}
img {
width: 50%;
width: 100%;
display: inline-block;
}
\ No newline at end of file
# Getting Started
## System Requirements
Any up to date modern browsers (Chrome, Firefox, Safari). In addition, your hardware needs to support WebGL2.
!!! Info
To check if your device and browser support WebGL2, visit <https://get.webgl.org/webgl2/>.
## Launching siibra-explorer
To launch siibra-explorer go to <https://atlases.ebrains.eu/viewer> in your web browser.
!!! info
An overview and the basic functionalities of siibra-explorer is presented in the quick tour, which is automatically launched on first use. You can always revisit the quick tour via the help menu, which can be found under the `?` icon at the top right of the UI, or using the `?` / `h` keyboard shortcut.
......@@ -7,8 +7,4 @@
## Overview
siibra-explorer is a browser based 3D viewer for exploring multi-resolution brain atlases and discovering spatially relevant data features covering a broad range of neuroscientific data modalities.
siibra-explorer provides an intuitive way of navigating brain reference volumes and 3D parcellation maps from conventional millimeter scale down to microscopic resolution. You can select different species, brain reference spaces and parcellation maps, search region hierarchies, and select brain regions to access detailed information. Data features are dynamically retrieved for selected parcellation regions or 3D views.
![](https://object.cscs.ch:443/v1/AUTH_7e4157014a3d4c1f8ffe270b57008fd4/reference-atlas-data/static/bigbrain_cortical.png)
siibra-explorer is a browser based 3D viewer for exploring multi-resolution brain atlases and discovering data features linked from different repositories to anatomical locations, covering a broad range of neuroscientific data modalities . The viewer provides an intuitive way of navigating brain reference volumes and 3D parcellation maps from conventional millimeter scale down to microscopic resolution. You can select different species, brain reference spaces and parcellation maps, search region hierarchies, and select brain regions to access detailed information. Data features are dynamically retrieved for selected parcellation regions or 3D views.
# Main elements of siibra-explorer
(TBD)
<!--
At its core, the viewer presents a 3D view of a brain. Per default, you see a volume in three orthogonal planes, …. In some cases, you just see a brain surface. Navigation inside these views is dewscribed in [Navigating volumetric..]
At the bottom of the viewer, you find element to select different species, parcellations and reference spaces. These are explained in …
At the top right of the views, there are several icons guiding you to additional dunctionalites. [help] [plugins] [settings]
-->
# What Makes a Brain Atlas
siibra organizes atlases into the following conceptual structures:
- Atlases. An atlas can be understood as a collection of complementary parcellations and reference spaces for a particular species, with links between brain regions, spatial locations and anatomically organized data features.
- Reference spaces. A reference space defines a coordinate system in the brain. Since reference spaces can be of different type (e.g. volumetric or surface-based, single-subject of average subject), an atlas can support multiple reference spaces. Each reference space comes with at least one reference template, which is an image volume or mesh representing the brain structures in that space.
- Parcellations. A parcellation defines a (searchable) hierarchy of brain regions and corresponding metadata, and thus represents a semantic object. Different parcellations may reflect different organizational principles of the brain, and thus an atlas can offer multiple, typically complementary parcellations. Each parcellation is linked to a set of corresponding parcellation maps.
- Parcellation maps. The regions defined by a given parcellation can be mapped in multiple reference spaces. The actual parcellation maps are spatial objects. They take the form of image volumes or surface meshes, and can be of labelled type, where coordinates or vertices in the reference space have a single unique brain region label, or of statistical type, where coordinates are linked to one floating point value per brain region, reflecting the weight or probability of each region at the given coordinate. Since statistical maps of closeby brain regions usually overlap, they are typically accessed by selecting a specific region from a labelled map in siibra-explorer.
- Regions. A region represents a subtree of a region hierarchy, and contains metadata about the parcellation it belongs to, the parcellation maps where it is included, related publications, and more. Each region has links to its parent and child regions.
# System requirements
Siibra exporer relies on [WebGL2.0](https://en.wikipedia.org/wiki/WebGL).
!!! info
To check if your device and browser combination support webgl 2.0, visit <https://get.webgl.org/webgl2/>.
## Desktop
- PC (Windows/Linux/MacOS)
- Latest Chrome/Firefox/Safari
- Dedicated graphics card (optional, but will drastically improve the performance)
## Mobile
- Latest Chrome/Firefox/Safari
You can download the currently selected reference template and parcellation map for offline use by clicking the button on the top right:
To launch siibra-explorer go to [https://atlases.ebrains.eu/viewer/](https://atlases.ebrains.eu/viewer/) in your web browser. The human atlas will be automatically selected.
If this is your first time using siibra-explorer, you will be prompted to take a quick tour. The quick tour can give a good first overview on siibra-explorer and explains the usage of basic functionalities.
You can always revisit the quick tour by first bringing up the help panel with the `[?]` key, or by clicking the `(?)` button at top right corner. Afterwards, the option to relaunch the quick tour can be found at the bottom of the help panel.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment