For this project we define a rudimentary scene graph language. Each command
begins with keyword and goes on until the next command or until the end of the
file is reached. Commands may extend across new-line characters. All numbers
are assumed to be floating point. Angles are given in radians.
tri
mat_id
x1 y1 z1
x2 y2 z2
x3 y3 z3
This command defines a triangle with coordinates (x1,y1,z1), (x2,y2,z2), and (x3,y3,z3).
The triangle will have the material indicated by mat_id,
an index into the list of materials previously defined within the same file.
If mat_id = -1, then no material is assigned immediately, and the surface
will either adopt the material specified with an enclosing begin and end
commands or a default material (gray) if there are no enclosing begin and
end commands.
box
mat_id
low_x low_y low_z
high_x high_y high_z
This command defines an axis-aligned box with corners (low_x,low_y,low_z) and (high_x,high_y,high_z), where high_x>low_x, high_y>low_y, and high_z>low_z.
The box will have the material indicated by mat_id,
an index into the list of materials previously defined within the same file.
If mat_id = -1, then no material is assigned immediately, and the surface
will either adopt the material specified with an enclosing begin and end
commands or a default material (gray) if there are no enclosing begin and
end commands.
sphere
mat_id
center_x center_y center_z
radius
This command defines a sphere with the specified center (center_x,center_y,center_z) and radius.
The sphere will have the material indicated by mat_id,
an index into the list of materials previously defined within the same file.
If mat_id = -1, then no material is assigned immediately, and the surface
will either adopt the material specified with an enclosing begin and end
commands or a default material (gray) if there are no enclosing begin and
end commands.
cylinder
mat_id
center_x center_y center_z
radius height
This command defines a cylinder, with a central axis parallel to the y-axis, and centered at the point (center_x,center_y,center_z). The radius and height are given by radius and height, respectively. The cylinder is a closed surface (i.e. it has end caps.). The ends lie at y=center_y-height/2 and y=center_y+height/2.
The cylinder will have the material indicated by mat_id,
an index into the list of materials previously defined within the same file.
If mat_id = -1, then no material is assigned immediately, and the surface
will either adopt the material specified with an enclosing begin and end
commands or a default material (gray) if there are no enclosing begin and
end commands.
cone
mat_id
center_x center_y center_z
radius height
This command defines a cone, with a central axis parallel to the y-axis, and centered at the point (center_x,center_y,center_z). The radius and height are given by radius and height, respectively. The cone is a closed surface (i.e. it has an end cap on the lower-y-side, and an apex on the higher-y-side). The base lies at y=center_y-height/2 and the apex lies at y=center_y+height/2.
The cone will have the material indicated by mat_id,
an index into the list of materials previously defined within the same file.
If mat_id = -1, then no material is assigned immediately, and the surface
will either adopt the material specified with an enclosing begin and end
commands or a default material (gray) if there are no enclosing begin and
end commands.
mesh
mat_id
meshname
This command includes a mesh into the scene. The file with name meshname is opened (.off, .ray, or .obj), and all the triangles of that file are read and added to the scene graph.
The mesh will have the material indicated by mat_id,
an index into the list of materials previously defined within the same file.
If mat_id = -1, then no material is assigned immediately, and the surface
will either adopt the material specified with an enclosing begin and end
commands or a default material (gray) if there are no enclosing begin and
end commands.
begin
mat_id
m11 m21 m31 m41
m12 m22 m32 m42
m13 m23 m33 m43
m14 m24 m34 m44
... commands ...
end
This pair of commands defines a node that will be added to the current scene-graph with the specified material and transformation context. All geometric primitives within the begin .. and associated end command are subject to the 4x4 transformation matrix given in the begin command, and any such geometric primitive that does not already have a material assigned (i.e., its mat_id was -1) will adopt the material indicated by mat_id (where mat_id is the index of a material in the same file).
Groups may be nested, permitting the specification of a transformation heirarchy. Shapes within nested groups are subject, in order, to the transformation contexts of all their enclosing groups. The total transformation context of a given shape is determined, then, by starting with the matrix of the root enclosing group, and concatenating additional matrices on the right as we decend into nested groups, until we reach the geometric primitives. The transformation context of a group is applicable only to its shapes and sub groups, so we must remove matrices from the right as we ascend back up the heirarchy.
The matrix elements appear as follows and are intended to operate on column vectors:
|m11 m21 m31 m41|
|m12 m22 m32 m42|
|m13 m23 m33 m43|
|m14 m24 m34 m44|
Note: When the .ray file is initially parsed the root scene-graph node is
instantiated with the identity matrix, so that geometric primitives may be specified
in world coordinates outside the context of any begin and end pair.
camera
eye_x eye_y eye_z
towards_x towards_y towards_z
up_x up_y up_z
xfov neardist fardist
This command defines a perspective camera in the scene. (eye_x,eye_y,eye_z) is the position of the camera in world coordinates, (towards_x,towards_y,towards_z) is a vector describing the direction the camera is pointing, and (up_x,up_y,up_z) is a vector in the up direction. The half-width angle of the viewing frustum is given by xfov, and the half-height angle is set based on the image aspect ratio according to yfov = atan(tan(xfov)*height/width), where width and height are the width and height of the output image (given on the command line in raypro or the size of the window in rayview).
The camera command is not required -- a default camera will be computed
if none is present in the file. If there is a camera command,
it must appear before of any begin commands. Also, if there
are more than one camera commands in the file, the last is used,
and the others are ignored.
material
ka_r ka_g ka_b
kd_r kd_g kd_b
ks_r ks_g ks_b
kt_r kt_g kt_b
e_r e_g e_b
n ir texturename
This command defines a material. The first material declared will take the interger identifier 0, and subsequent materials will follow in order (i.e. 1, 2, 3, ...). This integer handle is used in geometric commands later in the file to assign reflectance properties to surfaces. Note that materials have file scope. So, the material indices will not be affected by include commands.
(ka_r,ka_g,ka_b), (kd_r,kd_g,kd_b), and (ks_r,ks_g,ks_b) are the RGB coefficients of ambient, diffuse, and specular specular reflectance, (kt_r,kt_g,kt_b) are the coefficient of transparency (where 0 is fully opaque and 1 is fully transparent), and (e_r,e_g,e_b) is the emmisive color of the material (e.g., if a geometric primitive is a light source).
The exponent n defines the specular 'shininess' of the material, and takes positive values where 0.0 is not shiny at all and 100.0 is very shiny. The cosine of the angle between the ray direction and the specular reflection direction raised to the power of n gives the specular highlight factor.
The index of refraction is given by ir and is used in Snell's Law computations for refraction direction. For non-closed surfaces, such as triangles, it is assumed that ir is the index of refraction on the backside of the surface. For closed surfaces, such as cones, it is assumed that ir is the index of refraction on the inside of the surface.
To assign a texture to this material, texturename should be the
name of an image file, and texture coordinate should be generated for primitives.
At rendering time, it is assumed that the color of the appropriate texture pixel
will modulate the color computed by the lighting equation. If no texture is
to be associated with the material, then a value of 0 must be indicated
for texturename.
point_light
r g b
px py pz
ca la qa
This command defines a point light source in the scene. (r,g,b) gives the color of the light. (px,py,pz) gives the position of the light in world coordinates.
The attenuation of the light with distance from its position is given by ca, la, and qa which define the constant, linear and quadratic components of the attenuation factor. If d is the distance from the light to the surface, then the light's color at the surface is given by (r,g,b) *1.0/ (ca + la*d + qa*d*d). Each coeficient must be positive or equal to zero. Note: to achieve no attenuation use a (ca,la,qa) of (1.0,0.0,0.0).
If no light sources
appear in the file, default ones will be provided by the parser (two directional
light sources). Otherwise, every light source must
appear before any begin commands in the file.
spot_light
r g b
px py pz
dx dy dz
ca la qa
sc sd
This command defines a spot light in the scene. (r,g,b) gives the color of the light, and (px,py,pz) gives the position of the light in world coordinates. In this ray tracer, use this single light color for diffuse and specular contributions at each surface. Do not compute ambient contributions from each light, but rather use the global ambient light defined by the ambient command.
The attenuation of the light with distance from its position is given by ca, la, and qa which define the constant, linear and quadratic components of the attenuation factor. If d is the distance from the light to the surface, then the light's color at the surface is given by (r,g,b) *1.0/ (ca + la*d + qa*d*d). Each coeficient must be positive or equal to zero. Note: to achieve no attenuation use a (ca,la,qa) of (1.0,0.0,0.0).
The direction of the spot light source is given by (dx,dy,dz), and the cutoff angle is given by sc -- i.e., the half angle of divergence of the light cone. It can be measured as the angle from the center axis (dx,dy,dz) to the edge of the spot cone (in radians). The fall off in intensity from the center axis to the cone edge is given by the spot drop-off exponent, sd. So, for a given direction, L, whose angle to the center axis (dx,dy,dz) is less than sc, the light intensity (before attenuation with distance) can be computed by cos(angle)^sd, or equivalently (L dot (dx,dy,dz))^sd. Note that sc should be less than pi/2 radians, and sd can take any positive value, where 0.0 indicated constant intensity across the cone, and 100.0 yields a sharp fall-off.
If no light sources
appear in the file, default ones will be provided by the parser (two directional
light sources). Otherwise, every light source must
appear before any begin commands in the file.
dir_light
r g b
dx dy dz
This command defines a directional light in the scene. (r,g,b) gives the color of the light, and (dx,dy,dz) is a vector describing the direction of the light (it will be normalized by the parser). Since directional light sources do not attenuate with distance, ca, la, and qa are not parameters of this command.
If no light sources
appear in the file, default ones will be provided by the parser (two directional
light sources). Otherwise, every light source must
appear before any begin commands in the file.
ambient
r g b
This command defines the color of ambient light for the scene. For a
ray tracer, it specifies the RGB color that should be added to every illumination
calculation (in addition to the contributions determined for diffuse and specular
reflections from dir_lights, point_lights, and spot_lights. Do not compute ambient
contributions from each light, but rather use the color provided by this
command for the single, global ambient light source.
background
r g b
This command defines the background color for the scene. For a
ray tracer, it specifies the RGB color that should be used for rays that
fail to intersect any object. The r, g, and
b values range from 0 to 1 (where 0,0,0 is black
and 1,1,1 is white). The background command is not required --
a default background (black) will be computed if none is present in
the file. If there is a background command, it must appear
before of any begin commands. Also, if there are more than one
background commands in the file, the last is used, and the
others are ignored.
include scenefile
This command includes the scene defined by the specified file into the current scene. Specifically, the scene graph constructed while parsing scenefile will be added to the current scene graph as a subtree rooted at the current parsing position. So, this command can occur anywhere in the scene file, and transformations of the scene graph hierarchy will affect included geometry in the same way that it would if the commands were copied into the file at the same location. Yet, materials defined in scenefile will not affect the indices to be used for materials in the current file.