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 of ways.

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 of the term.

MARKING:              This coursework is worth 50% of the 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. if you complete I.-V. flawlessly, your base mark will be 40/50.  But if your 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 of the 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, if you 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 of Week 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 of the implications of this 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:

1.          an input file (either ASCII or binary)

2.          an integer factor n, and

3.          an output file

and reduces the input file by that factor in each dimension.  For example, if the invocation is:

pgmReduce inputFile 5 outputFile

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 of the image.  For

example, suppose that the invocation is:

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

sampleFile_2_2.pgm

i.e. substituting the relative position of the 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

2.          width of the output image

3.          height of the 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 of the 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 of the  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

Usage: ./pgma2b inputImage .pgm outputImage .pgm

Usage: ./pgmb2a inputImage .pgm outputImage .pgm

Usage: ./pgmReduce inputImage .pgm reduction_factor outputImage .pgm

Usage: ./pgmTile inputImage .pgm tiling_factor outputImage_<row>_<column> .pgm

Usage: ./pgmAssemble outputImage.pgm width height (row column inputImage.pgm)+

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

Value   String                 Programme      Meaning

0            ECHOED                       pgmEcho                        Programme echoed the input

0            IDENTICAL                 pgmComp                       The two files were identical

0            DIFFERENT                 pgmComp                       The two files were not identical

0            CONVERTED              pgma2b/pgmb2a           The file was converted

0            REDUCED                    pgmReduce                    The file was successfully reduced in size

0            TILED                             pgmTile                           The tiles were successfully written

0          ASSEMBLED             pgmAssemble              The full image was written

Value  String                                                      Condition

1           ERROR: Bad Argument Count                        Programme given wrong # of arguments