Overview

Your current assignment focuses on the PathTracer component of Scotty3D.

Important Information

Due Date: Nov 14th, 2016 11:59pm

You will need three things to complete this assignment:

1. The skeleton code for Scotty3D---the specific files you will modify are specified in Developer Manual with individual tasks. This is the same code base as you used for A2, but with some changes made for A3. You will modify different files for A3.

2. The User Guide explains how to use the software to an end-user.

3. The Developer Manual explains low-level details and internals of the code to a software developer.

Note that the User Guide is not the Assignment Writeup. The User Guide contains only instructions on how to use the software, and serves as a high-level specification of what the software should do. The Developer Guide contains information about the internals of the code, i.e., how the software works. This division is quite common in software development: there is a design specification or "design spec", and an implementation that implements that spec. Also, as in the real world, the design spec does not necessarily specify every tiny detail of how the software should behave! Some behaviors may be undefined, and some of these details are left up to the party who implements the specification. A good example you have already seen is OpenGL, which defines some important rules about how rasterization should behave, but is not a "pixel-exact" specification. In other words, two different OpenGL implementations from two different vendors (Intel and NVIDIA, say) may produce images that differ by a number of pixels. Likewise, in this assignment, your implementation may differ from the implementation of your classmates in terms of the exact values it produces, or the particular collection of corner-cases it handles. However, as a developer you should strive to provide a solution that meets a few fundamental criteria:

• Failing gracefully is preferable to failing utterly---for instance, if a rare corner case is difficult to handle, it is far better to simply refuse to perform the operation than to let the program crash!
• Your implementation should follow the principle of least surprise. A user should be able to expect that things behave more or less as they are described in the User Guide.
• You should not use an algorithm whose performance is asymptotically worse just because it makes your code easier to write (for instance, using bubble sort rather than merge sort on large data sets).
• That being said, when it comes to performance, premature optimization is the root of all evil! The only way to know whether an optimization matters is to measure performance, and understand bottlenecks.
• Finally, you should take pride in your craft. Beautiful things just tend to work better.

Just to reiterate the main point above:

As in real-world software development, we will not specify every little detail about how methods in this assignment should work!

If you encounter a tough corner case (e.g., "how should edge flip behave for a tetrahedron"), we want you to think about what a good design choice might be, and implement it to the best of your ability. This activity is part of becoming a world-class developer. However, we are more than happy to discuss good design choices with you, and you should also feel free to discuss these choices with your classmates. Practically speaking, it is ok for routines to simply exit if they encounter a rare and difficult corner case---as long as it does not interfere with successful operation of the program (i.e., if it does not crash or yield bizarre behavior). Your main goal here above all else should be to develop effective tool for modeling, rendering, and animation.

Getting started

The basic code skeleton will be distrbuted via Git. This skeleton includes basic functionality (e.g., file loading/saving, a graphical user interface, etc.), but the core software features have been removed. You can find the repository for this assignment at https://github.com/15462-f16/Scotty3D. If you are unfamiliar with git, run

$ git pull

to get the updated code base, or, if you prefer, run

$ git clone https://github.com/15462-f16/Scotty3D.git

to start with a new copy. You will have to manually merge your code for A2 if you do git clone. If you are unfamiliar with git, backup your work.

Build Instructions

In order to ease the process of running on different platforms, we will be using CMake for our assignments. You will need a CMake installation of version 2.8+ to build the code for this assignment. The GHC 5xxx cluster machines have all the packages required to build the project. It should also be relatively easy to build the assignment and work locally on your OSX or Linux. Building on Windows is currently not supported.

If you are working on OS X and do not have CMake installed, we recommend installing it through Macports:

sudo port install cmake

Or Homebrew:

brew install cmake

To build your code for this assignment:

Create a directory to build your code:

$ cd Scotty3D && mkdir build && cd build

Run CMake to generate makefile:

$ cmake ..

Build your code:

$ make

Install the executable:

$ make install

Windows Build Instructions

We have a beta build support for Windows systems. You need to install the latest version of CMake and install Visual Studio 2015 from CMU Dreamspark web store. After installing these programs, you can run runcmake_win.bat by double-clicking on it. This should create a build directory with a Visual Studio solution file in it named Scotty3D.sln. You can double-click this file to open the solution in Visual Studio.

If you plan on using Visual Studio to debug your program, you can change scotty3D project in the Solution Explorer as the startup project by right-clicking on it and selecting Set as StartUp Project. You can also set the commandline arguments to the project by right-clicking scotty3D project again, selecting Properties, going into the Debugging tab, and setting the value in Command Arguments. If you want to run the program with the default cube file, you can set this command argument to ../../cube.dae. After setting all these, you can hit F5 to build your program and run it with the debugger.

If you feel that your program is running slowly, you can also change the build mode to Release from Debug by clicking the Solution Configurations drop down menu on the top menu bar. Note that you will have to set Command Arguments again if you change the build mode.

Using the Scotty3D App

When you have successfully built your code, you will get an executable named scotty3d. The scotty3d executable takes exactly one argument from the command line. You may load a single COLLADA file by specifying its path. Initially we have provided only a simple cube mesh cube.dae, but as you develop the software you will be able to create (and save) more and more interesting surfaces. You can load the cube from the build directory by running

./scotty3d ../cube.dae

See more in the User Guide on Github, Scotty3d UserGuide.

Note that since most of the features of Scotty3D have not yet been implemented, you may encounter occasional unexpected behavior (even crashes!). Your goal is to replace these blank routines with stable implementations.

More on .dae files

For this assignment, lighting is important. The cube.dae file does not have lights. The application by default adopts ambient light for .dae files with no lights.

More .dae files coming soon...

Handin Instructions

Your handin directory is on AFS under:

/afs/cs/academic/class/15462-f16-users/ANDREWID/asst3/

Note that you may need to create the asst3 directory yourself. All your files should be placed there. Please make sure you have a directory and are able to write to it well before the deadline; we are not responsible if you wait until 10 minutes before the deadline and run into trouble. Also, you may need to run aklog cs.cmu.edu after you login in order to read from/write to your submission directory.

You should submit all files needed to build your project, this includes:

• The src folder with all your source files

Please do not include:

• The build folder
• Executables
• Any additional binary or intermediate files generated in the build process.

You should include a README file (plaintext, MarkDown, or PDF) indicating which features you chose to implement, including any features implemented for extra credit. You should also briefly state any other issues the grader should be aware of.

Do not add levels of indirection when submitting. And please use the same arrangement as the handout. We will enter your handin directory, and run:

mkdir build && cd build && cmake .. && make

and your code should build correctly. The code must compile and run on the GHC 5xxx cluster machines. Be sure to check to make sure you submit all files and that your code builds correctly.

Evaluation

Your code must run on the GHC 5xxxx cluster machines as we will grade on those machines. Do not wait until the submission deadline to test your code on the cluster machines. Keep in mind that there is no perfect way to run on arbitrary platforms. If you experience trouble building on your computer, while the staff may be able to help, but the GHC 5xxx machines will always work and we recommend you work on them.

The assignment consists of a total of 100 pts. The point breakdown is as follows:

• Task 1 Generating Camera Rays: 5
• Task 2 Intersecting Triangles and Spheres: 15
• Task 3 Implementing a Bounding Volume Hierarchy (BVH): 20
• Task 4 Implementing Shadow Rays: 10
• Task 5 Adding Path Tracing: 15
• Task 6 Adding New Materials: 20
• Task 7 Infinite Environment Lighting: 15

To avoid complication, we will primarily run your code on meshes that were given to you and/or the ones used in Developer Manual.