README

CS184 Assignment 2: Raytracer
Wenson Hsieh
Developed and tested on OSX.
Compatibility tested with Unix on the EECS m125c servers (e.g. m125c-11.eecs.berkeley.edu). I intended to use hive, but servers were down and/or cripplingly slow on the week of submission.

vvvvv PLEASE READ THIS! vvvvv

IMPORTANT NOTE - The submission size limit appears to be 10MB, but my original compressed .tar.gz submission was 19MB. As such, I put the two most space-consuming resources, objects/ and textures/, in my public_html/ directory. They should be publicly accessible. Just "cp /home/cc/cs184/fa14/class/cs184-eq/public_html/textures/ /home/cc/cs184/fa14/class/cs184-eq/public_html/objects/ ."

^^^^^ PLEASE READ THIS! ^^^^^

I. The project directory
    - util.h      Contains data structures/helper functions used in other files.
    - parsing.h   Contains functions to parse .scene and .obj files.
    - trace.cpp   Contains functions to create and map view rays to colors. Also contains the main entry point to the program.
    - Makefile    Used to compile the code.
    - objects/    Contains some .obj files used to render scenes.
    - scenes/     Contains the final input-nn, image-nn.png and notes-nn files.
    - textures/   Contains the textures for 3 skyboxes: sky, space and desert.
    - lib/        Contains a bunch of code I didn't write, namely eigen and lodePNG

II. Features at a glance
    A. Basic functionality
        - Sphere and ellipsoid rendering
        - Triangle rendering, specified through .scene or .obj
        - Linear normal interpolation for triangles with vertex normals specified through .obj files
        - Phong shading model
        - Occlusion, shadows, and arbitrary-depth reflections
        - Linear transformations (translation, scaling, rotation)
        - Point and directional lights
        - Output in .png format
    B. Extra features
        - Anti-aliasing with arbitrary sample size
        - Skybox (world) texturing
        - Accelerated intersection tests using global AABB tree

III. Instructions
    - To build, just invoke "make" at the top level of the project (same level as the main source files).
    - To run on a scene, invoke "./trace <scene_name>.scene" to generate a corresponding <scene_name>.png at the same level.
        - "./trace" only accepts a single string argument, which must have a ".scene" suffix.
    - I made some additions and adjustments to the standard scene file format.
        1. "aa <x>" sets the anti-aliasing level to x
        2. "dim <w> <h>" sets the width and height of the generated image to w and h, respectively
        3. "rd <d>" sets the maximum reflection depth to d
        4. "obj <objfile> [-f]" has been tweaked to include an optional "-f" argument that flips vertex order
        5. "bg <texture_suffix> <xmin> <xmax> <ymin> <ymax> <zmin> <zmax> <width> <height>" is used to specify the skybox
            - The <texture_suffix> is a bit tricky. There should be 6 faces corresponding to the sides of the skybox, with each face 1...6 with the ith face corresponding to the file "<texture_suffix>i.png". The faces are numbered as such:
                    1 FRONT
                    2 RIGHT
                    3 BACK
                    4 LEFT
                    5 UP
                    6 DOWN
                Alternately, think of the skybox numbering as an "unrolled cube" texture:
                    |  5    |
                    |4 1 2 3|
                    |  6    |
            - The min/max x, y and z values specify the axis-aligned bounding box for the skybox. This bounding box should enclose all objects in the scene.
            - The <width> and <height> indicate the width and height of each face's image. All 6 images must have the same dimensions.

IV. Sources

    A. Skyboxes
        - http://forum.blockland.us/index.php?topic=207695.0
        - http://www.ehdwalls.com/plog-content/images/1280x800/space/space-art-wallpaper-space-6997700-1280-800.jpg
        - http://quadropolis.us/node/413

    B. .obj files
        - From various links posted on piazza.
        - http://people.sc.fsu.edu/~jburkardt/data/obj/obj.html
        - https://piazza.com/class/hysvdosomfhx?cid=237 for the T-rex

    C. Code
        - Basic split and trim functions copied from stackoverflow posts (see util.h).
        - http://stackoverflow.com/questions/216823/whats-the-best-way-to-trim-stdstring
        - http://stackoverflow.com/questions/236129/how-to-split-a-string-in-c