COMP 1921: Programming Project 

2021-2022 

ASSIGNMENT 1: PGM Utilities 

[50 marks] 

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 of your 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__.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 and 

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 locationTESTING: 

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 MUST be 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__.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 arguments2 

ERROR: Bad File Name (fname) 

Programme failed to open a file stream 

3 

ERROR: Bad Magic Number (fname) 

Programme failed on a magic number 

4 

ERROR: Bad Comment Line (fname) 

Programme failed on comment line 

5 

ERROR: Bad Dimensions (fname) 

Programme failed on image dimensions 

6 

ERROR: Bad Max Gray Value (fname) 

Programme failed on max gray value 

7 

ERROR: Image Malloc Failed 

Malloc failed for image allocation 

8 

ERROR: Bad Data (fname) 

Programme failed when reading in data 

9 

ERROR: Output Failed (fname) 

Programme failed during output 

10 

ERROR: Bad Layout 

Layout file for assembly went wrong 

100 

ERROR: Miscellaneous (text) 

Any other error that is detected. 

In each case, fname should be replaced by the name of the file that failed. Similarly, 

in a miscellaneous error, "text" should be replaced by a description in no more than 

100 characters of the error detected. 

Note that we do NOT guarantee that this is an exhaustive list of possible errors. 

HANDIN INSTRUCTIONS: 

Your work should be submitted via the COMP1921 gitlab repository. 

Your submission should be in a directory in the root of your git repository called 

"assignment_1" and should contain files which conform to the specification outlined in the 

assignment specification. You submission should contain all the relevant source code and 

header files, a brief README file explaining how to run your submission, and a Makefile 

which builds all of the executables specified. It is your responsibility to ensure that your 

submission compiles and executes on the feng-gps machine. Your commit and push must be 

made prior to the deadline. 

You should also include a test script called “testscript.sh” and any test files you rely on. 

In summary, your handin should include: 

1. 

All necessary .c and .h files 

2. 

A makefile as described above 

3. 

A test script “testscript.sh” 

4. 

A readme file called “readme.txt” 

5. 

A test plan file called “testplan.txt” 

6. 

A file called “modules.txt” 

7. 

Any .pgm files which you use for your test script. 

With the exception of the .pgm files, all of these files must be in the assignment_1 directory. 

You may place the .pgm files in a subdirectory if you wish. 

If there are ANY other files or subdirectories in the directory when it has been handed in, you 

will lose marks. This includes any hidden file (prefixed with .), except for .git and .gitignore. 

DUE DATE: 

March 11, 2022 at 10:00 am.