Realflow Maya Connectivity

RealFlow Maya Plug-in Features and Improvements

This document describes the improvements made to the RealFlow Maya plug-in. The main focus areas have been workflow and performance. The code has been rewritten from scratch but care has been taken to preserve backwards compatibility.

NOTE: the new plug-in will not function if any of the following plug-ins are active:

• sdTranslator.mll

• RealflowParticler.mll

• RealflowMesher.mll

Please unload these plug-ins and remove the files from the Maya plug-in directory before loading the new plug-in.

Installer The new plug-in has an installer wizard so that users are no longer required to manually copy files into the Maya directory. The installer auto-detects which Maya versions are installed and where. All versions of Maya starting with 8.0 a re supported, with both 32-bit and 64-bit builds where applicable.

Figure 1: The wizard auto-detects Maya versions and installation directories.

MEL Support The plug-in functionality is available to MEL through the realflow command. The syntax for each of the functions (SD export, BIN import etc.) is described in the corresponding section later in this document.

Toolbar The functionality of the plug-in is conveniently exposed through a shelf (toolbar). The plug-in manages this toolbar automatically and updates its contents when a newer version is available.

Figure 2: RealFlow toolbar.

The purpose of the buttons, starting from left to right:

• Export SD: Exports the current scene as a SD file using the last settings. If this is the first time the scene is exported, or the settings are not persistent, the button brings up the settings dialog.

• Export SD Settings: Allows the user to adjust the SD export settings.

• Import SD: Imports a SD scene file into the current Maya scene.

• Import BIN Particle Sequence: Creates a RealFlow particle system which loads particles from a sequence of BIN files.

• Export BIN Particles: Can be used to export Maya particles as a sequence of BIN files. It uses the last settings stored in the scene if available or brings up an options dialog, just like the SD exporter.

• Export BIN Particles Settings: Displays the options dialog for the BIN particle exporter.

• Import BIN Mesh Sequence: Creates a mesh object inside Maya and loads its geometry from a sequence of BIN mesh files.

File Translators SD scene files can also be handled through the “Import”, “Export All” and “Export Selection” items in the File menu. Click the option box on the right of the export menu items to access the export settings.

BIN files can be imported through the File->Import menu. The importer will detect the type of the sequence – mesh or particles – and create the corresponding Maya objects.

Both importers also function in the “Best Guess” mode, so there’s no need to select the file type explicitly in the file browser dialog.

SD File Import/Export This section will discuss the usage of the SD part of the plug-in and its improvements compared to the previous version.

Geometry support All 3 geometry representation methods are supported by the plug-in: polygonal meshes, NURBS surfaces and Subdivision surfaces. Polygonal meshes no longer need to be triangulated before export. The plug-in also exports the diffuse color for those meshes which do not use a texture.

Progress reporting Both the import and export processes report progress through the main Maya progress bar, in the status line. The user can cancel at any time by pressing the ESC key. Please note that aborting an import before any frames have been read will leave all the imported objects at the origin.

Figure 3: Progress reporting.

Export options The exporter settings can be made persistent in the scene so that they don’t have to be re-entered before every export.

Figure 4: SD export settings dialog.

The following settings are available:

• File: the path to the destination SD file.

• Frame interval: the active playback range can be used, or an explicit interval can be specified.

• Export deformation: when this option is enabled, the geometry of the objects is exported at every frame. This is useful when you need to export skinned meshes, soft bodies or other deformable objects. When the option is disabled, the geometry of the objects is exported once and only positioning data (translation, rotation, scaling) is exported per-frame.

• Camera: The active 3D view can be used, or you can explicitly choose which camera to export.

• Persistent Options: when this is on, the settings are stored in the scene so that it can be re-exported later with a single button click. However, the settings node causes problems if you try to open the scene later on a system where the plug-in is not installed so this option can be used in those cases to prevent the plug-in from creating the node.

MEL support SD files can be imported with the following syntax:

realflow –importSD path_to_file

When using the command to export scenes, the export settings can either be taken from the scene, or explicitly specified. To use the settings stored inside the scene, invoke the command like this:

realflow –exportSD –useSettingsNode

To specify the options as arguments, start with:

realflow –exportSD –file path_to_file

then add one or more of the following flags:

• -selected to export only the selected objects. The default is to export everything.

• -camera camera_name to select which camera to use. The default is to use the active 3D view.

• -startFrame specifies the first frame to export. The default is 1.

• -endFrame specifies the last frame to export. The default is 24.

• -usePlaybackRange is used to export the currently active playback range. If you use this flag, -startFrame and -endFrame are ignored.

• -deformation turns on per-frame geometry export on all objects. By default the command does not export deformations.

RealFlow-specific mesh attributes A RealFlow rollup is added in the Attribute Editor for shape nodes. The rollup contains attributes which control how the SD exporter treats the object:

• Ignore: when this is checked, the exporter simply skips the object.

• Export deformation: this can be used as an object-level override for the deformation mode which is specified in the export options.

Figure 5: RealFlow-specific shape attributes.

These attributes are dynamically added to shape nodes only when they are set to a non-default value. If an attribute is later set back to its default value, it is removed from the object. This solution prevents bloating the scene.

Performance improvements The old plug-in used to build the entire SD file in memory at export time and only wrote it to disk at the end of the process. This caused problems in large scenes, where Maya was already using a lot of memory by itself. The new code writes the data directly to the file, so no extra memory is needed. It is also significantly faster.

To illustrate the improvement we have used a scene containing 900 objects which added up to 1,080,000 polygons. We have exported 100 frames with and without deformation, with both the old and the new plug-ins. The resulting SD files were 89 MB without deformation and 714 MB with deformation.

Time Memory usageNo Deformation Old Plug-in 13:16 103 MBNew plug-in 00:40 0.3 MBWith Deformation Old Plug-in 17:19 1589 MBNew Plug-in 01:24 0.3 MBTable 1: SD performance comparison

Additionally, the new plug-in takes around 01:30 to import back the resulting file (with deformation) and the performance is acceptable when moving the time slider. The old plug-in would require in excess of 700 GB of memory to import the same scene.

Greatly improved handling for soft body objects The old plug-in used to keep the entire SD file in memory for each soft body object in the scene. This made it impossible to work with large files or large numbers of objects. The soft body node in the new plug-in only caches file offsets for each frame and loads the geometry from disk when the current frame changes, ensuring optimal memory usage.

The node detects when the SD file changes and displays an error mesh (currently a cube). It also issues a warning which asks the user to re-import the modified SD file.

We have also changed the behavior of the soft body objects when the current time is set outside the frame range contained in the SD file. The old node made the geometry disappear when this happened. The new node displays the first or last frame, depending on whether the current time is before or after the animation range.

Figure 6: Attribute Editor for the soft body node.

Miscellaneous improvements • Large file support: the plug-in uses 64-bit offsets for file operations, so there are no restrictions

on the size of the SD files.

• Reused animation curves: when importing an animation for an object which exists in the scene, the new plug-in reuses the animation curves of that object, if they are present. The old plug-in used to create a new set of curves with each import, resulting in a bunch of unused nodes lying around in the scene if the user repeatedly imported a SD file.

RealFlow Particles in Maya This section covers the part of the plug-in which handles sequences of particle BIN files.

BIN Import Pressing the “Import BIN sequence” button in the toolbar will ask the user to select a BIN file. After this is done, the plug-in will try to autodetect the name format and frame padding used for the given file name and will display a dialog box which allows setting the options for the emitter which will be created.

Figure 7: Particle import options.

You can adjust the name format or padding here if the initial guess made by the code is not correct. The plug-in will extract the file prefix based on the format and padding selection. Note that if you choose an invalid format or padding (i.e. the file name cannot be reconstructed using your settings) the dialog will display an error message in the “Prefix” field, like in the example below:

Figure 8: The file name cannot be reconstructed using the name_#.ext format because it uses a dot, not an underscore.

New Attribute Editor interface for the emitter node The Attribute Editor now displays each loaded sequence in a collapsible frame. All the sequence attributes are accessible directly in the AE instead of having to press an “Options” button like before. The set of sequences can also be edited after creation now using the “Add Sequence” and “Remove Sequence” buttons. All the attributes which were inherited from the Maya emitter node have been hidden since they are not relevant to the RealFlow node.

Figure 9: New emitter AE interface.

Changed attributes The options for suppressing certain channels from the BIN files (e.g. mass, normals, viscosity etc.) have been removed because they didn’t provide any performance gains. Everything is loaded now and sent to the particle shape.

The “load sequence”, “use range” and “clip to range” attributes have been changed from integer arrays to boolean arrays.

The “rfPosition” and “rfVelocity” output channels have been removed because they have native Maya equivalents (the “position” and “velocity” attributes on the particle shape node).

Performance and stability improvements The particle loader is two times faster than the old plug-in, resulting in better interactivity when working with large numbers of particles.

The code is around 5 times shorter so it’s easier to maintain. It does no explicit dynamic memory allocations, resulting in better stability in low memory situations.

Backwards compatibility Existing scenes should work without changes with the new plug-in. Make sure that the realflow.mll plug-in is loaded before opening a scene with emitters created by the old plug-in (the best way to do this is to set realflow.mll to auto-load in the plug-in manager). Also make sure that you remove the RealflowParticler.mll file from the Maya plug-ins directory, otherwise Maya will try to load it when you open the existing scene.

Maya will show a warning dialog when you load an existing scene with this plug-in. It is safe to ignore this warning. If you simply close the dialog box and re-save the scene the nodes will be converted to the format used in the new plug-in and you won’t receive any more warnings the next time you open the file.

Figure 10: Warning dialog when loading old scenes.

Sometimes when loading old scenes the new plug-in fails to remove the existing particles before emitting new ones for the current frame. To fix this just change the current time so that the existing particles are cleared and a fresh set is created and then save the scene. You only need to do this once after you open an old scene.

BIN Export Any Maya particle system can be exported as a sequence of BIN files and loaded in RealFlow. As with the SD exporter, the BIN export options can be made persistent so that subsequent exports can be performed with a single button click.

Figure 11: BIN particle export options.

You can add several Maya emitters to the “Particle Nodes” list and they will all be exported as a single emitter to RealFlow.

MEL Support You can export particles as a BIN sequence using the following syntax:

realflow –exportBIN –useSettingsNode

or, to specify options manually:

realflow –exportBIN –path export_directory –prefix file_prefix –node emitter_node_name

The -node flag can appear several times if you wish to include more than one Maya emitter.

The following flags can be used to specify extra options:

• -nameFormat N, where N is 0 for “name.#.bin”, 1 for “name#.bin”, 2 for “name.bin.#”, 3 for “name_#.bin”. The default is “name#.bin”.

• -padding N, where N is the number of digits used for the frame number. The default is 5.

• -particleType N, where N is 0 for gas, 1 for liquid, 2 for dumb, 3 for elastics, 4 for custom. The default is “dumb”.

• -startFrame specifies the first frame to export. The default is 1.

• -endFrame specifies the last frame to export. The default is 24.

• -usePlaybackRange is used to export the currently active playback range. If you use this flag, -startFrame and -endFrame are ignored.

• -frameOffset can be used to offset the exported sequence relative to the Maya time. For

example specifying an offset of -10 will cause frame 11 in Maya to be exported as file0001.bin.

Progress reporting The main Maya progress bar is used to display the status of the BIN export operation. The export can be canceled at any time by pressing the ESC key.

Figure 12: Progress bar for BIN particle export.

RealFlow Meshes in Maya Sequences of BIN mesh files can be loaded using the last button in the toolbar or the File->Import menu. An options dialog similar to the BIN particle dialog will be displayed:

Figure 13: BIN mesh import settings.

Motion blur support RealFlow meshes usually have unstable topology: vertices are created or removed at each frame. This causes problems with motion blur in most renderers, since this effect needs the same number of vertices in every sub-step to function correctly. The plug-in tries to work around this by using the same BIN file for half a frame before and after each integer frame, e.g. file0004.bin will be used between frames 3.5 and 4.5. The vertex positions are displaced using the speed stored in the BIN file to obtain the correct data for motion blur.

This gives correct results in mental ray as long as you keep the camera shutter angle below 359 degrees (see the “Special Effects” rollup in the camera AE). Note that using custom motion offsets in the mental ray render options affects the sample times so you might have to lower the shutter angle in that case.

Maxwell has a different sample method compared to mental ray, so you will have to keep the exposure time below half a frame. For example, at 24 FPS, one frame is 0.416 seconds, so the exposure time will have to be lower than 0.208 seconds. If you’re using the rotary shutter, you’ll have to keep the shutter angle below 180 degrees (note that Maxwell uses a different control for shutter angle than mental ray, check the “Maxwell Render” rollup in the camera AE).

If you wish to lengthen the motion blur, the RealFlow mesh node has a “Motion Blur Multiplier” attribute. Use this instead of increasing the shutter angle or speed to prevent the problems caused by varying mesh topology.

RealflowMesh node attributes The Attribute Editor interface for the RealflowMesh node has been rewritten.

Figure 14: RealflowMesh Attribute Editor.

The new interface exposes controls for the file name format and a new way of managing clip and cull cubes. Note that the old BIN mesh node had two LOD parameters, one for view and one for render. The render LOD factor has been removed since it only worked with the Maya Software renderer.

Performance The new BIN mesh node is roughly 50% faster than the old plug-in.

Clip & cull cubes Specially designated cubes can be used to clip a RealFlow mesh. Clip cubes remove the triangles which are inside them, while cull cubes remove all the faces which are outside their volume.

Figure 15: X-Ray view of RealFlow mesh and clip cube. Left: the clip cube is off. Right: the clip cube is on and removes the faces which fall inside it.

Figure 16: X-Ray view of RealFlow mesh and cull cube. Left: cull cube is off. Right: cull cube is on so it removes all the faces which are outside.

Several improvements have been made to the clip/cull cubes: they now work when the RealFlow mesh is transformed (rotated/translated/scaled), they can be rotated and they are managed from the RealFlow mesh Attribute Editor instead of relying on a naming convention.

To use the clip/cull lists in the AE, follow these steps:

• Select the RealFlow mesh and display its Attribute Editor.

• In the “List” menu of the AE window uncheck “Auto Load Selected Attributes”.

• Select the cube which you wish to use.

• Click “Add Selected” under the clip or cull cube list.

Figure 17: "Auto Load Selected" must be off so that selecting the desired cube does not change the Attribute Editor.

Visualizing fluid weights If a RealFlow mesh is computed from several fluids, the per-vertex weight of each fluid can be visualized in the Maya viewport using the Blind Data Editor. Simply add the tag for the RealFlow weight data (123321), set the mapping mode to “continuous”, assign colors for each fluid and click “Set Color”. Please note that because of the varying topology of the RealFlow mesh, the colors will only be valid for the frame when the coloring was applied. To inspect another frame click “Remove Color”, set the time to the new frame and click “Set Color” again.

Figure 18: Sample usage of the Blind Data Editor to visualize the weights for the fluids which interact to produce this mesh.