Ray Trace software package, release 3.3.

Author: Sam Buss
Univ. of California, San Diego

Release 3.0  was available as of June 28, 2006, with bug fixes have brought it up to release 3.3.   The main new features, as of release 3.0, are the ability to read .NFF and .OBJ files, and the use of KD-Tree acceleration structures.  There is a new main project RayTraceKd that uses the new features of release 3.0.   Apart from some very minor items, release 3.X is compatible with release 2.0.

This software package accompanies my book 3D Computer Graphics: A Mathematical Introduction with OpenGL (Cambridge University Press, 2003).  It implements a ray tracing package in C++ in an extensible, object-oriented fashion.

Overview: This ray tracing software is written an C++. It contains classes for handling geometric objects, for calculating Phong and Cook-Torrance light calculations, and for tracing rays and determining the intersections of rays with geometric objects.  There is no nice user interface; instead, you have to write C++ code to interact with the RayTracing class library.  Geometric modeling is done by making C++ function calls to create objects and set their properties.  There is source code for high level control of ray tracing, but you probably need to modify this to fit your application.
    Geometric objects supported: (Members of the ViewableObject class): Triangles, Parallelograms, Parallelepipeds (includes cubes and rectangular prisms), Cylinders, Cones, Spheres, Ellipsoids, Toruses, and collections of Bezier patches.
    Texture mapping features: Some support for checkerboard patterns, for texture maps from bitmap files, for bump mapping, and for combining multiple texture maps.  Also some fairly general methods for working with texture coordinates.
    Lighting models: Phong and Cook-Torrance.  The Phong lighting model includes all the standard OpenGL material and light properties.
    Camera:  Orthographic and perspective views supported.
    OpenGL/GLUT previewing:  The scene can be viewed with OpenGL/GLUT before ray tracing is begun.  A convenience for placing objects correctly and choosing the view.  This is new for release 2.0.
    Objects's extents:  Low-level routines calculate bounding planes for objects.  Available for future use in spatial data structures such as BSP trees or k-d-trees or octtrees.   This is new in release 2.0.
    File input:  Scene descriptions may be read from .NFF or .OBJ files (New for release 3.0.)
    KD-tree data structure acceleration.  Substantially improves ray tracing times; for large scenes raytracing is not much slower than OpenGL rendering!  (New for release 3.0.)

The software is distributed with two main programs that were designed mostly for testing purposes, RayTrace and RayTrace2 and RayTraceKd.   These generate the following images:  (Not shown: images from .NFF and .OBJ files as generated by RayTraceKd.)

Image1Small.gif (11070 bytes)     The main program RayTrace generates this image.  In the background, there are two triangles with checkerboard texture maps.  In the center is a largely grayish transparent sphere.  Above the other objects, there is a small blue sphere, and there are several small yellow triangles floating in the air.  A larger version of the image is also available.  The larger version took approximately 9 seconds to generate on a 350 MHz Pentium 3, many few years ago. On my 2006 system it is quite a bit faster.
Image2Small.gif (16120 bytes)     The main program RayTraceKd can be used to generate this rather full second image.  For this, change the "MODE" variable in RayTraceKd.cpp to equal 1 and recompile. There is a back wall (texture mapped with blue and black stripes).  The side walls are triangles and are reflective.  Scattered around the scene are various spheres, tori, cylinders, cones, parallelepipeds, ellipsoids, and Bezier patches.   In the back right corner, there is a curved mirror mounted in the corner --- this is formed from Bezier patches.  For a better look, check out the larger version of the image.  The larger version took approximately 10.5 minutes to generate, again, on 350 MHz Pentium 3 many few years ago. On my 2006 system, it takes about 50 seconds --- the slowness is due to the Bezier surfaces.
    There is also an annotated version of the large image available, if you are trying to figure out what all the different shapes are.
jacks_5_1_thumb.jpg (9.2K bytes)     The main program RayTraceKd can be used to generate the "Jacks-5-1" image shown here.  For this, the "MODE" variable should be equal to 3. For a better look, check out the larger version of the image. This takes about 3 seconds to ray trace on my 2006 system.

Legalities:  You may use this software without restriction.   If you use it for substantial projects or commercial projects, please let me know (recognition of this type is one of the ways us academic types get rewarded.).  In particular, its use should be acknowledged in any publication and in any product.     In addition, if you find or fix bugs, please let me know, so that I can update the software for everyone else.  The software is distributed "as-is", and carries no warranty of any kind.

Software available.  Release 3.3.   To get the software:

  1. Download RayTrace_3.3.zip.   This includes all source files, and Visual C++ .NET project and workspace files.  The main workspace file is RayTraceKd/RayTraceKd.sln .  To start, double click this .sln file.
    The projects and solution files are for Visual C++.NET 2003. Make sure the main project is either RayTraceKd (best) or RayTrace (out of date, but simpler). If you convert to NET 2005 or later, it is possible that the main project or the project dependencies will not be correctly converted. If you have troubles linking the project, you may need to fix the dependencies by hand.
  2. For non-PCs and other compilers: you will have to rebuild the project yourself.  The code uses cross-platform OpenGL commands, so it should compile and run under Unix, Linux and Macintosh systems.   (I could release Unix makefiles, etc., if there is sufficient demand, but lately nearly all downloads appear to be for PC environments.

Documentation:  See appendix B of the above-mentioned book and the Introduction to Upgraded Releases.   Or examine the source code....  (Sorry, that's what is available for now.  Maybe someday I will create better documentation.)

Running the software:  Start with the project RayTraceKd as the main program.   If you make the window larger, it takes proportionally longer for the image to be ray traced. With the new kd-tree acceleration (release 3.X), the ray tracing runs quite quickly. Indeed, for large files, you may find that the ray tracing is faster than the native OpenGL code!.   It is highly recommended that you use an optimizing compiler such as Visual C++'s Release mode when not debugging your code --- this will improve runtimes substantially.  When debugging your code, keep the window very small to get decent run times.

Parallelism. Ray tracing is "embarassing parallelizable" as the phrase goes. Dale Ranta has reported that he has converted the code to be multithreaded with relatively good speed-up. For this he needed to remove the calls that gather statatistics in the KdTree::Traverse routine and gave each thread its own "traverseStack". Ranta reports achieving 3 or 4 frames raytraced per second (720 x 480) on a Quad Macintosh with eight threads. Ranta's code is not available at this web site however.

Acknowledgements. i Thanks to Dale Ranta, Sven-Bertil Blom, Rob Graeyer, Robert Hanson, and Hans Dietrich for bug fixes incorporated into releases 3.1 through 3.3.

History of changes and documentation:  Release 1.0 was the version documented in Appendix B of my book mentioned above.  Release 2.0 added a couple new features including (a) the OpenGL/GLUT previewing and (b) the low level routines for calculating the extents of objects.  Release 3.0 added more features including reading scene descriptions from files and KD-tree acceleration.  More documentation on how to use the new features of Releases 2.0 and 3.0  which are not described in the appendix B can be found in the online Introduction to Upgraded Releases

Detailed release notes:
Release 3.1-3.1.2.
   - Bug fixes and better use of ISO C++ standards, including a number of items found by Dale Ranta and Sven-Bertil Blom.
Release 3.2:
   - Bug fix to VisiblePoints to affected KD-trees using texture maps loaded from bitmap files (diagnosed and fixed by Bob Graeyer)
   - Bug fix to extents calculation of ViewableParallelepipeds (now should work with Kd-Trees).
   - Code cleanup and removing syntax that generated warning messages with GNU C++ reported by Dale Ranta.
Release 3.2b:
   - Two sign errors in Quaternion.cpp, diagnosed and fixed by Robert Hanson.
Release 3.3:
   - Assignment method for Array fixed, with assistance from Hans Dietrich.