\chapter{Running Rayshade}

{\em Rayshade}
can take anywhere from seconds to weeks to render an image.  The exact
time spent rendering an image is a function of the speed of the
machine(s) on which
you're working, the complexity of the scene, and how ``good'' you want
the final image to be.

Creating a finished ray-traced image is an iterative process.  Usually, many
test renderings are made at low resolution and with
non-essential features turned off.  After each test image is created,
surface definitions might be modified, the eye or look positions may be
slightly changed, or the intensity of a light source changed.

This chapter describes the basic operation of \rayshade and some of
the options that control that operation.
Setting these options properly can greatly reduce
rendering time, improve the quality of your images, and make you a better
person.

{\em Rayshade} usually works as a filter, reading a description from
the standard input and writing
an image to the standard output.  As it is working, {\em rayshade} reports
on the progress of the rendering by writing messages to the standard
error.

\section{The Input File}

The scene description read by \rayshade consists of a number of
keywords, each followed by a set of arguments.  These keywords can
be thought of as commands that direct rayshade to do various things,
such as create objects, set the eye's position, and change an object's
appearance.

Many of the keywords have related command-line options for turning
on special features and setting values.
These options override the values given in the input file,
and are explained in detail in chapter N.

Rayshade is ``case sensitive,'' which means that typing
``SPHERE'' or ``Sphere'' instead of ``sphere'' won't work.
{\em Rayshade} keywords are all lower-case.  Many people choose to
capitalize the first letter of names that they give to objects
or surfaces in order to make then ``stand out'' in an input file.

Keywords, numbers and strings in the input file are separated by spaces,
tabs, or new lines (carriage returns).  These ``whitespace'' characters
are handled identically by \rayshade, which means that you can separate
keywords from keywords, key words from arguments, and arguments from
arguments by any combination of whitespace characters that you choose.

\begin{table}
\centering
\begin{tabular}{|c|c|l|}\hline\hline
Operator &    Use    & Operation \\ \hline \hline
\verb+^+ &  \verb!a ^ b!  & Exponentiation \\  \hline
\verb+-+ &  \verb! -a  !  & Negation  \\   \hline
\verb+*+ &  \verb!a * b!  & Multiplication  \\  \hline
\verb+/+ &  \verb!a / b!  & Division     \\  \hline
\verb+%+ &  \verb!a % b!  & Remainder    \\  \hline
\verb-+- &  \verb!a + b!  & Addition     \\ \hline
\verb+-+ &  \verb!a - b!  & Subtraction  \\ \hline \hline
\end{tabular}
\caption{Operators, in order of decreasing precedence.}
\label{tab:operators}
\end{table}

Numbers may be entered directly as reals or as parenthesized expressions.
Reals may be written in exponential notation if you wish, and
integers may be written with or without a trailing decimal point.
When an integer value is called for and a real is given,
the real value is truncated and the resulting integer is used.
Table \ref{tab:operators} lists the available operators
available for use in expressions, in order of decreasing precedence.

As a result, the strings
{\tt $42$}, {\tt $42.$},
{\tt $(20 + 22)$}, and {\tt $(7^2 - 7)$} mean the same thing
to {\em rayshade}.

\Rayshade will automatically run the input it receives
through the C preprocessor if it is available.  This
allows you to use C preprocessor directives, such as {\tt \#include},
{\tt \#define}, and {\tt \#ifdef} when designing your input files.

Comments may be included in \rayshade input files by enclosing
text between the strings \verb!/*! and \verb!*/!, as in the C
programming
language.

\section{Images}

The end result of running \rayshade is an image file.  Depending upon
how it was installed, \rayshade writes images in either the Utah Raster
{\em RLE} format or a generic but easily-manipulated {\em mtv} format
used by Mark VandeWettering in his {\em mtv} ray tracer.  The {\em mtv}
format consists of a header giving the resolution of the image followed
by interleaved red-green-blue values for each pixel.  The {\em RLE} format
supports an arbitrary number of color channels,
an alpha channel, comments, a history field, and the ability
to treat images as windows into a larger image.  As a result of this
flexibility, a number of {\em rayshade}'s features
are not
supported if the {\em mtv} format is being used. You are thus strongly
encouraged to obtain a copy of the Utah Raster Toolkit.

If the {\em mtv}
format is used, the image will (and must) consist of three eight-bit
color channels.
If the {\em RLE} format is used, the image file consists of three
eight-bit color channels plus an eight-bit alpha channel.  \Rayshade
also documents in the {\em RLE} header the command line and {\em gamma}
value used in creating the image.

By default, \rayshade writes the computed image to the standard output.
The image file may be written to a file instead by specifying a file name
in the input stream.

\begin{defkey}{outfile}{{\em filename}}
	Write the computed image to the named file.
\end{defkey}
The output file name may also be specified on the command line by
using the {\tt -O} option.

The size of the output image is measured in pixels.  The {\em x} resolution
is the number of pixels left-to-right, while the {\em y} resolution is
the number of pixels top-to-bottom.

\begin{defkey}{screen}{{\em xres yres}}
	Use a screen {\em xres} pixels wide by {\em yres} pixels high.
\end{defkey}
The screen resolution may also be set on the command line through
the {\tt -R} option.
The default
screen resolution is 512 by 512 pixels.

When rendering an image, it is often advantageous to split the image
into a number of disjoint windows, each of which is rendered
on a different machine.  One then combines the images corresponding to
the windows into a final image.

\begin{defkey}{window}{{\em minx miny maxx maxy}}
	Render the image in the given screen subwindow.
\end{defkey}

The window must be properly
contained within the screen, i.e., {\em minx} and {\em miny} must
be greater than or equal to zero, {\em maxx} must be less
than the $x$ resolution of the screen, and {\em maxy} must be less than
the $y$ resolution.
The {\em mtv} format does not support windows.  The Utah Raster tool
{\em rlecomp\/} is useful for reconstructing the full image from
sub-images.
By default, the window
is equal to the entire screen.

{\em Gamma correction} may also be applied to the three output color
channels.  See Chapter N for more details.

\section{Statistics Reporting}

As it is working, \rayshade informs you of its progress by writing
messages to a ``report file''.  By default, the report file is the
standard error.  The report itself consists of a number of
progress reports lines consisting of the number of eye rays traced,
the total elapsed time, and the elapsed time since the last progress report.
The end of the report consists of detailed statistics about intersection
tests performed, the number of rays traced, and the like.

\begin{defkey}{report}{[{\tt verbose}] [{\tt quiet}] [{\em freq}] [{\em file}]}
	Specify the kind of
	information included in the report and to which
	file it should be written.
	If {\tt verbose} is specified, the
	report will also include a listing of the options selected,
	the 
	bounding volumes of each aggregate,
	and the total number of primitives in each aggregate.
	{\tt quiet} causes warning
	messages to be suppressed.  {\em freq} specifies the frequency,
	in scanlines rendered, that progress reports are made.
	If given, {\em file} names a file to which the report
	will be written.
\end{defkey}
By default, a non-verbose, non-quiet report is 
written to the standard error once every 10 lines.
The {\tt -V} option may also be used to direct the report to a named file.

\section{Antialiasing}

Given a screen with a fixed resolution, creating an image is accomplished by
sampling each pixel one or more times in order to determine what can
be seen ``through'' that pixel by the camera.  A pixel then covers
a square area of the image plane, not just a single point.

If a pixel is not sampled at the proper rate, aliasing will result.
Aliasing usually appears as ``jaggies'' or ``stair steps'' in the image.
In order to reduce these and other artifacts, \rayshade provides
two primary antialiasing methods.  Neither method is anywhere close
to the ideal, but the results are usually acceptable.

Adaptive supersampling begins by sampling each pixel at its corners.
The contrast between each color channel of these four samples is
computed, and if too large on {\em any} channel, the pixel is
subdivided into four
square sub-pixels.

This process is recursively applied to each
sub-pixel until the computed contrast is below a designated maximum or
until
the maximum recursion level is reached.  Finally,
contributions of the sub-pixels are appropriately weighted and summed
in order to compute the final color of the pixel.

\begin{defkey}{adaptive}{{\em depth}}
	Adaptive supersampling is used to reduce aliasing in the
	image.  The maximum recursion level is set to {\em depth}.
\end{defkey}
Note that $depth = 0$ causes no supersampling to occur.  {\em Depth}
may also be set on the command line by using the
{\tt -P} option.  The default value is 3.

\begin{defkey}{contrast}{{\em redcont greencont bluecont}}
	Set the maximum allowed contrast between four color
	samples when adaptive supersampling is used.
	The contrast test is applied to each color
	channel separately.
\end{defkey}
The default maximum contrast values for the red, green, and blue
channels are 0.25, 0.2, and 0.4, respectively.

The second antialiasing method is known as {\em jittered} sampling.
In jittered sampling, the location at which a sample is taken is
perturbed by a random amount.  This perturbation reduces aliasing
but adds noise to the image.

Jittered sampling is used in \rayshade to sample extended light
sources as well as to reduce aliasing in the image plane samples.
If adaptive supersampling is being used, the {\tt samples} keyword
controls the number of samples that are taken of
extended light sources per shadow ray.  If jittered sampling is
being used, the {\tt samples} keyword controls the number of
rays that are traced through each pixel.  In this latter case,
a single ray is traced to each extended source per shadow ray.

\begin{defkey}{samples}{{\em n}}
	Use $n^{2} $ samples when performing jittered
	sampling.  The maximum legal value is 5.
\end{defkey}
The default number of jittered samples is $4^{2}$.

\begin{defkey}{jittered}{}
	Use jittered sampling to perform antialiasing.
\end{defkey}
By default, adaptive supersampling is used to perform antialiasing.

\section{The Ray Tree}

When ray tracing a scene, reflected or transmitted rays may strike
other reflective or transparent objects.  Further reflected or
transmitted rays will be spawned, and so on.  Taken together, such
a family of rays is termed the {\em ray tree}.  Care must be taken
to control the depth of this tree:  If it is allowed to grow too deeply,
one may spend a great deal of time computing rays that contribute little
to the final picture; if it is not allowed to grow far enough, this
premature tree pruning may be evident in the image.

{\em Rayshade} provides two complimentary methods for controlling the depth
of the ray tree.  One method sets an absolute maximum for the tree.  The
other allows one to adaptively prune a tree as it grows so that ``unimportant''
rays are not spawned.

\begin{defkey}{maxdepth}{{\em level}}
	Do not spawn rays deeper than those at the given {\em level}.
\end{defkey}
Rays from the eye are of depth zero.  The default value for
{\em level} is 10.
This depth may also be set from the command line through the {\tt -D} option.

\begin{defkey}{cutoff}{{\em threshold}}
	Do not spawn rays whose contribution to the final color of
	the eye ray is less than {\em threshold}.
\end{defkey}
The default value is 0.001.  This threshold may also be set from
the command line through the {\tt -T} option.
