/ CMSC 435/634 Assignment 1

The Assignment

For this assignment, you must write a C++ program that will render spheres 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.

balls -s 3 -r 8 with random sphere colors


All of the sample input files mentioned here have been checked into your trace/data directory. Do a git pull to get them.

Build the path to the file to use from PROJECT_DATA_DIR plus a file name given as a single command-line argument. In Visual Studio, set the command line argument in the Debug tab of the project properties. In XCode, set it under "Edit Scheme".

For the base assignment, you should be able to trace balls3-color.ray. 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 only handle the following keywords: background, eyep, lookp, up, fov, screen, surface, and sphere. The surface keyword introduces a block of surface shading related keyworkds. Of these, you only need to handle diffuse. For anything in the file that you do not handle, just keep reading until you find one of those keywords.

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. In these generated files, all of the spheres are the same color. The balls3-color.ray file was created using a simple script make each sphere a random color. Generate the original balls3.ray file on GL with this command:

~olano/public/spd3.14/balls -s 3 -r 8 > balls3.ray

In this command, the -r option sets the output format, and the -s option sets the complexity level. Level 3 for this model consists of 820 spheres, The default balls.ray has 7381 spheres, which can be quite slow to ray trace:

~olano/public/spd3.14/balls -r 8 > balls.ray


Your output should be a file named "trace.ppm" in the PROJECT_BUILD_DIR directory (not the PROJECT_BASE_DIR directory as was done by the sample code).

We are using the PPM image file format because it is exceedingly simple to write. See the specification for details. PPM colors use unsigned bytes, but colors in the rayshade file are floating point numbers between 0 and 1. I recommend using floating point colors until it is time to assign the color into an image pixel (just multiply by 255 and cast to unsigned char).

balls -s 3 -r 8 gears -s 2 -r 8
From balls3-color.ray From gears2.ray

634 only

Students who are taking this class as CMSC 634 should also add the ability to trace arbitrary polygons ("polygon" in the .ray file). Examples of this include the orange floor in the balls scene, or any scene generated by the "gears" SPD program.

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 assn0 sample code, 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.