\chapter{Range Map Files}

This version of Rayshade can generate not only images, but also Range Maps
(also known as {\em Z Buffers}).  A Range Map is a two dimensional
image, where each pixel is the floating point distance from the image
plane\footnote{The distance is actually measured
from the object to the plane containing
the camera position ({\tt eyep}) that is {\em parallel} to the image plane.}
to the object in the scene.  This is especially useful for generating
synthetic data sets for use in Computer Vision research, e.g. depth from
stereo and shape from shading.  Those techniques all attempt to reconstruct
3D information from 2D images, and having the actual Range Map available
makes a quantitative analysis of the accuracy of reconstruction possible.

Range Maps are rendered for single frames\footnote{The Range Map file
formats do not support animation.} from the same viewpoint used to
generate images, with the same window size and resolution.  To enable Range
Map output, use the {\tt -z} command line option:

\begin{defkey}{-z}{{\em filename}}
	Generate a Range Map (i.e., Z buffer).
\end{defkey}

The format of the file is specified by the filename suffix.  Three formats
are available:
\begin{description}
\item[.hf] \,\, Heightfield Format -- The most compact format, see Appendix
C for a complete description.  This is the default output format.
\item[.txt] \,\, Text Format --  After some opening comments, each line will
correspond to a single row in the image.  Pixel distances on each row are
represented as text (e.g. {\tt 5.45454}) and are separated by spaces.
\item[.etxt] \,\, Expanded Text Format -- After some opening comments, each
line will correspond to a single {\em pixel}:
\begin{quotation}
\em integer X-coord \,\,\,\, integer Y-coord \,\,\,\, float
Distance
\end{quotation}
Since each output line contains information on just one pixel, a blank line
is inserted when the Y coordinate changes (i.e., when the data corresponds
to a new scanline).
\end{description}
In all three formats, a distance of {\tt -1000} is used to represent the
background; this value is unique since all visible objects will have a
distance greater than zero.

Why three formats?  Heightfield Format is useful because it's very compact
and can also be used as {\em input} to Rayshade; Text Format is easier to
process in shell scripts; and Expanded Text Format is just right for quick
displays using the {\em GNUPlot} display tool.

\section{Displaying Range Maps}
There are several ways to display Range Maps.  If you want to see a flat
range image, where intensity corresponds to depth, generate the range map in
Heightfield format.  Then the sequence of commands
in Appendix C will work fine (i.e., {\em hf2gil} together with {\em viewgil}).
You can also use Rayshade itself to display a Range Map, as in this example:

\begin{verbatim}
   light .6 .6 .6 directional 0 0 -1
   light 1 1 1 directional 1 1 -5
   light 1 1 1 directional -1 1 -5
   up 0 1 0
   eyep 0 0 -100   	/* Long focal length */
   lookp 0 0 0
   fov 0.458364		/* Small field of view, to eliminate the
      		   worst of the perspective effects */
   heightfield RANGE.hf translate -.5 -.5 -.5 rotate 0 0 1 180
\end{verbatim}

\noindent But be aware that this is just for display purposes; pixels in
this re-rendered image do not correspond exactly to those in the original
image.

You can also get a more precise plot, with axes labelled, using {\em
GNUPlot}.  Generate the Range Map in Extended Text format, and run it
through this filter to remove the background pixels and negate the depth
values:

\begin{verbatim}
   sed '/-1000/d' | uniq | awk '/#/ {print; next} \
      NF == 3 {print $1, $2, -$3; next} {print}'
\end{verbatim}

Store the output from this filter in some file (e.g., {\tt range.plot}).
Now start GNUPlot and give it the following commands:

\begin{verbatim}
   set parametric
   splot 'range.plot'
\end{verbatim}

\noindent You can change the viewpoint easily in {\em GNUPlot}:  enter
{\tt help set view} at the command prompt for details.