Getting Started

Before you approach a computer

Before you even approach a computer to start coding, make sure that you do the following:

Setting up your account

When you are ready to start coding, and after you have settled on project partners, it's time to start developing your project. To this end, set up your account by following the steps below:
  1. Log on an epic.

  2. If you plan to work with a partner, make sure you have an AFS account. To this end, type 
    printenv HOME
    If the reply starts with /afs/, proceed to the next step; otherwise, contact Distributed Computing Consulting and ask them to incorporate your account under the AFS hierarchy.

  3. cd to the directory which should be configured to contain your project subdirectory.

  4. Make sure you have at hand the logins of your partners, if any.

  5. Type 
    /afs/ir.stanford.edu/class/cs161/97summer/project/do setup
    and follow the instructions on the screen.
Your account is now ready. In the newly created subdirectory cs161_project, you will find these files and subdirectories:

Starting to write code

In the files src/octree.h and src/vrender.h, you will find a complete description of the interface by which your octree implementation should abide, as well as documentation on our provided supporting code. The following outline describes how your code and ours interact:
  1. Our code loads a raw volume (i.e. a volume in a 3D array representation) from disk.

  2. Our code calls your BuildOctree() function once and only once, sometime before it invokes any other octree operations.

  3. BuildOctree() creates the octree, and stores it in variables local to your implementation (i.e. static within octree.c or octree.cc). In the process, it reads, but does not modify, the global variables set by our code; it does this either directly (e.g. reading VarianceLimit or Size) or via macro calls to our code (VOXEL()).

  4. When your implementation returns from BuildOctree(), our code will do one of the following:

    As discussed in the provided src/octree.h, your code may call our exported functions and macros, declared in src/vrender.h, and read, but not write, our exported global variables.

Rendering a volume

When you invoke the executable vrender with the -tst r command-line argument, it renders a volume from one or more viewpoints. This rendering process is controlled by the following parameters, which you must supply to the standard input of vrender:
  1. The base name of the output image files. The name of each generated image file will be the base name, followed by a three-digit number (from 000 onwards), and ending with the extension .pgm, identifying the image file format. Example: with a base name of horse, the first image will be saved in horse000.pgm, the second in horse001.pgm, etc.

  2. The image scaling factor and size. You have two options:

  3. The maximum traversal depth. Instead of supplying this number directly, you supply a number R (the depth reduction), from which MaxDepth is computed as log2L-R. In words, you specify at which height over the leaves of a complete octree OctreeTraceRay() should prune its traversal.

  4. A sequence of viewpoint positions. The coordinate system used to define each viewpoint position is shown below:

    You supply pairs of values for phi and theta, in degrees, one pair per viewpoint. Caution: the coordinate system in the figure above is rotated relative to the coordinate systems in all other figures.

Although it is not necessary to invoke vrender manually to render images (see below), if you choose to do so, you will find helpful the vrender command-line arguments. Type 
vrender -help
to get a list of the command-line arguments that vrender recognizes. In short, Also, if you want to avoid typing the same rendering parameters time and again, use the /usr/bin/echo command (which is not the same as the echo command of the shell); for example, 
/usr/bin/echo 'image\n64\n200\n0\n90\n0\n' | \
vrender -tst r -var 0 \
-vol /afs/ir.stanford.edu/class/cs161/97summer/project/data/sphere64.vol.gz
renders a frontal view (phi is 90, theta is 0) with scaling factor 64 of the sphere demo volume with L=64, using an octree with lossless compression and no depth reduction, and storing the result in the 200 by 200 image file named image000.pgm.

You can render a volume without ever invoking vrender manually; just run do image or do movie, instead. Both use the executable vrender present in your cs161_project directory, so if you want to use the demo executable, you must copy bin/vrender into your cs161_project directory first.

do image allows you to set the viewpoint in a simpler, but more limiting, way than vrender: you just form a combination of the first letters of the words "over", "under", "left", "right", "front", and "behind" (see the above diagram) to position the viewpoint relative to the volume. Caution: the human and orangutan volumes are oriented in a nonstandard manner, i.e. "over" etc. yield unintuitive results when you render these volumes.

do movie creates a collection of images, with the viewpoint always lying on the x-z plane, and slowly rotating about the y axis towards increasing theta. To turn your image sequence into an MPEG movie file, follow the steps below:

  1. Log on a fast Silicon Graphics workstation; there are 18 of them in the basement of Sweet Hall (named firebird1 through firebird18).
  2. Convert the movie frames, one at a time, into the Silicon Graphics rgb image format using the pnmtosgi program. We recommend you write a script to do that for you: it's an awfully tedious process.
  3. Assemble your images into an MPEG movie using the mediaconvert program.
  4. Finally, you may use movieplayer to playback and preview your movie.

Compiling and debugging

When you have written some code and you are ready to try it out, just type 
do compile
in your cs161_project directory. If you get the infamous error 
do: Command not found.
add the current directory . - just a single period - to your path definition in your ~/.cshrc file.

The above command compiles your code, generating two executables, both in the same directory:

  1. vrender_d, which can be subjected to debugging using dbx or gdb, and
  2. vrender, which is fully optimized, and which do uses to evaluate your implementation.
Once you've successfully compiled your code, execute do test to run a few simple correctness checks on your code. For the most part, do test runs your implementation and ours side by side; whenever the two implementations produce different results, do test prints a failed message and exits. Here is some advice to heed as you develop your code:

Performance tuning

Having debugged a basic implementation of your octree management code, you are ready to start evaluating and improving the performance of your code. To this end, first compile your code. Then, run do image to render a volume from a viewpoint of your choice, and save the result in an image file; you can view this file by typing xv followed by the file name. The full pathname of xv is 
/usr/pubsw/X/bin/xv
just in case your file search path is nonstandard. Your code's performance is reported on the line starting with Rendering....

To assess the performance of our implementation and compare it to yours, execute our demo executable using do image, as outlined earlier. The reason we are not giving you any performance numbers is that the load on Sweet Hall machines varies a lot from minute to minute, due to the presence of multiple users on a single workstation. For your information, your code will be graded on an epic running in single-user mode, so load variations will not cause unfairness in grading.

Your code will be graded using our grading version of the do script, which compiles your code using our provided Makefile. No other optimization flags - besides those in our Makefile - will be used for compiling and linking your code during grading. Also, we will measure your performance using several different variance limits, maximum traversal depths, and volumes (not all of which were given to you as demo volumes).

Before you start optimizing your code, make sure you have written a good, reliable, debugged version first. It's true that optimization may introduce new bugs, but having a working version is crucial to getting a good grade: after all, optimization is only worth 5 points, while correctness is worth a lot more. One cautionary note for die-hard hackers: inline assembly, although allowed, is probably a waste of time since

Still, providing reasonable hints to the compiler, e.g. via clever loop reordering or using the register qualifier, is a good compromise between the competing attitudes "the compiler knows it all" and "the compiler knows scrap". For tips on code optimization, we recommend the following sources:

Non-standard development

If you want to develop your code on any other platform, or with the aid of tools beyond the ones described above, you are on your own. Here are some hints to help you get started; recall that, no matter how you develop your code, you must submit code that compiles and executes - producing correct results - on an epic, using our do script:
© 1998 Apostolos Lerios