<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[12pt]{article}
\usepackage[margin=1in]{geometry}
\usepackage{graphicx}
\def\BOX#1{\fbox{\tt #1}}
\begin{document}

\title{Project 3: Neural Networks and Face Recognition}
\author{CSC 242 Introduction to Artificial Intelligence\\
Fall 2014}

\maketitle
\noindent
Adapted from Mitchell, Tom. ``Neural Networks for Face Recognition: Companion to Chapter 4 of the textbook Machine Learning'', http://www.cs.cmu.edu/\~tom/faces.html, Carnegie Mellon University, 16 Oct 1997. Accessed 2 Apr 2014. 

\section{Introduction}

This assignment gives you an opportunity to apply neural network learning to
the problem of face recognition.  
You will experiment with a neural network
program to train a sunglasses recognizer, a face recognizer, and an expression recognizer.

You will work in assigned groups of 2 or 3 students.  
After your group turns in your assignment, you will each send a confidential email
to xdong@cs.rochester.edu rating the other members of your group on a scale of 3 to 0:
\begin{itemize}
\item 3 = did more than her share
\item 2 = did her share
\item 1 = did less than her share
\item 0 = did nothing
\end{itemize}
The body of the email should contain the name and the score for each
partner on a separate line.
We will use this information to adjust the group project score for each individual.  If scores
significantly disagree, we will investigate.

You will not need to do huge amounts of coding for this assignment,
and you should not let the size of this document scare you, but training
your networks will take time.  It is recommended that you read the
assignment in its entirety first, and start early.  You should work closely 
together, sitting side by side at a computer. You can probably get the project finished in two (long) evenings working
togther like, but if you work independently it will take much longer and you
may well not finish at all.  
 You will be modifying
code written in C.

\textbf{Read this \emph{entire} document before you begin. Do not
  start modifying the code until you have read and discussed the
  functions discussed in Section~\ref{sec:neural} with your team.}

\subsection{The face images}

The base directory of the project is {\tt /home/hoover/u1/cs242/projects-spring2014/FaceRecog/}. We refer to this directory below as BASE.

It will be easiest to complete this project using the CSUG cycle
servers.  Login into cycle.csug.cs.rochester, or one of the other
servers, using ssh and  X-windows.  If you copy the files to your
computer, note that you will have to edit the training and testing
files to change the directory paths to match where the files are on
your machine.

The image data can be found in {\tt BASE/data/faces/}.
This directory contains 20 subdirectories, one for each person, named by
userid.  Each of these directories contains several different face images of
the same person.

You will be interested in the images with the following naming convention:

{\tt &lt;userid&gt;\_&lt;pose&gt;\_&lt;expression&gt;\_&lt;eyes&gt;\_&lt;scale&gt;.pgm}

\begin{itemize}

\item {\tt &lt;userid&gt;} is the user id of the person in the image, and this
field has 20 values: an2i, at33, boland, bpm, ch4f, cheyer, choon, danieln,
glickman, karyadi, kawamura, kk49, megak, mitchell, night, phoebe, saavik,
steffi, sz24, and tammo.

\item {\tt &lt;pose&gt;} is the head position of the person, and this field
has 4 values: straight, left, right, up.

\item {\tt &lt;expression&gt;} is the facial expression of the person, and this
field has 4 values: neutral, happy, sad, angry.

\item {\tt &lt;eyes&gt;} is the eye state of the person, and this field has
2 values: open, sunglasses.

\item {\tt &lt;scale&gt;} is the scale of the image, and this field has 3
values: 1, 2, and 4.  1 indicates a full-resolution image ($128$ columns
$\times$ $120$ rows); 2 indicates a half-resolution image ($64 \times 60$);
4 indicates a quarter-resolution image ($32 \times 30$).  For this
assignment, you will be using the quarter-resolution images for experiments.
This both makes training very fast and keeps the input representation
small.  
If you like, you can try running on the full size images by
using the ``{\tt straightevenHD\_}'' training and test file lists
rather than the `{\tt straighteven\_}'' lists.

\end{itemize}

If you've been looking closely in the image directories, you may notice
that some images have a {\tt .bad} suffix rather than the {\tt .pgm}
suffix.  As it turns out, 16 of the 640 images taken have glitches due to
problems with the camera setup; these are the {\tt .bad} images.
Some people had more glitches than others, but everyone who got ``faced''
should have at least 28 good face images (out of the 32 variations
possible, discounting scale).

\subsection{Viewing the face images}

To view the images, you can use the program gimp.  Gimp is available on all computing platforms; see {\tt http://www.gimp.org/} for documentation.
Gimp is installed on CSUG machines.

\subsection{The neural network and image access code}

We're supplying C code for a three-layer fully-connected feedforward
neural network which uses the backpropagation algorithm to tune its weights.
To make life as easy as possible, we're also supplying you with an image
package for accessing the face images, as well as the top-level
program for training and testing, as a skeleton for you to modify.
To help explore what the nets actually learn, you'll also find a
utility program for visualizing hidden-unit weights as images.

The code is located in {\tt BASE/code/}.  Copy all
of the files in this area to your own directory, and type {\tt make}. 
 When
the compilation is done, you should have one executable program: {\tt
facetrain}.  Briefly, {\tt facetrain} takes lists of image files as input, and
uses these as training and test sets for a neural network.  {\tt facetrain}
can be used for training and/or recognition, and it also has the capability to
save networks to files.

Details of the routines, explanations of the source files, and related
information can be found in Section \ref{docs} of this handout.

\section{The Assignment}

Perform the following tasks and write up answers to the questions.  Describe the designs of 
the neural networks you used for each problem, and why you chose the design.
Turn in the writeup along with files containing the modified code for each part.

\begin{enumerate}

\item Issue the following command in your home directory to obtain
the training and test set data for this assignment:

{\tt cp BASE/trainset/*.list .}

\item The code you have been given is currently set up to learn to recognize
the person with userid {\tt glickman}.  By default, the code creates a
network with an input for each pixel, 4 hidden units, and 1 output
unit.  The function call to {\tt bpnn\_create} that appears in the file {\tt
  facetrain.c} establishes the dimensions of the neural network.

\begin{figure*}[h]
\includegraphics[width=5in]{Layers.pdf}
\caption{The default neural net has an input unit for each pixel, four
  hidden units, and one output unit.}
\end{figure*}


Modify this code to implement a
``sunglasses'' recognizer; \emph{i.e.}, train a neural net which, when given an image
as input, indicates whether the face in the image is wearing sunglasses, or
not. 

You will still have an input for each pixel, and one output unit
(sunglasses), but you might need to vary the number of hidden units
initialized {\tt bpnn\_create}.

\item Train a network using the default learning parameter settings (learning
rate 0.3, momentum 0.3) for 75 epochs, with the following command:

{\tt facetrain -n shades.net -t straightrnd\_train.list -1}
\\
\-\qquad {\tt straightrnd\_test1.list -2 straightrnd\_test2.list -e 75}

{\tt facetrain}'s arguments are described in Section \ref{RUNFACE},
but a short description is in order here.  {\tt shades.net} is the name of
the network file which will be saved when training is finished.
{\tt straightrnd\_train.list}, {\tt straightrnd\_test1.list}, and\\
{\tt straightrnd\_test2.list} are text files which specify the training
set (70 examples) and two test sets (34 and 52 examples), respectively.

This command creates and trains your net on a randomly chosen sample of 70 of
the 156 ``straight'' images, and tests it on the remaining 34 and 52 randomly
chosen images, respectively.  One way to think of this test strategy is that
roughly $\frac{1}{3}$ of the images ({\tt straightrnd\_test2.list}) have been
held over for testing.  The remaining $\frac{2}{3}$ have been used for a train
and cross-validate strategy, in which $\frac{2}{3}$ of these are being used
for as a training set ({\tt straightrnd\_train.list}) and $\frac{1}{3}$ are
being used for the validation set to decide when to halt training ({\tt
straightrnd\_test1.list}).

\noindent
\textbf{Are you confused?  Program not working?  PUT YOUR HANDS UP,
  AND SLOWLY WALK AWAY FROM THE TERMINAL.  DON'T MAKE A SUDDEN MOVE.
 Read the whole document all the way through the end, no skimming this time!
  Together
  with your other team members, diagram the structure of the code on
 a whiteboard.  Look at contents of the training list files.  Now you
 are ready to restart work!}

\item What code did you modify?  What was the maximum classification accuracy 
achieved on the training set?  How many epochs did it take to reach this
level?  How about for the validation set?  The test set?  Note that if you run
it again on the same system with the same parameters and input, you should get
exactly the same results because, by default, the code uses the same seed to
the random number generator each time. You will need to read Section~\ref{sec:interp}
carefully in order to be able to interpret your experiments and
answer these questions.


\item \textbf{Optional:} The ``straight'' training and test files only include
  images of the face-front pose.  Teaching the neural network to work
  for all four poses could be more challenging.  
Repeat the previous step using all poses, by specifying the ``all''
training and test file sets:

\noindent
{\tt facetrain -n shadesall.net -t all\_train.list -1}
\\
\-\qquad {\tt all\_test1.list -2 all\_test2.list -e 75}

\noindent
If performance is poor, try increasing the number of hidden units.

\item Now, implement a 1--of--20 face recognizer; \emph{i.e.}, implement a neural 
net that accepts an image as input, and outputs the userid of the person.  To
do this, you will need to implement a different output encoding (since you
must now be able to distinguish among 20 people).  (Hint: leave learning rate
and momentum at 0.3, and use 20 hidden units.)  You will need to modify
the code as described below so that it outputs the
name associated with the output neuron with the highest output value.

\item As before, train the network, this time for 100 epochs:

{\tt facetrain -n face.net -t straighteven\_train.list -1 }
\newline
\- {\tt \qquad  straighteven\_test1.list -2 straighteven\_test2.list -e 100}

The difference between the {\tt straightrnd\_*.list} and the {\tt
straighteven\_*.list} sets is that while the former divides the images purely
randomly among the training and test sets, the latter ensures a relatively
even distribution of each individual's images over the sets.  Because we have
only 7 or 8 ``straight'' images per individual, failure to distribute them
evenly would result in testing our network the most on those faces on which it
was trained the least.

\item Which parts of the code was it necessary to modify this time?
How did you encode the outputs?  What was the maximum classification accuracy
achieved on the training set?  How many epochs did it take to reach this
level?  How about for the validation and test set?

\item Now let's take a closer look at which images the net may have failed
to classify:

{\tt facetrain -n face.net -T -1 straighteven\_test1.list }
\newline
\- {\tt \qquad -2 straighteven\_test2.list}

Do there seem to be any particular commonalities between the misclassified
images?

\item Implement a pose recognizer; \emph{i.e.}, implement a neural net which,
when given an image as input, indicates whether the person in the image
is looking straight ahead, up, to the left, or to the right.  You
will also need to implement a different output encoding for this task.
(Hint: leave learning rate and momentum at
0.3, and use 6 hidden units).

\item Train the network for 100 epochs, this time on samples drawn
from all of the images:

{\tt facetrain -n pose.net -t all\_train.list -1 all\_test1.list}
\newline {\tt -2 all\_test2.list -e 100}

Note that you need to train on all images, not just the ``straight'' pose images.
In this case, 260 examples
are in the training set, 140 examples are in test1, and 193 are in test2.

\item How did you encode your outputs this time?
What was the maximum classification accuracy achieved on the training set?
How many epochs did it take to reach this level?  How about for each test set?

\item Now, try taking a look at how backpropagation tuned the weights
of the hidden units with respect to each pixel.  First type {\tt make
hidtopgm} to compile the utility on your system.  Then, to visualize the
weights of hidden unit {\it n}, type:

{\tt hidtopgm pose.net} {\it image-filename} {\tt 32 30} {\it n}

Invoking {\tt xv} on the image {\it image-filename} 
should then display the range of weights,
with the lowest weights mapped to pixel values of zero, and the highest
mapped to 255.  If the images just look like noise, try retraining using
{\tt facetrain\_init0} (compile with {\tt make facetrain\_init0}), which
initializes the hidden unit weights of a new network to zero, rather
than random values.

\item Do the hidden units seem to weight particular regions of the image
greater than others?  Do particular hidden units seem to be tuned
to different features of some sort?

\item \emph{Optional:} Implement an expression recognizer; \emph{i.e.}, implement a neural net that,
when given an image as input, indicates whether the person in the image
is neutral, happy, sad, or angry.  You
will also need to implement a different output encoding for this task.
You will have to experiment to determine the number of hidden units.  Use only
the ``straighteven'' training and test sets.  You might need to use the full-resolution 
images rather than the quarter-size images in order to capture enough detail of the expressions.
You can run on the full size images by using the training set lists:

{\tt straightevenHD\_train.list}\newline
{\tt straightevenHD\_test1.list}\newline
{\tt straightevenHD\_test2.list}

In your report, describe what you tried and how well it worked in the end.

\end{enumerate}

\section{Documentation}
\label{docs}

The code for this assignment is broken into several modules:

\begin{itemize}

\item {\tt facetrain.c}: the top-level program which uses all of the
modules below to implement an image classification system.  You will need to
modify this code to change network sizes and learning parameters.
The performance evaluation routines\\
{\tt performance\_on\_imagelist()} and {\tt evaluate\_performance()} are
also in this module; you will need to modify these for your face
and expression recognizers.

\item {\tt imagenet.c}: interface routines for loading images into
the input units of a network, and setting up target vectors for training.
You will need to modify the routine {\tt load\_target}, when
implementing the face recognizer and the pose recognizer, to set
up appropriate target vectors for the output encodings you choose.


\item {\tt backprop.c}, {\tt backprop.h}: the neural network package.
Supports three-layer fully-connected feedforward networks, using the
backpropagation algorithm for weight tuning.  Provides high level
routines for creating, training, and using networks.  {\bf You will not
need to modify any code in this module to complete the assignment.}


\item {\tt pgmimage.c}, {\tt pgmimage.h}: the image package.  Supports
read/write of PGM image files and pixel access/assignment.  Provides
an {\tt IMAGE} data structure, and an {\tt IMAGELIST} data structure
(an array of pointers to images; useful when handling many images). 
{\bf You will not need to modify any code in this module to complete
the assignment.}

\item {\tt hidtopgm.c}: the hidden unit weight visualization utility.
It's not necessary modify anything here, although it may be interesting
to explore some of the numerous possible alternate visualization
schemes.
{\bf You will not need to modify any code in this module to complete
the assignment.}

\end{itemize}

Although you'll only need to modify code in {\tt imagenet.c} and
{\tt facetrain.c}, feel free to modify anything you want in any of
the files if it makes your life easier or if it allows you to do
a nifty experiment.

\subsection { The top level package ({\tt facetrain.c})}

\subsubsection{Running {\tt facetrain}}
	\label{RUNFACE}

{\tt facetrain} has several options which can be specified on the
command line.  This section briefly describes how each option
works.  A very short summary of this information can be obtained
by running {\tt facetrain} with no arguments.

\begin{description}
\item {\tt -n &lt;network file&gt;} - this option either loads an existing
network file, or creates a new one with the given name.  At the end
of training, the neural network will be saved to this file.

\item {\tt -e &lt;number of epochs&gt;} - this option specifies the number
of training epochs which will be run.  If this option is not
specified, the default is 100.

\item {\tt -T} - for test-only mode (no training).  Performance
will be reported on each of the three datasets specified, and
those images misclassified will be listed, along with the corresponding
output unit levels.

\item {\tt -s &lt;seed&gt;} - an integer which will be used as the
seed for the random number generator.  The default seed is 102194
(guess what day it was when I wrote this document).  This allows you to
reproduce experiments if necessary, by generating the same sequence of
random numbers.  It also allows you to try a different set of random
numbers by changing the seed.

\item {\tt -S &lt;number of epochs between saves&gt;} - this option specifies
the number of epochs between saves.  The default is 100, which means
that if you train for 100 epochs (also the default), the network is
only saved when training is completed.

\item {\tt -t &lt;training image list&gt;} - this option specifies a text
file which contains a list of image pathnames, one per line, that
will be used for training.  If this option is not specified, it
is assumed that no training will take place ($epochs = 0$), and
the network will simply be run on the test sets.  In this case,
the statistics for the training set will all be zeros.

\item {\tt -1 &lt;test set 1 list&gt;} - this option specifies a text
file which contains a list of image pathnames, one per line, that
will be used as a test set.  If this option is not specified,
the statistics for test set 1 will all be zeros.

\item {\tt -2 &lt;test set 2 list&gt;} - same as above, but for test set 2.
The idea behind having two test sets is that one can be used as part
of the train/test paradigm, in which training is stopped when performance
on the test set begins to degrade.  The other can then be used as a
``real'' test of the resulting network.

\end{description}

\subsubsection{Interpreting the output of {\tt facetrain}}
\label{sec:interp}

When you run {\tt facetrain}, it will first read in
all the data files and print a bunch of lines regarding
these operations. Once all the data is loaded, it will
begin training. At this point, the network's training 
and test set performance is outlined in one line per epoch.
For each epoch, the following 
performance measures are output:

{\tt &lt;epoch&gt; &lt;delta&gt; &lt;trainperf&gt; &lt;trainerr&gt; &lt;t1perf&gt; &lt;t1err&gt;
&lt;t2perf&gt; &lt;t2err&gt;}

These values have the following meanings:

\begin{description}
\item {\tt epoch} is the number of the epoch just completed; it follows
that a value of 0 means that no training has yet been performed.

\item {\tt delta} is the sum of all $\delta$ values on the hidden and
output units as computed during backprop, over all training examples
for that epoch.

\item {\tt trainperf} is the percentage of examples in the training set
which were correctly classified.

\item {\tt trainerr} is the average, over all training examples,
of the error function $\frac{1}{2} \sum (t_{i} - o_{i})^{2}$, where
$t_{i}$ is the target value for output unit $i$ and $o_{i}$ is the actual
output value for that unit.

\item {\tt t1perf} is the percentage of examples in test set 1
which were correctly classified.

\item {\tt t1err} is the average, over all examples in test set 1,
of the error function described above.

\item {\tt t2perf} is the percentage of examples in test set 2
which were correctly classified.

\item {\tt t2err} is the average, over all examples in test set 2,
of the error function described above.
\end{description}

\subsubsection{Procedures in {\tt facetrain.c}}

You will need to make several changes in this package for the face
and expression recognizers, as described below.


\begin{description}
\item{\tt void backprop\_face(\newline
    IMAGELIST *trainlist, IMAGELIST *test1list, IMAGELIST *test2list,\newline
    int epochs, int savedelta, \newline
    char *netname,\newline
    int list\_errors)}

This is main routine you will modify.  It begins by reading in a
neural net file, or creating one if it does not exist.
The line
\begin{quote}
{\tt net = bpnn\_create(imgsize, 4, 1); }
\end{quote}
creates a neural net with specified number of input units, hidden
units, and output units.  


If the number of training epochs is greater
than zero, then the network is trained. 
The line
\begin{quote}
{\tt    bpnn\_train(net, 0.3, 0.3, \&amp;out\_err, \&amp;hid\_err);}
\end{quote}
sets the learning rate (second parameter) and momentum (third
parameter) both to 0.3.  You may need to vary these parameters.  (You
might find it useful to change them from constants to variables that
can be set by new command line arguments.)

The accuracy of the neural
network on the training set and two test sets is calculated and
printed before training and at the end of each epoch by calling the
procedure {\tt evaluate\_performance}. Finally, the network is saved.

You will add statements at the end of
this procedure for the face and expression recognizer.  For example, for the face
recognizer, you need to print the name of person corresponding to the
output unit with the highest value for each test image.  You will also
check whether the highest unit is indeed the correct one for the
image.  You can implement these changes by making a copy of {\tt
  evaluate\_performance} and modifying it.

\item{\tt int evaluate\_performance(\newline
    BPNN *net,\newline
    double *err)}

You will also need to modify this routine.  It checks if the output of
the network matches the target for the currently loaded image.  It
returns a Boolean value (1 for correct, 0 for incorrect), as well as
the difference between the target and output values ({\tt err}).  The
default code handles a single output neuron.  For the face and expression
recognizers, you will need to check all of the output neurons, in
order to see if they are all at or near (less than 0.5 distance) their
target values.  The returned {\tt err} should be sum of the errors
(squared {\tt delta}) for all of the output units.

\end{description}


\subsection{The interface package ({\tt imagenet.c})}

This package provides the interface routines for loading images into
the input units of a network, and setting up target vectors for
training.  You will need to modify the following procedure to set up 
appropriate target vectors for the output encodings you choose for the
face and expression recognition.

\begin{description}
\item {\tt void load\_target(\newline
IMAGE *img,\newline
BPNN *net)}

{\tt img} is an image that has been loaded.  The routine checks the
name of the file corresponding to the image, {\tt NAME(img)}, in order
to determine the true label for the image --- for example, the
person's name, or whether they are wearing sunglasses, or their
expression.  It then sets the target(s) of the output unit(s) to
appropriate values, {\tt TARGET\_HIGH} or {\tt TARGET\_LOW}, depending
upon what you are trying to learn.  The default code establishes a
target for a single output neuron that recognizes ``glickman''.
\end{description}


\subsection{The neural network package ({\tt backprop.c})}
\label{sec:neural}

As mentioned earlier, this package implements three-layer fully-connected
feedforward neural networks, using a backpropagation weight tuning
method.  We begin with a brief description of the data structure,
a {\tt BPNN} ({\tt B}ack{\tt P}rop{\tt N}eural{\tt N}et).

All unit values and weight values are stored as {\tt double}s in a
{\tt BPNN}.

Given a {\tt BPNN *net}, you can get the number of input, hidden,
and output units with {\tt net-&gt;input\_n}, {\tt net-&gt;hidden\_n},
and {\tt net-&gt;output\_n}, respectively.

Units are all indexed from $1$ to $n$,
where $n$ is the number of units in the layer.  To get the value
of the {\tt k}th unit in the input, hidden, or output layer, use
{\tt net-&gt;input\_units[k]}, {\tt net-&gt;hidden\_units[k]}, or
{\tt net-&gt;output\_units[k]}, respectively.

The target vector is assumed to have the same number of values as the number
of units in the output layer, and it can be accessed via {\tt net-&gt;target}.
The {\tt k}th target value can be accessed by {\tt net-&gt;target[k]}.

To get the value of the weight connecting the {\tt i}th input unit
to the {\tt j}th hidden unit, use {\tt net-&gt;input\_weights[i][j]}.
To get the value of the weight connecting the {\tt j}th hidden unit
to the {\tt k}th output unit, use {\tt net-&gt;hidden\_weights[j][k]}.

The routines are as follows:

\begin{description}
\item {\tt void bpnn\_initialize(seed)\newline
int seed;}

This routine initializes the neural network package.  It should be
called before any other routines in the package are used.  Currently,
its sole purpose in life is to initialize the random number generator
with the input {\tt seed}.

\item {\tt BPNN *bpnn\_create(n\_in, n\_hidden, n\_out)\newline
int n\_in, n\_hidden, n\_out;}

Creates a new network with {\tt n\_in} input units, {\tt n\_hidden} hidden
units, and {\tt n\_output} output units.  All weights in the network
are randomly initialized to values in the range $[-1.0, 1.0]$.  Returns
a pointer to the network structure.  Returns {\tt NULL} if the routine
fails.

\item {\tt void bpnn\_free(net)\newline
BPNN *net;}

Takes a pointer to a network, and frees all memory associated with
the network.

\item {\tt void bpnn\_train(net, learning\_rate, momentum, erro, errh)\newline
BPNN *net;\newline double learning\_rate, momentum;\newline
double *erro, *errh;}

Given a pointer to a network, runs one pass of the backpropagation algorithm.
Assumes that the input units and target layer have been properly set up.
{\tt learning\_rate} and {\tt momentum} are assumed to be values between
$0.0$ and $1.0$.  {\tt erro} and {\tt errh} are pointers to doubles, which
are set to the sum of the $\delta$ error values on the output units
and hidden units, respectively.

\item {\tt void bpnn\_feedforward(net)\newline
BPNN *net;}

Given a pointer to a network, runs the network on its current input
values.

\item {\tt BPNN *bpnn\_read(filename)\newline
char *filename;}

Given a filename, allocates space for a network, initializes it with the
weights stored in the network file, and returns a pointer to this new
{\tt BPNN}.  Returns {\tt NULL} on failure.

\item {\tt void bpnn\_save(net, filename)\newline
BPNN *net;\newline char *filename;}

Given a pointer to a network and a filename, saves the network to that
file.

\end{description}

\subsection{The image package ({\tt pgmimage.c})}

The image package provides a set of routines for manipulating PGM images.
An image is a rectangular grid of pixels; each pixel has an integer value
ranging from 0 to 255.  Images are indexed by rows and columns; row 0
is the top row of the image, column 0 is the left column of the image.

\begin{description}

\item {\tt IMAGE *img\_open(filename)\newline char *filename;}

Opens the image given by {\tt filename}, loads it into a new {\tt IMAGE}
data structure, and returns a pointer to this new structure.
Returns {\tt NULL} on failure.

\item {\tt IMAGE *img\_creat(filename, nrows, ncols)\newline
char *filename;\newline
int nrows, ncols;}

Creates an image in memory, with the given filename, of dimensions
{\tt nrows} $\times$ {\tt ncols}, and returns a pointer to this image.
All pixels are initialized to 0.  Returns {\tt NULL} on failure.

\item {\tt int ROWS(img)\newline IMAGE *img;}

Given a pointer to an image, returns the number of rows the image has.

\item {\tt int COLS(img)\newline IMAGE *img;}

Given a pointer to an image, returns the number of columns the image has.

\item {\tt char *NAME(img)\newline IMAGE *img;}

Given a pointer to an image, returns a pointer to its base filename
(\emph{i.e.}, if the full
filename is {\tt /usr/joe/stuff/foo.pgm}, a pointer to the string
{\tt foo.pgm} will be returned).

\item {\tt int img\_getpixel(img, row, col)\newline IMAGE *img;\newline
int row, col;}

Given a pointer to an image and row/column coordinates, this routine returns
the value of the pixel at those coordinates in the image.

\item {\tt void img\_setpixel(img, row, col, value)\newline
IMAGE *img;\newline int row, col, value;}

Given a pointer to an image and row/column coordinates, and an integer
{\tt value}
assumed to be in the range $[0, 255]$, this routine sets the pixel
at those coordinates in the image to the given value.

\item {\tt int img\_write(img, filename)\newline
IMAGE *img;\newline char *filename;}

Given a pointer to an image and a filename, writes the image to disk with
the given filename.  Returns 1 on success, 0 on failure.

\item {\tt void img\_free(img)\newline IMAGE *img;}

Given a pointer to an image, deallocates all of its associated memory.

\item {\tt IMAGELIST *imgl\_alloc()}

Returns a pointer to a new {\tt IMAGELIST} structure, which is really just
an array of pointers to images.  Given an {\tt IMAGELIST *il},
{\tt il-&gt;n} is the number of images in the list.  {\tt il-&gt;list[k]}
is the pointer to the {\tt k}th image in the list.

\item {\tt void imgl\_add(il, img)\newline
IMAGELIST *il;\newline IMAGE *img;}

Given a pointer to an imagelist and a pointer to an image, adds the image
at the end of the imagelist.

\item {\tt void imgl\_free(il)\newline IMAGELIST *il;}

Given a pointer to an imagelist, frees it.  Note that this does not
free any images to which the list points.

\item {\tt void imgl\_load\_images\_from\_textfile(il, filename)\newline
IMAGELIST *il;\newline char *filename;}

Takes a pointer to an imagelist and a filename.  {\tt filename} is
assumed to specify a file which is a list of pathnames of images,
one to a line.  Each image file in this list is loaded into memory
and added to the imagelist {\tt il}.

\end{description}

\subsection {The hidden unit visualization package ({\tt hidtopgm})}

{\tt hidtopgm} takes the following fixed set of arguments:

{\tt hidtopgm} {\it net-file image-file x y n}

\begin{description}

\item {\it net-file} is the file containing the network in which
the hidden unit weights are to be found.

\item {\it image-file} is the file to which the derived image will
be output.

\item {\it x} and {\it y} are the dimensions in pixels of the image
on which the network was trained.

\item {\it n} is the number of the target hidden unit. {\it n} may
range from 1 to the total number of hidden units in the network.

\end{description}

\subsection {The output unit visualization package ({\tt outtopgm})}

{\tt outtopgm} takes the following fixed set of arguments:

{\tt outtopgm} {\it net-file image-file x y n}

\begin{description}
\item This is the same as hidtopgm, for output units instead of input units.
Be sure you specify x to be 1 plus the number of hidden units, so that you get
to see the weight $w_{0}$ as well as weights associated with the hidden units.
For example, to see the weights for output number 2 of a network containing 3
hidden units, do this:

outtopgm expression.net expression-out2.pgm 4 1 2

\item {\it net-file} is the file containing the network in which
the hidden unit weights are to be found.

\item {\it image-file} is the file to which the derived image will
be output.

\item {\it x} and {\it y} are the dimensions of the hidden
units, where {\it x} is always 1 + the number of hidden units
specified
for the network, and {\it y} is always 1.

\item {\it n} is the number of the target output unit. {\it n} may
range from 1 to the total number of output units for the network.

\end{description}

\subsection{Tips}

Although you do not have to modify the image or network packages,
you will need to know a little bit about the routines and data structures
in them, so that you can easily implement new output encodings for
your networks.  You should look at {\tt imagenet.c},
{\tt facetrain.c}, and {\tt facerec.c} to see how the routines are
actually used.  

In fact, it is probably a good idea to look over {\tt facetrain.c}
first, to see how the training process works.  You will notice
that {\tt load\_target()} from {\tt imagenet.c} is called to set
up the target vector for training.  You will also notice the
routines which evaluate performance and compute error statistics,
{\tt performance\_on\_imagelist()} and {\tt evaluate\_performance()}.
The first routine iterates through a set of images, computing the
average error on these images, and the second routine computes
the error and accuracy on a single image.

Finally, the point of this assignment is for you to obtain first-hand
experience in working with neural networks; it is {\bf not} intended as an
exercise in C hacking.  An effort has been made to keep the image package
and neural network package as simple as possible.  If you need
clarifications about how the routines work, don't hesitate to ask.

If you read all the way to the end of this document before starting
to modify the code, congratulations!  You are on the road to success!

\end{document}
</pre></body></html>