COMP1011 Assignment 2 - 05s2
Computing 1A 05s2 Last updated Fri 21 Oct 2005 17:10

Scene descriptions, the Renderer and PPM files

Scene descriptions

This section explains what a valid scene file is composed of. Note that you won't have to implement the scene parser, but for testing purposes it's vital that you are able to write valid scene files.

Scenes are ASCII text files and can have any name whatsoever, although you may prefer to add a .scn extension to the file to distinguish it from other files. We now desribe their format. Note that anything in typewriter font is something that must actually appear in the file while the fields (in italics) must be replaced with something valid.

Scene description file format

file name
depth recursion depth
fov degrees
size width height
ambient red green blue
... and then any number of lines of either:
light x y z red green blue
sphere x y z radius diffuse specular red green blue
plane distance nx ny nz diffuse specular red green blue

The fields are subject to the following restrictions:

There is one more piece of important information. Even if the scene has no errors and hence parses correctly, some additional checks will be made on the scene by the checkScene function in module World. Firstly, we see if the eye position (at point (0,0,-1)) overlaps with any objects. The we check whether any light sources overlap with any objects. For a sphere this means that the light source is inside the sphere. For a plane it means that it is somewhere on the surface. If either of these two conditions fails the render function in module Renderer signals an error.

The Renderer

The final program binary is called renderer. It takes a scene description as a command line argument and then writes to the PPM file specified in the scene description. If the scene contains any errors renderer will let you know. A sample invocation of this program at the unix command line is:

flute01% ./renderer lotsa_spheres.scn

Building the Renderer

A Makefile has been included to allow you to build the renderer. Although it will be build straight away, it will not be possible to test the program as a whole until you have completed all the function definitions. Therefore, it is very important that you test individual functions as you implement them by writing test harnesses and using GHCi. You need to make sure that all functions work by themselves properly before you can test the whole program in any meaningful way.

Building on Unix machines

To build the assignment type the following at the unix prompt:

flute01% make

Building on Windows machines

If you're using a Windows machine make may not be installed. To build the assignment type the following on the commandl line:

C:\> ghc -O2 --make Renderer.hs -o renderer

Testing the whole program

To test the whole program without solving the bonus part of the assignment, you need to download the appropriate binary files RayTrace.hi and RayTrace.o for your operating system. You find them here.

PPM Files

renderer writes images into files in the Portable Pixmap format (PPM). Since you'll actually be coding this part we describe the format here.

The format consists of a ASCII header followed by the pixel data in binary form. The format of the header is

These items are separated by whitespace (spaces, TABs, CRs, and LFs: spaces are just fine though). After the maximum colour value, there is a single whitespace character (usually a newline), which is followed by the pixel data. The pixel data is a sequence of three-byte pixel values (red, green, blue) in row-major order. Row major order simply means that the 0th row goes first, then the first and so on. The rows are notseparated by any characters.

Colours (defined in the Physics module) are converted to RGB format by clamping the range to [0,1] and scaling. Clamping means that if a number is less than zero it becomes zero and if it is greater than one it becomes one. For example, a colour Col (1.1, -0.2, 0.3) would be clamped to (1.0, 0.0, 0.3). Scaling involves multiplying by 255 and turning the number into an integer using the floor function. The result will be in the range [0,255].

We give an example of a tiny 2x2 grey PPM file. The ASCII value of a is 97. So each colour component (red, green, and blue) is set to 97. There are four pixels and three componets per pixel for a total of twelve as

2 2

New Example!

As a second example consider a 2x3 (that is, two pixels wide and three high) coloured PPM file defined by the following image value:

((2,3),[[Col (0.496,0.13,0.13),Col (0.13,0.496,0.13),
Col (0.13,0.13,0.496)],[Col (0.13,0.13,0.496),Col (0.13,0.496,0.13),
Col (0.496,0.13,0.13)]]) 

The colour values Col (0.496,0.127,0.127), Col (0.127,0.496,0.127), and Col (0.127,0.127,0.496) will appear as a dark red, green, and blue, respectively.

The PPM file generated for this image should be the following:

2 3

In particular, the value 0.496 is clamped to 126, which corresponds to the ASCII character '~', and 0.13 is clamped to 33, which corresponds to '!'.