Assignment 3 - Raytracing - Due

Apr 11, 2025 11:59 PM

o Spring 2025 CSC 305 A01 A02 X

For this assignment, you will be building a Ray Tracer using C/C++, Python, or Java. The choice of which of these languages is up to you, but keep in mind that language-specific support is not provided. You should use the language you can locally support and are comfortable coding in. The system only needs to handle the rendering of ellipsoids (transformed spheres), with a fixed camera situated at the origin in a right-handed coordinate system, looking down the negative z-axis. Local illumination, reflections, and shadows will also need to be implemented. You must read the entirety of the assignment. There  are several important clarifications/requirements below. There is also a suggested order of tasks for how to tackle this assignment that comes from my personal experience implementing this raytracer multiple times.

The program should take a single argument, which is the name of the file to be parsed. Make sure your executable has the name “RayTracer.exe” (or equivalent for the language you choose) and that we can run it as in the following examples (where " > " is your console prompt):

> RayTracer.exe testCase1.txt

or

> java RayTracer testCase1.txt

or

> python RayTracer.py testCase1.txt

We will use a script. to generate the outputs for the set of posted test cases.

You will get zero marks if we cannot compile your program and if we cannot run this script because your project does not implement the required specifications above.

Make sure you carefully read the Instructions and Clarifications below as they contain important information on the lighting, scene setup, tracing depth etc.

Input File Format

The content and syntax of the file is as follows:

File Content

LEGEND: * integer       ** float(s)                  *** float(s) between 0 and 1

1. The near plane**, left**, right**, top**, and bottom**

2. The resolution of the image nColumns* X nRows*

3. The position** and scaling** (non-uniform), color***, Ka***, Kd***, Ks***, Kr*** and the specular exponent n* of a sphere

4. The position** and intensity*** of a point light source

5. The background colour***

6. The scene’s ambient intensity***

7. The output file name (you should limit this to 20 characters with no spaces)

8. Look at the example files before you ask questions about the format. The included testcases are exactly what we will be testing with.

File Syntax

Do not write the angle brackets, these are to show you where to insert values. See the testcase files!

NEAR <n >

LEFT <l>

RIGHT <r >

BOTTOM <b>

TOP <t>

RES <x > <y >

SPHERE <name> <pos x="" > <pos y="" > <pos z="" > <scl x="" > <scl y="" > <scl z="" > <r > <g > <b> <ka > <kd> <ks > <kr > <n >

… / up to 14 additional sphere specifications

LIGHT <name> <pos x="" > <pos y="" > <pos z="" > <ir > <ig > <ib>

… / up to 9 additional light specifications

BACK <r > <g > <b>

AMBIENT <ir > <ig > <ib>

OUTPUT <name>

All names should be limited to 20 characters, with no spaces. All fields are separated by spaces. There will be no angle brackets in the input file. The ones above are used to indicate the fields. Look at the example files before you ask questions about the format. The included testcases are exactly what we will be testing with.

Output File Format

You should output your images in PPM format. You can choose binary (P6) or text-based ppm (P3). The text-based format is very simple, but it is important to understand the assumptions about which pixel is where (where (0,0) is for  example). Example code for these has been provided in C++ attached to the assignment. We must be able to open your output files in a viewer that is freely available see clarifications below. We suggest using the text-based ppm format for simplicity and debugging.

https:/net p b m.sourceforge.net/doc/ppm.htm l

Marking Scheme

Total Marks: 26

1. [2] Coding Style (i.e. well designed, clean, & commented code with functions)

2. [2] x 12 For each of the given test cases. We will visually verify each and check your code. The name of each test case file is a hint at what we are looking for.

3. [-4 Marks if not] Provide a readme.txt that describes what you have done, what you have omitted, and any other information that will help the grader evaluate your work, including what is stated below.

There will be no partial marks given for a test case if your program fails to parse an input file.

Make sure you submit all the required files so we can compile and build your program. If there are missing libraries, you will get zero marks.

We will use a script. to generate the outputs for a set of test cases. You will get zero marks if we cannot run this script because your program does not adhere to the given requirements. (Repeated for emphasis)

Requirements/Policies

Collaboration

None. If you discuss this assignment with others, you should submit their names along with the assignment material.

Original Work

The assignment must be done from scratch. Apart from the code provided, you should not use code from any other source, including the previous offering of the class. (see clarifications below)

Zero Mark

If the code does not run, no objects appear in the window, or only any  template/given code is running properly, no partial marks will be given.

INSTRUCTIONS AND CLARIFICATIONS

·  Start working on A3 early. You wi l not have time to do it at the last minute.

。TIPS on order. You can go about this assignment in many ways, but after years of writing this ray tracer myself many times it is worth working on it in an order that takes advantage of the positive snowba l effect (build from smaler, clear knowns, testing as you go, toward more difficult problems)

  Work on importing the test cases first. The format is

fixed and we only use the included files so you can keep parsing relatively simple.

  Work on outputting a PPM image given all the RGB

values in an image. Make a simple test for yourself that outputs a white image with a few coloured pixels you hardcode quickly to verify you can output images and   open them.

  Create the outline of the entire program given the

pseudo-code in the slides. It 's best to work through what the expected output is for each of the functions caled so you understand what is going on.

  Write the final RGB lighting equation. At this point, it should just output the defaults from your functions assuming no hits are made.

  Write the sphere intersection code. This takes time to work through. You need to think about using

homogeneous coordinates as a tool for transformations and then not using them as necessary to get correct

intersections. You need to work out how to get normals. Remember the normal on the unit sphere is simple

(intersection point as a vector!), you need to transform  that normal so it is the correct normal after undergoing the transformation applied to the sphere.

  Work on the shadow ray test

  Work on ADS lighting

  Work on your reflected rays

·  Your submission should include ALL of the code necessary to compile and run the program, and should not contain any additional functionality besides what is described here. It should not contain any OpenGL API calls.

·  You may use vector and matrix libraries, i.e. any vector/matrix libraries for C/C++ (e.g. GLM), Java (JAMA, EJML), or Python (NumPy). You cannot use library code that solves any part of the raytracing problem  on its own, you must write this code yourself. It must be clear how to   set up your code, and, if possible, all libraries *must* be included. If we cannot set up your code we cannot mark it.

·  In the assignment attachments, you will find two pieces of example C++ code. One inverts a 4x4 matrix, and the other writes a char buffer  to a ppm image, which is the expected output of this program. You also have an example of inverting a 4x4 matrix and forming the inverse transpose for the normal matrix in your A1 and A2 code in JavaScript.

·  The code included here that inverts a 4x4 matrix expects two 4x4 matrices to be passed in as arguments. The first matrix will be inverted and the result will be stored in the second matrix. Both matrices are row order storage, so you have M[row][column].

·  You may use the STL string and vector classes.

·  The assignment must be done from scratch.

·  Make sure that your parse routine does not crash based on where the EOF character is.

·  Given a reasonable resolution (400x400) on a modern machine, your program should generally take no more than five to twenty seconds (probably less than that) to run when compiled in “release” mode in C++. Interpreted languages, like python, may take longer, but if the files do not return within a reasonable time the case will fail. For interpreted languages, reasonable may be upwards of a minute. NOTE: we are assuming a naive implementation--one without space partitioning or parallelization.

·  A sphere at position (0,0,0), with scaling parameters (1, 1, 1) should be centred at (0,0,0) with a radius of 1.

·  If the eye ray is constructed using the convention described in class, then when intersecting it with an object, the closest object is the one with a minimum hit t greater than 1. A hit t between 0 and 1 falls between the eye and the near plane, and hence is not a part of the view volume.

·  When creating rays from the hit point on an object (e.g. shadow rays and reflect rays), you need to start them at a small value offset along the new ray such as t = 0.000001, (try a larger number like t = 0.0001 if this does not work), to avoid false self-intersections due to numerical errors. A common artifact for this is getting black or dark pixels peppered onto surfaces.

·  For the keys and results, we use the following convention: Rays from the eye that hit nothing return the colour of the background, while reflected rays that hit nothing return black (i.e. nothing).

·  The template code for saving your image to disk uses the ppm image format. If you do not already have a program that can read images of this type, you can download, GIMP (recommended!), IfranView (www.irfanview.com), or Xnviewgb. These are excellent and free programs for viewing images, and can, amongst others, read ppm files.

·  The “NEAR” value is an absolute value and represents the distance along the negative z-axis.

·  Your code may need to handle hollow spheres, which are “cut” open by the near plane.

·  Your code may need to be able to handle lights inside spheres.

·  You will be using the following local illumination model (similar to what we learned in class, apply the ADS lighting to a point assuming reflected rays contribute):

。PIXEL_COLOR[c] = Ka*Ia [c]*O[c] +

for each point light (p) { Kd*Ip [c]*(N dot L)*O[c]+Ks*Ip [c]*(R dot

V)n } +

Kr*Ir

。O i n this case is the object color (<r > <g > <b>)

。Ia is the ambient colour

。Ip is the light colour

。Ir is the colour returned from reflection ray

。the Ks are just coefficients

。N is the normal vector

。L is the light vector

。[c] means that the variable has three different colour

components, so the value may vary depending on whether the red, green, or blue colour channel is being calculated

。 Remember you may need to normalize before using or renormalize vectors after operations with them

·  You should not spawn more than three reflection rays for each pixel, i.e. stop the recursion after 3 bounces.

·  When summing over all lights, it is possible for the PIXEL_COLOR value to go above 1. In this case, the simplest solution is to c lamp the value to 1.

·  Do not forget to scale by 255 before creating the ppm image

。(C/C++) using the given “save_imageP6()” function in ppm.cpp.

“save_imageP3()” is provided for debugging reasons because it produces a human-readable text file. The P6 version produces a binary file. You are welcome to produce the human-readable format for any of the available languages, as long as it can be opened by an image reader listed above.

·  Make sure you submit all the required files so we can compile and build your program. If there are missing libraries, you will get zero marks.

(C/C++) On Linux, we should be able to compile by just typing make “make”, and, on Windows, with MS VS -> Build. Make it clear in your readme how your code is compiled.

·  (C/C++) Make sure that your Visual Studio project is designed to create a “Console Application” or “Command Line Tool”.

·  Make sure that everything works on a standard Windows machine as this is what the la b and TAs support. (However, you should avoid using platform-dependent code, like the Windows API. You do not need it here.)

·  (C/C++) Make sure you “clean” your project before zipping it and submitting it, to remove all the large auxiliary files that VS creates.

·  Make sure you check regularly the forum and the announcements in case the grading or submission instructions change.