' '

Follow the steps below carefully. If you’re in trouble and I see you haven’t followed these steps, I’ll simply refer you back to this page.

Important

Note that some steps need to be taken by each team member while others should only happen once per team.

1. Cloning the Repository

Due to GitHub issues, the repo does not come with the starter code. This combined with the fact that it’s a group project slightly complicates the setup process.

each team member

  • Go to the GitHub classroom link (see Toledo).

  • Create a new team or pick an existing team.

  • Clone the repository git clone URL.

  • Add the original repo as remote: git remote add upstream https://github.com/ucll-3dcg/student
once per team

If the repo is empty, it means you are the first one of your team to perform these steps and the starter code still needs to be added.

  • Pull in the starter code: git pull upstream master.

  • Push it to your repo: git push.

2. GitHub

once per team

  • Go to your repo’s website.

  • Go to the Projects tab.

  • Create a new project.

  • Name it 'raytracer' (the name is important).

  • As template, use Automated kanban.

3. Issues

Warning

A student reported problems with the next student. I haven’t been able to replicate it on my machine, so I’ll have to experiment on a student’s machine during the next session. If you run into trouble, just skip it for now and keep an eye out for updates.
once per team

Look for a directory named github in your repo’s root. There should be a script named create-issues.sh. Running it will create an issue for each extension on GitHub.

4. Development Environment

4.1. Visual C++

Here, we assume you use Visual Studio together with the Visual C++ compiler (this is the name of the C++ compiler that Visual Studio comes with).

each team member

  • Open the solution file raytrace/raytracer.sln.

  • In the Solution Explorer, click on "Show All Files". Instead of only seeing "Header files", "Resource files" and "Source files" you should get a long list of folders.

  • In the toolbar, pick Release build.

  • Build the project (Ctrl+Shift+B). This creates an executable file raytracer.exe. Locate it; it should be somewhere under a raytracer\raytracer\x64\Release directory.
Important

Do not dare open the project as a folder in Visual Studio.

Important

Really, don’t. We mean it.

Important

You will regret it if you do. We’ll make sure of it.

4.2. GCC

If you wish, you can also use GCC as your compiler. People working on Linux and Mac might prefer this. Realize though that this path requires a bit more technical expertise from you.

each team member

  • Run the script named run-cmake.sh.

  • Depending on which build you are interested in, enter the debug, release or testing subdirectory.

  • Run cmake --build ..
Important

The run-cmake.sh script creates a Makefile based on what .cpp files exist at time of execution. If you add more .cpp files (which you most assuredly will), you will have to rerun this script so that it adds the new files in the Makefile.

5. WIF Viewer

The project (a ray tracer) you will develop during this course outputs graphical data (images and movies.) We could output this data as PNG, JPG, MP4, … but in order to keep things simple, we will use a custom file format named WIF. Since regular graphics software will not be able to open WIF files, we provide you with two options: a WPF-based viewer and a Python one.

viewer

5.1. WPF-Based WIF Viewer

This viewer will only work on Windows.

each team member

  • Clone this repository.

  • Open the solution.

  • Open Configuration.cs.

  • Change RAYTRACER_PATH so that it refers to the raytracer.exe file you just build.

  • Change to Release build.

  • Build (Ctrl+Shift+B).

  • Run (Ctrl+F5).

  • Optional but recommended: pin the application to the task bar so that you can easily launch it.
Important

Some students think they that, in order to run this viewer, they need to open Visual Studio and launch it from there. Please stop this foolishness: compiling C# produces an .exe file, so you can simply launch that. Feel free to copy this file to your desktop, or create a shortcut to it (better), or simply pin it to your taskbar (best).

5.2. Python WIF Viewer

This viewer should work on all platforms, but it’s still very much untested.

each team member

  • Run pip install git+https://github.com/ucll-3dcg/wif.git

6. Where to Start