GOAL:                       The goal of this assignment is to develop your skills in writing code   systematically and well, with due attention to commenting, structure, modularity, defensive programming, testing and good programming habits.

TASK:                       We will therefore take a small task – that of extending the pgmEcho utility shown in class and used in the debugging exercise.  You will construct a set of         programmes (or utilities) that manipulate PGM files in a number ofways.

CONTEXT:               This assignment prepares you for the main project, which is currently under NDA (non-disclosure agreement).  We can however tell you that this task is related to the main project, and that you should be able to adapt your code from this assignment for it  when it is available.  You should therefore make every effort to write your code as robustly  and reusably as possible, to reduce your workload in the second half ofthe term.

MARKING:              This coursework is worth 50% ofthe final grade, divided between         tasks as shown.  We will assign a separate percentage mark for code quality, and your result   will be the product of the two numbers - i.e. ifyou complete I.-V. flawlessly, your base mark  will be 40/50.  But ifyour code quality is poor (50%), this will be downgraded to 20/50.         Notice that Tasks V. & VI. are significantly harder than Tasks I.-IV.  This is because they are intended to push the abilities ofthe class.  However, they are worth fewer marks, which          means that a student who completes I.-IV. with reasonable (60%) code quality can expect       24/50 overall - i.e. a passing mark.  A student who completes I.-IV. with high (80%) code       quality can expect 32/50 overall - i.e. a good mark.  And a student who completes I.-IV.          meticulously (with perfect code) can expect 40/50 overall, and will already have passed the    module, with the marks in Assignment 2 moving them up into higher classifications.

MACHINES:            For this assignment, you should continue to work on the lab machines, feng-gps or feng-linux, in order to develop your command-line skills further.  We                   recommend that you use vi, nano or emacs for command-line editing until you are                  comfortable that you can use these tools correctly in future. After that, ifyou wish to use        GUI-based text editors on feng-linux or the lab machines, you may.  Any code which does     not compile and run on feng-gps with no modification will receive a mark of 0, but we will    usually give the student ONE chance to fix it.

PROCESS:                We will check the commit logs ofyour git repository.  By the end of  Week 5, you should commit a text file called "modules.txt" describing your proposed           modules and which module is used in which programme.  Each module should have 1          paragraph of no more than 500 characters that describes the module and what its purpose is. By the end ofWeek 5, you should also commit a text file called "testplan.txt" with no more  than 2 paragraphs each of no more than 500 characters, describing your test plan.                  We expect to see steady progress towards completion, as revealed in the pattern of git           commits.  One ofthe implications ofthis is that we will be penalising any student who         develops their code without git, then dumps it all into git at the last minute.

THE TASKS:            There are six sub-tasks, labelled I.-VI, each worth 5 or 10 marks.

I           (10).    Analyse pgmEcho.c to identify how it should be improved, then rewrite it so

that it is more modular, more suitable for reuse, and properly defensive in terms of errors. Note that this should involve understanding the remaining tasks as well.

II.        (10)     Write a programme called pgmComp which takes two pgm file names as arguments, reads them in and tests whether they are logically identical.

III.       (10)     Modify pgmEcho and pgmComp to accept binary PGM as well as ASCII, and write utilities called pgma2b to convert the ASCII form to the binary, and pgmb2a to convert the binary form to the ASCII.

IV.      (10)     Write a programme called pgmReduce which takes 3 arguments:

and inputFile is a 13x17 image, then outputFile should be a 2x3 image in which only the pixels with row and column of 0 modulo 5 in the inputFile exist.

V.        (5)       Write another programme called pgmTile which takes 3 arguments, an input  file (either ASCII or binary), an integer factor n, and an output file name template.  It should divide the input file into nxn smaller images corresponding to parts ofthe image.  For

pgmTile  sampleFile.pgm  3  sampleFile_<row>_<column>.pgm  then the programme should read in sampleFile.pgm and output 9 smaller images, named:

sampleFile_0_0.pgm

sampleFile_0_1.pgm

sampleFile_0_2.pgm

sampleFile_1_0.pgm

sampleFile_1_1.pgm

sampleFile_1_2.pgm

sampleFile_2_0.pgm

sampleFile_2_1.pgm

i.e. substituting the relative position ofthe subimage in the larger image into the <row> and <column> tags in the template name

VI.       (5)       Write a final programme called pgmAssemble which can be used to assemble a large image from smaller ones. It should take 3n+3 arguments of which the first three are:

1.         an output file name

3.         height ofthe output image

and the remainder are the layout: triples of:

3i+1.   row at which the subimage starts

3i+2.   column at which the subimage starts

3i+3.    The subimage to insert at that location

TESTING:                We will be running our own test scripts in order to mark the                  assignments, and doing our best to come up with creative ways to break your code.  You        should therefore develop your own test plan, test scripts and test files to beat us to it.  You      should have a single test script called “testscript.sh” which runs through all ofthe tests you     have constructed, but your code MUSTbe strictly compliant with our standards in order for   our test scripts to function, as described under return values. Code that is not strictly               compliant will receive a mark of 0, but we will usually give the student ONE chance to fix it.

MAKEFILES:           In order for us to be able to compile and run your code automatically, you should also submit a makefile with separate targets for each programme, and two

additional targets:  all and clean.  “make all” compiles all of the targets, while “make clean”  removes all object files (.o), all executables, and any temporary files created during your run.

FILE LOCATIONS:Your code should not make any new directories, or hard code any  relative paths.  All file names should be specified by command-line arguments. This will allow us to test any file location for input and output in our scripts.

RETURN VALUES AND ERROR CODES:

All programmes should return the value 0 in case of success, non-0 in   case of failure, and a string to describe the result.  This is a standard Unix convention: we       return 0 on success because there is often only one way the programme can succeed, but         many ways it can fail, which allows us to use the return value to indicate what type of failure.

There is an exception to this: if no arguments are given, the programme should return a          special message indicating the correct usage and return 0. This message (which is also a         standard convention) is a minimal help message that starts with the string "Usage: " followed by the name of the executable (which can be found in argv[0]) and a brief description ofthe   correct parameters.  In this case, input files should be called "inputImage" and output files      should be called "outputImage", so the forms are:

Usage:  ./pgmEcho  inputImage.pgm  outputImage.pgm

Usage:  ./pgmComp  inputImage.pgm  inputImage.pgm

The string to be output on success depends on the programme:

0           ECHOED                     pgmEcho                      Programme echoed the input

0           IDENTICAL               pgmComp                    The two files were identical

0          CONVERTED           pgma2b/pgmb2a         The file was converted

0          TILED                        pgmTile                      The tiles were successfully written

1          ERROR: Bad Argument Count

Programme given wrong # ofarguments