Syntax of COS426 Scene File Format

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. 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 three new commands (particle, particle_source, and particle_sink), as described below.

particle
    mat_id
    center_x center_y center_z
    velocity_x velocity_y velocity_z
    mass drag elasticity lifetime
    shape_id

This command defines a particle with initial position (center_x,center_y,center_z) and initial velocity (velocity_x,velocity_y,velocity_z).

The particle should be drawn with 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. The last five values specify the mass of the particle (range: 0 to infinity), the drag coefficient of the particle (range: 0 to infinity), the elasticity of the particle (range: 0 to 1), the liftime of the particle (in seconds from the start of execution), and the shape to be used for drawing the particle. If shape_id = -1, then the shape is just a point at (center_x, center_y, center_z). Otherwise, the shape_id should be treated as index into the list of shapes previously defined within the same file (where shapes include tri, box, sphere, cylinder, cone, and mesh).

particle_source
    mat_id
    source_shape_id
    center_x center_y center_z
    direction_x direction_y direction_z
    speed rate sc mass drag elasticity lifetime
    particle_shape_id

This command defines a particle source, a generator of particles. The source should generate rate particles per second, where each particle adopts the initial state provided in this command. Specifically, the particles should be generated randomly from random positions on the surface of the shape indicated by source_shape_id after centering that shape at (center_x,center_y,center_z). If shape_id = -1, then the source shape is just a point at (center_x, center_y, center_z). Otherwise, the shape_id should be treated as index into the list of shapes previously defined within the same file (where shapes include tri, box, sphere, cylinder, cone, and mesh). Every generated particle should have an initial velocity vector with magnitude equal to speed and a random direction within the cone defined by the axis (direction_x, direction_y, and direction_z) and the half-angle sc.

The particle should be drawn with 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. The last five values specify the mass of the generated particles (range: 0 to infinity), the drag coefficient of the generated particles (range: 0 to infinity), the elasticity of the particle (range: 0 to 1), the liftime of the generated particles (in seconds from their creation), and the shape to be used for drawing the generated particles. If particle_shape_id = -1, then the particle shape is just a point. Otherwise, the particle_shape_id should be treated as index into the list of shapes previously defined within the same file (where shapes include tri, box, sphere, cylinder, cone, and mesh).

particle_sink
    sink_shape_id
    center_x center_y center_z
    force ca la qa

This command defines a particle sink, an attactor of particles. The sink has the shape indicated by sink_shape_id centered at (center_x,center_y,center_z). If sink_shape_id = -1, then the sink shape is just a point at (center_x, center_y, center_z). Otherwise, the sink_shape_id should be treated as index into the list of shapes previously defined within the same file (where shapes include tri, box, sphere, cylinder, cone, and mesh). The sink attracts particles towards the sink surface with a force equal to force*1.0/ (ca + la*d + qa*d*d), where d is the distance from a particle to the sink shape's surface, and ca, la, and qa define the constant, linear and quadratic components of the attenuation factor. Note: to achieve no attenuation use a (ca,la,qa) of (1.0,0.0,0.0).

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 kt 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 direction of the spot light source is given by (dx,dy,dz), and the cutoff angle is given by cs -- 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.