multicolor test file

The Assignment

For this assignment, you must write a C or C++ program that will render triangles using ray tracing. The input is in a subset of the rayshade (.ray) file format, containing information about the view and objects in the scene. You will read a .ray scene from a file, and ray trace the single image described there. Rays that hit an object should be rendered in the object color, while rays that do not hit any object should use the background color of the scene. Do not try to include any of the more advanced ray tracing features you may read about (shadows, reflection, refraction, lights, etc.), we will get to those later. Your output should be an image file in PPM format.


For the base assignment, you should be able to trace tetcolor.ray. Additional .ray format scenes can be generated using a set of programs called the 'Standard Procedural Databases', using the "-r 8" command-line option to generate rayshade-formatted output. A compiled copy of these programs may be found in ~olano/public/spd3.14/ on the UMBC GL Linux systems. While rayshade format is relatively simple, it does contain many features we will not be using in this assignment. For the basic assignment, you should handle "background", "eyep", "lookp", "up", "fov", "screen", "surface", and "polygon", and "triangle". For "surface" you only need to handle the "diffuse" keyword.

triangle fan


The "polygon" shape can have any number of vertices. You may assume the polygon is convex, so can be split into a fan of triangles using the first vertex with pairs of subsequent vertices. For the example to the right, the triangles are (v0,v1,v2), (v0,v2,v3), (v0,v3,v4), and (v0,v4,v5).

The "triangle" shape only ever has three vertices (9 floats total); but may have an additional 3-element vector per vertex, which you can ignore (18 floats total, you'd use floats and 1-3, 7-9, 13-15).


We are using the PPM image file format because it is exceedingly simple to write. See the specification for details, and the initial trace.cpp code for an example that writes a PPM. PPM files can be viewed directly or converted to other image formats for viewing. The Mac Preview app will open these files. On Windows or Linux, the ImageMagick package includes a "display" program to view these files and "convert" program to convert PPM into most other image formats. Alternately, the Gimp package can both display PPM images and save in other formats.

When filling in this array, remember that it is in y/x order (the entire first row, followed by the entire second row, etc.), with the first pixel in the top left corner of the image. Also, PPM colors are unsigned bytes ranging from 0 to 255, while rayshade colors are floating point numbers, ranging from 0 to 1. Use floating point colors internally, then convert to bytes for output. Be careful to check for overflow or underflow when mapping floating point values into a byte. For example, something like this could convert a floating point color value, f, to byte form:

(f>1.0) ? 255 : (unsigned char)(f*255.0)

File locations

Take the .ray filename to use as a single command-line argument (you can set the command-line arguments in the Debug project settings in Visual Studio, or under Edit Scheme in XCode). Look for this file relative to the cmake build directory, using the PROJECT_BUILD_DIR defined in config.h.

Create your output in a file named trace.ppm in the PROJECT_BUILD_DIR. Note that this is different than the directory used for assn0 (which used PROJECT_BASE_DIR). Creating the ppm file in the build directory will prevent you from having a ton of extra commits that are just because you ran a new rayshade file through your program and trace.ppm changed.

Extra credit

For up to 10 points of extra credit, do spheres as well.

gears -s 2 -r 8
From gears-2.ray

634 only

Students who are taking this class as CMSC 634 should also add the ability to trace arbitrary concave polygons. For example, the gear faces from the "gears" SPD program are each a single 144-vertex concave polygon. You are free to handle these however you want. Two possibilities are ray tracing triangles, but using a triangulation algorithm like ear clipping that can handle concave polygons, rather than the simple triangle fan algorithm described above; or using a general polygon ray intersection instead of the simpler ray-triangle intersection to avoid triangulation entirely.

Other people's code

Ray tracing is a popular rendering technique, and the internet contains lots of resources for ray tracers in general and things like ray-object intersection in particular. Other than the PPM snippet above or files provided by me in your git repo, YOU MAY NOT USE ANY OUTSIDE CODE. All code that you use must be strictly your own.


This is a big assignment. Start NOW, or you will probably not finish. No, really, I promise you will not be able to do it in the last two days. Even before we get to all of the details of the ray tracing itself, you can still start working on your file parsing.

I have created a separate page with some additional development suggestions.

What to turn in

Turn in this assignment electronically by pushing your source code to your class git repository by 11:59 PM on the day of the deadline and tagging the commit assn1. Do your development in the trace directory so we can find it.

Also include an assn1.txt file at the top level of your repository telling us about your assignment. Tell us what works, and what does not. Also tell us what (if any) help you received from books, web sites, or people other than the instructor and TA.

You must make multiple commits along the way with useful checkin messages. We will be looking at your development process, so a complete and perfectly working ray tracer submitted in a single checkin one minute before the deadline will NOT get full credit. Individual checkins of complete files one at a time will not count as incremental commits. Do be sure to check in all of your source code, but no build files, log files, generated images, zip files, libraries, or other non-code content.

You should not use the github file upload for anything in this class. You will lose points on the assignment if you do. Commit to your local repository, then push to github.