Syntax of the COS426 Scene File Format

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, lines starting with the hash character # will be ignored as comments. All numbers are assumed to be floating point. Angles are given in radians.

Most of the commands are the same as in assignment #3. There are only five new commands (particle, particle_source, and particle_sink, particle_spring, and particle_gravity), as described below.

In general, positions and distances should be in meters, times in seconds, and weights in kilograms.
 

particle
    position_x position_y position_z
    velocity_x velocity_y velocity_z
    mass fixed drag elasticity lifetime mat_id

This command defines a particle with initial position (position_x,position_y,position_z) and initial velocity (velocity_x,velocity_y,velocity_z).

The last six values specify the mass of the particle (range: 0 to infinity), whether or not the particle has a fixed position (range: 0=freetomove or 1=fixed), the drag coefficient of the particle (range: 0 to infinity), the elasticity of the particle (range: 0 to 1), the lifetime of the particle (in seconds from its creation, or <=0 to live forever), and the material ID for the particle, 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.
 

particle_source
    mass fixed drag elasticity lifetime mat_id
    rate velocity angle_cutoff
    source_shape

This command defines a particle source, a generator of particles. The source should generate rate particles per second with initial positions randomly distributed on the surface of the source.

The surface of the source is specified by the source_shape parameters, which appear in one of the following formats: 

   line    x1 y1 z1  x2 y2 z2  
   box     low_x low_y low_z  high_x high_y high_z
   circle  center_x center_y center_z  normal_x normal_y normal_z radius 
   sphere  center_x center_y center_z  radius
   mesh    meshname

These shape descriptions are similar to the ones used for creating scene elements. Specifically, if the source shape is a line, then six values appear after the "line" keyword to specify the two endpoints of the line segment: (x1,y1,z1) and (x2,y2,z2). If the source shape is a box, then six values appear after the "box" keyword to specify the "low" corner of the box (low_x,low_y,low_z) and the "high" corner of the box (high_x,high_y,high_z) (e.g., a unit cube is "box -1 -1 -1 1 1 1"). If the source shape is a circle, then seven values appear after the "circle" keyword to specify its center (center_x,center_y,center_z), its normal direction (normal_x,normal_y,normal_z), and its radius (e.g., a unit circle in the xz-plane is "circle 0 0 0 0 1 0 1"). If the source shape is a sphere, then four values appear after the "sphere" keyword to specify its center (center_x,center_y,center_z) and radius (e.g., a unit sphere is "sphere 0 0 0 1"). Finally, if the source shape is a mesh, then one parameter follows the "mesh" keyword to specify the mesh filename (e.g., "mesh teapot.off").

When a particle is generated with this source, it should have an initial velocity vector with magnitude equal to velocity and with a direction equal to the normal of the surface (or line) at the particle's initial position perturbed by a random angle between zero and angle_cutoff.

The particle should be generated with the given mass (range: 0 to infinity), fixed status (range: 0=freetomove or 1=fixed), drag coefficient (range: 0 to infinity), elasticity (range: 0 to 1), liftime (in seconds from their creation, or <=0 to live forever), material ID (mat_id is an index into previous defined materials), where all these parameters are interpreted in the same way as described in the particle command.
 

particle_sink
    intensity ca la qa
    sink_shape

This command defines a particle sink, an attactor or repulsor of particles. The sink attracts particles towards (or away from) the sink surface and kills them if they intersect its surface.

The sink surface is specified by the sink_shape, which has the same format and interpretation as described for particle sources.

If the intensity of the particle sink is non-zero, then the sink exerts a force on particles. The direction of the force is along the vector from the particle to the closest point on the surface. The magnitude is equal to intensity*1.0/ (ca + la*d + qa*d*d), where d is the distance from a particle to the closest point on the sink shape's surface, and ca, la, and qa define the constant, linear and quadratic components of the attenuation factor. Note that the specified intensity can be negative (to repel particles).
 

particle_spring
    particle1 particle2
    rest_length ks kd

This command defines a "spring" between two particles with the given rest_length, spring coefficient (ks), and damping_coefficient(kd). This pair of particles should apply a force upon each other according to Hooke's Law.
 

particle_gravity
    vx vy vz

This command defines the vector of acceleration due to gravity. For earth, you can use (0, -9.80665, 0), assuming that Y is "up."
 
 

The following commands define the non-particle elements of the scene -- they follow the syntax of assignment #3 without change.

 

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.
 

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.
 

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.
 

line
    mat_id
    x1 y1 z1
    x2 y2 z2

This command defines a line segment with endpoints (x1, y1, z1) and (x2, y2, z2). You do not have to intersect lines in your ray tracer, since they are infinitely thin. This command is provided mainly for visualization purposes (the lines will be drawn in rayview).

The line segment 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 line segment 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.
 

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.
 

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.
 

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.
 

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 emissive color of the material (e.g., if a geometric primitive is a light source). With the exception of the distributed ray tracing task, emissive surfaces do not actually contribute illumination to other surfaces, but, unlike the explicit light sources, they are directly visible in the camera and in reflections etc.

The exponent n defines the specular 'shininess' of the material, and takes non-negative 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, the diffuse color kd will be modulated by the color of the corresponding texture pixel . If no texture is to be associated with the material, then a value of 0 must be given for texturename.
 

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.
 

area_light
    r g b
    px py pz
    dx dy dz
    radius
    ca la qa

This command defines a light with a planar, circular area in the scene.  (r,g,b) gives the color of the light. (px,py,pz) gives the center of the circular area in world coordinates. (px,py,pz) and (dx,dy,dz) define the plane on which the area light resides, and radius defines extent of the area on the plane (i.e., the radius of the circle). Use this type of light to demonstrate soft shadows.

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, and thera is the angle between the light direction and the direction to the surface, then the light's color at the surface is given by (r,g,b) *cos(theta)/ (ca + la*d + qa*d*d). Each coeficient must be non-negative. 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.
 

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.
 

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 non-negative. 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 non-negative. 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 non-negative, 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.
 

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.
 

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.
 

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.