Films

A film defines how conducted measurements are stored and converted into the final output file that is written to disk at the end of the rendering process.

In the XML scene description language, a normal film configuration might look as follows:

XMLPython

<scene version=3.0.0>
    <!-- .. scene contents -->

    <sensor type=".. sensor type ..">
        <!-- .. sensor parameters .. -->

        <!-- Write to a high dynamic range EXR image -->
        <film type="hdrfilm">
            <!-- Specify the desired resolution (e.g. full HD) -->
            <integer name="width" value="1920"/>
            <integer name="height" value="1080"/>

            <!-- Use a Gaussian reconstruction filter. -->
            <rfilter type="gaussian"/>
        </film>
    </sensor>
</scene>

The <film> plugin should be instantiated nested inside a <sensor> declaration. Note how the output filename is never specified—it is automatically inferred from the scene filename and can be manually overridden by passing the configuration parameter -o to the mitsuba executable when rendering from the command line.

High dynamic range film (hdrfilm)

Parameter	Type	Description	Flags
width, height	integer	Width and height of the camera sensor in pixels. Default: 768, 576)
file_format	string	Denotes the desired output file format. The options are openexr (for ILM’s OpenEXR format), rgbe (for Greg Ward’s RGBE format), or pfm (for the Portable Float Map format). (Default: openexr)
pixel_format	string	Specifies the desired pixel format of output images. The options are luminance, luminance_alpha, rgb, rgba, xyz and xyza. (Default: rgb)
component_format	string	Specifies the desired floating point component format of output images (when saving to disk). The options are float16, float32, or uint32. (Default: float16)
crop_offset_x, crop_offset_y, crop_width, crop_height	integer	These parameters can optionally be provided to select a sub-rectangle of the output. In this case, only the requested regions will be rendered. (Default: Unused)
sample_border	boolean	If set to true, regions slightly outside of the film plane will also be sampled. This may improve the image quality at the edges, especially when using very large reconstruction filters. In general, this is not needed though. (Default: false, i.e. disabled)
compensate	boolean	If set to true, sample accumulation will be performed using Kahan-style error-compensated accumulation. This can be useful to avoid roundoff error when accumulating very many samples to compute reference solutions using single precision variants of Mitsuba. This feature is currently only supported in JIT variants and can make sample accumulation quite a bit more expensive. (Default: false, i.e. disabled)
State parameters
(Nested plugin)	rfilter	Reconstruction filter that should be used by the film. (Default: gaussian, a windowed Gaussian filter)
size	Vector2u	Width and height of the camera sensor in pixels	P
crop_size	Vector2u	Size of the sub-rectangle of the output in pixels	P
crop_offset	Point2u	Offset of the sub-rectangle of the output in pixels	P

This is the default film plugin that is used when none is explicitly specified. It stores the captured image as a high dynamic range OpenEXR file and tries to preserve the rendering as much as possible by not performing any kind of post processing, such as gamma correction—the output file will record linear radiance values.

When writing OpenEXR files, the film will either produce a luminance, luminance/alpha, RGB(A), or XYZ(A) tristimulus bitmap having a float16, float32, or uint32-based internal representation based on the chosen parameters. The default configuration is RGB with a float16 component format, which is appropriate for most purposes.

For OpenEXR files, Mitsuba 3 also supports fully general multi-channel output; refer to the aov or stokes plugins for details on how this works.

The plugin can also write RLE-compressed files in the Radiance RGBE format pioneered by Greg Ward (set file_format=rgbe), as well as the Portable Float Map format (set file_format=pfm). In the former case, the component_format and pixel_format parameters are ignored, and the output is float8-compressed RGB data. PFM output is restricted to float32-valued images using the rgb or luminance pixel formats. Due to the superior accuracy and adoption of OpenEXR, the use of these two alternative formats is discouraged however.

When RGB(A) output is selected, the measured spectral power distributions are converted to linear RGB based on the CIE 1931 XYZ color matching curves and the ITU-R Rec. BT.709-3 primaries with a D65 white point.

The following XML snippet describes a film that writes a full-HD RGBA OpenEXR file:

XMLPython

<film type="hdrfilm">
    <string name="pixel_format" value="rgba"/>
    <integer name="width" value="1920"/>
    <integer name="height" value="1080"/>
</film>

Spectral film (specfilm)

Parameter	Type	Description	Flags
width, height	integer	Width and height of the camera sensor in pixels Default: 768, 576)
component_format	string	Specifies the desired floating point component format of output images. The options are float16, float32, or uint32. (Default: float16)
crop_offset_x, crop_offset_y, crop_width, crop_height	integer	These parameters can optionally be provided to select a sub-rectangle of the output. In this case, only the requested regions will be rendered. (Default: Unused)
sample_border	boolean	If set to true, regions slightly outside of the film plane will also be sampled. This may improve the image quality at the edges, especially when using very large reconstruction filters. In general, this is not needed though. (Default: false, i.e. disabled)
compensate	boolean	If set to true, sample accumulation will be performed using Kahan-style error-compensated accumulation. This can be useful to avoid roundoff error when accumulating very many samples to compute reference solutions using single precision variants of Mitsuba. This feature is currently only supported in JIT variants and can make sample accumulation quite a bit more expensive. (Default: false, i.e. disabled)
(Nested plugin)	rfilter	Reconstruction filter that should be used by the film. (Default: gaussian, a windowed Gaussian filter)
State parameters
(Nested plugins)	spectrum	One or several Sensor Response Functions (SRF) used to compute different spectral bands	P
size	Vector2u	Width and height of the camera sensor in pixels	P
crop_size	Vector2u	Size of the sub-rectangle of the output in pixels	P
crop_offset	Point2u	Offset of the sub-rectangle of the output in pixels	P

This plugin stores one or several spectral bands as a multichannel spectral image in a high dynamic range OpenEXR file and tries to preserve the rendering as much as possible by not performing any kind of post-processing, such as gamma correction—the output file will record linear radiance values.

Given one or several spectral sensor response functions (SRFs), the film will store in each channel the captured radiance weighted by one of the SRFs (which do not have to be limited to the range of the visible spectrum). The name of the channels in the final image appears given their alphabetical order (not the location in the definition).

To reduce noise, this plugin implements two strategies: first, it creates a combined continuous distribution with all the different SRFs using inverse transform sampling. Then it distributes samples across all the spectral ranges of wavelengths covered by the SRFs. These strategies greatly reduce the spectral noise that would appear if each channel were calculated independently.

RGB spectral rendering#

CH-1: band1_red#

CH-2: band2_green#

CH-3: band3_blue#

The following snippet describes a film that writes the previously shown 3-channel OpenEXR file with each channel containing the sensor response to each defined spectral band (it is possible to load a spectrum from a file, see the Spectrum definition section). Notice that in this example, each band contains the spectral sensitivity of one of the rgb channels.

XMLPython

<film type="specfilm">
    <integer  name="width" value="1920"/>
    <integer  name="height" value="1080"/>
    <spectrum name="band1_red" filename="data_red.spd" />
    <spectrum name="band2_green" filename="data_green.spd" />
    <spectrum name="band3_blue" filename="data_blue.spd" />
</film>