-
Notifications
You must be signed in to change notification settings - Fork 332
Project File Format
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.
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.
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.
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.
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.
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.
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).
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).
appleseed distinguishes entities and entity instances. 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.
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.
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:
- A
<scene>element containing the description of the scene contents. - An optional
<rules>element containing various "rules" to modify the scene. - An
<output>element containing the description of the desired outputs. - 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>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:
-
<project>!
Here is the hierarchy for <color> elements:
Here is the hierarchy for <transform> elements:
The <alpha> element is used to define the alpha channel in color entities.
None.
None.
<alpha>1.0</alpha>The <assembly> element defines a new assembly.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the assembly. |
<bsdf>, <color>, <edf>, <light>, <material>, <object>, <object_instance>, <surface_shader>, <texture>, <texture_instance>.
The <assembly_instance> element places ("instantiates") an existing assembly into the scene or a parent assembly.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the assembly instance. |
assembly |
Required | The name of the assembly to instantiate. |
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.
| 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. -
both: the material will be assigned to both sides 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.
None.
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" />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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the BSDF. |
model |
Required | The model of the BSDF. |
None.
The <camera> element defines a new camera.
See the Built-in Entities document for the list of available built-in camera models.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the camera. |
model |
Required | The model of the camera. |
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the color. |
| 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.
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>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
finalconfiguration is used for final frame rendering. - The
interactiveconfiguration 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>| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the configuration. |
base |
Optional | The name of the configuration to inherit from. |
None.
The <configurations> element is the root element for <configuration> elements.
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the EDF. |
model |
Required | The model of the EDF. |
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the environment. |
model |
Required | The model of the environment. |
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the environment EDF. |
model |
Required | The model of the environment EDF. |
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the environment shader. |
model |
Required | The model of the environment shader. |
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the frame. |
| 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:
-
linear_rgb: pixels are expressed in the linear RGB color space. -
srgb: pixels are expressedin the sRGB color space. -
ciexyz: pixels are expressedin the CIE XYZ color space.
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.
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the light. |
model |
Required | The model of the light. |
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.
| 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). |
None.
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" />The <material> element defines a new material.
See the Built-in Entities document for the list of available built-in material models.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the material. |
model |
Required | The model of the material. |
None.
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.
None.
None.
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>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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the object. |
model |
Required | The model of the object. |
None.
The <object_instance> element places ("instantiates") an existing object into an assembly, defining its pose and its materials.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the object instance. |
object |
Required | The name of the object to instantiate. |
<assign_material>, <transform>.
The <output> element is the root element for elements that describe the outputs the renderer must produce.
None.
The <project> element is the root element of an appleseed project file.
| 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.
<configurations>, <output>, <rules>, <scene>.
None.
The <rules> element is the root element for scene modification rules such as render layer assignment rules, etc.
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the rule. |
model |
Required | The model of the rule. |
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:
assemblyassembly_instanceedfenvironment_edfenvironment_shaderlightmaterialobjectobject_instancesurface_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.
None.
The <rotation> element defines a rotation around an arbitrary axis in space.
| Attribute | Presence | Description |
|---|---|---|
axis |
Required | The axis of rotation (3D vector). |
angle |
Required | The angle of rotation in degrees. |
None.
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" />The <scaling> element defines a non-uniform scaling.
| Attribute | Presence | Description |
|---|---|---|
value |
Required | The scaling factor (3D vector). |
None.
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" />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.
None.
<assembly>, <assembly_instance>, <camera>, <color>, <environment>, <environment_edf>, <environment_shader>, <texture>, <texture_instance>.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the surface shader. |
model |
Required | The model of the surface shader. |
None.
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.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the texture. |
model |
Required | The model of the texture. |
None.
The <texture_instance> element instantiates an existing texture and gives it additional characteristics.
| Attribute | Presence | Description |
|---|---|---|
name |
Required | The name of the texture instance. |
texture |
Required | The name of the texture to instantiate. |
None.
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.
| Attribute | Presence | Description |
|---|---|---|
time |
Optional | The time at which this transform is defined. The default is 0.0. |
<look_at>, <matrix>, <rotation>, <scaling>, <translation>.
<assembly_instance>, <camera>, <light>, <object_instance>.
The <translation> element defines a translation in space.
| Attribute | Presence | Description |
|---|---|---|
value |
Required | The translation amount (3D vector). |
None.
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" />The <values> element is used to define spectral amplitudes in color entities.
None.
None.
<values>1.0 -2.0 0 3.0004</values>