mitsuba/README

Mitsuba renderer v2.0.2 (c) 2010 by Wenzel Jakob

Features:
    - Runs on Linux (32/64-bit), MacOS X (x86/PPC) and Microsoft 
      Windows (32-bit).
    - Written in portable C++ with optional SSE2 optimizations when compiled 
      for the i386 and x86_64 platforms.
    - Modular architecture inspired by PBRT.
    - Fully parallelized for multi-core operation.
    - Supports interactive walkthroughs using OpenGL and real-time coherent ray tracing.
    - Network rendering - can distribute the computational load of a single job 
      over a cluster without requiring a shared filesystem.
    - For convenience, Mitsuba can also transparently SSH into a cluster, 
      remotely launch itself and communicate through the encrypted link.
    - Uses a O(n log n) KD-tree compiler with primitive clipping support
      and Havran's fast traversal algorithm.
    - Highly optimized SSE2 intersection code for triangle meshes. Custom
      shapes such as spheres and cylinders are also supported.
    - High dynamic-range (EXR) support for textures and generated images
    - Cross-platform hardware rendering abstraction layer.
    - BSDFs: Lambertian, Perfect Mirror, Phong, Dielectric, Anisotropic Ward,
             Microfacet BRDF, Rough Glass (Walter et al.), 
    - Supports homogeneous as well as heterogeneous participating media
    - Implements Jensen's dipole approximations to sub-surface scattering
    - Supports a variety of image reconstruction filters 
      (eg. Mitchell-Netravali, Catmull-Rom, Gaussian, Lanczos-Sinc, ..) 
    - Comes with several numerical testbenches, which verify rendered 
      test scenes against analytic results.
    - Full spectral rendering is supported.
    - Light sources: area lights, point lights, environment maps, 
	  collimated beams.
    - QMC sampling
	- Cluster job submission support using PBS
    - Low dynamic-range textures (JPEG and PNG)
    - Depth of field
    - Adaptive/error-estimating sampling

External dependencies:
    A recent C++ compiler (GCC 4.1-4.3 or Visual Studio 2005/2008)
    SCons (An advanced build system built on top of Python)
    Xerces-C (For scene description XML parsing)
    GLEW (For the hardware acceleration abstraction layer)
    OpenEXR (Needed for high dynamic-range image file export/import)
	Boost (An extensive C++ class library)
	libpng & libjpeg (For PNG & JPG image import/export)

    When building Mitsuba on Windows or OSX, it is recommended to use
    the pre-compiled versions of these dependencies, which are supplied 
    with the source code. If you follow the instructions below, this
	will happen automatically.

Building:
    Go to the "config" directory and copy the "config.py" version which 
    best matches your environment. Some minor adaptions may be 
    required. The following configurations are currently provided:

    config-linux.py          - Linux build (GCC 4.2+ recommended)
    config-linux-icc.py      - Linux build using the Intel compiler
    config-darwin-x86.py     - OSX build targeting x86 using GCC4.2
    config-darwin-ppc.py     - OSX build targeting PPC using GCC4.2
    config-msvc2005-win32.py - Windows build using MSVC 2005 or 2008 (32 bit)
    config-msvc2005-win64.py - Windows build using MSVC 2005 or 2008 (64 bit)

	Make sure that you have a working install of Python. On the Windows
	platform, SCons (http://www.scons.org/) must also be installed before
	building.

    Next, run the script "tools/build.sh" (Linux, OSX) or "scons" (Windows) 
	to start compiling using the supplied version of SCons. On Windows, this 
	must be done on the Visual Studio command prompt (e.g by launching 
	Start->Programs->Microsoft Visual Studio 2005->
		Visual Studio Tools->Visual Studio 2005 Command Prompt).

	If Windows complains about a missing library named 'MSVCR80.dll',
	please install the redistributable in "tools/windows/bin". Also,
	be sure to add the path containing the Qt tools (e.g. 'moc.exe')
	to the PATH.

    To build an universal binary on OSX, enter
 
        $ tools/darwin/build-universal.sh

    and have a cup of coffee :).

Compilation flags:
    Some of the compilation flags in "config.py" have a big impact on
    the resulting executable:

    'MTS_DEBUG'           - Enable assertions etc.. Usually a good idea.
    'SINGLE_PRECISION'    - Use single precision floating point values
    'DOUBLE_PRECISION'    - Use double precision floating point values
    'MTS_SSE'             - Activate optimized SSE routines.
    'MTS_HAS_COHERENT_RT' - Include coherent ray tracing support (needs SSE)
    'MTS_DEBUG_FP'        - Generated NaNs will cause FP exceptions, which
	                        can be caught in a debugger. Warning: This is slow!

    Single precision is sufficient in most cases. The use of double precision
    currently precludes the SSE feature, since the accelerated code has only
    been written as a single-precision version.

Getting started:
    On Linux/OSX, the library path must be manually set: on the command line, 
    this can be done using the script "setpath.sh":

        $ . setpath.sh

	On Windows, all relevant files are installed to 'dist' and the binaries
	should be executed from there. 

	On Linux, an interactive preview can be launched by entering (e.g.)

        $ mtsgui scenes/cornell/box.xml

    Rendering can be started by pressing the 'r' key. 

	The 'mitsuba' binary is an alternative non-interactive rendering 
	frontend for command-line use and batch job operation.

    To get a listing of the supported command-line parameters, run
    the executables without parameters:

	$ mitsuba 

	Mitsuba version 2.0.2, Copyright (c) 2010 Wenzel Jakob
	Usage: mitsuba [options] <One or more scene XML files>
	Options/Arguments:
	-h          Display this help text

	-D key=val  Define a constant, which can referenced as "$key" in the scene

	-o fname    Write the output image to the file denoted by "fname"

	-a p1;p2;.. Add one or more entries to the resource search path

	-p count    Override the detected number of processors. Useful for reducing
				the load or creating scheduling-only nodes in conjunction with
				the -c and -s parameters, e.g. -p 0 -c host1;host2;host3,...

	-q          Quiet mode - do not print any log messages to stdout

	-c hosts    Network rendering: connect to mtssrv instances over a network.
				Requires a semicolon-separated list of host names of the form
						host.domain[:port] for a direct connection
					or
						user@host.domain[:path] for a SSH connection (where
						"path" denotes the place where Mitsuba is checked
						out -- by default, "~/mitsuba" is used)

	-s file     Connect to additional Mitsuba servers specified in a file
				with one name per line (same format as in -c)

	-j count    Simultaneously schedule several scenes. Can sometimes accelerate
				rendering when large amounts of processing power are available
				(e.g. when running Mitsuba on a cluster. Default: 1)

	-n name     Assign a node name to this instance (Default: host name)

	-t          Test case mode (see Mitsuba docs for more information)

	-v          Be more verbose

	-b          Disable progress bars

	The README file included with the distribution contains further information.

	On Windows, a scene file can simply be dropped on the 'mtsgui.exe'
	executable to start the interactive preview.

	When doing lengthy command line renders on Linux or OSX, it is possible 
	to send a signal to the process using 'kill -HUP', causing Mitsuba to 
	write out the partially finished image and continue rendering.

Network rendering:
    For extremely lengthy rendering tasks, it may make sense to spread the 
    computational load of a single job over multiple machines. Mitsuba 
    supports this via two mechanisms: The easiest and most secure method can
    only be used when Linux or OSX is installed on the server machine
    machine:

    This works as follows: The client creates an encrypted SSH connection 
	to the server, launches a Mitsuba worker instance on the remote end 
	and tunnels all subsequent communication over the encrypted link. All 
	of this can be done simply by running

        $ mitsuba -c user1@host:path-to-mitsuba-install path/to/scene.xml

    Passwordless logins must be enabled for this to work, which generally
	entails installing a suitable "~/.ssh/authorized_keys2" file on the server
	and running "ssh-agent" on the client. On Windows, the situation is a bit
	more complicated because it does not come with a suitable SSH client by
	default. To get SSH to work, biquaque requires plink.exe (from PUTTY) to
	be on the $PATH. For passwordless authentication with a Linux/OSX-based
	server, convert your private key to PuTTY's format (with the help 
	of puttygen.exe). Afterwards, pageant.exe is required to load and 
	authenticate the key. All of these binaries are available in
	'tools/windows/bin'

	The alternative to SSH-based communication is to run a dedicated mitsuba
    server:

        $ mtssrv
  
    By default, the server is configured to listen on port 7554. Clients can
	then connect using the following syntax:

        $ mitsuba -c host1;host2:1234 path/to/scene.xml

    Note that it is possible to use both connection mechanisms at the same
    time and connect to, say, 3 SSH-based servers and 10 dedicated servers.

    CAUTION: The dedicated Mitsuba server setup uses no authentication
    mechanism whatsoever! It might easily be possible to perform denial of 
    service- or remote code execution attacks by sending corrupt requests 
	to the server. It was not written to withstand these kinds of attacks 
	and is only meant as a high-performance option for trusted and firewalled 
    networks.

Cluster rendering:
    The directory 'tools/pbs' contains sample files illustrating how lengthy
    render jobs can be sent to a cluster using the PBS job submission system.

Structure:
    Mitsuba is split into several libraries and modular extension types:

    libcore      - Core components such as plugin support, logging, file
                   streams, threading, scheduling and elementary graphics 
				   classes such as color spectra + matrices.
    librender    - Ray-tracing and rendering-specific components.
    libhw        - Hardware acceleration using OpenGL. Used by some
                   of the integrators.

    cameras      - Different types of cameras
    bsdfs        - Bidirectional scattering distribution functions
    films        - Floating-point framebuffer implementations
    integrators  - Rendering algorithms such as 'direct', 'photonmapper', etc.
    luminaires   - Different types of light sources for use in scenes.
    samplers     - Sampling methods (independent/stratified/QMC sampling etc.)
    subsurface   - Subsurface scattering integrators
    textures     - Procedural and loadable surface textures
    shapes       - Intersection primitives and 3D model loaders
    rfilters     - Image reconstruction filters

Acknowledgements:
    The architecture of Mitsuba as well as some individual components 
    are based on implementations discussed in:
        "Physically Based Rendering - From Theory To Implementation" 
        by Matt Pharr and Greg Humphreys.