Syntax of COS526 Scene File Format

Syntax of the COS526 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.

Commands in the language belong to several different groups; note that any geometry definition must occur after camera, material(s) and light(s) have been defined.

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 (emitted radiance at each frequency in Watts/sr/m^2). (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 theta 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 (emitted radiance at each frequency), 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 (emitted radiance at each frequency). (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 (emitted radiance at each frequency), 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.