Skip to content

RenderToolbox4

Ben Heasly edited this page Oct 18, 2016 · 26 revisions

Here are some notes about what's new in RenderToolbox4. The previous version was RenderToolbox3.

Summary

RenderToolbox4 is a lot like RenderToolbox3, but better.

The basic workflow is the same. Much has changed under the hood to make it better. The biggest changes are:

  • We now use Assimp to read and write many 3D scene formats, not just Collada.
  • We now use JSON for the Mappings File Format.
  • more below...

Big Changes

These are the big changes that we're most excited about. They will affect how you work with RenderToolbox.

Assimp and mexximp

RenderToolbox4 uses the Assimp library to read and write a variety of 3D scene file formats. This includes Collada as always, and many others.

To get the scene data from Assimp into Matlab, RenderToolbox4 uses a new mex-function called mexximp. This gives you the whole scene as a Matlab struct, which you can explore and edit like any other Matlab struct. Not that bad!

This enables new kinds of workflows, for example examining unfamiliar scenes or authoring scenes from scratch entirely in Matlab.

JSON

RenderToolbox4 uses JSON as the Mappings File Format, instead of the old custom text file format. This is a better approach because standards like JSON make reading and writing text files from programs a solved problem. There's no need for RenderToolbox to re-invent this.

Moreover, with the tool jsonlab, it's now possible to interact with mappings files as Matlab structs. You don't have to write mappings files by hand.

rtb Prefix

All of the RenderToolbox4 function names now begin with the prefix rtb. This is to distinguish RenderToolbox from other toolboxes that might be on your Matlab path.

This is conceptually a small change, but it will affect every call you make to RenderToolbox.

For reverse compatibility, a few functions are still included that don't use the rtb prefix. These will print annoying warnings encouraging you to update your code. See Compatibility and Migration, below.

inputParser for Function Arguments

All of the RenderToolbox4 functions now use Matlab's inputParser class to handle their arguments. This changes the style of argument passing:

  • Required arguments always come first.
  • Optional arguments always come as name-value pairs.

This makes for a cleaner, more self-descriptive style. No more padding out an argument list with [], [], ... just to supply an argument at the end.

Here's an example. Say you want to call MakeSceneFiles() but you want to leave out the optional arguments conditionsFile and mappingsFile. This used to require ugly padding:

MakeSceneFiles(colladaFile, [], [], hints)

Now you can leave out the padding, and the optional arguments you do supply get a name so you can tell what they are at a glance:

rtbMakeSceneFiles(colladaFile, 'hints', hints);

This is not a deep change in how RenderToolbox works, but it will affect every call you make to RenderToolbox.

Installation with ToolboxToolbox and Docker

RenderToolbox4 can be installed with the ToolboxToolbox, and pre-built renderers distributed with Docker.

This is an attempt to make the installation process easier for you, and easier for us to maintain. Compare the RenderToolox4 instructions to the RenderToolbox3 instructions. Note the shorter length and fewer ifs, ands, and buts.

ToolboxToolbox is a win because it automates downloading toolboxes and adding them to the Matlab path. So you have less clicking, reading, and typing to do. It also makes this process declarative and less error-prone.

Docker is a win because it allows us to distribute pre-built renderers and other tools, and lets them run in a portable, isolated environment. This means you have less software to build, and fewer headaches about installed system libraries.

Now that Docker is available on OS X and Windows, not just Linux, we hope the days of asking you to build native dependencies are coming to an end!

Small Changes

These changes are good, too. But you might not notice them.

Unit Tests

We added an automated test suite based on Matlab's unit test framework.

This allows us to check the code for regressions, without having to do renderings and comparisons by eye. We should have had this all along. Now we do!

Remove Dynamic Library Path from hints

RenderToolbox4 no longer uses the hints struct to configure the dynamic library search path used with the system() command. On some systems this was necessary when invoking renderers. But hints was the wrong place for it.

Now, the dynamic library search path is configured in a renderer-specific way. And with Docker, this may be unnecessary altogether.

Plain Old help Documentation

RenderToolbox4 functions now contain documentation text compatible with Matlab's help command. This is probably how most users expect to read documentation in Matlab, and makes the text easier to read when editing a function.

In RenderToolbox3, we used a different style of documentation intended for use with tools like Doxygen. Doxygen is still an awesome tool. But it turned out we rarely updated the published docs, and having separate docs was not a natural fit for Matlab workflows.

RenderToolbox3 Compatibility and Migration

We want your old code from RenderToolbox3 to keep working with RenderToolbox4. To support this, we added a "Collada Strategy" to the internals of RenderToolbox4. This should behave like RenderToolbox3 by reading Collada scenes and mappings in the old custom text format.

The Collada Strategy works on all of the old Collada-based RenderToolbox3 Example Scenes. We hope it works for your code, too.

However, to encourage you to migrate your code to take advantage of RenderToolbox4, the Collada Strategy will display irritating messages like this:

Warning: BatchRender is deprecated and will be removed.
Please use rtbBatchRender instead.

For help migrating to RenderToolbox4, please see the new Example Scenes. Most of them produce the same results as the old example scenes from RenderToolbox3, so the comparison may be helpful.

Have Fun!

We think RenderToolbox4 is cool and we hope you will enjoy using it!