From 901fc493c4dbd1ab05614d0dcc13a33c897d09d4 Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Wed, 11 Aug 2010 20:00:16 +0200 Subject: [PATCH] format documentation is done --- doc/format.tex | 163 ++++++++++++++++++++++++++++++++++++++++++------- doc/main.tex | 3 +- 2 files changed, 144 insertions(+), 22 deletions(-) diff --git a/doc/format.tex b/doc/format.tex index 627160de..19a1e500 100644 --- a/doc/format.tex +++ b/doc/format.tex @@ -1,12 +1,13 @@ \section{Scene file format} Mitsuba uses a very simple and general XML-based format to represent scenes. -The framework's underlying approach is to represents discrete blocks of functionality as plugins, -hence a scene file can essentially be interpreted as description that determines which +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 might looks like this +An simple scene with a single mesh and the default lighting and camera setup might look +something like this: \begin{xml} @@ -17,14 +18,15 @@ An simple scene might looks like this \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 \code{string}), +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 tags let the renderer know what kind of object is to be instantiated: for instance \code{obj} is a -WaveFront OBJ loader, which conforms to the \emph{Shape} interface. Similarly, -you could write +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} @@ -45,8 +47,6 @@ and one or more luminaires. Here is a more complex example: - - @@ -92,14 +92,15 @@ and one or more luminaires. Here is a more complex example: \end{xml} -This example introduces several new object types (\code{integrator, camera, sampler, film, bsdf}, and \code{luminaire}) -and a few property types (\code{integer}, \code{transform}, and \code{rgb}). -Objects are usually declared at the top level except if there is some -inherent relation that links them to another object. For example, BSDFs are usually specific to a certain geometric object, so -they appear as a child object of a shape. Similarly, the sampler and film both affect the way in which -rays are generated from the camera, hence they are nested inside it. +\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 before nested child objects, otherwise you'll see something like the following slightly cryptic +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} ... @@ -109,15 +110,135 @@ Note that you should always put properties before nested child objects, otherwis ... \end{xml} -produces +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} -\subsubsection{Spectra} -\subsubsection{Transformations} -\subsubsection{Vectors, Positions} +Integer and floating point values can be passed as follows: +\begin{xml} + + + +\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} -\subsection{Instancing materials} +Passing strings is very straightforward: +\begin{xml} + +\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 values as floating-point triplets or hex values +\begin{xml} + + +\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} + +\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} + +\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} + +\end{xml} +\subsubsection{Vectors, Positions} +Points and vectors can be specified as follows: +\begin{xml} + + +\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} + + + + +\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} + +\end{xml} +\item Rotations around a specified direction. The angle is given in degrees, e.g. +\begin{xml} + +\end{xml} +\item Scaling operations. The coefficients may also be negative to obtain a flip, e.g. +\begin{xml} + +\end{xml} +\item Explicit 4$\times$4 matrices, e.g +\begin{xml} + +\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} + +\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} + + + + + + + + + + + + + + + + + +\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} + +\end{xml} +In this case, the file \code{nested-scene.xml} must still be a proper scene file with a \code{} 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} + +\end{xml} diff --git a/doc/main.tex b/doc/main.tex index 55a829d8..dbf2b8c9 100644 --- a/doc/main.tex +++ b/doc/main.tex @@ -79,7 +79,8 @@ keywordstyle = \bfseries, commentstyle=\color{lstcomment}\itshape, basicstyle = \small\ttfamily, - breaklines = true + breaklines = true, + showstringspaces = false } \lstnewenvironment{cpp}{\lstset{language=c++}}