* -The following text is included in the main documentation page by doxygen
/*! \mainpage msdi : Manchester's Shape Data Iterator library
* Classes to iterate through images with point annotations.
* Key base class is msdi_marked_images, which allows stepping through images and
* associated points.
* 
* An important class is msdi_marked_images_from_files, which reads images and points from
* files defined in a pair of lists of filenames.
* 
* \section Reflections Using Reflected Images and Points
* msdi_marked_images_from_files includes options for reflecting both the images (about the centreline in x) and
* the points.  The way that reflections are used is controlled by the msdi_reflection_state value.
* 
* In summary:
* - Raw: Return raw data 
* - ReflectOnly: Return reflected points and reflected images (but not originals)
* - OnlyReflectIm: Return reflected images and original points from files (without reflecting them)
* - ReflectSym: Return raw + reflected images, with original points + their reflections 
* - ReflectAsymRawPts: Return raw image+points, then reflected image and raw points (separate file)
* - ReflectAsymRefPts: Return raw image+points, then reflected image and reflected points (separate file)
* 
* These are useful when building models from images of objects with approximate symmetry.
* Examples of use:
* \subsection ReflectOnly ReflectOnly
* If you have images + points for the left hand, reflecting both can be used to build a model of the right hand
* 
* \subsection OnlyReflectIm OnlyReflectIm
* When you have annotated points on reflected images and wish to build the model from the original images + those points
* 
* \subsection ReflectSym ReflectSym
* When you have annotated an approximately symmetric object, such as the face. You get two examples per image by reflecting both the image and the points.  In this case the points must be renumbered (using the list supplied by the ref_point_index() function).
* 
* When points are reflected, their order must be changed.  For instance, consider 10 points around
* the eyes of a face:
* \verbatim
         3                7
    2    0    4      8    1    6
         5                9
\endverbatim
* when reflected, this becomes:
* \verbatim
         7                3
    6    1    8      4    0    2
         9                5
\endverbatim
* To construct the permutation list, identify the new index for each point:
* \verbatim
Original : 0 1 2 3 4 5 6 7 8 9
Reflected: 1 0 6 7 8 9 2 3 4 5
\endverbatim
* The lower line gives the list that should be supplied in the ref_point_index.  
* When supplied in a parameter file, this can be summarised as { 1 0 6:9 2:5 }
* 
* \subsection ReflectAsymRefPts ReflectAsymRefPts
* For when you have both a left and a right handed version of an object in a single image, with separate point files.  For instance, for a pelvic X-ray you might have both the left and right femurs annotated.  The points files should have the same name, but be in separate directories. For instance the left points should be in ./points, and the right in ./points/right.  In this case the points_dir would be "points" and the ref_prefix should be "right/".  In that case the iterator with first return the original image and the left points, then the reflected image together with the reflected right points (which thus look like the left points).
* 
* \subsection ReflectAsymRawPts ReflectAsymRawPts
* Similar to ReflectAsymRefPts except it assumes that the reflected points on file have been annotated on a reflected version of the image, so must be returned as is.  This happens when you build a model from the left example, then apply it to reflected images to generate the right hand example (but reflected).  
*/
