RealFlow Maya Plug‐in Features and Improvements 

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

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 7.0 are supported, with both 32‐bit and 64‐bit builds where applicable. 

 

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

NOTE:  the  installer will  remove  the  files belonging  to  the old plug‐in because  they  interfere with  the functioning of the new code. 

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  shown  via  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 options, from left to right: 

• Export SD: Exports the current scene as an 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. 

• 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 SD: Imports an 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. 

• 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 to 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 with 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, and 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 auto‐detect 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, as 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 makes 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, and 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 shows controls for the file name format, a new way of managing clip/cull cubes, and checkboxes which determine how fluid weights are exposed to Maya and mental ray®. 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 that 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.  First, make  sure  “Fluid Weights  as  Blind Data”  is checked  in  the mesh AE.  Then  add  the  tag  for  the RealFlow weight data  (123321)  in  the Blind Data Editor, 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. 

The mental ray® melt shader We have added a mental ray® shader which can be used to combine several materials based on the fluid weights contained  in a RealFlow mesh file. The shader  is called “realflowMeltShaderMr” and  it can be found  in the “Materials” section of Hypershade when “Create mental ray Nodes”  is selected, or  in the “Assign New Material” menu which appears when right clicking on a mesh in the viewport. 

To use the shader, create as many input slots as there are fluids on the mesh and connect a material for each fluid. The following image shows an example shading network for a mesh with two fluids: 

 

Figure 19: Sample shading network for two fluids. 

The Attribute Editor for the melt shader will show one rollup for each of the connected materials. You can use the AE to connect and disconnect inputs and to control the number of materials. The trashcan button can be used to remove a fluid material. 

 

Figure 20: Melt shader Attribute Editor. 

The “melt  index” attribute gives  the user some control over  the appearance of  the parts of  the mesh where several fluids meet. A value of 0 will blend the material colors using the fluid weights exactly as they are stored  in the BIN file.  Increasing the value towards 1 will exaggerate the weights, brightening the blend. Negative values will scale down the weights, so the result will be darker. 

Notes: 

• You need to connect shading group nodes as inputs, not material nodes directly. If you use the Attribute Editor to manage the connections and assign a material node as input (e.g. by dragging a Phong node from Hypershade to one of the material fields, or by using the checker button to create a new material), the plug‐in will automatically redirect the connection to the material’s shading group. However, if you set up the shading network manually in Hypershade, make sure you use the “message” attribute of the shading group, not the material itself. 

• The melt shader will only function on BIN meshes because it requires per‐vertex fluid weights. 

• The “Export Fluid Weights For mental ray” attribute must be enabled on the BIN mesh. 

• The shader is not available in Maya 7. 

• The shader will not function if you disable the “export custom data” function of the mental ray translator.  This  setting  can  be  found  in  the mental  ray  render  options  under  Translation  ‐> Customization. The option is enabled by default. 

Advanced: using the fluid weights from other mental ray® shaders If “Export Fluid Weights  for mental ray”  is enabled,  the weights can be accessed  from any mental ray shader.  Maya  exports  them  as  extra  texture  spaces  for  the  shape,  so  they  are  available  in  the tex_list array of the state structure. 

To determine the indices which need to be used to access the weights, shader writers must search for a maya_vertexdata object in the mesh data (magic number 1298749048) and look for entries named 

“RfWeightsX”, where X  is a number from 0 to the number of fluids minus one. The entries will contain the  offsets which  need  to  be  applied  to  the tex_list  array  for  each  fluid.  The weights  have  one component, so they will be available in the x member of the tex_list entries. 

Advanced: obtaining fluid weights from 3rd party plug­ins and renderers There are two methods for reaching the fluid weights from a 3rd party Maya plug‐in: 

• They  are  available  as  per‐vertex  blind  data  on  the  mesh  object.  Use  the polyQueryBlindData MEL command or the MFnMesh::getDoubleBlindData() API function to access them. For this to work, “Fluid Weights As Blind Data” must be checked in the AE of the mesh object. 

• When “Export Fluid Weights For mental ray” is enabled, the weights are attached to the object as  custom  attributes  of  type  “doubleArray”.  One  attribute  is  created  for  each  fluid.  The attributes are called “miCustomTexRfWeightsX”, where “X” is the fluid number. The weights are stored per‐vertex, so the number of elements in each array equals the number of vertices of the mesh.