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 n_x n_y n_z diffuse specular red green blue

The fields are subject to the following restrictions:

• Any amount of white space (that is not a newline, linefeed or carriage return) can exist between fields.
• The name can be any string, however it should end in a .ppm extension. This is the file the image will be written to.
• recursion depth is how many reflections we are prepared to follow until we reach a light source. 10 gives quite reasonable results.
• degrees is the field of view argument and must be between 1 and 179 degrees (inclusive)
• width and height are the final dimensions of the image file. They must be positive integers. (i.e. not negative, not zero). Large values for this will take a long time to render. We suggest you limit it to 256x256 until you complete the assignment
• red, green and blue describe the colour components for ambient lighting, light sources, spheres and planes. These values must be in the range [0.0, 1.0].
• x, y and z defines the position of a light, the centre of a sphere. These values must be doubles (real numbers).
• radius must be a double
• diffuse and specular determine the surface properties of an object and must be in the range [0.0, 1.0]. 0.0 means that the object is not diffuse (or specular) and 1.0 means that reflections are perfectly diffuse (or specular.)
• n_x, n_y and n_z define a normal vector. Unlike almost everywhere else in the assignment it does not have to be a unit vector. The SceneParser module will take care of this.
• Any field of the scene description that must be a double must be of the form [-]X.X or [-]X . The square brackets([ ]) mean that the minus sign is optional and X stands for any number of digits.

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 magic number, which are the two characters ``P6.''
• A width, formatted as ASCII characters in decimal.
• A height, again in ASCII decimal.
• The ASCII text ``255,'' which is the maximum color-component value.

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

P6
2 2
255
aaaaaaaaaaaa

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:

P6
2 3
255
~!!!!~!~!!~!!!~~!!

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 '!'.