Assignment 001

Overview

In this class, you will be using C++ to write a ray tracer largely from scratch. To help you get off the ground, however, we provide you with some base code: The Dartmouth Introductory Ray Tracer, or DIRT, developed by Wojciech Jarosz as a modified version of the Nori educational ray tracer

DIRT is a minimalistic skeleton for a ray tracer, written in C++. It runs on Windows, Linux, and MacOS and will provide the foundation for the programming assignments we'll be doing in this class. While DIRT cannot (yet) produce images, it provides many features that would be tedious to implement from scratch, including:

A JSON-based scene file loader
A command-line interface with option parsing, colorful text output, and a text-based progress bar for long operations
Basic color/vector/matrix/ray/bounding box classes
A pseudorandom number generator ([PCG32](https://www.pcg-random.org/))
Support for loading and saving images in a variety of formats
A loader for Wavefront OBJ files
A basic acceleration structure that will let you ray trace scenes with many primitives reasonably quickly
In the first few assignments, you will fill in empty methods left in the base code, and test them using the tools provided with each assignment. In latter assignments, you will need to figure out what functions and classes you will need to add to the code to accomplish the tasks.

In this assignment, you will learn the basics of how to setup your programming environment, how to get the Dirt base code, and how to submit your solutions. There is no grading or deadline for this assignment. This assignment is not difficult to do, and its only intention is to make sure you have a working development environment.

Tasks

By the end of this assignment, you will have

• Setup a repo with basecode using Github Classroom

• Setup your programming environment and successfully compiled the basecode

• Completed both parts of the programming assignment, explained below

Permissible sources of information

Beyond lecture material, we will rely on two different books for this class.

Firstly, we will be using Peter Shirley's excellent and very accessible "In One Weekend" series of mini e-books. These "books" are short, fun and informal – more like blog posts than textbooks – and are a great way to get started on this exciting topic. Peter Shirley walks through the implementation of a fully operational, though simple, ray tracer. You can and should read through these books and the contained implementation. However, the full source of the ray tracer described in the book is now also available online. We ask that you do not read/copy-paste the source code directly, but instead read the books. We are firm believers that you should actually go through the process of writing the code yourself. Beyond the obvious academic integrity issues, you are also unlikely to learn much by copy-pasting. Furthermore, since we build off of DIRT in this class, the code bases and design decisions will deviate from those in the books, so you will ultimately need to write your own code to complete the assignments.

On the other end of the spectrum, we will be also be using "Physically Based Rendering, Third Edition: From Theory To Implementation" by Matt Pharr, Wenzel Jakob, and Greg Humphreys. This is a big (sometimes intimidating) textbook, with all the mathematical details you will need to dive deep into a rendering topic. We will use this as a reference to complement the Shirley mini-books and lecture.

The first few assignments will largely mirror the concepts in Shirley's three mini books, but as the quarter progresses, we will introduce more and more concepts from the Pharr et al. book. Our hope is that this combination will get you started making images quickly, but by building off the DIRT basecode, and following the design suggestions we incorporate from PBR, you will end up with a much more general and full-featured render than the one in Shirley's books alone.

You are also welcome to consult additional references when completing projects, but remember to cite them in your writeup. Remember, when asked to implement feature X, we request that you don't go and read the source code of the implementation of X in some other renderer, because you will likely not learn much in the process. The official course textbooks are excluded from this rule. If in doubt, get in touch with the course staff.

Obtaining the base code

The base code for this class is provided as a git repository. git is a version control system that allows you to keep track of changes in your code over time, collaborate with other people, track down bugs and more. git is the most widely used version control system today, and this is a good opportunity to learn it if you haven't already.

In this class, you will use git to obtain new and updated versions of the base code. During assignments, you will edit your own local copy of the base code. If we hand out new assignments or add improvements to the base code, git allows you to obtain the updated code and merge it with your local copy without losing your changes.

git is a versatile tool and allows you to achieve more than just obtaining new code from us. If you want to know more, a few external resources we can recommend are try git, git-the simple guide, the git immersion tutorial, and the extensive free Pro Git ebook.

Before proceeding to the rest of this section, you need to install git. Please see the first chapter of the git book to find installation instructions for your system.

Git Setup

You will setup from github classrooom to get: [email protected]:cmu-15-468/dirt-s23-KokeCacao.git

$ git remote add upstream https://github.com/cmu-15-468/dirt-s23    // add base repository upstream
$ git pull upstream main --allow-unrelated-histories    // pull updates from the base repository

Accessing Scene Files

To download scene file, go to cmu-15-468 repository. You will find a template .tar.gz and a scene files .tar.gz.

Submitting Assignments

Your report should use the template provided in report/pa#/report.html where # is the assignment number.

You will submit your code and report by tagging a commit in your repository and creating a release. When submitting, follow these steps:

1. commit all of the changes you want to include in your submission
2. tag and push the commit you want to use as assignment-#-submission
3. zip your report including all rendered images and create a release on Github that includes your report

$ git add -A
$ git commit -m "assignment-#-commit"
$ git push

Once your commit is ready, next you need to create a tag and push it to your remote branch.

$ git tag assignment-#-submission
$ git push origin assignment-#-submission

The last step when submitting is to create a release and add a zip of your report directory to the release. Note that the report directory should contain all of your rendered images. From the root directory of your codebase you can use the tar command to zip your repo

$ tar -czvf report-pa#.tar.gz report/pa#

Finally, publish your release and go to your release page to verify that your release has been created. We will use the timestamp on the release to check whether your assignment is submitted on time. You're free to update your release or change it up until the submission, we will grade the most recent release.

Updating a Tag

You may want to update or change a tag at some point. To update a tag, follow these steps:

1. delete the existing remote tag
2. tag your desired commit as assignment-#-submission
3. push your new tag to your remote

$ git push origin :refs/tags/assignment-#-submission
$ git tag -f assignment-#-submission
$ git push origin assignment-#-submission

You can alternatively specify the commit you'd like to tag instead of using your latest commit.

$ git tag {COMMIT_ID} assignment-#-submission

Build Error Penalty

Code submitted with your assignment must be possible to compile and run on a standard Linux environment (e.g., an Ubuntu or Debian distribution with g++ and libstdc++ installed, but no other specialized packages). If your code does not compile, you will receive a 5% penalty and your assignment will not be graded until you can fix the compilation errors. This is important, as we will need to compile and run your code to verify that it is generating the images you submit in your report.

A high-level overview of DIRT

The dirt repository consists of the base code files (first table) and several dependency libraries (second table) that we briefly explain below.

Directory	Description
src/	A directory containing the main C++ source code
include/dirt	A directory containing header files with declarations
CMakeLists.txt	A CMake build file which specifies how to compile and link Dirt
scenes/	Example scenes and test datasets to validate your implementation
ext/	External dependency libraries (see the second table)
ext/CMakeLists.txt	A low-level CMake build file which specifies how to compile and link Dirt and its several dependency libraries. You probably won't have to change anything here.

Directory	Description
ext/pcg32	A tiny self-contained pseudorandom number generator
ext/filesystem	A tiny self-contained library for manipulating paths on various platforms
ext/json	A JSON parsing library for C++
ext/tinyformat	Type-safe C++11 version of printf and sprintf
ext/stb_image	For loading and saving images

Programming Assignment

For the programming part of this assignment, you will need to familiarize yourself with the basecode that we provide and implement a few tiny changes to make things work.

Go ahead and open up src/00_dirt_tutorial.cpp. This is the file you will be editing for this assignment.

Don't be overwhelmed by the size of this file - the majority of it is comments and functionality provided by us to test your code.

Part 1: Vectors

For the first part of the programming assignment you need to learn how to use vectors and matrices in DIRT. Head over to void testVectorsAndMatrices() and read the comments to get started. Everything that you need to change has been marked with a TODO comment.

Part 2: Colors and Images

Head on over to void testColorAndImage() and read through the instructions. Everything that you need to change has been marked with a TODO comment.

You will generate and write a gradient.png image, that should look something like this:

To complete the last part of the function, you should load the image in scenes/00_preliminaries/cornellbox.png that comes with the base code, convert it to grayscale (as described in the code) and save it under scenes/00_preliminaries/cornell_grayscale.png. The input image is shown below on the left; the expected output is shown on the right.

What to submit

There is nothing to submit for this assignment, this assignment is intended to get you set up and ready to work on assignment 1.