csci5607/assignment-1a/ASSIGNMENT.md

# Assignment 1a: Getting Started with Ray Casting

In this assignment, you are asked to begin writing a basic ray casting program.

This program should:

1. read a simple scene description from a file that is provided as a command
   line argument
2. define an array of pixels that will hold a computer-generated image of the
   scene
3. use ray casting to determine the appropriate color to store in each pixel of
   the output image
4. write the rendered image to an output file in ascii PPM format

As with assignment 0, the output file name should match the input file name
except for the suffix. You can also earn extra credit by enabling your program
to render a parallel projection and/or to render not only spheres but also
cylinders.

You are asked to run your program on multiple different input files, featuring a
diverse range of different input parameter settings. One of the objectives of
this assignment is to help you to develop an intuitive understanding of how each
of the various input settings affects the appearance of the rendered scene.
Please be sure to specifically consider these three questions:

- How does the direction of the 'up' vector affect the rendered view of a scene?
  You should specifically consider tipping the 'up' vector from side to side and
  forward to back. You will want to define scenes with multiple objects,
  asymmetrically arranged, to explore this question.
- How do changes in the field of view settings affect the contents of your
  rendered images?
- How do various modifications of the viewing parameters affect the amount of
  perspective distortion apparent in your image?

In subsequent assignments you will be asked to extend the code you write for
this assignment to incorporate additional effects like illumination, shadows,
specular reflections and transparency, with these latter effects being achieved
by recursive ray tracing. Be sure that your code is structured with these
extensions in mind. In particular, you are advised to write simple, modular code
following the example described in class.

Please be sure to check the grading criteria to ensure that all requirements are
understood.

### Detailed instructions

1.  Your program should read the following information from an input scene
    description file (the syntax is shown below each item; entries in italics
    are variables, entries in bold are keywords):

    - The view origin, also variously referred to as the 'eye position', 'camera
      position' or 'center of projection' (a 3D point in space)

          eye   eyex eyey eyez

    - The viewing direction (a 3D vector)

          viewdir   vdirx  vdiry  vdirz

    - The 'up' direction (a 3D vector)

          updir   upx  upy  upz

    - The horizontal field of view (in degrees, please)

          hfov   fovh

    - The size of the output image (in pixel units)

          imsize   width  height

    - The 'background' color (using r, g, b components defined on a scale from
      0-1)

          bkgcolor   r  g  b

    - A 'material' color (in terms of r, g, b components defined on a scale from
      0-1). The material color should be treated as a state variable, meaning
      that all subsequently-defined objects should use the immediately-preceding
      material color

          mtlcolor   r  g  b

    - A sequence of one or more objects. For this assignment, your program is
      only required to be able to handle spheres. In subsequent assignments you
      will be asked to extend your code to handle triangles, so you will want to
      write your code with this future extension in mind. A sphere should be
      defined by the coordinates of its center point (a 3D point in space) and
      radius.

          sphere   cx  cy  cz  r

    - If you would like to attempt the extra credit portion of this assignment,
      please use this format to define a parallel projection

          projection  parallel

    - If you would like to attempt the extra credit portion of this assignment,
      please use this format to define a finite cylinder (without endcaps) that
      is centered at the point (cx, cy, cz) and oriented in the direction (dirx,
      diry, dirz).

          cylinder   cx  cy  cz  dirx  diry  dirz  radius  length

2.  Define an array of sufficient size to store the color values of your image.

3.  Using knowledge of the view origin, viewing direction, up direction,
    horizontal field of view and desired image aspect ratio, define an
    appropriate “viewing window” in world coordinate space, and a 1-1 mapping
    between points within this viewing window and pixel locations in your output
    image.

4.  For each pixel in the output image:

    - Define the equation of the ray that begins at the view origin and passes
      through the corresponding 3D point in the viewing window
    - Then, for each object in the scene:
      - Determine whether the current viewing ray intersects that object, and if
        so at what point or points
      - If there are one or more ray/object intersection points that are 'in
        front of' the view origin with respect to the positive viewing
        direction, determine which of them is closest to the view origin,
        remembering that ray/object intersection points that are 'behind' the
        view origin, with respect to the viewing direction, should be ignored
      - Determine the color of the object at the closest forward ray/object
        intersection point, if there is one, and return that value to be stored
        at the appropriate location in your image array
      - If no ray/object intersection is found, return the background color

5.  After all of the rays have been cast and a color has been determined for
    each pixel in the output image, write the final image to an output file,
    using the ascii PPM format.

You are strongly encouraged to begin with a very simple scene description,
consisting for example of a single sphere located directly in front of the eye
in the direction of view. You are also advised to begin by using a very small
image size, to expedite the debugging process.

To explore the effects of various scene parameters, you are advised to start by
varying the values of just one viewing parameter at a time, such as: the eye
position, the viewing direction, the direction of the 'up' vector, the vertical
field of view, the image aspect ratio, etc. Once you understand the effect of
each parameter in isolation, you should experiment with combinations of changes,
such as: co-varying the field of view and the proximity of the eye to the
objects in your scene. Your ability to appreciate the effects of different view
settings will be improved if you use a relatively complex but intuitively
organized scene, with some asymmetric features and not too much empty space. One
example is: spheres centered at each of the 8 corners of a cube, using different
colors for each corner, or cylinders arranged along each of the 12 edges of a
cube.

### What you should turn in

- All of your source code, clearly commented, plus a ~~readme file with
  compiling instructions or a~~ Makefile or CMake file that the TA can use to
  compile your code.
- One "showcase" image produced by your program, that I can share with the rest
  of the class. To save time for the TA, we would be grateful if you could
  provide this image in a format that is supported for direct display in Google
  Slides or Powerpoint.
- A 1-3 page writeup (including pictures) in which you discuss your observations
  on how the key viewing parameters affect the appearance of the rendered scene.
  Please incorporate sufficient images produced by your ray casting program to
  illustrate and explain your findings. In your writeup, be sure to specifically
  address each of these three points:
  - How does the apparent rotation of the scene with respect to the viewpoint
    change with changes in the direction of the 'up' vector?
  - How do changes in the field of view settings affect the appearance of the
    scene in your rendered image?
  - How can the viewing parameters (e.g. the camera location, field of view
    settings, …) be adjusted to achieve a less exaggerated vs more exaggerated
    amount of apparent perspective distortion in your image?
- Please submit all of the above as a single zip file, containing appropriate
  subfolders, using the naming convention hw1a.firstname.lastname.zip. Please
  do not use tar or rar or any other alternative compression mode that could
  complicate the grading process for the TA.

---

Two sample input files with their corresponding output images are provided in
the Files directory of this Canvas website. Please feel free to use these
examples to partially check the functionality of your program. We will be
testing your code on additional input files.