246 lines
11 KiB
TeX
246 lines
11 KiB
TeX
\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}
|