A guide for CIS 565 students by Patrick Cozzi.
Last updated: September 11, 2016
Presenting your work well is at least as important as the quality of the work itself. The web is full of noise and visitors will quickly move on if you do not grab their attention immediately.
Do not keep the original README.md with our project instructions. Instead, completely rewrite it so it introduces your project to a technical hiring manager or developer. Remember, things that are obvious to you might not be obvious to them so provide enough background and context.
The README.md should start with a title, followed by your name (with a link to your website, twitter, blog, etc. with your contact info), and then a representative image of your work. Including an image like this has been tradition in SIGGRAPH and many other graphics venues for years. Here's some good examples:
- GPU-Accelerated Dynamic Fracture in the Browser by Jiatong He and Kai Ninomiya
- Surface Mesh Reconstruction from RGBD Images by Collin Boots and Dalton Banks
- Accelerated Stochastic Progressive Photon Mapping on the GPU by Ishaan Singh, Yingting Xiao, and Xiaoyan Zhu
Here's the photon mapping image:
The image should be representative in that it highlights the breadth and depth of your work. It should be your favorite showpiece. Make sure the resolution is reasonable so it downloads quickly. Do not use bmp files; use png or jpg.
Show. Don't tell.
Use screenshots with captions to build up the features in your project. For example, see:
- WebGL Interactive Water by Binglu Du and Xingjie Ma
In this project, each feature is highlighted with a screenshot (animated gifs actually work quite well here). Scroll down to the Water Simulationn section where they introduce the components of the fluid simulation with screenshots starting with just the height map and then building up to object interaction.
The representative image for Surface Mesh Reconstruction from RGBD Images also nicely builds up its features and pipeline:
In addition to screenshots that highlight each feature, it is illustrative to annotate a representative image, perhaps even the representative image. Point out each feature like Kai Ninomiya did in his GPU path tracer:
I know the caustics and Fresnel are obvious to you, but they are not obvious to everyone.
Debug views are useful while developing, but they are also really useful to explain how your project works. A few good examples are:
- GPU Ray Tracer by Collin Boots
- Deferred Shader by Cheng-Tso Lin
- Uniform grid and kd-tree in CUDA by Jeremy Newlin and Danny Rerucha
In Collin's ray tracer, the following screenshots show distance to the closest surface, normals, and oversampling.
For a deferred shader, it is insightful to show each texture in the g-buffer like, for example, the depth and normal buffers in Cheng's deferred shader:
For some projects, the only visual output will be debug views. In Jeremy and Danny's spatial data structure project, this screenshot shows nearest neighbor search:
It is instructive to highlight features by showing side-by-side screenshots, one with the feature and one without. Some good examples are:
- Deferred Shader by Collin Boots
- GPU Path Tracer by Wei-Chien Tu
Here's the bump mapping screenshots in Collin's deferred shader:
The first screenshot shows the bump map itself, the second is the surface shaded without the bump map, and the third is the surface shaded with the bump map clearly showing the additional detail.
Here's the anti-aliasing screenshot in Wei-Chien's path tracer:
Wei-Chien also included a description and image that presents the implementation:
Recall that your audience is not me nor is it the teaching assistant; it is technical hiring managers and developers. Therefore, it is useful to target a broad audience.
Similar to side-by-side feature comparisons, it is also instructive to tweak key parameters and take multiple screenshots to show the effect of the parameter. For example, here are two screenshots showing depth-of-field in Wei-Chien's path tracer. Both have a focal length of 10. The first has an aperture radius of 0.2; the second is 0.5. Note the clear difference in the area out of focus.
To help a broad audience, Wei-Chien also included some details and a screenshot on the algorithm itself:
We all make mistakes while coding. If a bug results in an interesting image, feel free to share it in a bloopers section with a description of what was wrong. For examples, see I Get Your Fail.
If your project uses WebGL, host it using GitHub Pages and have a prominent link to it in your README.md. The representative image can also link to it. Make sure your demo:
- Has a link back to your github repo since people might link directly to your demo.
- Has your name and a link to your website.
- Includes instructions on how to use it.
- Fails gracefully if WebGL or any required extensions are not supported.
- Has a UI to tweak parameters and show debug views (use dat.GUI).
A great example is WebGL Interactive Water.
If you can't provide a live demo or you are using a WebGL extension that is not widely supported, create a video and link to it from the README.md (since we can't embed YouTube videos in markdown files, it can be useful to take a screenshot of the YouTube video before it starts and then use it as a link to your video). Like the demo, the video should include a link to your github repo and personal website for when people link directly to your video. For an example, see Surface Mesh Reconstruction from RGBD Images.
Animated gifs were hot in the 1990's and they have made a come back! Since we can't embed YouTube videos in markdown, another alternative is to create an animated gif using LICEcap, which is very easy to use. Here's an example from Baking Ambient Occlusion in the glTF Pipeline:
Our course is all about performance so each project should include detailed and insightful performance analysis. This includes both the high-level takeaways and graphs and charts with data supporting the claims. Include the details of the system used for performance tests, including the CPU, GPU, amount of memory, OS, and browser and version (if it is a WebGL app).
For running performance tests, see WebGL Profiling Tips. For C++ apps, make sure you are using a release build.
Here's some examples of projects with great performance analysis:
- Uniform grid and kd-tree in CUDA by Jeremy Newlin and Danny Rerucha
- GPU path tracer by Kai Ninomiya
- CUDA Rasterizer by Zhenghan Mei
- Accelerated Stochastic Progressive Photon Mapping on the GPU by Ishaan Singh, Yingting Xiao, and Xiaoyan Zhu
Include concise instructions on how to build your project, including what software is required, e.g., CUDA drivers, Visual Studio, etc. Make building as simple as possible and avoid the need to set environment variables, chase down third-party dependencies, etc.
Read the Elements of Style. Follow its advice and make every word tell. Have someone proofread your README.md.
Up until the final project, we will implement similar projects: path tracer, rasterizer, deferred shader, etc. Each project provides opportunities to develop custom features. Select these based on your strengths and interests and make sure your README.md highlights them.
As a recruiter, I have been to many career fairs where every computer science student told me about the same project. Boring. Differentiate yourself by highlighting what is unique about your work.
- Feel free to rename your fork of the starter-code repo. For example, just because we named a repo
Project6-DeferredShader, doesn't mean you have to. Likewise, feel free to edit the description at the top of the repo page. - Don't clutter the root directory with many files because it will force visitors to have to scroll a lot to get to your
README.md.