Skip to content

Project File Format

Jump to bottom Edit New page
François Beaune edited this page Feb 25, 2014 · 1 revision
File Format Revision 7 -- appleseed 1.1.0 alpha-21

This document describes the appleseed project 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.

The appleseed project file format is not cast in stone. Although it is fairly stable, new releases of appleseed often bring small changes to the file format such as new entity models, new parameters or new attributes. Therefore the only version of appleseed that is guaranteed to match this specification exactly is the one stated at the top of this document. Note however that appleseed can always open project files using an older revision of the file format, and can automatically upgrade project files to the latest format revision.

In order to improve the quality of this document, please report (or better, fix!) errors, typos, omissions as well as incomplete or unclear material.

Table of Contents

### 1. Introduction

The appleseed project file format is based on the XML standard. XML is a textual format with a strict, well-defined syntax and a large ecosystem of authoring tools and parsers.

The choice of XML was motivated as follow:

  • As a textual format, it is easy to read, modify, author, diff and merge.
  • It has a strict, well-defined syntax.
  • With XML Schema, it is possible to define a strict grammar and enforce it at runtime.
  • It has a rich ecosystem of authoring tools and parsers.

A quick XML recap:

  • The order of attributes is irrelevant.
  • Comments take the following form:
<!-- a comment -->
  • Comments can spawn several lines.
  • All XML elements need closing tags.
  • An empty element (an element without text or child element) can be closed as follow:
<parameter name="x" value="42" />

This is equivalent to:

<parameter name="x" value="42"></parameter>

Traditionally, appleseed project files use the .appleseed extension.

### 2. Conventions

2.1. Coordinate System

appleseed uses a right-handed coordinate system, where X+ (positive X axis) points to the right, Y+ points upward and Z+ points out of the screen, toward the viewer.

2.2. Units

appleseed is not tied to the use of particular units (e.g. for distance). Any unit (like meters or inches) may be used as long as it is used consistently for the whole scene and all other measures (e.g. radiance) are scaled appropriately.

2.3. Identifiers

Identifiers, such as entity names, are user-defined strings assigned to entities in order to uniquely identify them within a scene and allow entities to reference each other.

Identifiers can use any characters that is allowed by the XML standard, including spaces. Identifiers are case-sensitive: “bunny" and “Bunny" are considered distinct identifiers.

2.4. Scopes

A scope is a context in which an entity can be defined and used. The scene defines a scope, and each assembly defines its own distinct scope.

When an entity A references another entity B, the referenced entity B is first searched in the same scope as entity A, then in the immediately parent scope, then in the next parent scope, etc.

For instance, if a BSDF located in an assembly references a color (by name), a color with this name will be first searched in the scope of the assembly containing the BSDF. If a color with this name is found in this scope, it will be bound to the BSDF. Otherwise, it will be searched in the parent scope, in this case the scope of the scene. If one is found there, it will be bound to the BSDF, otherwise an error will be emitted and rendering will stop since there is no other scope to look for the color.

### 3. Concepts

3.1. Assemblies

An assembly is a part of a scene. It can either be fully self-contained, or it can reference elements from the parent scene, but in no circumstances can an assembly reference elements from another assembly.

Assemblies can be loaded on-demand by the renderer (lazy loading). They can also be unloaded (“flushed") during rendering to free some memory. Finally, an assembly can be rotated, translated or scaled during rendering, at virtually no cost (but rendering will be started again from scratch).

Assemblies can also be instantiated multiple times: that is, an assembly can be replicated many times in the scene with a minimal impact on memory usage. Assemblies are a relatively heavyweight primitive and should be used sparsely (TODO: measure the real cost of assemblies).

3.2. Objects

An object is a geometric entity: it defines a shape and assigns materials to it.

All objects of an assembly are loaded when the assembly is loaded. Individual objects cannot be unloaded. Objects can be instantiated but there is no memory advantage in doing so (objects’ geometry is replicated).

3.3. Instances

appleseed distinguishes entities and entity instances. For instance, objects, assemblies and textures are entities. They cannot be used or referenced directly: they must be instantiated first. Instantiating an entity usually means placing it in the scene (defining its position, orientation and scale) and often allows setting additional parameters on the instance.

The sections 4.2.1 (assembly instances), 4.2.1.7 (object instances) and 4.2.8 (texture instances) detail which additional parameters can be set on those particular instance types.

3.4. The Material Model

In appleseed, the appearance of objects is defined by materials. A material is a collection of entities defining its light reflection, light emission and shading properties.

The principal characteristic of a material is its appearance when lit by an exterior light source, that is how it reflects (for opaque materials) or transmits (for transparent materials) the incoming light. In appleseed, the reflection/transmission properties of a material are defined by Bidirectional Scattering Distribution Functions (BSDF). A BSDF characterizes how much of the light energy coming from a given direction is reflected/transmitted in another given direction.

BSDF fall into two broad categories:

  • BRDF (for Bidirectional Reflection Distribution Functions) define how light is reflected by the surface of opaque materials.
  • BTDF (for Bidirectional Transmission Distribution Functions) define how light is transmitted through the surface of transparent or translucent materials.

In appleseed, a material may also emit light. The light emission properties of a material are defined by Emission Distribution Functions (EDF). An EDF characterizes the amount of light energy (intensity and “color") emitted in a given direction

If a material has no EDF associated, it doesn’t emit light.

Finally, an appleseed material must define a surface shader which will describe how directly visible surfaces (surfaces that are directly visible to the camera) are rendered. For physically-based rendering, a “physical" surface shader must be used: it simply uses the EDF and BSDF of the material to determine the appearance of directly visible surfaces.

### 4. File Structure

4.1. General File Structure

A valid project file should start with a XML declaration specifying the version of XML being used and the encoding of the file, although this is not strictly required by the XML recommendation:

<?xml version="1.0" encoding="UTF-8"?>

The file should then contain the root element :

<project>
...
</project>

The <project> element must contain, in this order:

  1. A <scene> element containing the description of the scene contents.
  2. An optional <rules> element containing various "rules" to modify the scene.
  3. An <output> element containing the description of the desired outputs.
  4. A <configurations> element containing the rendering parameters.

A valid project file thus always adheres to the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <scene>
        <!-- Description of the scene contents goes here -->
    </scene>
    <rules>
        <!-- Scene modification rules go here (this whole block is optional). -->
    </rules>
    <output>
        <!-- Description of the desired outputs goes here -->
    </output>
    <configurations>
        <!-- Rendering parameters organized in configurations go here -->
    </configurations>
</project>

4.1. Element Hierarchy

This section summarizes the allowed parent/child relationships between elements.

The following symbols are used to denote order and cardinality:

  • !: the element must appear exactly once, at a fixed location in the parent element.
  • +: the element may appear at most once, at a fixed location in the parent element.
  • ?: the element may appear at most once, anywhere in the parent element.
  • *: the element may appear zero or multiple times anywhere in the parent element.

Here is the main hierarchy:

Here is the hierarchy for <color> elements:

Here is the hierarchy for <transform> elements:

#### 4.32. The `` Element
Description

The <alpha> element is used to define the alpha channel in color entities.

Attributes

None.

Child Elements

None.

Parent Elements

<color>.

Example
<alpha>1.0</alpha>
#### 4.1. The `` Element
Description

The <assembly> element defines a new assembly.

Attributes
Attribute Presence Description
name Required The name of the assembly.
Child Elements

<bsdf>, <color>, <edf>, <light>, <material>, <object>, <object_instance>, <surface_shader>, <texture>, <texture_instance>.

Parent Elements

<assembly>, <scene>.

#### 4.2. The `` Element
Description

The <assembly_instance> element places ("instantiates") an existing assembly into the scene or a parent assembly.

Attributes
Attribute Presence Description
name Required The name of the assembly instance.
assembly Required The name of the assembly to instantiate.
Child Elements

<transform>.

Parent Elements

<assembly>, <scene>.

#### 4.3. The `` Element
Description

The <assign_material> element allows to assign an existing material to a given slot of an object, within an object instance. Material assignments are local to an object instance, i.e. distinct instances of the same object may use distinct material assignments.

Attributes
Attribute Presence Description
slot Required The slot to assign the material to.
side Optional The side to assign the material to. The default is front.
material Required The name of the material to assign.

The side attribute must be set to one of the following values:

  • front: the material will be assigned to the front side of the object's surface.
  • back: the material will be assigned to the back side of the object's surface.

The front side of an object's surface is the side seen from the half space pointed by the shading (smooth) normals of that surface.

Child Elements

None.

Parent Elements

<object_instance>.

Example

The following declaration assigns the “wood" material to the front side of the "door" slot of the object:

<assign_material slot="door" side="front" material="wood" />
#### 4.4. The `` Element
Description

The <bsdf> element instantiates a new Bidirectional Scattering Distribution Function (BSDF).

See the Built-in Entities document for the list of available built-in BSDF models.

Attributes
Attribute Presence Description
name Required The name of the BSDF.
model Required The model of the BSDF.
Child Elements

None.

Parent Elements

<assembly>.

#### 4.5. The `` Element
Description

The <camera> element defines a new camera.

See the Built-in Entities document for the list of available built-in camera models.

Attributes
Attribute Presence Description
name Required The name of the camera.
model Required The model of the camera.
Child Elements

<transform>.

Parent Elements

<scene>.

#### 4.6. The `` Element
Description

The <color> element defines a new color or spectrum.

In appleseed, colors must be defined before they can be referenced by other entities. The reason is that colors may be large and complex entities, unlike in most other renderers where they are just (red, green, blue) triplets.

Attributes
Attribute Presence Description
name Required The name of the color.
Parameters
Parameter Presence Description
color_space Required Set the color space in which the color is defined.
wavelength_range See below Define the range of wavelengths covered by the spectrum values.

The color_space parameter must be set to one of the following values:

  • linear_rgb: the color is defined a linear RGB triplet.
  • srgb: the color is defined by a triplet in the sRGB color space.
  • ciexyz: the color is defined by a triplet in the CIE XYZ color space.
  • spectral: the color is defined by a set of regularly spaced spectral amplitudes over a given wavelength range.

The default value of the color_space parameter is srgb.

If color_space is set to spectral, the wavelength_range parameter must be set to a pair of values defining the range of wavelengths (in nanometers) covered by the spectral values.

Child Elements

<alpha>, <values>.

Parent Elements

<assembly>, <scene>.

Examples

A 30% opaque red color in the sRGB color space:

<color name="transparent_red">
    <parameter name="color_space" value="srgb" />
    <values>1.0 0.0 0.0</values>
    <alpha>0.3</alpha>
</color>

The green reflectance of the Cornell Box scene is defined as a spectrum over the wavelength range 400-700 nm:

<color name="green">
    <parameter name="color_space" value="spectral" />
    <parameter name="wavelength_range" value="400 700" />
    <values>
        0.092000 0.097562 0.095000 0.096188 0.097000 0.098250 0.104000 0.110437
        0.125000 0.172125 0.285000 0.413625 0.472000 0.472750 0.441000 0.389875
        0.337000 0.279875 0.250000 0.196000 0.160000 0.138437 0.126000 0.121563
        0.114000 0.117063 0.120000 0.129937 0.144000 0.150937 0.159000
    </values>
    <alpha>
        1.0
    </alpha>
</color>
#### 4.7. The `` Element
Description

The <configuration> element defines a new rendering configuration. A configuration is a named collection of parameters.

An arbitrary number of configurations can be defined. The order in which configurations are defined is irrelevant. Like for any entity, the order of the parameters inside a configuration is irrelevant.

A configuration can inherit from another configuration using the base attribute.

A valid project file must define at least the following configurations:

  • The final configuration is used for final frame rendering.
  • The interactive configuration is used for interactive rendering.

There are two built-in configurations called base_final and base_interactive that can be used as convenient starting points for the final and interactive configurations.

The base_final configuration is defined as follow:

<configuration name="base_final">
    <parameter name="frame_renderer" value="generic" />
    <parameter name="tile_renderer" value="generic" />
    <parameter name="pixel_renderer" value="uniform" />
    <parameters name="uniform_pixel_renderer">
        <parameter name="samples" value="64" />
    </parameters>
    <parameter name="sample_renderer" value="generic" />
    <parameter name="lighting_engine" value="pt" />
</configuration>

The base_interactive configuration is defined as follow:

<configuration name="base_interactive">
    <parameter name="frame_renderer" value="progressive" />
    <parameter name="sample_generator" value="generic" />
    <parameter name="sample_renderer" value="generic" />
    <parameter name="lighting_engine" value="pt" />
</configuration>
Attributes
Attribute Presence Description
name Required The name of the configuration.
base Optional The name of the configuration to inherit from.
Child Elements

None.

Parent Elements

<configurations>.

#### 4.8. The `` Element
Description

The <configurations> element is the root element for <configuration> elements.

Attributes

None.

Child Elements

<configuration>.

Parent Elements

<project>.

#### 4.9. The `` Element
Description

The <edf> element instantiates a new Emission Distribution Function (EDF).

See the Built-in Entities document for the list of available built-in EDF models.

Attributes
Attribute Presence Description
name Required The name of the EDF.
model Required The model of the EDF.
Child Elements

None.

Parent Elements

<assembly>.

#### 4.10. The `` Element
Description

Similarly to how the <material> element defines a material as a collection of a BSDF, an EDF and a surface shader, the <environment> element defines an environment as a collection of an environment EDF and an environment shader.

See the Built-in Entities document for the list of available built-in environment models.

Attributes
Attribute Presence Description
name Required The name of the environment.
model Required The model of the environment.
Child Elements

None.

Parent Elements

<scene>.

#### 4.11. The `` Element
Description

The <environment_edf> element defines a new environment Emission Distribution Function. An environment EDF is responsible for emitting light from the environment into the scene.

See the Built-in Entities document for the list of available built-in environment EDF models.

Attributes
Attribute Presence Description
name Required The name of the environment EDF.
model Required The model of the environment EDF.
Child Elements

None.

Parent Elements

<scene>.

#### 4.12. The `` Element
Description

The <environment_shader> element defines a new environment shader. An environment shader is responsible for shading pixels that are not covered by any geometry and thus belong to the environment.

See the Built-in Entities document for the list of available built-in environment shader models.

Attributes
Attribute Presence Description
name Required The name of the environment shader.
model Required The model of the environment shader.
Child Elements

None.

Parent Elements

<scene>.

#### 4.13. The `` Element
Description

The <frame> element defines a frame that should be produced by the renderer.

A frame is a rectangular array of pixels. A frame is divided into tiles.

Attributes
Attribute Presence Description
name Required The name of the frame.
Parameters
Parameter Presence Description
clamping Optional A boolean parameter indicating whether pixel values should be clamped in the [0, 1] range. This parameter only makes sense when pixel_format is set to half, float or double. The default is false.
color_space Optional The color space in which pixel values are expressed. The default is linear_rgb.
filter Optional The reconstruction filter used to reconstruct the frame from individual point samples. The default is gaussian.
filter_size Optional The radius in pixels of the reconstruction filter. The default is 2.0.
gamma_correction Optional The gamma correction applied to pixel values. The default is 1.0.
pixel_format Optional The data type used to represent pixel values. The default is half.
premultiplied_alpha Optional If true, pixel values are expressed using premultipled alpha, otherwise they are expressed using straight alpha. The default is true.
resolution Required The dimensions in pixels of the frame. The syntax is width height.
tile_size Optional The dimensions in pixels of a tile. The syntax is width height. The default is 64 64.

The color_space parameter must be set to one of the following values:

The filter parameter must be set to one of the following values:

  • box: a simple box filter.
  • triangle: a triangle filter (also called a cone or tent filter).
  • gaussian: a Gaussian filter.
  • mitchell: a Mitchell-Netravali filter.
  • bspline: a cardinal B-Spline filter.
  • catmull: a Catmull-Rom filter.
  • lanczos: a Lanczos filter.
  • blackman-harris: a Blackman-Harris filter.

The pixel_format parameter must be set to one of the following values:

  • uint8: 8-bit unsigned integer per channel.
  • uint16: 16-bit unsigned integer per channel.
  • uint32: 32-bit unsigned integer per channel.
  • half: 16-bit floating point value per channel.
  • float: 32-bit floating point value per channel.
  • double: 64-bit floating point value per channel.
Child Elements

None.

Parent Elements

<output>.

#### 4.14. The `` Element
Description

The <light> element defines and instantiates a new shape-less light.

See the Built-in Entities document for the list of available built-in light models.

Attributes
Attribute Presence Description
name Required The name of the light.
model Required The model of the light.
Child Elements

<transform>.

Parent Elements

<assembly>.

#### 4.15. The `` Element
Description

The <look_at> element provides a convenient way to position an observer (such as a camera) in space and orient it such that it "looks" at a specific point called the point of interest.

Attributes
Attribute Presence Description
origin Required The position of the observer (3D point).
target Required The point of interest (3D point).
up Required The up vector (3D vector).
Child Elements

None.

Parent Elements

<transform>.

Examples

The following defines a transformation such that the observer is at the position (0, 1, -3), is looking toward the origin at (0, 0, 0) and the up vector is Y+ (0, 1, 0):

<look_at origin="0.0 1.0 -3.0" target="0.0 0.0 0.0" up="0.0 1.0 0.0" />
#### 4.16. The `` Element
Description

The <material> element defines a new material.

See the Built-in Entities document for the list of available built-in material models.

Attributes
Attribute Presence Description
name Required The name of the material.
model Required The model of the material.
Child Elements

None.

Parent Elements

<assembly>.

#### 4.17. The `` Element
Description

The <matrix> element defines a transformation as a 4x4 row-major matrix.

appleseed uses premultiplication: a vector v is transformed by a matrix M by the left-multiplying the vector by the matrix: v’ = M · v.

Attributes

None.

Child Elements

None.

Parent Elements

<transform>.

Examples

Identity matrix:

<matrix>
    1.0 0.0 0.0 0.0
    0.0 1.0 0.0 0.0
    0.0 0.0 1.0 0.0
    0.0 0.0 0.0 1.0
</matrix>

Translation by (3.0, 4.0, 5.0):

<matrix>
    1.0 0.0 0.0 3.0
    0.0 1.0 0.0 4.0
    0.0 0.0 1.0 5.0
    0.0 0.0 0.0 1.0
</matrix>
#### 4.18. The `` Element
Description

The <object> element defines a new geometric object. The object is not placed ("instantiated") in the assembly; this is done using the <object_instance> element.

See the Built-in Entities document for the list of available built-in object models.

Attributes
Attribute Presence Description
name Required The name of the object.
model Required The model of the object.
Child Elements

None.

Parent Elements

<assembly>.

#### 4.19. The `` Element
Description

The <object_instance> element places ("instantiates") an existing object into an assembly, defining its pose and its materials.

Attributes
Attribute Presence Description
name Required The name of the object instance.
object Required The name of the object to instantiate.
Child Elements

<assign_material>, <transform>.

Parent Elements

<assembly>.

#### 4.20. The `` Element
Description

The <output> element is the root element for elements that describe the outputs the renderer must produce.

Attributes

None.

Child Elements

<frame>.

Parent Elements

<project>.

#### 4.21. The `` Element
Description

The <project> element is the root element of an appleseed project file.

Attributes
Attribute Presence Description
format_revision Optional The revision number of the file format followed by the project file.

If the format_revision parameter is omitted, the project file is assumed to follow revision 2 of the project file format.

Child Elements

<configurations>, <output>, <rules>, <scene>.

Parent Elements

None.

#### 4.22. The `` Element
Description

The <rules> element is the root element for scene modification rules such as render layer assignment rules, etc.

Attributes

None.

Child Elements

<render_layer_assignment>.

Parent Elements

<project>.

#### 4.23. The `` Element
Description

The <render_layer_assignment> element defines a rule to assign entities to render layers. Multiple rules can be defined: all rules will be applied, in the order defined by the value of their order parameters.

See the Built-in Entities document for the list of available built-in render layer rule models.

Attributes
Attribute Presence Description
name Required The name of the rule.
model Required The model of the rule.
Parameters

These parameters are common to all render layer rule models.

Parameter Presence Description
render_layer Required The name of the render layer entities will be assigned to. This name is also used to construct the name of the render layer file. Variable substitution is supported, see below for the list of known variables.
entity_type Optional If specified, restrict the rule to entities of this type.
order Required A positive or negative integer which defines the precedence of this rule with respect to the other rules. Rules are applied in increasing order. The order of application of rules with identical order values is undefined.

If defined, the entity_type parameter must be set to one of the following values:

  • assembly
  • assembly_instance
  • edf
  • environment_edf
  • environment_shader
  • light
  • material
  • object
  • object_instance
  • surface_shader

The render layer name may contain variables that will be susbtituted with their value at render time. The known variables are:

  • {entity-name} : the name of the entity assigned to this render layer.
  • {entity-path} : the path of the entity assigned to this render layer.
Child Elements

None.

Parent Elements

<rules>.

#### 4.24. The `` Element
Description

The <rotation> element defines a rotation around an arbitrary axis in space.

Attributes
Attribute Presence Description
axis Required The axis of rotation (3D vector).
angle Required The angle of rotation in degrees.
Child Elements

None.

Parent Elements

<transform>.

Examples

The following defines a rotation by -45° around the X axis (1, 0, 0):

<rotation axis="1.0 0.0 0.0" angle="-45.0" />
#### 4.25. The `` Element
Description

The <scaling> element defines a non-uniform scaling.

Attributes
Attribute Presence Description
value Required The scaling factor (3D vector).
Child Elements

None.

Parent Elements

<transform>.

Examples

The following defines a scaling by a factor of 2 along the X axis, by a factor of 10 along Y and by a factor of 0.1 along Z:

<scaling value="2.0 10.0 0.1" />
#### 4.26. The `` Element
Description

The <scene> element is the root element for the description of the scene contents. All the elements that describes the contents or the appearance of the scene are children of the <scene> element. Inside the <scene> element, the order of the child elements is irrelevant.

Attributes

None.

Child Elements

<assembly>, <assembly_instance>, <camera>, <color>, <environment>, <environment_edf>, <environment_shader>, <texture>, <texture_instance>.

Parent Elements

<project>.

#### 4.27. The `` Element
Description

The <surface_shader> element defines a new surface shader. A surface shader is responsible for shading pixels covered by geometry. Typically, the Physical surface shader is used to trigger physically-based shading using the BSDFs, EDFs and lights of the scene.

See the Built-in Entities document for the list of available built-in surface shader models.

Attributes
Attribute Presence Description
name Required The name of the surface shader.
model Required The model of the surface shader.
Child Elements

None.

Parent Elements

<assembly>.

#### 4.28. The `` Element
Description

The <texture> element defines a new texture.

Textures cannot be used directly by other entities; they must first be instantiated with the <texture_instance> element.

See the Built-in Entities document for the list of available built-in texture models.

Attributes
Attribute Presence Description
name Required The name of the texture.
model Required The model of the texture.
Child Elements

None.

Parent Elements

<assembly>, <scene>.

#### 4.29. The `` Element
Description

The <texture_instance> element instantiates an existing texture and gives it additional characteristics.

Attributes
Attribute Presence Description
name Required The name of the texture instance.
texture Required The name of the texture to instantiate.
Child Elements

None.

Parent Elements

<assembly>, <scene>.

#### 4.30. The `` Element
Description

The <transform> element allows to define the position, orientation and scaling of entities (assembly and object instances, cameras, lights, etc.) as the composition of multiple transformation primitives.

A <transform> element may contain an arbitrary number of transformation primitives. These transformation primitives are applied to the entity in the order of their appearance inside the <transform> element. If the <transform> element is empty, it represents the identity transformation.

Attributes
Attribute Presence Description
time Optional The time at which this transform is defined. The default is 0.0.
Child Elements

<look_at>, <matrix>, <rotation>, <scaling>, <translation>.

Parent Elements

<assembly_instance>, <camera>, <light>, <object_instance>.

#### 4.31. The `` Element
Description

The <translation> element defines a translation in space.

Attributes
Attribute Presence Description
value Required The translation amount (3D vector).
Child Elements

None.

Parent Elements

<transform>.

Examples

The following defines a translation of 1 unit along the X axis, 2 units along Y and 3 units along Z:

<translation value="1.0 2.0 3.0" />
#### 4.32. The `` Element
Description

The <values> element is used to define spectral amplitudes in color entities.

Attributes

None.

Child Elements

None.

Parent Elements

<color>.

Example
<values>1.0 -2.0 0 3.0004</values>
Add a custom footer
Add a custom sidebar
Clone this wiki locally