fix broken tutorial.rst

doc/tutorial.rst

@@ -7,8 +7,8 @@ begin with an example that uses the default configuration of pFIRE.  After this
 some of the more advanced options that allow us to control both how pFIRE performs its
 registration, and the output formats that can be written.
 
-All the tutorial files can be found on the `pFIRE Github`_, or may be downloaded in a :download:`zip archive
-</_static/pfire_tutorial_files.zip>`.
+All the tutorial files can be found on the `pFIRE Github`_, or may be downloaded in a
+:download:`zip archive </_static/pfire_tutorial_files.zip>`.
 
 .. _pfire github: https://github.com/INSIGNEO/pFIRE/tree/master/doc/tutorial_files
 
@@ -29,11 +29,15 @@ The pFIRE Configuration File
 pFIRE is run from the command line, with all the configuration options set in a configuration file.
 This file uses ``.ini`` syntax, with ``key = value`` pairs.
 
+Minimum Requirements
+--------------------
+
 The minimum information pFIRE requires to perform a registration is a fixed image, a moved image,
 and a target nodespacing. If the parameters ``fixed``, ``moved`` and ``nodespacing`` are not set in
-the configuration file, pFIRE will abort with an error. 
-
-# TODO ADD OUTPUT OPTION INFO
+the configuration file, pFIRE will abort with an error. The two images must have the same
+dimensions in order to perform registration.  Supported image formats include typical 2D formats
+such as ``.png``, ``.jpeg`` or ``.tiff`` (see the OpenImageIO_ documentation for a full list), as
+well as 2D and 3D dicom files.
 
 A minimal configuration file will look like this:
 
@@ -43,8 +47,60 @@ A minimal configuration file will look like this:
    moved = path/to/moved.img
    nodespacing = 10
 
-Example: Cartoon Faces
-----------------------
+Output Files
+------------
+
+pFIRE produces a pair of output files: the registered image, and the corresponding displacement
+map.  The registered image is generated by warping the moved image using the final displacement
+map. In the ideal case this will be identical to the fixed image. In practical usage, the
+registered image may be compared with the fixed image to determine the quality of the registration.
+
+The filename and format of the registered image may be chosen using the ``registered =``
+configuration parameter. By default the image is be saved with the filename ``registered =
+registered.xdmf``. This produces an XDMF_ metadata file and an HDF5_ binary data file which may be
+plotted with ParaView_, VisIt_ or similar scientific viewer software.  Alternatively, for 2D
+images, an image extension such as ``.png`` or ``.jpeg``, may be specified, and the image will be
+output in this format (as with image reading, see the OpenImageIO_ documentation for a full list).
+
+The output path for the map may also be specified using the ``map =`` parameter.  At the current time, the only
+available output format is HDF5_, either with or without the XDMF_ metatdata file.  If the map
+filename ends with ``.xdmf`` both files will be created, if it ends with ``.h5`` only the binary
+data will be stored.
+
+As an example, the minimal configuration above can be extended to output the image to
+``myimage.png`` and the map to ``mymap.xdmf`` with:
+
+.. code-block:: ini
+
+   fixed = path/to/fixed.img
+   moved = path/to/moved.img
+   nodespacing = 10
+   registered = myimage.png
+   map = mymap.xdmf
+
+An HDF5 file can contain many datasets, similar to the way a filesystem can can
+contain many files with different names.  In HDF5, directories are called groups and may contain
+any number of uniquely named datasets. It is therefore possible to place the registered image data
+and map data in the same file.  The name of the group that the dataset should be placed in can be
+chosen with the syntax ``path/to/file:/path/to/dataset``.  Note that while the image is a single dataset,
+the map is made up of multiple datasets and only the group name can be set. (For more information
+see `The HDF5/XDMF Map Format`_)
+
+The below example would cause the image and map data to both be placed in ``results.xdmf.h5``, with
+the image data in a dataset named ``registered_image`` and the map datasets in a group called
+``registration_map``:
+
+.. code-block:: ini
+
+   fixed = path/to/fixed.img
+   moved = path/to/moved.img
+   nodespacing = 10
+   registered = results.xdmf:/registered_image
+   map = results.xdmf:/registration_map/
+
+
+Registration Example: Cartoon Faces
+-----------------------------------
 
 This example is located in the ``faces_1`` directory, here you will find the files ``happy.png``,
 ``sad.png`` and ``sad2happy_default.conf``.  If you open ``sad2happy_default.conf`` in an editor
@@ -110,7 +166,7 @@ registration.  Both of these parameters have an effect on how smooth the displac
 The Smoothing Parameter :math:`\lambda`
 ---------------------------------------
 
-The registration equation [ref_] includes a smoothing constraint through the laplacian matrix,
+The registration equation includes a smoothing constraint through the laplacian matrix,
 which imposes a requirement for smoothness on the solution to the equation, and therefore on the
 displacement field.  The value of the parameter :math:`\lambda` determines the relative strength of
 the smoothing constraint relative to the registration constraint.
@@ -390,14 +446,14 @@ This relationship is demonstrated graphically below:
 If the inverse mapping field is needed at the original node coordinates this can be found by
 interpolating the reverse mapping at the desired points.
 
-The HDF5/XDMF Output Format
----------------------------
+The HDF5/XDMF Map Format
+------------------------
 
 The primary output format that pFIRE uses for displacement maps is an HDF5_ file, with XDMF_
-metatdata file, both of which are well known and standardised formats.  The HDF5 file is a binary format which contains the map as arrays of displacement
-field values and node locations.  The XDMF file is a small metadata file which describes the layout
-of the data within the HDF5 file, and is intended to be consumed by visualisation programs such as
-ParaView_ or VisIt_.
+metatdata file, both of which are well known and standardised formats.  The HDF5 file is a binary
+format which contains the map as arrays of displacement field values and node locations.  The XDMF
+file is a small metadata file which describes the layout of the data within the HDF5 file, and is
+intended to be consumed by visualisation programs such as ParaView_ or VisIt_.
 
 HDF5 Data Layout
 """"""""""""""""
@@ -420,6 +476,7 @@ This HDF5 file may be opened and used by and program or library which supports i
 simply viewing the map, the supplied XDMF metadata file makes it straightforward to view the map
 using standard visualisation software such as Paraview.
 
+.. _OpenImageIO: https://sites.google.com/site/openimageio/home
 .. _HDF5: https://portal.hdfgroup.org/display/HDF5/HDF5
 .. _XDMF: http://www.xdmf.org/index.php/XDMF_Model_and_Format
 .. _ParaView: https://www.paraview.org/
@@ -623,10 +680,10 @@ Running this results in an image like the following:
 .. |mapped_annotations| image:: /tutorial_files/lung_lobes/mapped_annotations.png
    :scale: 100%
 
-The script plots the fixed (black) and moved (red) images along with the annotated landmarks and shows the
-displacement that would be applied to each node in the moved image if warped using the pFIRE
-map.  If the registration is correct each red node should be linked directly to a black node by a
-displacement vector.  In this case the registration is poor and the displacment field does not
+The script plots the fixed (black) and moved (red) images along with the annotated landmarks and
+shows the displacement that would be applied to each node in the moved image if warped using the
+pFIRE map.  If the registration is correct each red node should be linked directly to a black node
+by a displacement vector.  In this case the registration is poor and the displacment field does not
 correctly map all the nodes. Optimisation of registration parameters will likely improve the
 quality, but this is an exercise left to the dedicated reader.
 

upload_docs.sh

@@ -15,7 +15,7 @@ zip --exclude=tutorial_files/faces_1/sad2happy.xdmf.h5 \
 export PATH="${PATH}:${basedir}/bin:${basedir}/reglab"
 sphinx-build -an . $ghpdir
 cd $ghpdir
-#git add --all
-#git commit -m "$(date)"
-#git push upstream gh-pages
+git add --all
+git commit -m "$(date)"
+git push upstream gh-pages
 )