\section{Scene file format}
Mitsuba uses a very simple and general XML-based format to represent scenes.  
Since the framework's philosophy is to represent discrete blocks of functionality as plugins, 
a scene file can essentially be interpreted as description that determines which 
plugins should be instantiated and how they should be interface with each other.
In the following, we'll look at a few examples to get a feeling for the scope of the
format.

An simple scene with a single mesh and the default lighting and camera setup might look
something like this:
\begin{xml}
<?xml version="1.0" encoding="utf-8"?>
<scene>
	<shape type="obj">
		<string name="filename" value="dragon.obj"/>
	</shape>
</scene>
\end{xml}
This example already contains the most important things to know about format: you can have
\emph{objects} (such as the objects instantiated by the \code{scene} or \code{shape} tags), which are allowed to be nested within
each other. Each object optionally accepts \emph{properties} (such as the \code{string} tag),
which further characterize its behavior. All objects except for the root object (the \code{scene})
cause the renderer to load and instantiate a plugin, hence you must provide the plugin name using
\code{type=".."} parameter. 

The object tags also let the renderer know \emph{what kind} of object is to be instantiated: for instance, 
any plugin loaded using the \code{shape} tag must conform to the \emph{Shape} interface, which
the certainly case for the plugin named \code{obj} (it contains a WaveFront OBJ loader).
Similarly, you could write
\begin{xml}
<?xml version="1.0" encoding="utf-8"?>
<scene>
	<shape type="sphere">
		<float name="radius" value="10"/>
	</shape>
</scene>
\end{xml}
This loads a different plugin (\code{sphere}) which is still a \emph{Shape}, but instead represents 
a sphere configured with a radius of 10 world-space units. Mitsuba ships with 
a large number of plugins; please refer to the next chapter for a reference.

The most common scene setup is to declare an integrator, some geometry, a camera, a film, a sampler  
and one or more luminaires. Here is a more complex example:
\begin{xml}
<?xml version="1.0" encoding="utf-8"?>
<scene>
	<integrator type="path"> <!-- Path trace an 8-bounce GI solution -->
		<integer name="maxDepth" value="8"/>
	</integrator>
	<!-- Instantiate a perspective camera with 45 degrees field of view -->
	<camera type="perspective">
		<!-- Rotate the camera around the Y axis by 180 degrees -->
		<transform name="toWorld">
			<rotate y="1" angle="180"/>
		</transform>
		<float name="fov" value="45"/>

		<!-- Render with 32 samples per pixel using a basic
             independent sampling strategy -->
		<sampler type="independent">
			<integer name="sampleCount" value="32"/>
		</sampler>

		<!-- Generate an EXR image at HD resolution -->
		<film type="exrfilm">
			<integer name="width" value="1920"/>
			<integer name="height" value="1080"/>
		</film>
	</camera>

	<!-- Add a dragon mesh made of rough glass (stored as OBJ) -->
	<shape type="obj">
		<string name="filename" value="dragon.obj"/>

		<bsdf type="roughglass">
			<!-- Tweak the roughness parameter of the material -->
			<float name="alphaB" value="0.01"/>
		</bsdf>
	</shape>

	<!-- Add a mesh stored using a more compact representation -->
	<shape type="serialized">
		<string name="filename" value="lightsource.serialized"/>
		<transform name="toWorld">
			<translate x="5" x="-3" z="1"/>
		</transform>

		<!-- This mesh is an area luminaire -->
		<luminaire type="area">
			<rgb name="intensity" value="100,400,100"/>
		</luminaire>
	</shape>
</scene>
\end{xml}
\newpage
This example introduces several new object types (\code{integrator, camera, bsdf, sampler, film}, and \code{luminaire})
and property types (\code{integer}, \code{transform}, and \code{rgb}). 
As you can see in the example, objects are usually declared at the top level except if there is some
inherent relation that links them to another object. For instance, BSDFs are usually specific to a certain geometric object, so 
they appear as a child object of a shape. Similarly, the sampler and film affect the way in which
rays are generated from the camera and how it records the resulting radiance samples, hence they are nested inside it.

Note that you should always put properties \emph{before} nested child objects, otherwise you'll see something like the following slightly cryptic
 XML validation error. For instance,
\begin{xml}
...
	<shape type="obj">
		<bsdf type="phong"/>
		<string name="filename" value="lucy.obj"/>
	</shape>
...
\end{xml}
fails with this message:
\begin{shell}
Caught a critical exeption: 2010-08-11 03:23:31 ERROR main [src/mitsuba/shandler.cpp:359] Error in file "/home/wenzel/mitsuba/test.xml" (line 63): Element 'string' is not valid $\texttt{for}$ content model: '(((integer|float|point|vector|boolean|transform|string|spectrum|rgb)|blackbody),((bsdf|subsurface|ref)|luminaire))'
\end{shell}
\subsection{Property types}
This section documents all of the ways in which properties can be supplied to objects. If you are more
interested in knowing which properties a certain plugin accepts, you should look at the next section instead.
\subsubsection{Numbers}
Integer and floating point values can be passed as follows:
\begin{xml}
<integer name="intProperty" value="1234"/>
<float name="floatProperty" value="1.234"/>
<float name="floatProperty2" value="-1.5e3"/>
\end{xml}
Note that you must adhere to the format expected by the object, i.e. you can't pass an integer property
to an object, which expects a floating-point value associated with that name.
\subsubsection{Strings}
Passing strings is very straightforward:
\begin{xml}
<string name="stringProperty" value="This is a string"/>
\end{xml}
\subsubsection{Color spectra}
There are several different ways of passing color spectra to objects, which can be used interchangeably.
The most basic one is to supply linear RGB or sRGB values as floating-point triplets or hex values
\begin{xml}
<rgb name="spectrumProperty" value="0.2, 0.8, 0.4"/>
<srgb name="spectrumProperty" value="0.4, 0.3, 0.2"/>
<srgb name="spectrumProperty" value="#f9aa34"/>
\end{xml}
When Mitsuba is compiled with the default settings, it internally uses linear RGB to represent colors, so
these values are directly used. The renderer can also be configured to sample the color spectrum using a specified
number of samples, in which case the RGB values are first converted into spectra using a simple heuristic.

You can also directly supply the spectral color samples that Mitsuba internally uses if spectral rendering is
active. This unfortunately closely couples the interpretation of a scene to how Mitsuba is compiled, which can be a disadvantage.
For instance, the below example assumes that 6 spectral samples are being used:
\begin{xml}
<spectrum name="spectrumProperty" value="0.2, 0.8, 0.4, 0.6, 0.1, 0.9"/>
\end{xml}
A safer way is to specify a linearly interpolated spectral power distribution, which is converted into
the internal spectral representation as the scene is loaded.
\begin{xml}
<spectrum name="spectrumProperty" value="400:0.56, 500:0.18, 600:0.58, 700:0.24"/>
\end{xml}
This is essentially a mapping from wavelength in nanometers (before the colon) to a reflectance or intensity value (after the colon). Missing values are linearly interpolated from the two closest neighbors.

Finally, it is also possible to specify the spectral distribution of a black body emitter, where the temperature is given in Kelvin.
\begin{xml}
<blackbody name="spectrumProperty" temperature="10000"/>
\end{xml}
\subsubsection{Vectors, Positions}
Points and vectors can be specified as follows:
\begin{xml}
<point name="pointProperty" x="3" y="4" z="5"/>
<vector name="vectorProperty" x="3" y="4" z="5"/>
\end{xml}
It is important that whatever you choose as world-space units (meters, inches, etc.) is 
used consistently in all places.
\subsubsection{Transformations}
Transformations are the only kind of property, which require more than a single tag. The idea is that, starting
with the identity, you build up a transformation using nested commands. For instance, a transformation that 
does a translation followed by a rotation might be written like this:
\begin{xml}
<transform name="trafoProperty">
	<translate x="-1" y="3" z="4"/>
	<rotate y="1" angle="45"/>
</transform>
\end{xml}
Mathematically, each incremental transformation in the sequence is left-multiplied onto the current one. The following
choices are available:
\begin{itemize}
\item Translations, e.g.
\begin{xml}
<translate x="-1" y="3" z="4"/>
\end{xml}
\item Rotations around a specified direction. The angle is given in degrees, e.g.
\begin{xml}
<rotate x="0.701" y="0.701" z="0" angle="180"/>
\end{xml}
\item Scaling operations. The coefficients may also be negative to obtain a flip, e.g.
\begin{xml}
<scale x="2" y="1" z="-1"/>
\end{xml}
\item Explicit 4$\times$4 matrices, e.g
\begin{xml}
<matrix value="0 -0.53 0 -1.79 0.92 0 0 8.03 0 0 0.53 0 0 0 0 1"/>
\end{xml}
\item LookAt transformations --- this is useful for setting up the camera. The \textbf{o} coordinates
provide the camera origin, \textbf{t} specifies the target and \textbf{u} is the ``up'' direction.
\begin{xml}
<lookAt ox="10" oy="50" oz="-800" tx="0" ty="0" tz="0" ux="0" uy="1" uz="0"/>
\end{xml}
\end{itemize}
Cordinates that are zero (for \code{translate} and \code{rotate}) or one (for \code{scale})
do not explicitly have to be specified.
\newpage
\subsection{Instancing}
Quite often, you will find yourself using an object (such as a material) in many places. To avoid having
to declare it over and over again, which wastes memory, you can make use of references. Here is an example
of how this works:
\begin{xml}
<scene>
	<texture type="ldrtexture" id="myImage">
		<string name="filename" value="textures/myImage.jpg"/>
	</texture>

	<bsdf type="lambertian" id="myMaterial">
		<!-- Reference the texture named myImage and pass it 
			to the BRDF as the reflectance channel -->
		<ref name="reflectance" id="myImage"/>
	</bsdf>

	<shape type="obj">
		<string name="filename" value="meshes/myShape.obj"/>

		<!-- Reference the material named myMaterial -->
		<ref id="myMaterial"/>
	</shape>
</scene>
\end{xml}
Note that this feature cannot yet be used to do geometry instancing.
\subsection{Including external files}
A scene can be split into multiple pieces for better readability. 
to include an external file, please use the following command:
\begin{xml}
<include filename="nested-scene.xml"/>
\end{xml}
In this case, the file \code{nested-scene.xml} must still be a proper scene file with a \code{<scene>} tag at the root.
This feature is sometimes very convenient in conjunction with the \code{-D key=value} flag of the \code{mitsuba} command line renderer (see the previous section for details).
This lets you include different parts of a scene configuration by changing the command line parameters (and without having to touch the XML file):
\begin{xml}
<include filename="nested-scene-$\texttt{\$}$version.xml"/>
\end{xml}
