Project 1

[Logo]

Project 1: Ray Tracing

Project Description

You will build a program that will generate ray-traced images of complex scenes using the Whitted illumination model. This will include implementing primary rays, and secondary shadow, reflection, and transmission rays. You will also implement the Phong Illumination model, ray-triangle intersects (intersects for other shapes are provided), and texture mapping.

Getting Started

We recommend running this code on the CS lab machines, as the build process will be simpler, but it will require working physically in the labs rather than sshing in. While it's technically possible to use X11 forwarding to work remotely, this will have its own complexity and pitfalls, so I'd recommend against it.

In order to start the project, you will want to download:

  1. Starter code
  2. Reference binaries for Linux, Windows, and Mac
  3. Scene models in JSON format
  4. Scene models in the ray format
  5. Cubemap images previously collected from the web
Note that this system can read both .bmp and .png files for texture maps and can write out images you produce as .bmps.

To install the starter code on the lab machines, Linux, or OSX, untar the file and do the following:
mkdir build
cd build
cmake ..
make -j8

This will generate a binary under build/bin/. The starter code can run in both text mode and GUI mode. Running without any arguments will execute the program in the GUI mode, but you can also set the recursion level, input scene, and output image (among other features) from the command line. For complete usage see 'ray -help'.

Note: that this code has been tested and found to work on many of these configurations of OSX and Windows, but for OSX, you will likely want to use a package manager such as OSX's Homebrew for installing the necessary dependencies. You will need to use CMake along with the libraries for FLTK, JPEG, ZLIB, and PNG, as well as OpenGL and GLEW for debugging. Windows instructions can be provided if absolutely necessary, but if you're not comfortable working with Visual Studio compilers and installing packages, I'd highly recommend against it.

Once you have a working build, take a little time to navigate through the project files. This project is a very large collection of files and object-oriented C++ code, but you only need to work on a subset of it. That said, the more familiar you are with the layout and class hierarchy, the better you will know what classes and methods are available for your use/expected access patterns. Basic linear algebra operations are provided by the OpenGL Mathematics (glm) librar. Documentation (lacking as it is) is available at https://glm.g-truc.net/0.9.9/api/modules.html. I'd also recommend not taking "expected behavior" for granted with GLM. Do some small test cases where you have calculated expected results on paper, before using it "in the wild."

You will be adding code to files: RayTracer.cpp, light.cpp, material.cpp, and trimesh.cpp. The starting point for where ray tracing begins, and where you will be needing to add a lot of functionality, is in the RayTracer.cpp file. This is a good file to start exploring what methods get called and what they do.

In the GUI mode, clicking on the screen will shoot a single ray through that pixel. Although this won't do much now (it won't even compute intersections on polygon meshes), you can use this plus the debugging window, which allows you to see individual rays bouncing around the scene, to visually debug. The debugging window provides a lot of visual feedback that can be enormously useful when debugging your application. Here is a more detailed explanation of how to use the debugging window.

Required Functionality

For this assignment, you will need to implement:
  1. The Whitted illumination model, which includes Phong shading (emissive, ambient, diffuse, and specular terms) as well as reflection and refraction terms. You only need to handle directional and point light sources (i.e. no area lights), but you should be able to handle multiple lights. You will implement this primarily in the RayTracer, material, and light files.
  2. Triangle-ray intersections. Fill in the triangle intersection code so that your ray tracer can display triangle meshes in the trimesh files.
  3. Implement Phong interpolation for per-vertex normals on triangle meshes in trimesh.
  4. Implement cube mapping as a user-selectable option with bilinear interpolation. The default for any scene is no cube mapping. You will add this functionality primarily in material and cubeMap.

Notes on Whitted's illumination model

The first three terms in Whitted's model will require you to trace rays towards each light, and the last two will require you to recursively trace reflected and refracted (e.g. transmitted) rays. Notice that the number of reflected and refracted rays that will be calculated is limited by the "depth" setting in the ray tracer. This means that to see reflections and refraction, you must set the depth to be greater than zero!

When tracing rays toward lights, you should look for intersections with objects, thereby rendering shadows. You do not need to handle shadows of semi-transparent objects differently, but you can attenuate the light through these objects to achieve partial (color-filtered) shadows for extra credit.

Here are some equations that will come in handy when writing your shading and ray tracing algorithms.

Debugging and Troubleshooting

Two scripts have been provided to help you test your code. raycheck.py will attempt to run on the provided examples. Your binary should terminate within 180 seconds for all scenes except those involving large triangle meshes. sancheck.py will identify some common problems with how you've packaged your source code for submission.

In terms of debugging your ray tracer, you will want to use both the command line UI and the debug window to makes sure you both implemented correctly and are correct conceptually.

Segfaults

If you encounter segfaults (likely) you can use gdb to help debug: 

$ gdb bin/ray
(gdb) run input.ray tmp.png
# ...  RUNNING
# ...  Segfault Captured
(gdb) bt
# ...  Backtrace is shown

Now you can locate where the problem is.

Note: cmake -DCMAKE_BUILD_TYPE=Debug is required to enable the debugging symbols, otherwise bt only shows the memory address rather than the line number of your source file.

Suspicious Shading Result

It would be very expensive to render the whole scene in order to fix one pixel. The recommended procedure is

  1. Locate the pixel
  1. Hack CommandLineUI.cpp
  1. Add print/std::cout everywhere you are not sure it is correct.

A1 Milestone

For your A1 milestone, submit a progress report as a .pdf document stating what has been accomplished (and by whom if working with a partner), and what the plan is for completing the assignment on time. Include some image artifacts of what's been implemented as well.

As a guideline of what we're expecting, you should have all of Phong shading completed as well as lighting and reflection. You should also be making good progress into either refraction, triangle-ray intersections, or cube mapping, or a little progress for all of them.

In terms of your plan, please try to be specific -- this document is also intended to help you think through what needs to be done and what a reasonable timeline should be. Therefore, you should include:

You should also include a link to a git repo with your milestone code frozen in a branch called a1-milestone so we can verify you're on target to complete the assignment. Note, you can also link this documentation from your git repo if you prefer and submit a link of that directly to Canvas -- either way is fine.

Submissions Instructions

Submit your project via GitLab and provide a link to it via Canvas. Make sure to keep your repository private and give access to me (thesharkcs) and the TA (GitLab username will be posted to Announcements on Canvas). We will be grading based on a branch called code-freeze, so please make sure you have a working final version of the project on that branch. If commits are made after the deadline, we will treat that as a late submission, and we will deduct late slips accordingly and/or apply the late submission penalty as per the syllabus.

In addition to the code, please include:

If you developed your program on Windows or some other platform, please try to port your work to the lab Linux machines before submitting it, running sancheck.py to look for potential issues. We will do our best to grade despite the natural issues that arise from remote/cross-platform development, but please try to assist the TA as much as possible.

Notes on Grading

You'll be graded on how well you met the requirements of the assignment. D quality or below work has few or none of the features implemented/working. C quality work has implemented some or most of the features, but the features are built in a way that is not fully working and/or the logic is not well-considered. B quality work has implemented most or all of the features in a way that works but may have some issues and/or the logic is not fully considered. A quality work has implemented all of the features in robust, polished way that demonstrates your understanding of the assignment, the math, and the provided code base. Note that a well-written report can help us understand your thought process, which is a large part of what we are grading you on in these assignments.

  1. The repository should include everything needed to build your project, including CMake configuration files like CMakeLists.txt. We will dock points on submissions that have obviously problems building correctly “out of the box.” Please use sancheck.py to identify some (but not all) potential problems with your submission.

  2. Do not include output .pngs, core dumps, or other large extraneous files in your repository. Anything you'd like us to see should be included in the report.

  3. The ray tracer is graded using the COMMAND LINE UI (with the -r 5 recursion option). Please make sure the command line UI produces the same image your GUI version does.

  4. During grading, the executable is built with cmake -DCMAKE_BUILD_TYPE=Release rather than the bare cmake, which enables optimizations. Please make sure the ray tracer does not segfault and still generates correct images with this build type. Some bugs are invisible in Debug builds and only appear when the code is compiled in Release mode.

  5. When grading, we will terminate programs that take longer than 180 seconds (in Release build). 180 seconds should be ample unless your implementation is egregiously inefficient. Please make sure your code is not too slow to finish complicated scenes like dragon.ray within the time limit. (trimesh*.ray scenes are exceptions. These are very large scenes and may not finish in 180 seconds).

Acknowledgements

The starter code is modified from a codebase originally developed by Don Fussell, and done in conjunction with Etienne Vouga's honors version of this class.

References

Last modified: 01/10/24 by Sarah Abraham theshark@cs.utexas.edu