\documentclass[a4paper, 11pt]{article}
\begin{document}
\section{Introduction}

This module will provide expertise for finding diffraction images in a
directory. 

\subsection{Glossary}

The following exact terms will be used in this document.

\begin{itemize}
\item{Template - a string which represents the names for a sequence of
diffraction images, like \verb|foo_bar_1_####.img|. The \verb|###| will
be replaced with a sequence of three-digit numbers.}
\item{Directory - the location of these files.}
\item{Prefix, Extension - - strings representing the two halfs of the 
template around \verb|###.| e.g. foo\_bar\_1 and img above.}
\item{Sweep - a continuous set of frames, where the phi end of one
image is the same as the phi start of the next. All images will have 
the same wavelength, distance and beam centre.}
\item{Reference image - a single frame or set of isolated frames collected 
for the purposes of characterizing a crystal.}
\end{itemize}

\section{Use Cases}

\subsection{UC 1: Derive Template and Directory from Image Name}

Action: Derive from a (full path) image name, return a likely template and
directory for these files. 

Function: image2template\_directory(image), image2template(image)

\subsection{UC 2: Finding Images from Template and Directory}

Action: a template and directory are provided. This directory is searched for
files which have a matching name, and the list of matching image numbers 
returned as a sorted list of integers.

Function: find\_matching\_images(template, directory)

\subsection{UC 3: Constructing Full Path}

When provided with a template, directory and image, construct the full path
to the image.

Function: template\_directory\_number2image(template, directory, number)

\subsection{UC 4: Define Sweeps}

Provided with a set of image headers from a single template, directory
combination, identify any sweeps and reference images therein. This will
make use of a dictionary of headers including the image numbers, and populate
``Sweep'' objects. FIXME: not sure how to handle reference images yet.

Function: headers2sweeps(template, directory, images, header_dict)

Note. The template, directory and images are in there to allow storage of
this information in a sweep object - it is not needed to implement the 
sweep identification.

Note further. This makes no sense - it is far better that this functionality
is called from the Sweep constructor. This means that this method will
simply digest the headers into a summary, which is to be a list of
dictionaries containing the sweep information. This can then be used to
indentify the ``sweeps'' from the puff in the Sweep constructor (e.g. setting
the correct frame ranges.)

Ok, this now works by initializing the first sweep as the first image. The
next frame in sequence (e.g. by image number) either belongs to this sweep
or is the first image in a new sweep. Belonging is defined as having the 
same wavelength and distance, and having the phi start the same as the 
current phi end of the sweep.

\section{Implementation}

\subsection{UC 1}

This will use the following regular expression to match the image name:

{
\tiny
\begin{verbatim}
(.*)_([0-9]*)\.(.*)
\end{verbatim}
}

which means (whatever) (underscore) (some digits) (dot) (whatever). This will
not match files called foo001.img or foo.001 etc. Is this a problem?? Look 
in to this - could the (underscore) and (dot) be optional? Should be doable.
Adding ? after the offending tokens could do it - add this to the unit test.
This would make the expression:

{
\tiny
\begin{verbatim}
(.*)_?([0-9]*)\.?(.*)?
\end{verbatim}
}

Oh - this et's stuck on the greediness of things - better off trying to 
match a number of patterns in sequence and see which works best... Yes, this
works though it makes for notty code, including dictionarys of how to put
the template back together. I ended up with:

{
\tiny
\begin{verbatim}
def image2template(filename):
    '''Return a template to match this filename.'''

    # the patterns in the order I want to test them

    pattern_keys = [r'(.*)_([0-9]*)\.(.*)',
                    r'([^\.]*)\.([0-9]+)',
                    r'(.*?)([0-9]*)\.(.*)']

    # patterns is a dictionary of possible regular expressions with
    # the format strings to put the file name back together

    patterns = {r'(.*)_([0-9]*)\.(.*)':'%s_%s.%s',
                r'([^\.]*)\.([0-9]+)':'%s.%s%s',
                r'(.*?)([0-9]*)\.(.*)':'%s%s.%s'}

    for pattern in pattern_keys:
        match = re.compile(pattern).match(filename)

        if match:
            prefix = match.group(1)
            number = match.group(2)
            try:
                exten = match.group(3)
            except:
                exten = ''

            for digit in string.digits:
                number = number.replace(digit, '#')
                
            return patterns[pattern] % (prefix, number, exten)

    raise RuntimeError, 'filename %s not understood as a template' % \
          filename
\end{verbatim}
}

Still - it works!

\subsection{UC 2, 3}

Implemented.

\end{document}