HTTPS SSH

MitsubaExport

Introduction

MitsubaExport is a Unity Hackweek project and In-Editor solution to create a comparison between a physically-based, path-traced image of the current camera view based on the Mitsuba renderer and the same view rendered by Unity. This helps to assess were the Unity renderer and its components such as the Standard Shader, the global illumination system and the Image Effects deviate from physical models.

The UnityStd Mitsuba Plugin

In order to properly represent materials from Unity in Mitsuba, it is necessary to build a special plugin which enhances Mitsuba by a new material type called UnityStd, which mirrors the set of parameters given to the Unity Standard Shader.

Please check out the source code of Mitsuba and ensure you can compile a running version of it. Assume MitsubaExportSrc is the directory of MitsubaExport, and MitsubaSrc contains the checked out code of Mitsuba.

To add UnityStd to it, follow these simple steps:

  1. Copy MitsubaExportSrc/Plugin/unitystd.cpp into the MitsubaSrc/src/bsdf/ subfolder
  2. Add UnityStd to the list of materials in the build scripts

If you are using SCons to build Mitsuba, open MitsubaSrc/src/bsdf/SConscript and add the following line:

# Other materials
...
plugins += env.SharedLibrary('unitystd',  ['unitystd.cpp'])

Alternatively, if you are using CMake to build Mitsuba, open MitsubaSrc/src/bsdf/CMakeLists.txt and add the following line:

# Other Materials
...
add_bsdf(unitystd  unitystd.cpp)

Recompile, and Mitsuba will now support the UnityStd BSDF.

Basic usage

To use the MitsubaExport plugin in your project, simply drag and drop the entire folder into your project Assets. Once compiled, a new item called MitsubaExport should be visible in your menu.

First, open up the Unity Preferences window and select Mitsuba. Make sure that the variable mitsubaExecutable points to the Mitsuba binary you've just compiled above, so that MitsubaExport will use the version that comes with the UnityStd plugin.

Once this is done, either select the nodes you'd like to compare to a Mitsuba rendering in your Hierarchy view, or simply leave everything as it is. Then go to MitsubaExport and click Toggle comparison. This will trigger the following steps:

  1. Create a Mitsuba scene file of the all/the selected nodes in your Hierarchy
  2. Render the scene with Mitsuba
  3. Copy the rendered image back into the Assets
  4. Render a comparison with a shader between the Unity and the Mitsuba result in the Game view

If you have a camera set up in your scene, the first one will be used to render the comparison. If there is no camera in your Hierarchy, the Scene view will be used instead. A camera clone of either one of them will appear in your Hierarchy view, which has a Comparison FX script attached to it. It offers several sliders to manipulate the view of the comparison:

  • Colormap Screen Occupancy: Slide back and forth between the colormap-difference-image between Unity and Mitsuba and the Unity rendering of the scene.
  • Mitsuba Screen Occupancy: Slide back and forth between the Unity and Mitsuba rendering of the scene.
  • Colormap scale: Scale the colormap-difference-image error to better pronounce small scale differences.
  • Exposure: Change the exposure of both, the Unity and the Mitsuba rendering of the scene.
  • Gamma: Change the gamma of both, the Unity and the Mitsuba rendering of the scene.

If you click Toggle comparison again, the cloned camera will vanish again and return to the normal game view.

Settings for a correct comparison

Mitsuba is a physically-based path tracer, and therefore a comparison with Unity is only meaningful if the settings in your project are set up in a way that is also physically-based. MitsubaExport will warn you if that is not the case via a sanity check when clicking Toggle comparison and produce a list of settings that are wrong or incompatible in the Console.

Here is an incomplete checklist of things to be aware of:

  • The colorspace of the project should be linear
  • The camera background should match the environment background
  • The camera background should match reflection probe backgrounds
  • Reflection probes and cameras should be HDR
  • Light sources should have shadow strength or bounce intensity set to 1.0f
  • Lightmap settings should have bounce boost and intensity set to 1.0f

Other settings

MitsubaExport exposes other settings in the Preferences window:

  • version: Set the version of the exported Mitsuba file.
  • targetFolder: The folder into which all output files are dumped relative to the project root. This folder contains the exported Mitsuba version of the Unity scene with all geometry.
  • multiBounceEnable: Toggle off for comparison with direct lighting only.
  • exportEnvironment: Toggle off to ignore environment settings, such as the skybox.
  • exportLights: Toggle off to ignore light sources.
  • sampleCount: The number of samples per pixel for the Mitsuba film.
  • exportEXR: Toggle on to create an EXR image of the Mitsuba rendering.
  • textureOverwrite: Toggle on to always overwrite textures exported from Unity to Mitsuba. If your textures in the project do not change, you can leave this off and save some time.

State of development

MitsubaExport is still in development. This means that some of the differences visible after creating an image may be due to the fact that not everything is exported correctly or at all.

License

The MIT License (MIT)

Copyright (c) 2016, Unity Technologies

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.