diff --git a/doc/conf.py b/doc/conf.py
index 2d71266650647d73d4713ff952f92528468a652c..493064040fde918e6ac804e0131f22691d552026 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -33,6 +33,7 @@ extensions = [
'sphinx.ext.autosummary',
'sphinx.ext.viewcode',
'sphinx.ext.mathjax',
+ 'sphinx.ext.graphviz',
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/doc/fsl.fsleyes.rst b/doc/fsl.fsleyes.rst
index ed5a37489f37393334f3b0cfb2d1ce967176cc1e..cce8d14df987838ea03bf261ba23e57a976a64b1 100644
--- a/doc/fsl.fsleyes.rst
+++ b/doc/fsl.fsleyes.rst
@@ -1,38 +1,6 @@
fsl.fsleyes package
===================
-Subpackages
------------
-
-.. toctree::
-
- fsl.fsleyes.actions
- fsl.fsleyes.controls
- fsl.fsleyes.displaycontext
- fsl.fsleyes.editor
- fsl.fsleyes.gl
- fsl.fsleyes.profiles
- fsl.fsleyes.views
- fsl.fsleyes.widgets
-
-Submodules
-----------
-
-.. toctree::
-
- fsl.fsleyes.colourmaps
- fsl.fsleyes.frame
- fsl.fsleyes.fsleyes_parseargs
- fsl.fsleyes.icons
- fsl.fsleyes.overlay
- fsl.fsleyes.panel
- fsl.fsleyes.splash
- fsl.fsleyes.toolbar
- fsl.fsleyes.tooltips
-
-Module contents
----------------
-
.. automodule:: fsl.fsleyes
:members:
:undoc-members:
diff --git a/doc/images/fsleyes.png b/doc/images/fsleyes.png
new file mode 100644
index 0000000000000000000000000000000000000000..7335a98013a646706ba50b678970a6e1561e0113
Binary files /dev/null and b/doc/images/fsleyes.png differ
diff --git a/doc/images/fsleyes_architecture.png b/doc/images/fsleyes_architecture.png
new file mode 100644
index 0000000000000000000000000000000000000000..c1743823a509cf7acccd3544c9733fb724a61a92
Binary files /dev/null and b/doc/images/fsleyes_architecture.png differ
diff --git a/doc/images/fsleyes_architecture.xcf b/doc/images/fsleyes_architecture.xcf
new file mode 100644
index 0000000000000000000000000000000000000000..4c98e7f4def434c5e7b25e5610eed397c9cdd22e
Binary files /dev/null and b/doc/images/fsleyes_architecture.xcf differ
diff --git a/fsl/__init__.py b/fsl/__init__.py
index 7a74e26c1f64b1e563154aab5866fd898aeb848d..482c7f16bdac78bae7222fb9eb63aa9e6c2da54c 100644
--- a/fsl/__init__.py
+++ b/fsl/__init__.py
@@ -222,7 +222,7 @@ def _parseArgs(argv, allTools):
- The :class:`argparse.Namespace` instance containing parsed arguments.
- - The return value of the ``FSLTool.parseArgs` function (see
+ - The return value of the ``FSLTool.parseArgs`` function (see
:func:`_loadFSLTool`).
"""
diff --git a/fsl/data/atlases.py b/fsl/data/atlases.py
index b747ae8675e3c08365f7d0003e957b57e819dbb0..6b2ea54c0e90ec26cd58cf8a2c00543bf757ef94 100644
--- a/fsl/data/atlases.py
+++ b/fsl/data/atlases.py
@@ -394,10 +394,14 @@ class ProbabilisticAtlas(Atlas):
def proportions(self, worldLoc):
- """:returns: a list of values, one per region, which represent
- the probability of each region for the given world
- location. Returns an empty list if the given
- location is out of bounds.
+ """Looks up the region probabilities for the given location.
+
+ :arg worldLoc: Location in the world coordinate system.
+
+ :returns: a list of values, one per region, which represent
+ the probability of each region for the specified
+ location. Returns an empty list if the given
+ location is out of bounds.
"""
voxelLoc = transform.transform([worldLoc], self.worldToVoxMat.T)[0]
diff --git a/fsl/fsleyes/__init__.py b/fsl/fsleyes/__init__.py
index 7ac0ec0ec9f26e85f2e4172d391e3b0d85966768..76b9b9944416eed3174d79de205c198057e30d1d 100644
--- a/fsl/fsleyes/__init__.py
+++ b/fsl/fsleyes/__init__.py
@@ -1,45 +1,170 @@
#!/usr/bin/env python
#
-# __init__.py - FSLEyes - a python based OpenGL image viewer.
+# __init__.py - FSLeyes - a python based OpenGL image viewer.
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
+"""This package contains the application logic for *FSLeyes*.
-"""A 3D image viewer.
-The application logic is spread across several sub-packages:
+--------
+Overview
+--------
- - :mod:`actions` - Global actions (e.g. load file), and abstract base
- classes for other actions, and entities which
- provide actions.
- - :mod:`controls` - GUI panels which provide an interface to control
- the display of a single view.
+*FSLeyes* is an OpenGL application for displaying 3D :mod:`overlays
+<.overlay>`. All overlays are stored in a single list, the
+:class:`.OverlayList`. Only one ``OverlayList`` ever exists - this list is
+shared throughout the application. The primary overlay type is the NIFTI1
+image format, but other overlay types are supported (VTK models), and more
+will be supported in the future (e.g. surfaces).
- - :mod:`displaycontext` - Classes which define options controlling the
- display.
- - :mod:`editor` - Image editing functionality.
+Amongst other things, *FSLeyes* provides the following features:
- - :mod:`gl` - OpenGL visualisation logic.
+ - Orthographic view (:mod:`.orthopanel`)
+ - Lightbox view (:mod:`.lightboxpanel`)
+ - Time series plotting (:mod:`.timeseriespanel`)
+ - Histogram plotting (:mod:`.histogrampanel`)
+ - FSL atlas explorer (:mod:`.atlaspanel`)
+ - FEAT cluster results explorer (:mod:`.clusterpanel`)
+ - NIFTI1 image editing (:mod:`.editor`)
+ - A comprehensive command line interface (:mod:`.fsleyes_parseargs`)
- - :mod:`profiles` - Mouse/keyboard interaction profiles.
- - :mod:`views` - GUI panels which display image data.
+---------------------------
+Frames, views, and controls
+---------------------------
- - :mod:`widgets` - General purpose custom :mod:`wx` widgets.
+The :class:`.FSLEyesFrame` is the top level GUI object. It is a container for
+one or more *views*. All views are defined in the :mod:`.views` sub-package,
+and are sub-classes of the :class:`.ViewPanel` class. Currently there are two
+primary view categories - :class:`.CanvasPanel` views, which use :mod:`OpenGL`
+to display overlays, and :class:`.PlotPanel` views, which use
+:mod:`matplotlib` to plot data related to the overlays.
-A :class:`FSLEyesFrame` is a container for one or more 'views' - all of the
-possible views are contained within the :mod:`.views` sub-package, and the
-views which may be opened by the user are defined by the
-:func:`.views.listViewPanels` function. View panels may contain one or more
-'control' panels (all defined in the :mod:`.controls` sub-package), which
-provide an interface allowing the user to control the view.
+View panels may contain one or more *control* panels which provide an
+interface allowing the user to control some aspect of the view (e.g. the
+:class:`.OverlayDisplayToolBar`), or to display some other data associated
+with the overlays (e.g. the :class:`.ClusterPanel`). All controls are defined
+in the :mod:`.controls` sub-package.
-All view (and control) panels are derived from the :class:`.FSLEyesPanel`
-which, in turn, is derived from the :class:`.ActionProvider` class.
-As such, view panels may expose both actions, and properties, which can be
-performed or modified by the user.
+
+The view/control panel class hierarchy is shown below:
+
+.. graphviz::
+
+ digraph hierarchy {
+
+ graph [size=""];
+
+ node [style="filled",
+ fillcolor="#ffffdd",
+ fontname="sans"];
+
+ rankdir="BT";
+ 1 [label="panel.FSLEyesPanel"];
+ 3 [label="views.viewpanel.ViewPanel"];
+ 4 [label="views.plotpanel.PlotPanel"];
+ 5 [label="views.canvaspanel.CanvasPanel"];
+ 6 [label="views.orthopanel.OrthoPanel"];
+ 7 [label="<other canvas panels>"];
+ 8 [label="views.histogrampanel.HistogramPanel"];
+ 9 [label="<other plot panels>"];
+ 10 [label="controls.overlaylistpanel.OverlayListPanel"];
+ 11 [label="<other control panels>"];
+
+ 3 -> 1;
+ 4 -> 3;
+ 5 -> 3;
+ 6 -> 5;
+ 7 -> 5;
+ 8 -> 4;
+ 9 -> 4;
+ 10 -> 1;
+ 11 -> 1;
+ }
+
+All toolbars inherit from the :class:`.FSLEyesToolBar` base class:
+
+.. graphviz::
+
+ digraph toolbar_hierarchy {
+
+ graph [size=""];
+
+ node [style="filled",
+ fillcolor="#ffffdd",
+ fontname="sans"];
+
+ rankdir="BT";
+ 2 [label="toolbar.FSLEyesToolBar"];
+ 12 [label="controls.overlaydisplaytoolbar.OverlayDisplayToolBar"];
+ 13 [label="controls.lightboxtoolbar.LightBoxToolBar"];
+ 14 [label="<other toolbars>"];
+
+ 12 -> 2;
+ 13 -> 2;
+ 14 -> 2;
+ }
+
+
+----------------------
+The ``DisplayContext``
+----------------------
+
+
+In order to manage how overlays are displayed, *FSLeyes* uses a
+:class:`.DisplayContext`. Because *FSLeyes* allows multiple views to be opened
+simultaneously, it needs to use multiple ``DisplayContext`` instances.
+Therefore, one master ``DisplayContext`` instance is owned by the
+:class:`FSLEyesFrame`, and a child ``DisplayContext`` is created for every
+:class:`.ViewPanel`. The display settings managed by each child
+``DisplayContext`` instance can be linked to those of the master instance;
+this allows display properties to be synchronised across displays.
+
+
+Each ``DisplayContext`` manages a collection of :class:`.Display` objects, one
+for each overlay in the ``OverlayList``. Each of these ``Display`` objects
+manages a single :class:`.DisplayOpts` instance, which contains overlay
+type-specific display properties. Just as child ``DisplayContext`` instances
+can be synchronised with the master ``DisplayContext``, child ``Display`` and
+``DisplayOpts`` instances can be synchronised to the master instances.
+
+
+The above description is summarised in the following diagram:
+
+
+.. image:: images/fsleyes_architecture.png
+ :scale: 40%
+ :align: center
+
+
+In this example, two view panels are open - an :class:`.OrthoPanel`, and a
+:class:`.LightBoxPanel`. The ``DisplayContext`` for each of these views, along
+with their ``Display`` and ``DisplayOpts`` instances (one of each for every
+overlay in the ``OverlayList``) are linked to the master ``DisplayContext``
+(and its ``Display`` and ``DisplayOpts`` instances), which is managed by the
+``FSLEyesFrame``. All of this synchronisation functionality is provided by
+the ``props`` package.
+
+
+--------------------
+Package organisation
+--------------------
+
+
+The rest of *FSLeyes* is organised into the following sub-packages:
+
+.. autosummary::
+ ~fsl.fsleyes.views
+ ~fsl.fsleyes.controls
+ ~fsl.fsleyes.displaycontext
+ ~fsl.fsleyes.gl
+ ~fsl.fsleyes.profiles
+ ~fsl.fsleyes.editor
+ ~fsl.fsleyes.actions
+ ~fsl.fsleyes.widgets
"""
diff --git a/fsl/tools/fsleyes.py b/fsl/tools/fsleyes.py
index e3fe72e794724ef1423c8e03f0054c52203ae5db..982d66994fdcfa8f74c3e78b9b35a0bc792950a1 100644
--- a/fsl/tools/fsleyes.py
+++ b/fsl/tools/fsleyes.py
@@ -224,9 +224,10 @@ def interface(parent, args, ctx):
return frame
-#########################################
-# See the fsl.tools package documentation
-#########################################
+#############################################
+# See the fsl.tools package documentation for
+# details on these module-level attributes
+#############################################
FSL_TOOLNAME = 'FSLeyes'