This document describes the toxic scene file format. It is written to be easy to read and understand, but it also contains enough details to be considered as a reference document.

In order to improve the quality of this document, please report typos and errors but also missing, incomplete or unclear material. In any case your comments and suggestions are welcome. In all cases, please use the forums to discuss this document.

• 1  Introduction
  • 1.1  Why XML?
  • 1.2  toxic Coordinate System
• 2  File Structure
• 3  Frames
• 4  Surface Shaders
  • 4.1  General Structure
  • 4.2  BDF
  • 4.3  Reflectance
  • 4.4  EDF
  • 4.5  Radiant Exitance
• 5  Objects
  • 5.1  General Structure
  • 5.2  Transformation
  • 5.3  Properties
  • 5.4  Geometric Objects
    • 5.4.1  Plane
    • 5.4.2  Square
    • 5.4.3  Sphere
    • 5.4.4  Cube
    • 5.4.5  Ring
    • 5.4.6  Mesh
  • 5.5  Lights
    • 5.5.1  Point Light
  • 5.6  Cameras
    • 5.6.1  Pinhole Camera
    • 5.6.2  Thin Lens Camera
• 6  XML Schema
• 7  Sample Files

The toxic scene file format is based on the XML standard. From a user perspective, this has several implications:

• Since XML is a textual format, scene files can be easily read, edited, merged, diff-ed, etc.
• Basic syntax is well defined and well known.
• Scene files can be edited using a XML editor: this has several advantages over using a standard text editor: XML editors provide facilities such as autocompletion, basic syntax checking, and even in-depth file validation (using XSD schemas provided along with toxic).
• Several tools exist to display XML files in a user-friendly manner (usually with syntax highlight and outlining).
• Scene files manipulation can be automated using XSLT transformations.

Using XML as an underlying format for scene files also make life easier from a developer point of view, since several powerful XML parsers are available (number of them being open source or free software, like the powerful Apache Xerces C++ XML Parser which toxic uses) with bindings for the vast majority of programming languages.

toxic uses a right-handed coordinate system. X+ (positive X axis) points to the right, Y+ (positive Y axis) points up and Z+ (positive Z axis) points out of the screen, toward the user in front of the screen.

Here is the basic structure of a valid scene file:

The first statement (<?xml ... ?>) indicates the type and the encoding of the document.

The second statement (<ToxicScene ... >) opens the root element of the scene. The xsi:noNamespaceSchemaLocation attribute is the path to the toxicscene.xsd schema (which is located in the schemas/ directory of the toxic distribution). toxic does not rely on this path to find the schema, so it will not complain if it is incorrect. However, you must specify the right path to the toxicscene.xsd file in order to allow your favorite XML editor to find the schema and to validate your scene file.

The last statement (</ToxicScene>) closes the root element.

One and ony one root element must appear in the file.

toxic scene file format is multi-frame: a single scene file may contain several scenes which can share shaders and geometry. This is particularly useful for animations, where each frame is described in the same scene file. That way, all frames can be rendered with a single run of toxic.

A frame is declared as follow:

A single scene file can contain any number of frames. It is legal for a scene file to contain no frame. A frame can not be declared inside another frame.

Each <Frame /> element defines its own set of namespaces. An object or a shader declared inside a <Frame /> element can not be accessed outside this <Frame /> element. Consequently, it is legal to define two different shaders, with exactly the same name, in two distinct <Frame /> elements.

If several frames have a shader in common (which is typically the case), it can be declared once outside all <Frame /> elements and then used by as many frames as needed.

Note: future versions of toxic will allow to declare shared objects in addition to shared shaders.

Note: current version of toxic can not handle more than one <Frame /> element in a given scene file. This will be fixed in future versions of toxic.

A shader describes properties of a material. Currently, only surface materials are implemented in the current version of toxic. In addition to surface materials, future versions will allow to declare and use volume materials to describe transparent and translucent materials, such as glass, water, smoke and so on.

Note: with the current version of toxic, surface shaders must be defined before they can be used. This limitation will be removed in future toxic versions.

The following code fragment declares a new shader named mat01:

A unique name must be given to each surface shader. Names are case-sensitive: for example, mat01 is not the same as Mat01. The name can contain any printable character of the system character set (ASCII under Windows). Name length is not limited.

Surface shader names are defined in their own namespace. Consequently, it is legal (although not very smart) to use the same name for a surface shader and for a different entity like an object.

The optional base attribute can be specified to make the current material inherit all the properties of the specified base material. For example, the code fragment

defines a new material named mat01 which inherits all the properties of the base_mat material. It not altered, the mat01 material is exactly equivalent to the base_mat material.

A surface shader can contain at most one of each of these elements:

• <BDF /> to set the material BRDF or BTDF (current toxic version only supports BRDF);
• <Reflectance /> to set the material reflectance;
• <EDF /> to set the material EDF;
• <RadiantExitance /> to set the material radiant exitance.

Order of the elements does not matter.

The <BDF /> element sets the material BRDF of the material. The BRDF characterizes how light is reflected from a surface.

Here is the syntax to use a Lambertian (perfectly diffuse) BRDF:

With the current version of toxic, the only two correct values for the type attribute are lambertian (perfectly diffuse BRDF) and perfectspecular (perfectly specular BRDF). Note that value of the type attribute is case-sensitive: type="lambertian" is legal but type="Lambertian" is not.

If the <BDF /> element is not specified, a Lambertian BRDF is assumed.

The <Reflectance /> element defines the material reflectance, that is, how much light is reflected by this material. Material reflectance is unit-less.

Current toxic version supports two types of reflectance: constant reflectance and image-based reflectance.

A constant reflectance of 0.5 is defined as follow:

The value attribute is a vector of scalars, each one defining the reflectance in a particular band of the light spectrum. Current version of toxic deals only with the RGB format (future versions will probably implement richer formats). Consequently, the value attribute is a vector of three scalars, each one defining the reflectance in one of the R, G, B channel (in that order). Reflectance values must be contained in the [0.0, 1.0] closed interval.

If reflectance value is the same for all channel, the previous code fragment can be equivalently rewritten as follow:

This shortcut can be used everywhere a vector value is needed.

Image-based reflectance is defined in the following manner:

The value of the href attribute must be the path to an image file, like wood.png or textures/wood.png. Under Windows, both '/' and '\' slashes are supported. Under most other operating systems, only '/' can be used.

The specified file is first searched in the directory containing the XML scene file. If not found, it is then searched in the current directory (the directory from which toxic binary has been launched).

Amongst others, the following image formats are currently supported: BMP, JPEG, PNG, TGA, TIFF (this list is not exhaustive). Prefered file format is PNG. There are several reasons to use the PNG format over other image formats:

• PNG format is royalty free.
• PNG's compression is fully lossless (in contrast to JPEG format).
• PNG's compression is among the best that can be had without losing image information and without paying patent fees.

If the <Reflectance /> element is empty or not defined, a constant reflectance of 0.5 0.5 0.5 is assumed.

The EDF element defines how light is emitted from the surface of this material. Here is the syntax:

This code fragment make this material emit light in a perfectly diffuse manner. Every object using this shader will therefore be considered as a light source: this is the most common way to define a light source in toxic.

By default, light emission is disabled. This is equivalent to the following code:

Radiant exitance characterizes how much light is emitted from a material. Radiant exitance is expressed in W.m^-2.

Here is the syntax:

The value attribute is a vector of scalars, each one defining the radiant exitance in a particular band of the light spectrum (see the description of the Reflectance element for more details). Each component of the radiant exitance must be greater or equal to 0.0.

For a material to effectively emit light, the <EDF /> element must be specified with the lambertian value (which is the only one emission profile implemented in current version of toxic), and at least one the radiant exitance component must be non-null.

Note: since radiant exitance is defined in Watts per unit of surface area, the total amount of emitted light is proportional to the surface area of the light source.

All objects are defined using the same template:

The type attribute defines the object type.

Naming objects is not required and by default objects are unnamed. An object can be named using the name attribute:

A unique name must be given to each named object. Names are case-sensitive: for example, sphere01 is not the same as Sphere01. The name can contain any printable character of the system character set (ASCII under Windows). Name length is not limited.

Object names are defined in their own namespace. Consequently, it is legal (although not very smart) to use the same name for an object and for a different entity like a surface shader.

Note: currently, object names are accepted but not used by toxic.

Similarly to a surface shader, an object can inherit its properties from a base object. This is done using the optional base attribute:

Note: currently, the base attribute in object definition is accepted but not used by toxic.

The following object types are accepted: plane, square, sphere, cube, ring, mesh, pointlight and camera.

An object description is made up of at most one <Transform /> element and zero, one or several <Parameter /> elements.

The <Transform /> element can be used to specify scale, orientation and position of any object. An object can contain at most one <Transform /> element which in turn can contain any number of transformation elements, in any order.

A <Transform /> element is declared as follow:

Four transformation elements are available:

• <Scale /> scales the object by a given value on each axis;
• <Rotation /> rotates the object by a given angle, around a given axis;
• <Translation /> translates the object by a given vector.
• <Matrix4 /> allows to define an arbitrary transformation.

The syntax to declare a <Scale /> element is:

The value attribute is a vector of three scalars defining scale along X, Y and Z axis respectively, in that order. If the scale is uniform (scale factors are the same on all three axis), the code fragment above can be rewritten as follow:

The syntax to declare a <Rotation /> element is:

The angle attribute is an angle of rotation, expressed in degrees. It can take any positive or negative real value. The axis attribute is a 3-dimensional vector defining the axis of rotation. It does not have to be unit-length (it will be normalized at load time). angle and axis attributes can be specified in any order.

The syntax to declare a <Translation /> element is:

The value attribute is a 3-dimensional vector defining the object translation.

The syntax to declare a <Matrix4 /> element is:

There must be 16 matrix coefficients separated by spaces. Matrices are row-major: the first 4 coefficients define the first row, the next 4 define the second row, and so on.

Of course, transformation elements can be combined:

Transformation elements can be specified in any order. Transformations are applied in the same order they are declared: in the example above, the object is first scaled, then it is orientated and finally it is translated. Different orders give different results: the code fragment

does not specify the same transformation as this one:

Most of the time, the right transformation order is scale, rotation, translation.

If the <Transform /> element is omited or if no transformation is specified, the identity transformation is assumed.

Object properties are defined using <Parameter /> elements, which are simple (key, value) pairs.

The following code fragment defines the surfaceshader parameter to be equal to mat01:

The next table summaries available parameters for each object type. Bold parameters are required, others are optional:

Required parameters:

• surfaceshader: name of the surface shader to assign to the object surface.

Optional parameters:

• visible: valid values are true and false. If set to true, the object will be visible and will cast shadows. Otherwise, it will not be visible and will not cast shadow.

Declaration:

The plane object is an infinite planar surface coinciding with the XZ plane. Surface normal is pointing toward Y+ (it goes away from the plane toward increasing Y).

Declaration:

The square object is a unit square contained in the XZ plane and centered at the origin. It extends from (-0.5, 0.0, -0.5) to (0.5, 0.0, 0.5) (borders are included). Surface normal is pointing toward Y+ (it goes away from the square plane toward increasing Y).

Declaration:

The sphere object has unit radius and is centered at the origin. Surface normal is pointing outward (it goes away from the sphere center).

Declaration:

The cube object has unit length sides and is centered at the origin. It extends from (-0.5, -0.5, -0.5) to (0.5, 0.5, 0.5). Surface normal is pointing outward (it goes away from the cube center).

Declaration:

The ring object has unit outer radius and unit height (ring base is located at y=-0.5 and ring top at y=0.5). Its inner radius is defined by the innerradius parameter. The ring is centered at the origin and its axis is directed along Y.

Required parameters:

• innerradius: inner radius of the ring. Must be contained in the [0..1) interval (note that 1.0 is not a valid value for the inner radius).

Declaration:

The mesh object is a 3D polygon soup. The geometry is imported from a mesh file using the href parameter. If the mesh file contains several submeshes, the include parameter can be used to select which submeshes to include. Alternatively, the exclude parameter can be used to select which submeshes to exclude.

Required parameters:

• href: path to a mesh file. Currently supported mesh file formats are Alias|Wavefront .obj, discreet 3ds max .ase and ENST/Telecom Paris .tri.

Optional parameters:

• rebuildnormals: valid values are true and false. If set to true and if the smoothingthresholdangle parameter is correctly defined, normal vectors will be reconstructed at load time (see explanation below). By default, normal reconstruction is disabled.
• smoothingthresholdangle: the value of this parameter must be a single scalar defining the smoothing threshold angle in degrees. The value of this parameter is largely scene-dependent, but a value of 70.0 (degrees) is quite typical.
• optimizemesh: valid values are true and false. If set to true and if the vertexweldingthreshold and normalweldingthreshold parameters are defined correctly, the mesh will be optimized at load time (see explanation below). By default, mesh optimization is disabled.
• vertexweldingthreshold: the value of this parameter must be a single scalar defining the vertex welding distance threshold, in meters. The value of this parameter is largely scene-dependent. It must be small compared to object size.
• normalweldingthreshold: the value of this parameter must be a single scalar defining the normal welding angle threshold, in degrees. The value of this parameter is quite scene-independant, and a value of 1.0 degree seems to work well in most cases.

Normal reconstruction consists of building a new set of vertex normals from the actual object geometry, sharing normals between faces if they form an angle smaller than the threshold angle defined with the smoothingthresholdangle parameter.

Normal reconstruction is recommended when importing geometry from a .ase file exported from discreet 3ds max, because the standard .ase exporter in 3ds max is broken and often outputs wrong normals. It is recommended to always enable mesh optimization when enabling normal reconstruction.

Mesh optimization tries to reduce the number of vertices and normal vectors of the mesh, and eliminates degenerate (empty) faces. No mesh reduction or simplification is performed. Vertices and normals are just packed together.

Two vertices are welded together if the distance between them is smaller than the distance threshold set with the vertexweldingthreshold parameter. Two normal vectors are welded together if the angle between them is smaller than the angle threshold set with the normalweldingthreshold parameter.

Note that mesh optimization is a very slow process and can take ages even with moderately complex objects.

Light objects are pure light emitters. They don't have geometry, and thus don't appear themselves in renders.

Required parameters:

• power: the value of this parameter must be a vector of scalars, each one defining the emission power (in Watts) in a particular band of the light spectrum (see surface shader radiant exitance element for more details). Each component of this vector must be greater or equal to 0.0.

Optional parameters:

• castshadow: valid values for this parameter are true and false. If set to true, this light will cast shadows through the scene. Otherwise, no shadow will be casted.

Declaration:

The pointlight object is a punctual light emitter located at the origin. It emits light equally in all directions.

Point lights have no physical (real life) equivalent. However, they can be very handy to approximate distant or small lights. They are the only lights producing true hard shadows.

Camera objects materialize scene observers. They don't have geometry, and thus don't appear themselves in renders.

At least one camera must be defined in the scene. Current version of toxic reports an error if more than one camera is defined, but future versions will allow to define several cameras, and will provide a way (an option on the command line, for example) to select one or multiple cameras at launch time.

Required parameters:

• None.

Optional parameters:

• hfov: value of the horizontal field of view in degrees. Default value is 70.0 degrees.
• aspectratio: aspect ratio of the image plane (aspect ratio + horizontal field of view define vertical field of view). Default value is width / height, where 'width' and 'height' are the dimensions of the rendered picture, in pixels. Default value produces square pixels.

Declaration:

The pinhole camera is the simplest one. Since it has infinite depth of field, objects can't be out of focus and thus never appear blurred.

Pinhole camera is located at the origin and looks toward Z-.

Declaration:

The thin lens camera is slightly more complex (and much more plausible) than the pinhole camera. It will produce depth of field according to the fstop, focaldistance and focallength parameters. Out of focus objects will appear blurred.

Required parameters:

• fstop: this is the aperture number or f-stop number. Lens diameter is computed as follow: lensdiameter = focallength / fstop.
• focallength: focal length of the camera, expressed in meters.

Additionally, one of the two following parameters must be defined:

• focaldistance: focal distance of the camera, expressed in meters. The focal distance is the distance along the view direction at which objects will be in focus.
• autofocus: 2-dimensional vector defining which point, in the image plane, must be in focus. The focus point is expressed in Normalized Device Coordinates (NDC): bottom left corner of the image plane is at (-0.5, -0.5), upper right corner is at (0.5, 0.5), regardless of the image resolution.

You can get the full XML Schema describing toxic scene files format here.

You can browse these sample files to get an idea of what a complete scene file looks like:

• cornellbox.xml
• gally.xml
• ring.xml

Note that this files do not constitute complete scenes. They refer to external files like mesh files and texture files which are not included here. You can download complete sample scenes from the Download page.