You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/brain.rst
+241-28
Original file line number
Diff line number
Diff line change
@@ -1,59 +1,266 @@
1
1
.. _Brain:
2
2
3
3
Brain
4
-
======
4
+
=====
5
5
6
-
Description
7
-
-----------
8
-
9
-
.. figure:: picture/example.png
10
-
:align:center
11
-
12
-
Brain is a flexible graphical user interface for 3D visualizations on an MNI brain. It can be use to display deep sources, brodmann areas, materialize connectivity... This module use `vispy <http://vispy.org/>`_ and can be imported as follow :
6
+
*Brain* is a flexible graphical user interface for 3D visualizations on an MNI brain. It can be use to display deep sources, connectivity, region of interest... This module can be imported as follow :
13
7
14
8
.. code-block:: python
15
9
16
10
from visbrain import Brain
17
11
18
-
Visit this page for a set of `examples <https://github.com/EtienneCmb/visbrain/tree/master/examples/brain>`_.
12
+
Visit this page for a set of `examples <http://visbrain.org/auto_examples/index.html#brain-examples>`_.
19
13
20
-
Objects
21
-
-------
14
+
Main features
15
+
-------------
22
16
23
-
There's four fundamental objects in Brain :
17
+
GUI description
18
+
~~~~~~~~~~~~~~~
24
19
25
-
* The main brain, which can be generated using one of the three possible template or simply pass vertices / faces of your own template.
26
-
* Sources, which can represent deep electrodes, EEG / MEG captors or source localization...
27
-
* Connectivity, in order to materialize a connexion strength between those sources (like coherence, amplitude-amplitude coupling...)
28
-
* ROI (Region Of Interest), which are brain sub-structures (Brodmann areas or AAL)
20
+
The *Brain* graphical user interface is subdivided into three main parts :
29
21
22
+
* **Main canvas** where the brain is displayed
23
+
* **Menu** (*Save/load GUI config, take a screenshot*)
* Cbar tab (*colorbar properties of the selected object*)
31
+
32
+
.. note::
33
+
34
+
If you want to save the current GUI state (i.e. all buttons properties) and retrieve it later, use the menu File/Save/GUI config and File/Load/GUI config or the associated *Brain* method.
Brain can manage several types of color inputs. All possible colors can be a matplotlib color name ('olive', 'slateblue'...), an hexadecimal type ('#9b59b6', '#3498db', '#95a5a6'...*) or an array of RGB or RGBA colors ((1., 0., 0.), (.1, .1, .1)...).
39
46
40
-
The colormap can be personalized using five variables :
47
+
MNI templates
48
+
~~~~~~~~~~~~~
49
+
50
+
.. figure:: picture/picbrain/brain_templates.png
51
+
:align:center
52
+
53
+
By default, *Brain* comes with three brain templates respectively B1 (with cerebellum), B2 and B3 (smoothest). But this list can be extended using those following functions :
54
+
55
+
* :ref:`ConvertMeshData` : convert vertices and faces to be compatibles with *Brain*
56
+
* :ref:`AddBrainTemplate` and :ref:`RemoveBrainTemplate` : using converted vertices and faces, add/remove the template to visbrain
57
+
58
+
Further brain templates can be downloaded `here <https://drive.google.com/open?id=0B6vtJiCQZUBvd0xfTHJqcHg2bTA>`_.
Sources can be added to the scene using (x, y, z) MNI coordinates and comes with a relatively large number of properties (radius, color, shape...). Source's array of coordinates must be have a shape of (N, 3) with **N** the number of sources. In addition, several objects can be attached to sources :
77
+
78
+
* **Text :** add a text to each source.
79
+
* **Source's data :** must be (N,) vector of data (for instance beta power, entropy, amplitude...). The radius of each source is then proportional to the data attached to it. This activity can be projected onto the brain surface using the cortical projection.
80
+
* **Connectivity :** must be a (N, N) upper triangular array describing how to connect sources
81
+
* **Time-series and/or pictures** : finally, it's also possible to visualize signals (such as time-series, spectral signals...) and 2-D pictures (time-frequency maps, comodulogram...)
* clim : define the colorbar limits (like (-10, 10) or (-245, 7)...). The clim parameter must be a tuple/list of two floats. Every values over or under the colorbar limits will clip.
43
-
* vmin / under : vmin is a float and under is a color. The vmin parameter can be defined in order to control the color of data that is under vmin.
44
-
* vmax / over : vmax is a float and over is a color. The over parameter can be defined in order to control the color of data that is over vmax.
93
+
Cortical projection and repartition
94
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
45
95
46
-
.. figure:: picture/colormap.png
96
+
.. figure:: picture/picbrain/brain_projection.png
47
97
:align:center
48
98
99
+
Cortical projection of source's activity (Left) and source's repartition (Right).
100
+
101
+
* **Cortical projection :** correspond to the projection of source's activity onto the brain (or ROI) surface.
102
+
* **Cortical repartition :** correspond to the number of sources contributing to each vertex of the surface. This is particularly convenient to inspect how sources are distributed on the surface.
103
+
104
+
Both methods use a **radius** parameter and only vertices with an euclidian distance under **radius** are going to be considered. From the GUI, those functions can be executed from the menu *Project*, from the tab *Sources/Properties/Projection*, using keyboard :ref:`BrainShortcuts` or *Brain* methods.
In the current 0.3.0 visbrain version, time-series and pictures don't rotate with the brain. As a consequence those elements can only be visualized in axial view. This should be solved in next release.
165
+
166
+
Volume
167
+
~~~~~~
168
+
169
+
Brain templates are surfaces defined by vertices and faces. In contrast, volumes are defined with a 3-D array (Nx, Ny, Nz). There is three scenarios where volumes can be used in *Brain*:
170
+
171
+
* **Cross-sections :** inspect volumes using slices
172
+
* **Region Of Interest (ROI) :** display deep brain regions
173
+
* **3-D volume rendering :** use VisPy.visuals.Volume rendering methods (mip, translucent, additive and iso)
174
+
175
+
Those volumes can be used to visualize nifti, dycom or any image files. By default, *Brain* comes with two volume files : **Brodmann areas** and **Anatomical Automatic Labeling (AAL)**.
176
+
177
+
Cross-sections
178
+
^^^^^^^^^^^^^^
179
+
180
+
.. figure:: picture/picbrain/brain_crossec.png
181
+
:align:center
182
+
183
+
Cross-sections of a Nifti volume
184
+
185
+
Cross-sections correspond to an axial, sagittal and coronal slice of the volume and can either be visualize in 3-D (inside the brain template) or in slitted view
Cortical projection on the thalamus (Left) and cortical repartition on Brodmann area 4 and 6.
203
+
204
+
If a volume is provided with corresponding labels, ROIs can be extracted and then be transformed into a mesh, compatible with source's projection methods.
The user functions correspond to a bundle of functions that can be used to control Brain operations without opening the graphical interface. This can be convenient to generate a large amount of pictures.
259
+
The user functions correspond to a bundle of functions that can be used to control Brain operations without opening the graphical interface. This can be convenient to generate a large amount of pictures.
53
260
54
261
.. toctree::
55
262
:maxdepth:4
56
-
263
+
57
264
brainAPI
58
265
59
266
@@ -64,23 +271,29 @@ See this tutorial to export your figures in a proper way in order to use them in
0 commit comments