Job & Scene Definition Reference

Properties in blue colour are optional, all other properties listed are mandatory

Items in italics are specific types/classes of object, e.g. a Light

Job Input

This is the top level of YAML that needs to be submitted to start a job

name:        Name of job to submit
width:       Width of image to render in pixels
height:      Height of image to render in pixels
maxDepth:    Maximum recursion depth when ray tracing (default: 4)
antiAlias:   Enable anti-aliasing, removes jagged edges but slower (default: false)
tasks:       How many tasks to split the job into. (default: number of active tracers)
animation:   Render an animation / video, omit this to render a single image
  duration:  Length of animation in seconds   
  framerate: Framerate (default 30)
scene:       Scene to render

Scene Definition

backgroundColour: Colour of the background, used when ray misses all objects (default: black)
ambientLevel:     Level of ambient light, typically: 0.0 ~ 0.3 (default: 0.1)
camera:           Camera settings
  fov:            Field of view, lower values "zoom in" (default: 30)
  pos:            Camera position Point in world space
  lookAt:         Camera will be oriented and looking at this Point in world space
  animation:      An array of Animations to modify the camera over time
seed:             String used to initialize the random number generator
lights:           Array of Lights in the scene
objects:          Array of Objects in the scene
materials:        Array of Materials which will be used as shared presets for Objects in the scene

Colour Definition

[r, b, g]   Array (tuple) of red, green & blue values. Integers in the range 0 ~ 255

Point Definition

[x, y, z]   Array (tuple) of X, Y & Z co-ordinate values, representing a point in 3D world space.

Rotation Definition

[x, y, z]   Array (tuple) of X, Y & Z rotation values, representing a rotation in 3D space around each axis. Values are in degrees.

Light Definition

pos:          A Point position in space where the light is located
brightness:   Brightness coefficient of the light, typical values are 0.8 ~ 1.3 (default: 1.0)
radius:       Falloff and attenuation radius, in world units (default: 200)
colour:       The Colour of the light (default: [1, 1, 1], i.e. white light)
animation:    An array of Animations to modify the light over time

Object Definition

All objects regardless of type have the following properties

type:      The type of object, allowed values are: sphere, plane, cuboid, cylinder, cone & mesh
name:      The name of the object, used for logging and debug purposes
pos:       A Point position in world space where the center of the object is to be located
material:  A Material describing the appearance and surface of the object
animation: An array of Animations to modify the object over time

Each object has additional parameters that will depend on the type that was specified

type: sphere

A sphere is a uniformly spherical ball

radius:    The radius of the sphere in world units

type: plane

A plane is an infinite 2D flat sheet, useful for creating walls and floors in a scene. If you need a finite 2D rectangle use a thin cuboid instead

rotation:  A Rotation tuple, orienting the plane. The starting orientation is [0, 1, 0] aligned with the Y axis, i.e. a flat "floor"

type: cuboid

A box shape with 6 sides, can be a regular cube or rectangular depening on parameters

rotation:  A Rotation tuple, orienting the cuboid (default: [0, 0, 0])
size:      A 3-tuple, specifying the dimensions of the cuboid along each axis before rotation

type: cylinder

A cylinder with a circular base

rotation:  A Rotation tuple, orienting the cylinder. Starting orientation is aligned along Y axis pointing "upwards"
radius:    The radius of the cylinder
length:    The length of the cylinder
capped:    Boolean. Cap the ends of the cylinder or have a hollow tube (default: false)

type: cone

A tapered cone with a circular base

rotation:  A Rotation tuple, orienting the cone. Starting orientation is aligned along Y axis pointing "upwards"
radius:    The radius of the cone
length:    The length of the cone
capped:    Boolean. Cap the end of the cone or have it hollow (default: false)

type: mesh

A polygon mesh in Wavefront .OBJ format. The mesh can only contain triangle polygons, and also must include vertex normals

src:       The source URL of the mesh OBJ file, URL must be accessible by the tracers
rotation:  A Rotation tuple, orienting the mesh. (default: [0, 0, 0])
scale:     A uniform scaling factor to resize the mesh (default: 1)

Material Definition

All material properties are parameters that are used in the Blinn-Phong illumination model. Many of the parameters are coefficients or scaling factors, that typically lay in the range 0.0 ~ 1.0, but can go over 1.0 in some cases. The only required properties are preset and texture

preset:    Base which defines starting values for ka, kd, etc. You can then override these values. Preset is one of: basic, matte, rubber, shiny or any of the custom presets you have defined in the scene materials list
texture:   A Texture object
ka:        Ambient coefficient: how much ambient light the material reflects, typically 0.1 ~ 0.5
kd:        Diffuse coefficient: how much diffuse light the material reflects, typically 0.8 ~ 1.0
ks:        Specular coefficient: how much specular light the material reflects, 0.0 for for matte objects through to 1.0 for very shiny
hardness:  Specular hardness: Used by Phong shading model, changes the size of specular highlights. Small values (2 ~ 10) will give large highlights, values over 50 will give small glassy highlights
kr:        Reflective coefficient: How much the object reflects surroundings, 1.0 is a perfect mirror, 0.0 turns off reflections. Note, setting above 0.0 will affect rendering time
kt:        Transmission coefficient: How much the object allows light through it, 1.0 is perfectly clear, 0.0 turns off transparency. Note, setting above 0.0 will affect rendering time
ior:       Index of refraction. Typically 1.0 ~ 2.5, see Refractive Index on Wikipedia for some values. Ignored when kt is 0.0
noShade:   Boolean. When enabled, no shading is done and the object simply returns the colour or texture directly (default: false)
name:      Only supply a name when the material is in the scene level materials list. This then makes it a preset for use on objects

Texture Definition

Textures are typed, and the properties are strongly linked to the given type, so all textures require a type

type:      The type of texture, one of: basic, check, image, noise, turbulence, wood or marble
scaleU:    Scaling factor for texture U coords (applies to check and image texture types)
scaleV:    Scaling factor for texture V coords (applies to check and image texture types)
flipU:     Boolean. Flip the direction of the texture U coords (applies to image texture types)
flipV:     Boolean. Flip the direction of the texture V coords (applies to image texture types)
swapUV:    Boolean. Swap U & V texture coords, equates to a 90deg rotation (applies to image texture types)

type: basic

A basic texture is a uniform single colour

colour:    The Colour of the texture

type: check

A check texture is a 2D checkerboard, use scaleU and scaleV to resize

colour1:    The first Colour of the checks
colour2:    The second Colour of the checks

type: image

A bitmap image texture mapped onto the surface of the object. Only PNG images are supported. In many cases it is advisable to select images that seamlessly tile together

src:       The source URL of the PNG image texture, URL must be accessible by the tracers

type: noise

Procedurally generated solid 3d texture, based on smoothed Perlin noise

colour1:    The first Colour of the checks
colour2:    The second Colour of the checks
scale:      3-tuple size/scaling factor for noise along each [X, Y, Z] axis
mult:       Scaling factor applied to colour1 (default: 1)
pow:        Power factor makes the ramp between colours steeper and colour1 more dense  (default: 1)

type: turbulence

Procedurally generated solid 3d texture, based on fractally scaled Perlin noise

colour1:    The first Colour of the checks
colour2:    The second Colour of the checks
scale:      3-tuple size/scaling factor for noise along each [X, Y, Z] axis
size:       Starting size of the turbulence (default: 32)
abs:        Clamp values to positive, results in finer looking textures (default: false)
mult:       Scaling factor applied to colour1 (default: 1)
pow:        Power factor makes the ramp between colours steeper and colour1 more dense (default: 1)

type: marble

Procedurally generated solid 3d texture, that approximates the look of veined marble based on applying sine function to turbulence

colour1:    The first Colour of the checks
colour2:    The second Colour of the checks
periods:    3-tuple scales the repeating marble pattern along each [X, Y, Z] axis
turbPower:  Power factor determines how sharp the marble veins are (default: 5)
turbSize:   Size of the turbulence used (default: 32)
mult:       Scaling factor applied to colour1 (default: 1)
pow:        Power factor makes the ramp between colours steeper and colour1 more dense (default: 1)

type: wood

Procedurally generated solid 3d texture, that approximates the look of grained wood grain, based on applying sine function to turbulence along one axis

colour1:    The first Colour of the checks
colour2:    The second Colour of the checks
period:     Scales the repeating wood grain pattern 
axis:       Integer axis to align the wood along, 0 = x, 1 = y, 2 = z (default: 1)
offset:     A Point which moves the center of the wood grain pattern in world coords
turbPower:  Power factor determines how sharp the wood grain pattern is (default: 5)
turbSize:   Size of the turbulence used (default: 32)
mult:       Scaling factor applied to colour1 (default: 1)
pow:        Power factor makes the ramp between colours steeper and colour1 more dense (default: 1)

Animation Definition

Animation Can modulate properties of objects, lights and the camera.

type:      The type of animation, one of: 'vector' or 'spline'
property:  Property name to modify, e.g. 'pos', 'rot' or 'lookAt'
start:     property of the object to modify, e.g. 'pos', 'rot' or 'lookAt'
duration:  property of the object to modify, e.g. 'pos', 'rot' or 'lookAt'

type: vector

target:    The destination value a three tuple of values, e.g. [200, 45, 6]

type: spline

points:    Array of spline control points, e.g. [[0, 10, 50], [0, 20, 20], [-30, 20, 20]]