Running Nori
Nori can be run in the command line by specifying the path to an XML scene file:
$ ./nori path/to/scene.xml
Nori also takes an optional argument
--threads (or
-t) that specifies
the number of threads to use to render the scene:
$ ./nori path/to/scene.xml --threads 4
If the argument is not specified, TBB automatically chooses the number of threads.
Scene file format and parsing
Take a moment to browse through the header files in
include/nori. You will generally find all important
interfaces and their documentation in this place. Most headers
files also have a corresponding .cpp implementation file
in the src directory.
The most important class is called NoriObject—it is
the base class of everything that can be constructed using the XML
scene description language. Other interfaces (e.g. Camera)
derive from this class and expose additional more specific
functionality (e.g. to generate an outgoing ray from a camera).
Nori uses a very simple XML-based scene description language, which
can be interpreted as a kind of building plan: the parser creates
the scene step by step as it reads the scene file from top to
bottom. The XML tags in this document are interpreted as requests
to construct certain C++ objects including information on how to
put them together.
Each XML tag is either an object or a property. Objects
correspond to C++ instances that will be allocated on the heap. Properties are
small bits of information that are passed to an object at the time of its
instantiation.
For instance, the following snippet creates red diffuse BSDF:
<bsdf type="diffuse">
<color name="albedo" value="0.5, 0, 0"/>
</bsdf>
Here, the <bsdf> tag will cause the
creation of an object of type BSDF, and the
type attribute specifies what specific subclass
of BSDF should be used.
The <color> tag creates a property of name albedo
that will be passed to its constructor.
If you open up the C++ source file src/diffuse.cpp, you will see that
there is a constructor, which looks for
this specific property:
Diffuse(const PropertyList &propList) {
m_albedo = propList.getColor("albedo", Color3f(0.5f));
}
The piece of code that associates the
"diffuse" XML identifier with the Diffuse
class in the C++ code is a macro found at the bottom of the file:
NORI_REGISTER_CLASS(Diffuse, "diffuse");
Certain objects can be nested hierarchically. For
example, the following XML snippet creates a mesh that loads its
contents from an external OBJ file and assigns a red diffuse BRDF
to it.
<mesh type="obj">
<string type="filename" value="bunny.obj"/>
<bsdf type="diffuse">
<color name="albedo" value="0.5, 0, 0"/>
</bsdf>
</mesh>
Implementation-wise, this kind of nesting will cause a method named
addChild() to be invoked within the parent object. In this
specific example, this means that Mesh::addChild() is
called, which roughly looks as follows:
void Mesh::addChild(NoriObject *obj) {
switch (obj->getClassType()) {
case EBSDF:
if (m_bsdf)
throw NoriException(
"Mesh: multiple BSDFs are not allowed!");
/// Store pointer to BSDF in local instance
m_bsdf = static_cast<BSDF *>(obj);
break;
// ..(omitted)..
}
This function verifies that the nested object is a BSDF, and that no BSDF was specified
before; otherwise, it throws an exception of type
NoriException.
The following different types of properties can currently be passed to
objects within the XML description language:
<!-- Basic parameter types -->
<string name="property name" value="arbitrary string"/>
<boolean name="property name" value="true/false"/>
<float name="property name" value="float value"/>
<integer name="property name" value="integer value"/>
<vector name="property name" value="x, y, z"/>
<point name="property name" value="x, y, z"/>
<color name="property name" value="r, g, b"/>
<!-- Linear transformations use a different syntax -->
<transform name="property name">
<!-- Any sequence of the following operations: -->
<translate value="x, y, z"/>
<scale value="x, y, z"/>
<rotate axis="x, y, z" angle="deg."/>
<!-- Useful for cameras and spot lights: -->
<lookat origin="x,y,z" target="x,y,z" up="x,y,z"/>
</transform>
The top-level element of any scene file is usually a
<scene> tag, but this is not always the
case.
For instance, some of the programming assignments will ask you to
run statistical tests on BRDF models or rendering algorithms, and
these tests are also specified using the XML scene description
language, like so:
<?xml version="1.0"?>
<test type="chi2test">
<!-- Run a χ2 test on the microfacet BRDF model (@ 0.01 significance level) -->
<float name="significanceLevel" value="0.01"/>
<bsdf type="microfacet">
<float name="alpha" value="0.1"/>
</bsdf>
</test>
Creating your first Nori class
In Nori, rendering algorithms are referred to as integrators
because they generally solve a numerical integration problem. The remainder
of this section explains how to create your first (dummy) integrator which
visualizes the surface normals of objects.
We begin by creating a new Nori object subclass in src/normals.cpp with
the following content:
#include <nori/integrator.h>
NORI_NAMESPACE_BEGIN
class NormalIntegrator : public Integrator {
public:
NormalIntegrator(const PropertyList &props) {
m_myProperty = props.getString("myProperty");
std::cout << "Parameter value was : " << m_myProperty << std::endl;
}
/// Compute the radiance value for a given ray. Just return green here
Color3f Li(const Scene *scene, Sampler *sampler, const Ray3f &ray) const {
return Color3f(0, 1, 0);
}
/// Return a human-readable description for debugging purposes
std::string toString() const {
return tfm::format(
"NormalIntegrator[\n"
" myProperty = \"%s\"\n"
"]",
m_myProperty
);
}
protected:
std::string m_myProperty;
};
NORI_REGISTER_CLASS(NormalIntegrator, "normals");
NORI_NAMESPACE_END
To try out this integrator, we first need to add it to the CMake build system:
for this, open
CMakeLists.txt and look for the command
add_executable(nori,
# Header files
include/nori/bbox.h
...
# Source code files
src/bitmap.cpp
...
)
Add the line src/normals.cpp at the end of the source file
list and recompile. If everything goes well, CMake will create an
executable named nori (or nori.exe on Windows) which
you can call on the command line.
Finally, create a small test scene with the following content and save it as test.xml:
<?xml version="1.0"?>
<scene>
<integrator type="normals">
<string name="myProperty" value="Hello!"/>
</integrator>
<camera type="perspective"/>
</scene>
This file instantiates our integrator and creates the default camera
setup. Running nori with this scene causes two things to
happen:
