Remodeler Plugin API

As of version 1.1, RenderToolbox3 can modify Collada parent scenes using custom functions, via the Remodeler Plugin API. A remodeler allows you to change any aspect of a Collada scene on the fly, in Matlab.

Currently, RenderToolbox3 defines plugins for two remodelers:

• MaterialSphere -- this remodeler is part of the MaterialSphereRemodeled example scene. It takes the original Material sphere scene and changes the vertex positions and normals of the sphere model.
• SampleRemodeler -- this remodeler provides no remodeling functionality, but it can be used as a placeholder for a remodeler. It will print statements whenever parts of the Remodeler Plugin API are invoked. It can serve as a template for writing new remodelers. It contains detailed documentation for how the Remodeler Plugin API works.

Overview of a Remodeler

A remodeler is really just a set of three functions. Each function name must conform to a specific pattern, which allows RenderToolbox3 to locate and invoke the function when needed. For example, the function RTB_BeforeAll_MaterialSphere() is part of MaterialSphere remodeler. RenderToolbox3 invokes this function at the beginning of scene file creation for the MaterialSphereRemodeled example scene.

Each of the three functions in a remodeler gets applied at a different time during scene file generation. Each function is optional:

• BeforeAll functions are invoked once, at the start of scene file generation. Changes made to the Collada parent scene will affect all generated scene files.
• BeforeCondition functions are invoked once per condition, just before mappings are applied to the Collada parent scene for the current condition. Changes made to the Collada parent scene will affect only the scene file for the current condition.
• AfterCondition functions are invoked once per condition, just after mappings are applied to the Collada parent scene for the current condition. Changes made to the Collada parent scene will affect only the scene file for the current condition.

The After Condition function has the "final say" about a Collada parent scene file, before the Collada is converted to a renderer native scene file by a renderer's [Render](Renderer Plugin API) function.

Plugin Details

Please see the code and documentation of the SampleRemodeler for details about the precise syntax and behavior of Remodeler Plugin API functions. The code can be found in the RenderToolbox3 source code at (path-to-RenderToolbox3)/ExampleScenes/MaterialSphere. The documentation can be found in the RenderToolbox3 function reference.

New Plugins

You can write your own remodelers. Hopefully, the existing SampleRemodeler and MaterialSphere remodeler will provide helpful templates and working examples from which you can generalize.

Each of your remodeler plugin functions must have a name that matches a specific pattern (see the function reference). Each function must also accept specific inputs and return specific outputs. That's the contract of the Renderer Plugin API.

But internally, your remodeler can do anything you want. You can rotate objects, delete lights, add textures, or whatever. Since remodeler functions work with Collada XML documents, you should get to know the RenderToolbox3 Scene DOM Paths and Scene DOM utilities. You should also get to know the Collada file format. This [reference card](COLLADA 1.4 Schema Reference Card) for the Collada 1.4 schema is useful.