There is a batch file in the root folder named "run.bat". It will execute the ray tracer's JAR file and send the scene file name along with the output file name, which must end in ".png" since only PNG is supported.

To specify the scene file, use "-scene scenename.dat" in the arguments. To specify the output file use "-out outname.png". Additionally, you can add "-batch" which will close the rendering window automatically after completion, which is handy for batch renderings with different scene files.

To enable caustics in the scene, you must place a "PhotonMap" line in the scene file (see below for details). After that, each light that contributes photons must specify how many. From that, the system will compute each photon's intensity and colour. The more photons a light shoots, the less intense they will be individually. As well, their colour will be tinted by the light's colour.

Elements in the file must be in a certain order. Textures must be defined first, followed by Materials. After that, Objects, Lights, and DXF Imports can be defined.

Each element in the file is to be placed on its own line, which starts with the element’s name (i.e. Texture, Material, Sphere, etc). After the element’s name, attributes are separated by the pipe character ‘|’. There can also be groupings of attributes delimitated by commas within the pipe delimiters. This makes for better visibility (for example coordinates are often grouped in 3’s). Comments can be placed by starting the line off with the pound character ‘#’. Lines containing objects not recognized will be ignored.

Settings|resX,resY|reflectDepth,refractDepth|superDepth,superTolerance

Settings allow you to specify the image resolution resX,resY and the various depth settings for reflection/refraction. If you want to use super sampling, set superDepth to an integer > 0. For each level of superDepth, every pixel will be divided up into 5 sections and averaged. If the averaged difference between each of those subsections with each other is > superTolerance, then that subsection will be subdivided even further up to a maximum of superDepth levels. Typical values for superTolerance are 0.01. Use –1 if you want to force super sampling regardless of tolerance.

Camera|x,y,z|lookX,lookY,lookZ|aspect|fov|rotation

This specifies where the camera is to be in the scene. It will be positioned at x,y,z and facing lookX,lookY,lookZ.Aspect deals with the screen resolution (usually 1.3333) and fov controls the field of view (usually 65). A rotation can be specified (0 is no rotation).

PhotonMap|radius|globalIntensity

This creates a photon map for the caustics in the scene. Use radius to specify how far each photon can be from a hit point. Typical values are 0.2 to 1.5. The globalIntensity controls how intense or bright all of the photons will be. The default value is 10000 and won't likely need to be changed.

Texture|ID|textureFilename|bumpFilename|bumpScale

The ID specifies this texture’s unique ID to be used by materials. Textures can have either graphic texture textureFilename, a bump map bumpFilename, or both. If you do not wish to include one or the other, instead of the filename specify null for that attribute. The bumpScale can be used to control how far apart the sample points are from each other when determining the normals from the map. This must be an integer (typically 1).

Material|ID|ar,ag,ab|dr,dg,db|sr,sg,sb|spec,refl,refr,refrI,textureID

ar,ag,ab defines the ambient lighting from 0..1

dr,dg,db defines the diffuse lighting from 0..1

sr,sg,sb defines the specular lighting from 0..1

Note that if a texture is used, the diffuse should be set to zero unless you want to “add” more light to the texture colours such as tinting. For texture ambient settings, values of 1 will make the texture appear at regular intensity (values as is from the bitmap file) when there are no lights hitting the object.

spec controls the size or “spread” of the specular highlights. The smaller the value, the more spread there is. A typical value is 10.

refl controls how reflective the object is from 0..1

refr controls how refractive the object is from 0..1

refrI is the refraction index (typically 1.4)

textureID can either be set to the index of a specified texture or 0. It must be set however.

Sphere|x,y,z,rad|materialID|useFresnel

Spheres are very straight forward. All attributes are required except useFresnel. If useFresnel is set to true, the fresnel effect will be applied to reflections on the object.

Plane|x1,y1,z1|x2,y2,z2|x3,y3,z3|materialID|textureScaleX,textureScaleY|bumpScaleX,bumpScaleY|useFresnel

Only attributes up to materialID are required. Planes are defined by 3 coordinates.

If the material contains a texture then textureScaleX … bumpScaleY will control how far the textures spans on the surface before it repeats. Typical values are 0.08 depending on the scale of the scene. If the material does not contain a texture, these values will be ignored. If useFresnel is set to true, the fresnel effect will be applied to reflections on the object.

Triangle|x1,y1,z1|x2,y2,z2|x3,y3,z3|materialID|textureScaleX,textureScaleY|bumpScaleX,bumpScaleY|useFresnel

Only attributes up to materialID are required. Triangles are defined by 3 coordinates.

If the material contains a texture then textureScaleX … bumpScaleY will control how far the textures spans on the surface before it repeats. Typical values are 0.08 depending on the scale of the scene. If the material does not contain a texture, these values will be ignored. If useFresnel is set to true, the fresnel effect will be applied to reflections on the object.

Point Light

LightPoint|x,y,z|r,g,b,intensity|photonCount|near,far

This creates a light at the x,y,z {0..1} position with a colour of r,g,b {0..1} and an intensity. A typical intensity is 1. If caustics is enabled, photonCount will cause this light to shoot that many photons into the scene. The variables near and far are optional, but specify light attenuation.

Area Light

LightArea|r,g,b,intensity,numSamples|isVisible|photonCount|near,far

Area lights are used to create soft shadows and are very expensive depending on the numSamples value. Basically an area light is an array of numSamples point lights. It is important to know that when area lights are created, they will use the previous object declared in the scene file to represent the area that the light covers. It will then take random samples from the surface of that object. Only spheres can be used to represent area lights. isVisible can be set to "false" if you don't want this area light's object to accept intersections, thus making it invisible.

If caustics is enabled, photonCount will cause this light to shoot that many photons into the scene. The variables near and far are optional, but specify light attenuation.

DXF|fileName|materialID|x,y,z|scale|textureScaleX,tetureScaleY|bumpScaleX,bumpScaleY

When DXF files are imported, they are scaled down to a size of 1.0 and shifted to the origin (0,0,0). x,y,z values allow you to place the DXF model anywhere in your scene and scale will expand the model to the desired dimensions. Similar to objects, you can adjust the texture and bump map scales.


ASE|fileName|materialID|x,y,z|rotX,rotY,rotZ|scale|textureScaleX,tetureScaleY|bumpScaleX,bumpScaleY|forceSmooth

When ASE files are imported, they are scaled down to a size of 1.0 and shifted to the origin (0,0,0). x,y,z values allow you to place the ASE model anywhere in your scene. You can rotate the model by specifying rotX,rotY,rotZ and scale will expand the model to the desired dimensions. Similar to objects, you can adjust the texture and bump map scales. If forceSmooth is set to true, phong shading will be used regardless of whether or not the ASE file says so.