GENRAY(1) UNIX System V GENRAY(1)
NAME
genray - a generic raytracer
SYNOPSIS
genray [ -s ] [ -geom WidthxHeight ] filename
DESCRIPTION
Genray is a simple raytracer. It supports scenes composed of
a limited range of basic objects and objects defined by
Constructive Solid Geometry (CSG) over these basic objects.
Surface attributes may be attached to each object, and
reflective and transparent objects are supported. A very
limited form of texture mapping is available.
The program reads input files in the format specified below,
and produces either tiff or ppm format files, depending on a
compile time option. Normally the program will display a
greyscale image of the scene being traced, but this can be
suppressed with the -s option. The output file is in 24-bit
colour.
OPTIONS
-s Silent operation. No runtime image will be displayed
and the file will be automatically saved.
-geom WidthxHeight
Render the image in a window of the given dimensions.
The image generated will also have these dimensions.
Command line dimensions override those given in the
input file.
FILE FORMAT
The file is passed through cpp first, so #define and
#include are allowable. In fact, any C preprocessor direc-
tive will work, but you can't pass the preprocessor any
options, so -I is out. Comments are C style /* */.
The following keywords are allowed in the input file. Argu-
ments are shown enclosed in <>, options in []. A vector is
a sequence of 3 numbers, eg: 1 2.5 -3.2. A string is a
sequence of characters enclosed by double quotes eg:
"string". A colour is a vector with elements between 0 and
1. An instance modifier is one of the keywords: scale,
rotate, translate, colour, diffuse, specular, reflect,
refract, transparency, pixmap. The seperator is any number
of spaces, tabs or newlines. All commands are case insensi-
tive, but strings are case sensitive.
lookfrom <vector>
The location of the eye in the world. All rays are cast
from this point. The default is 10 0 0.
Page 1 (printed 9/14/94)
GENRAY(1) UNIX System V GENRAY(1)
lookat <vector>
The center of the scene in the world. This point will
appear at the center of the final image. The default is
0 0 0.
lookup <vector>
A vector defining the up direction in the world. This
vector will always appear to be vertical in the scene.
The default is 0 0 1.
eyedist <float>
The distance that the viewplane is from the eye. This
influences the amount of perspective in the scene -
shorter eye distances give more pronounced perspective
effects. Shorter eye distances also give a wider field
of view for a given window size. The default is 10.
window <horiz_float> <vert_float>
The size of the viewing window in the world. This is
NOT the size of the image to be rendered, rather an
indication of how much of the scene you wish to see.
This, combined with the eye distance, determines the
field of view of the scene. Note also that the window
proportions should match those of the scene size, or
the image will be distorted.
screen <x_int> <y_int>
The size of the final image in pixels. This is also the
size of the window that the scene will be rendered into
(if not silent). It is overwridden by the -geom command
line option. As mentioned for window, the window and
screen proportions should match.
ambient <colour>
Defines the colour of the ambient light in the scene.
This light, scaled by the diffuse coefficient, contri-
butes to the final colour of every object, regardless
of whether or not it is shadowed.
light position <vector> colour <vector> end
Defines a light source in the scene, at the given posi-
tion with the given colour. All defined sources are
point sources (they radiate in every direction). Light
sources do not themselves appear in the scene, they
only illuminate other objects.
set <instance_modifiers> end
Set the object attributes for the following objects.
Translate, scale and rotate can not appear in the list
of modifiers. The given attributes will be used for all
objects up to the next set statement. Modifiers not set
inside the set statement will retain their previous
Page 2 (printed 9/14/94)
GENRAY(1) UNIX System V GENRAY(1)
values.
name <string> <object_definition>
Define an object with the given name. Such an object
WILL NOT be instantiated until an instance statement is
found. The defined object can have all the things a
normal object has. It is most useful for defining CSG
objects.
instance <string> <instance_modifiers> end
Creates an instance of the object named by a previous
name statement. The instance can be further modified
as desired.
cube [instance_modifiers] end
Creates a cube. It initially has corners at 1 1 1 and
-1 -1 -1, and has its center at the origin.
sphere [instance_modifiers] end
Creates a sphere centered at the origin with radius 1.
cylinder [instance_modifiers] end
Creates a cylinder with radius 1 and height 2, centered
on the origin.
cone [instance_modifiers] end
Creates a cone, with base radius 1, base center 0 0 -1
and point at 0 0 1, centered on the origin.
torus [radius] [instance_modifiers] end
Creates a torus with tube radius 1, mean radius radius,
centered on the origin with central axis 0 0 1. The
default mean radius is 2.
square [instance_modifiers] end
Creates a square, with corners 1 1 0 and -1 -1 0, lying
in the X-Y plane.
plane [instance_modifiers] end
Creates an infinite plane initially coincident with the
X-Y plane.
union <instance> <instance> [instance_modifiers] end
intersection <instance> <instance> [instance_modifiers] end
difference <instance> <instance> [instance_modifiers] end
Creates a CSG union, intersection or difference of the
2 instances given. Further modifiers may be applied to
the resulting object. CSG instances can be arbitrarily
nested ie you can take the intersection of 2 unions.
Difference takes the second instance away from the
Page 3 (printed 9/14/94)
GENRAY(1) UNIX System V GENRAY(1)
first.
scale <vector>
Scale the object by in the x, y and z directions by the
corresponding x, y and z components of the vector. 0
values in the vector will result in singular matrices
and halt the program. All scaling is relative to the
world axes, so scaling after rotation will actually
shear the object. Scaling is cummulative, so scale 2.0
3.0 4.0 followed by scale 1.0 1.5 3.0 is the same as
scale 2.0 4.5 12.0.
rotate <axis> <angle>
Axis is one of the characters x, y or z. Rotate the
object about the indicated axis by the given angle in
degrees. Positive rotation corresponds to anti-
clockwise motion about the axis using a right handed
frame. Rotation is always about the center of the body
ie rotation about an axis parallel to the given axis
passing through the center of the body. Rotations, like
scaling, are cummulative.
translate <vector>
Translate the object by the given amount. translations
also are cummulative.
colour <colour>
Set the object's basic colour. The default is 1 1 1
(white).
diffuse <float>
Set the diffuse reflection coefficient of the object to
a value between 0 and 1. Diffuse lighting for non-
shadowed light sources contributes diffuse coefficient
times colour times cos of the angle between the surface
normal and a vector to the light source to the total
colour of the object. The default is 1.
specular <float>
Set the specular reflection coefficient of the objec to
a value between 0 and 1. Specular lighting for non-
shadowed sources contributes similarly to diffuse
lighting, but the cos of the angle is taken to the
power of specular coefficient x 100, to produce a small
highlight on the object. The default is 0.
reflect <float>
Set the amount that the object reflects light off other
objects. The default is 0. Having large numbers of
reflective objects slows the trace considerably. Valid
values are in the range 0 to 1.
Page 4 (printed 9/14/94)
GENRAY(1) UNIX System V GENRAY(1)
refract <float>
Set the refractive index of the object. This will have
no effect unless the transparency is non-0. The default
is 1.
transparency <float>
Set the amount of light that passes through the object
to a value between 0 and 1. The light passing through
is refracted according to the refractive index of the
object. The default transparency is 0. Like reflection,
transparent objects slow the trace considerably.
pixmap <string>
This modifier can only be applied to squares and
planes. It takes the given string to be the name of a
ppm format image file. The image is mapped onto the
square or plane, ie the colour for a given point on the
square or plane is based on the colour of the pixmap at
a corresponding point. For squares the mapping is such
that the pixmap will cover the square - the pixmap will
be scaled to make it fit. For planes the pixmap is
scaled into a 1x1 square, then tiled onto the plane. If
the plane is scaled, the image will be scaled by the
same amount. Note that the colour of the point is taken
from the pixmap - all the standard surface modifiers
are then applied to this colour.
BUGS
The torus intersection code is a bit unstable. You may get
dots on the surface of the torus.
If you find any more, tell me.
AUTHOR
Stephen Chenney : stephen@cs.su.oz.au
Page 5 (printed 9/14/94)
