WIP: docs structure

docs/advanced_functionalities/annotating_structures.md

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

docs/advanced_functionalities/differential_gene_expression_analysis.md

+# Differential Gene Expression Analysis
+
+(TBD)
+<!-- 
+short description of siibra-jugex plugin with links to other resources
+ -->

docs/advanced_functionalities/superimposing_local_files.md

+# 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.

docs/basic_functionalities/exploring_3d_parcellation_maps.md

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

docs/basic_functionalities/finding_multimodal_data.md

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

docs/basic_functionalities/helperOnePager.md

+../../common/helpOnePager.md
\ No newline at end of file

docs/basic_functionalities/looking_up_coordinates.md

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

docs/basic_functionalities/selecting_brain_regions.md

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

docs/basic_functionalities/selecting_parcellation_maps.md

+# Selecting Parcellation Maps
+
+(TBD)

docs/basic_functionalities/storing_and_sharing_3d_views.md

+# 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. 

docs/extra.css

@@ -10,6 +10,6 @@ div.autodoc-members {
 }
 
 img {
-  width: 50%;
+  width: 100%;
   display: inline-block;
 }
\ No newline at end of file

docs/getting_started.md

+# 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. 

docs/index.md

@@ -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. 

docs/main_concepts/main_elements_of_the_viewer.md

+# 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]
+ -->

docs/main_concepts/what_makes_a_brain_atlas.md

+# 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.

docs/requirements.md

-# 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

docs/usage/download_maps.md

-You can download the currently selected reference template and parcellation map for offline use by clicking the button on the top right:
-

docs/usage/get_started.md

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