Merge pull request #656 from schuhschuh/doc-update-for-release-v2.0.0

Update installation instructions

Applications/src/construct-atlas.py

@@ -11,8 +11,13 @@
 if __name__ == '__main__':
     parser = argparse.ArgumentParser(description="""
         Construct (spatio-temporal) atlas from images of the same anatomy of different subjects.
+
         To construct a spatio-temporal atlas, images of subjects at different ages spread over
-        the atlas time range are required.""")
+        the atlas time range are required. Please cite the following preprint when you use this
+        command in your research (or the respective peer-reviewed article when accepted):
+
+        Schuh et al., "Unbiased construction of a temporally consistent morphological
+        atlas of neonatal brain development", bioRxiv, 2018. doi:10.1101/251512""")
     parser.add_argument("config", help="JSON file with atlas configuration.")
     parser.add_argument("-a", "--ages", "--means", dest="means", type=float, nargs="+",
                         help="Discrete time points for which to construct atlas.")

Docker/Completion/Bash/docker-mirtk

@@ -13,7 +13,7 @@
 #
 _docker_mirtk()
 {
-  local commands='deform-mesh recon-neonatal-cortex calculate-boundary-map calculate-surface-map calculate-volume-map compose-maps evaluate-surface-map evaluate-volume-map calculate-filtering calculate-gradients change-label measure-volume padding fill-holes fill-holes-nn-based em draw-em em-hard-segmentation kmeans normalize split-labels help-rst info aggregate-images average-images calculate-element-wise calculate-distance-map calculate-exponential-map calculate-lie-bracket calculate-logarithmic-map close-image combine-images convert-image cut-brain detect-edges dilate-image downsample-image edit-image erode-image evaluate-overlap extract-connected-components extract-image-region flip-image open-image reflect-image resample-image smooth-image subdivide-brain-image evaluate-similarity average-measure average-overlap register construct-atlas evaluate-atlas edit-dof invert-dof average-dofs bisect-dof compose-dofs convert-dof evaluate-dof evaluate-jacobian init-dof transform-image calculate-surface-attributes calculate-surface-spectrum close-scalars copy-pointset-attributes decimate-surface delete-pointset-attributes dilate-scalars erode-scalars evaluate-cardiac-motion evaluate-distance evaluate-distortion evaluate-surface-mesh evaluate-surface-overlap extract-connected-points offset-surface open-scalars project-onto-surface remesh-surface smooth-surface blend-surface convert-mris convert-pointset extract-pointset-cells extract-pointset-surface extract-surface merge-surfaces transform-points match-points convert-pointset-to-mat copy-pointset-attributes-from-mat'
+  local commands='deform-mesh recon-neonatal-cortex calculate-boundary-map calculate-surface-map calculate-volume-map compose-maps evaluate-surface-map evaluate-volume-map calculate-filtering calculate-gradients change-label measure-volume padding fill-holes fill-holes-nn-based em draw-em em-hard-segmentation kmeans normalize split-labels help-rst info aggregate-images average-images calculate-element-wise calculate-distance-map calculate-exponential-map calculate-lie-bracket calculate-logarithmic-map close-image combine-images convert-image cut-brain detect-edges dilate-image downsample-image edit-image erode-image evaluate-overlap extract-connected-components extract-image-region extract-image-slice extract-image-volume flip-image match-histogram open-image reflect-image resample-image smooth-image subdivide-brain-image evaluate-similarity average-measure average-overlap register construct-atlas evaluate-atlas edit-dof invert-dof average-dofs bisect-dof compose-dofs convert-dof evaluate-dof evaluate-jacobian init-dof transform-image calculate-surface-attributes calculate-surface-spectrum close-scalars copy-pointset-attributes decimate-surface delete-pointset-attributes dilate-scalars erode-scalars evaluate-cardiac-motion evaluate-distance evaluate-distortion evaluate-surface-mesh evaluate-surface-overlap extract-connected-points offset-surface open-scalars project-onto-surface remesh-surface smooth-surface blend-surface convert-mris convert-pointset extract-pointset-cells extract-pointset-surface extract-surface merge-surfaces transform-points match-points'
   local noreply='true'
   local nodocker='false'
   if [ $COMP_CWORD -gt 2 ] && [ ${COMP_WORDS[1]} = run ]; then

Documentation/commands/_descriptions/construct-atlas.rst

@@ -3,4 +3,8 @@
 
 Construct (spatio-temporal) atlas from images of the same anatomy of different
 subjects. To construct a spatio-temporal atlas, images of subjects at
-different ages spread over the atlas time range are required.
+different ages spread over the atlas time range are required. Please cite the
+following preprint when you use this command in your research (or the
+respective peer-reviewed article when accepted): Schuh et al., "Unbiased
+construction of a temporally consistent morphological atlas of neonatal brain
+development", bioRxiv, 2018. doi:10.1101/251512

Documentation/commands/_summaries/construct-atlas.rst

@@ -4,4 +4,8 @@
 
    Construct (spatio-temporal) atlas from images of the same anatomy of different
    subjects. To construct a spatio-temporal atlas, images of subjects at
-   different ages spread over the atlas time range are required.
+   different ages spread over the atlas time range are required. Please cite the
+   following preprint when you use this command in your research (or the
+   respective peer-reviewed article when accepted): Schuh et al., "Unbiased
+   construction of a temporally consistent morphological atlas of neonatal brain
+   development", bioRxiv, 2018. doi:10.1101/251512

Documentation/download.rst

@@ -60,15 +60,7 @@ of the downloaded MIRTK repository:
    after the initial clone command without any directory path argument. To download
    only selected additional files, run one or more of the following commands.
 
-The MIRTK group hosts Git submodule repositories with copies of the Boost_ and Eigen_
-library header files required to build the core modules of the MIRTK
-(see `MIRTK/Boost <https://github.com/MIRTK/Boost>`__ and
-`MIRTK/Eigen <https://github.com/MIRTK/Eigen>`__ projects on GitHub). Note that
-these unofficial copies may not be suitable to build also the optional MIRTK Packages
-below if these require additional header files not included in these repositories.
-It is therefore recommended to install a compatible version of Boost and Eigen using
-the official installation packages available for your operating system instead.
-Other optional third-party libraries for which no binary installation packages for the
+Optional third-party libraries for which no binary installation packages for the
 supported operating systems exists are included as Git submodules under the ThirdParty/
 subdirectory of the MIRTK project. To download these third-party source files,
 run the following command(s):
@@ -95,11 +87,10 @@ update the desired Git submodules before (re-)configuring the build files, e.g.:
     # Or download one or more of the following packages only
     git submodule update --init -- Packages/Deformable
     git submodule update --init -- Packages/Mapping
+    git submodule update --init -- Packages/Scripting
     git submodule update --init -- Packages/DrawEM
 
 
-.. _Git:   https://git-scm.com
-.. _Boost: http://www.boost.org
 .. _Eigen: http://eigen.tuxfamily.org
 
 
@@ -118,11 +109,9 @@ The license enables usage of MIRTK in both commercial and non-commercial applica
 without restrictions on the licensing applied to the combined work.
 
 The MIRTK Git repository includes source files and references to Git submodule repositories
-whose source files are covered by their own respective license terms which are compatible
+whose source files are covered by their own respective license terms, which are compatible
 with the MIRTK license. See the following links for details:
 
-- `ThirdParty/Boost <https://github.com/MIRTK/Boost>`__: `Boost Software License Version 1.0 <http://www.boost.org/users/license.html>`__
-- `ThirdParty/Eigen <https://github.com/MIRTK/Eigen>`__: `Mozilla Public License Version 2.0 <https://www.mozilla.org/en-US/MPL/2.0/>`__
 - `ThirdParty/LBFGS <https://github.com/BioMedIA/MIRTK/tree/master/ThirdParty/LBFGS>`__: `The MIT License <https://opensource.org/licenses/MIT>`__
 - `NIfTI C library <https://www.nitrc.org/projects/nifti>`__: `Public domain <https://en.wikipedia.org/wiki/Public_domain>`__
 - `GIFTI C library <https://www.nitrc.org/projects/gifti/>`__: `Public domain <https://en.wikipedia.org/wiki/Public_domain>`__

Documentation/getstarted.rst

@@ -9,28 +9,53 @@ Get Started
 Install the software
 --------------------
 
+**Custom build**
+
 Before you can start using the MIRTK or develop your own MIRTK applications,
 you have to install the desired modules and available applications on your
 system including their prerequisites. For a manual installation of the MIRTK,
 please follow the :doc:`download` and :doc:`install` instructions which
 list the third-party libraries required by each module and describe how to
 build the MIRTK from its publicly available source code.
 
+
+**Using Docker**
+
 Instead of manually installing the MIRTK locally on your system, you can use
 the pre-made `biomedia/mirtk <https://hub.docker.com/r/biomedia/mirtk/>`_
 Docker image to run the :doc:`commands` inside a `Docker container`_.
-
 For a guide to install and use Docker_, see the `official docs <https://docs.docker.com>`__.
 
 
+**AppImage for Linux**
+
+For Linux users, the easiest way to get started with MIRTK without the need for the Docker
+runtime environment is the `MIRTK AppImage`_ available on Bintray_. An AppImage_ contains
+all the required shared libraries and pre-built MIRTK commands. It can be executed on any
+Linux system with a compatible minimum glibc version (>=2.15). With this AppImage, there is no
+actual need for an installation. Simply download the file, make it executable, and copy it to
+a directory that is in your PATH, e.g.,::
+
+  wget -O mirtk https://bintray.com/schuhschuh/AppImages/download_file?file_path=MIRTK%2Bview-latest-x86_64-glibc2.15.AppImage
+  chmod a+x mirtk
+  sudo mv mirtk /usr/bin
+
+This AppImage is updated automatically when a change is committed to the master branch.
+
+
 .. _BashCompletion:
 
-Bash completion
----------------
+Enable Bash completion
+----------------------
+
+**Custom build**
 
 For information on how to enable auto-completion_ when running ``mirtk`` commands of
 a manual MIRTK installation in the Bash_ shell, see the :doc:`install` instructions.
 
+
+**Using Docker**
+
 To enable Bash completion for running the MIRTK commands with Docker,
 copy the `docker <https://raw.githubusercontent.com/docker/docker/master/contrib/completion/bash/docker>`__
 and `docker-mirtk <https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Docker/Completion/Bash/docker-mirtk>`__
@@ -47,7 +72,7 @@ On OS X with Homebrew, use these commands instead::
 
   brew install bash-completion
   curl -L https://raw.githubusercontent.com/docker/docker/master/contrib/completion/bash/docker        > $(brew --prefix)/etc/bash_completion.d/docker
-  curl -L https://raw.githubusercontent.com/BioMedIA/MIRTK/develop/Docker/Completion/Bash/docker-mirtk > $(brew --prefix)/etc/bash_completion.d/docker-mirtk
+  curl -L https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Docker/Completion/Bash/docker-mirtk > $(brew --prefix)/etc/bash_completion.d/docker-mirtk
 
 Alternatively, save the files to your home directory at, for example, ``$HOME/bash_completion/``
 and add the following lines to your ``.bashrc`` (Linux) or ``.bash_profile`` (OS X) file::
@@ -56,6 +81,22 @@ and add the following lines to your ``.bashrc`` (Linux) or ``.bash_profile`` (OS
   [ ! -f "$HOME/bash_completion/docker-mirtk" ] || . "$HOME/bash_completion/docker-mirtk"
 
 
+**Using AppImage**
+
+To enable Bash completion for running the MIRTK commands in Bash using the AppImage for Linux,
+copy `this file <https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Scripts/mirtk_bash_completion.sh>`__
+to ``/etc/bash_completion.d/``.
+
+This can be done with the following Terminal command::
+
+  sudo curl -L https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Scripts/mirtk_bash_completion.sh > /etc/bash_completion.d/mirtk
+
+Alternatively, save the file to your home directory at, for example, ``$HOME/bash_completion/``,
+rename it to ``mirtk``, and add the following line to your ``.bashrc`` file::
+
+  [ ! -f "$HOME/bash_completion/mirtk" ] || . "$HOME/bash_completion/mirtk"
+
+
 Run the commands
 ----------------
 
@@ -115,6 +156,9 @@ guidelines for more information on how to contribute your code to the MIRTK sour
 or develop your own MIRTK Package.
 
 
+.. _AppImage:           https://appimage.org/
+.. _MIRTK AppImage:     https://bintray.com/schuhschuh/AppImages/MIRTK/master
+.. _Bintray:            https://bintray.com/schuhschuh/AppImages/MIRTK/master
 .. _Bash:               https://www.gnu.org/software/bash/
 .. _auto-completion:    https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html
 .. _Homebrew:           http://brew.sh

Documentation/install.rst

@@ -19,6 +19,7 @@ for Linux and OS X is 2.8.12, while version 3.4 or newer is needed on Windows.
 For the compilation of the MIRTK source code, a C++ compiler with support for the
 `C++11`_ standard is required. On Windows, the minimum required Visual Studio compiler
 version is 18.0. A compatible compiler is shipped with Visual Studio 2013 or newer.
+For Unix operation systems, we recommend the use of the `GNU Compiler Collection`_ (GCC).
 
 To execute the :doc:`MIRTK commands <commands>`, a Python_ installation is required.
 Note that Python has to be installed before configuring the MIRTK build using CMake.
@@ -68,6 +69,7 @@ Module               Requires module(s)
 |Registration|       |Common|, |Numerics|, |Image|, |Transformation|               |PointSet|, |Deformable|
 |Deformable|         |Common|, |Numerics|, |Image|, |Transformation|, |PointSet|
 |Mapping|            |Common|, |Numerics|, |Image|, |PointSet|
+|Scripting|
 |DrawEM|             |Common|, |Numerics|, |Image|, |IO|
 ===================  ===========================================================   ========================================
 
@@ -260,6 +262,7 @@ The Bash completions are then available when a new Terminal window is opened.
 
 
 .. _C++11:     https://isocpp.org/wiki/faq/cpp11
+.. _GNU Compiler Collection: https://gcc.gnu.org/
 .. _Python:    https://www.python.org
 .. _Boost:     http://www.boost.org
 .. _Eigen:     http://eigen.tuxfamily.org

Documentation/modules.rst

@@ -17,6 +17,7 @@ Modules
    modules/registration
    modules/deformable
    modules/mapping
+   modules/scripting
    modules/drawem
 
 .. Replacements for use by descriptions included below to refer to other modules
@@ -115,6 +116,14 @@ Mapping
 :doc:`[more] <modules/mapping>`
 
 
+Scripting
+---------
+
+.. include:: modules/_descriptions/scripting.rst
+
+:doc:`[more] <modules/scripting>`
+
+
 Draw-EM
 -------
 

Documentation/modules/_descriptions/scripting.rst

@@ -0,0 +1,2 @@
+The Scripting module is a library of modules written in commonly used scripting
+languages which can be used to write custom scripts for medical image analysis.

Documentation/modules/_overview.rst

@@ -11,6 +11,7 @@ Module               Brief Description
 |Registration|       Image and point set registration library.
 |Deformable|         Library for Euler integration of deformable meshes such as cortical surfaces.
 |Mapping|            Filters for the mapping of brain surfaces and volumes.
+|Scripting|          Collection of auxiliary modules for scripting languages such as Python.
 |DrawEM|             Structural and tissue segmentation of neonatal brain MR images.
 ===================  ==============================================================================
 

Documentation/modules/_refs.rst

@@ -7,4 +7,5 @@
 .. |Registration|    replace:: :doc:`Registration   </modules/registration>`
 .. |Deformable|      replace:: :doc:`Deformable     </modules/deformable>`
 .. |Mapping|         replace:: :doc:`Mapping        </modules/mapping>`
+.. |Scripting|       replace:: :doc:`Scripting      </modules/scripting>`
 .. |DrawEM|          replace:: :doc:`Draw-EM        </modules/drawem>`

Documentation/modules/scripting.rst

@@ -0,0 +1,7 @@
+================
+Scripting Module
+================
+
+.. include:: _descriptions/scripting.rst
+
+.. todo:: Document main module classes and their usage.