RealFlowMayaPlugin

FeaturesandImprovements
This document describes the improvements that have been made to the RealFlow Maya plugin. The mainareasoffocushavebeenworkflowandperformance.Thecodehasbeenrewrittenfromscratch butcarehasbeentakentopreservebackwardscompatibility.

Installer
Thenewpluginhasaninstallerwizardsothatusersarenolongerrequiredtomanuallycopyfilesinto theMayadirectory.TheinstallerautodetectswhichMayaversionsareinstalledandwhere.Allversions ofMayastartingwith7.0aresupported,withboth32bitand64bitbuildswhereapplicable.

Figure1:ThewizardautodetectsMayaversionsandinstallationdirectories.

NOTE: the installer will remove the files belonging to the old plugin because they interfere with the functioningofthenewcode.

MELSupport
ThepluginfunctionalityisavailabletoMELthroughtherealflow command.Thesyntaxforeachof the functions (SD export, BIN import etc.) is described in the corresponding section later in this document.

Toolbar
The functionality of the plugin is conveniently shown via a shelf (toolbar). The plugin manages this toolbarautomaticallyandupdatesitscontentswhenanewerversionisavailable.

Figure2:RealFlowtoolbar.

Thepurposeoftheoptions,fromlefttoright: ExportSD:ExportsthecurrentsceneasanSDfileusingthelastsettings.Ifthisisthefirsttime thesceneisexported,orthesettingsarenotpersistent,thebuttonbringsupthesettingsdialog. ExportSDSettings:AllowstheusertoadjusttheSDexportsettings. ExportBINParticles:CanbeusedtoexportMayaparticlesasasequenceofBINfiles.Itusesthe last settings stored in the scene if available or brings up an options dialog, just like the SD exporter. ExportBINParticlesSettings:DisplaystheoptionsdialogfortheBINparticleexporter. ImportSD:ImportsanSDscenefileintothecurrentMayascene. ImportBINParticleSequence:CreatesaRealFlowparticlesystemwhichloadsparticlesfroma sequenceofBINfiles. ImportBINMeshSequence:CreatesameshobjectinsideMayaandloadsitsgeometryfroma sequenceofBINmeshfiles.

FileTranslators
SDscenefilescanalsobehandledthroughtheImport,ExportAllandExportSelectionitemsinthe Filemenu.Clicktheoptionboxtotherightoftheexportmenuitemstoaccesstheexportsettings. BIN files can be imported through the File>Import menu. The importer will detect the type of the sequencemeshorparticlesandcreatethecorrespondingMayaobjects. Both importers also function in the Best Guess mode, so theres no need to select the file type explicitlyinthefilebrowserdialog.

SDFileImport/Export
ThissectionwilldiscusstheusageoftheSDpartofthepluginanditsimprovementscomparedwiththe previousversion.

Geometrysupport
All3geometryrepresentationmethodsaresupportedbytheplugin:polygonalmeshes,NURBSsurfaces andSubdivisionsurfaces.Polygonalmeshesnolongerneedtobetriangulatedbeforeexport.Theplugin alsoexportsthediffusecolorforthosemesheswhichdonotuseatexture.

Progressreporting
BoththeimportandexportprocessesreportprogressthroughthemainMayaprogressbar,inthestatus line.TheusercancancelatanytimebypressingtheESCkey.Pleasenotethatabortinganimportbefore anyframeshavebeenreadwillleavealltheimportedobjectsattheorigin.

Figure3:Progressreporting.

Exportoptions
The exporter settings can be made persistent in the scene so that they dont have to be reentered beforeeveryexport.

Figure4:SDexportsettingsdialog.

Thefollowingsettingsareavailable: File:thepathtothedestinationSDfile. Frameinterval:theactiveplaybackrangecanbeused,oranexplicitintervalcanbespecified. 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 deformableobjects.Whentheoptionisdisabled,thegeometryoftheobjectsisexportedonce andonlypositioningdata(translation,rotation,scaling)isexportedperframe. Camera:Theactive3Dviewcanbeused,oryoucanexplicitlychoosewhichcameratoexport. Persistent Options: when this is on, the settings are stored in the scene so that it can be re exportedlaterwithasinglebuttonclick.However,thesettingsnodecausesproblemsifyoutry toopenthescenelateronasystemwherethepluginisnotinstalled,andsothisoptioncanbe usedinthosecasestopreventthepluginfromcreatingthenode.

MELsupport
SDfilescanbeimportedwiththefollowingsyntax: realflow importSD path_to_file Whenusingthecommandtoexportscenes,theexportsettingscaneitherbetakenfromthescene,or explicitlyspecified.Tousethesettingsstoredinsidethescene,invokethecommandlikethis: realflow exportSD useSettingsNode Tospecifytheoptionsasarguments,startwith: realflow exportSD file path_to_file Thenaddoneormoreofthefollowingflags: -selected toexportonlytheselectedobjects.Thedefaultistoexporteverything. -camera camera_name toselectwhichcameratouse.Thedefaultistousetheactive3D view. -startFramespecifiesthefirstframetoexport.Thedefaultis1. -endFramespecifiesthelastframetoexport.Thedefaultis24. -usePlaybackRange isusedtoexportthecurrentlyactiveplaybackrange.Ifyouusethis flag,-startFrameand-endFrameareignored. -deformationturnsonperframegeometryexportonallobjects.Bydefaultthecommand doesnotexportdeformations.

RealFlowspecificmeshattributes
ARealFlowrollupisaddedintheAttributeEditorforshapenodes.Therollupcontainsattributeswhich controlhowtheSDexportertreatstheobject: Ignore:whenthisischecked,theexportersimplyskipstheobject. Export deformation: this can be used as an objectlevel override for the deformation mode whichisspecifiedintheexportoptions.

Figure5:RealFlowspecificshapeattributes.

Theseattributesaredynamicallyaddedtoshapenodesonlywhentheyaresettoanondefaultvalue.If anattributeislatersetbacktoitsdefaultvalue,itisremovedfromtheobject.Thissolutionprevents bloatingthescene.

Performanceimprovements
TheoldpluginusedtobuildtheentireSDfileinmemoryatexporttimeandonlywroteittodiskatthe end of the process. This caused problems in large scenes, where Maya was already using a lot of memorybyitself.Thenewcodewritesthedatadirectlytothefile,sonoextramemoryisneeded.Itis alsosignificantlyfaster. To illustrate the improvement, we have used a scene containing 900 objects which added up to 1,080,000polygons.Wehaveexported100frameswithandwithoutdeformation,withboththeoldand thenewplugins.TheresultingSDfileswere89MBwithoutdeformationand714MBwithdeformation. NoDeformation OldPlugin Newplugin WithDeformation OldPlugin NewPlugin
Table1:SDperformancecomparison

Time 13:16 00:40 17:19 01:24

Memoryusage 103MB 0.3MB 1589MB 0.3MB

Additionally,thenewplugintakesaround01:30toimportbacktheresultingfile(withdeformation)and theperformanceisacceptablewhenmovingthetimeslider.Theoldpluginwouldrequireinexcessof 700GBofmemorytoimportthesamescene.

Greatlyimprovedhandlingforsoftbodyobjects
TheoldpluginusedtokeeptheentireSDfileinmemoryforeachsoftbodyobjectinthescene.This madeitimpossibletoworkwithlargefilesorlargenumbersofobjects.Thesoftbodynodeinthenew pluginonlycachesfileoffsetsforeachframeandloadsthegeometryfromdiskwhenthecurrentframe changes,ensuringoptimalmemoryusage. ThenodedetectswhentheSDfilechangesanddisplaysanerrormesh(currentlyacube).Italsoissuesa warningwhichaskstheusertoreimportthemodifiedSDfile. Wehavealsochangedthebehaviorofthesoftbodyobjectswhenthecurrenttimeissetoutsidethe framerangecontainedintheSDfile.Theoldnodemadethegeometrydisappearwhenthishappened. Thenewnodedisplaysthefirstorlastframe,dependingonwhetherthecurrenttimeisbeforeorafter theanimationrange.

Figure6:AttributeEditorforthesoftbodynode.

Miscellaneousimprovements
Largefilesupport:thepluginuses64bitoffsetsforfileoperations,sotherearenorestrictions onthesizeoftheSDfiles. Reusedanimationcurves:whenimportingananimationforanobjectwhichexistsinthescene, thenewpluginreusestheanimationcurvesofthatobject,iftheyarepresent.Theoldplugin usedtocreateanewsetofcurveswitheachimport,resultinginabunchofunusednodeslying aroundinthesceneiftheuserrepeatedlyimportedaSDfile.

RealFlowParticlesinMaya
ThissectioncoversthepartofthepluginwhichhandlessequencesofparticleBINfiles.

BINImport
PressingtheImportBINsequencebuttoninthetoolbarwillasktheusertoselectaBINfile.Afterthis isdone,thepluginwilltrytoautodetectthenameformatandframepaddingusedforthegivenfile nameandwilldisplayadialogboxwhichallowssettingtheoptionsfortheemitterwhichwillbecreated.

Figure7:Particleimportoptions.

Youcanadjustthenameformatorpaddinghereiftheinitialguessmadebythecodeisnotcorrect.The pluginwillextractthefileprefixbasedontheformatandpaddingselection.Notethatifyouchoosean invalidformatorpadding(i.e.thefilenamecannotbereconstructedusingyoursettings)thedialogwill displayanerrormessageinthePrefixfield,asintheexamplebelow:

Figure8:Thefilenamecannotbereconstructedusingthename_#.extformatbecauseitusesadot,notanunderscore.

NewAttributeEditorInterfacefortheemitternode
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 hiddensincetheyarenotrelevanttotheRealFlownode.


Figure9:NewemitterAEinterface.

Changedattributes
TheoptionsforsuppressingcertainchannelsfromtheBINfiles(e.g.mass,normals,viscosityetc.)have beenremovedbecausetheydidntprovideanyperformancegains.Everythingisloadednowandsentto theparticleshape.

Theloadsequence,userangeandcliptorangeattributeshavebeenchangedfromintegerarrays tobooleanarrays. TherfPositionandrfVelocityoutputchannelshavebeenremovedbecausetheyhavenativeMaya equivalents(thepositionandvelocityattributesontheparticleshapenode).

Performanceandstabilityimprovements
Theparticleloaderistwotimesfasterthantheoldplugin,resultinginbetterinteractivitywhenworking withlargenumbersofparticles. The code is around 5 times shorter so its easier to maintain. It makes no explicit dynamic memory allocations,resultinginbetterstabilityinlowmemorysituations.

Backwardscompatibility
Existingscenesshouldworkwithoutchangeswiththenewplugin.Makesurethattherealflow.mllplug inisloadedbeforeopeningascenewithemitterscreatedbytheoldplugin(thebestwaytodothisisto set realflow.mll to autoload in the plugin manager). Also make sure that you remove the RealflowParticler.mllfilefromtheMayapluginsdirectory,otherwiseMayawilltrytoloaditwhenyou opentheexistingscene. Mayawillshowawarningdialogwhenyouloadanexistingscenewiththisplugin.Itissafetoignore thiswarning.Ifyousimplyclosethedialogboxandresavethescenethenodeswillbeconvertedtothe formatusedinthenewpluginandyouwontreceiveanymorewarningsthenexttimeyouopenthe file.

Figure10:Warningdialogwhenloadingoldscenes.

Sometimes when loading old scenes the new plugin 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 particlesareclearedandafreshsetiscreatedandthensavethescene.Youonlyneedtodothisonce afteryouopenanoldscene.

BINExport
AnyMayaparticlesystemcanbeexportedasasequenceofBINfilesandloadedinRealFlow.Aswiththe SD exporter, the BIN export options can be made persistent so that subsequent exports can be performedwithasinglebuttonclick.

Figure11:BINparticleexportoptions.

YoucanaddseveralMayaemitterstotheParticleNodeslistandtheywillallbeexportedasasingle emittertoRealFlow.

MELSupport
YoucanexportparticlesasaBINsequenceusingthefollowingsyntax: realflow exportBIN useSettingsNode Or,tospecifyoptionsmanually: realflow exportBIN path export_directory prefix file_prefix node emitter_node_name

The-node flagcanappearseveraltimesifyouwishtoincludemorethanoneMayaemitter. Thefollowingflagscanbeusedtospecifyextraoptions: -nameFormat N, whereN is0for name.#.bin,1forname#.bin,2forname.bin.#,3 forname_#.bin.Thedefaultisname#.bin. -padding N, whereNisthenumberofdigitsusedfortheframenumber.Thedefaultis5. -particleType N, where N is 0 for gas, 1 for liquid, 2 for dumb, 3 for elastics, 4 for custom.Thedefaultisdumb. -startFramespecifiesthefirstframetoexport.Thedefaultis1. -endFramespecifiesthelastframetoexport.Thedefaultis24. -usePlaybackRange isusedtoexportthecurrentlyactiveplaybackrange.Ifyouusethis flag,-startFrameand-endFrameareignored. -frameOffset canbeusedtooffsettheexportedsequencerelativetotheMayatime.For examplespecifyinganoffsetof10willcauseframe11inMayatobeexportedasfile0001.bin.

Progressreporting
ThemainMayaprogressbarisusedtodisplaythestatusoftheBINexportoperation.Theexportcanbe canceledatanytimebypressingtheESCkey.

Figure12:ProgressbarforBINparticleexport.

RealFlowMeshesinMaya
SequencesofBINmeshfilescanbeloadedusingthelastbuttoninthetoolbarortheFile>Importmenu. AnoptionsdialogsimilartotheBINparticledialogwillbedisplayed:

Figure13:BINmeshimportsettings.

Motionblursupport
RealFlowmeshesusuallyhaveunstabletopology:verticesarecreatedorremovedateachframe.This causes problems with motion blur in most renderers, since this effect needs the same number of verticesineverysubsteptofunctioncorrectly.Theplugintriestoworkaroundthisbyusingthesame BIN file for half a frame before and after each integer frame, e.g. file0004.bin will be used between frames3.5and4.5.ThevertexpositionsaredisplacedusingthespeedstoredintheBINfiletoobtain thecorrectdataformotionblur. Thisgivescorrectresultsinmentalrayaslongasyoukeepthecamerashutteranglebelow359degrees (seetheSpecialEffectsrollupinthecameraAE).Notethatusingcustommotionoffsetsinthemental rayrenderoptionsaffectsthesampletimes,andsoyoumighthavetolowertheshutterangleinthat case. Maxwellhasadifferentsamplemethodcomparedtomentalray,soyouwillhavetokeeptheexposure timebelowhalfaframe.Forexample,at24FPS,oneframeis0.416seconds,sotheexposuretimewill havetobelowerthan0.208seconds.Ifyoureusingtherotaryshutter,youllhavetokeeptheshutter anglebelow180degrees(notethatMaxwellusesadifferentcontrolforshutteranglethanmentalray, checktheMaxwellRenderrollupinthecameraAE).

If you wish to lengthen the motion blur, the RealFlow mesh node has a Motion Blur Multiplier attribute.Usethisinsteadofincreasingtheshutterangleorspeedtopreventtheproblemscausedby varyingmeshtopology.

RealflowMeshnodeattributes
TheAttributeEditorinterfacefortheRealflowMeshnodehasbeenrewritten.

Figure14:RealflowMeshAttributeEditor.

Thenewinterfaceshowscontrolsforthefilenameformat,anewwayofmanagingclip/cullcubes,and checkboxeswhichdeterminehowfluidweightsareexposedtoMayaandmentalray.Notethattheold

BINmeshnodehadtwoLODparameters,oneforviewandoneforrender.TherenderLODfactorhas beenremovedsinceitonlyworkedwiththeMayaSoftwarerenderer.

Performance
ThenewBINmeshnodeisroughly50%fasterthantheoldplugin.

Clip&cullcubes
SpeciallydesignatedcubescanbeusedtoclipaRealFlowmesh.Clipcubesremovethetriangleswhich areinsidethem,whilecullcubesremoveallthefaceswhichareoutsidetheirvolume.

Figure15:XRayviewofRealFlowmeshandclipcube.Left:theclipcubeisoff.Right:theclipcubeisonandremovesthe faceswhichfallinsideit.

Figure16:XRayviewofRealFlowmeshandcullcube.Left:cullcubeisoff.Right:cullcubeisonsoitremovesallthefaces whichareoutside.

Severalimprovementshavebeenmadetotheclip/cullcubes:theynowworkwhentheRealFlowmesh is transformed (rotated/translated/scaled), they can be rotated and they are managed from the RealFlowmeshAttributeEditorinsteadofrelyingonanamingconvention.

 Tousetheclip/culllistsintheAE,followthesesteps: SelecttheRealFlowmeshanddisplayitsAttributeEditor. IntheListmenuoftheAEwindowuncheckAutoLoadSelectedAttributes. Selectthecubethatyouwishtouse. ClickAddSelectedunderthecliporcullcubelist.

Figure17:"AutoLoadSelected"mustbeoffsothatselectingthedesiredcubedoesnotchangetheAttributeEditor.

Visualizingfluidweights
IfaRealFlowmeshiscomputedfromseveralfluids,thepervertexweightofeachfluidcanbevisualized 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,setthemappingmodetocontinuous,assigncolorsforeachfluidandclickSetColor.Please note that because of the varying topology of the RealFlow mesh, the colors will only be valid for the framewhen thecoloring wasapplied.ToinspectanotherframeclickRemoveColor,setthetimeto thenewframeandclickSetColoragain.


Figure18:SampleusageoftheBlindDataEditortovisualizetheweightsforthefluidswhichinteracttoproducethismesh.

Thementalraymeltshader
Wehaveaddedamentalrayshaderwhichcanbeusedtocombineseveralmaterialsbasedonthefluid weightscontainedinaRealFlowmeshfile.TheshaderiscalledrealflowMeltShaderMranditcanbe foundintheMaterialssectionofHypershadewhenCreatementalrayNodesisselected,orinthe AssignNewMaterialmenuwhichappearswhenrightclickingonameshintheviewport. Tousetheshader,createasmanyinputslotsastherearefluidsonthemeshandconnectamaterialfor eachfluid.Thefollowingimageshowsanexampleshadingnetworkforameshwithtwofluids:

Figure19:Sampleshadingnetworkfortwofluids.

TheAttributeEditorforthemeltshaderwillshowonerollupforeachoftheconnectedmaterials.You canusetheAEtoconnectanddisconnectinputsandtocontrolthenumberofmaterials.Thetrashcan buttoncanbeusedtoremoveafluidmaterial.


Figure20:MeltshaderAttributeEditor.

The melt index attribute gives the user some control over the appearance of the parts of the mesh whereseveralfluidsmeet.Avalueof0willblendthematerialcolorsusingthefluidweightsexactlyas theyarestoredintheBINfile.Increasingthevaluetowards1willexaggeratetheweights,brightening theblend.Negativevalueswillscaledowntheweights,sotheresultwillbedarker. Notes: Youneedtoconnectshadinggroupnodesasinputs,notmaterialnodesdirectly.Ifyouusethe AttributeEditortomanagetheconnectionsandassignamaterialnodeasinput(e.g.bydragging aPhongnodefromHypershadetooneofthematerialfields,orbyusingthecheckerbuttonto createanewmaterial),thepluginwillautomaticallyredirecttheconnectiontothematerials shadinggroup.However,ifyousetuptheshadingnetworkmanuallyinHypershade,makesure youusethemessageattributeoftheshadinggroup,notthematerialitself. ThemeltshaderwillonlyfunctiononBINmeshesbecauseitrequirespervertexfluidweights. TheExportFluidWeightsFormentalrayattributemustbeenabledontheBINmesh. TheshaderisnotavailableinMaya7. Theshaderwillnotfunctionifyoudisabletheexportcustomdatafunctionofthementalray translator. This setting can be found in the mental ray render options under Translation > Customization.Theoptionisenabledbydefault.

Advanced:usingthefluidweightsfromothermentalrayshaders
If Export Fluid Weights for mental ray is enabled, the weights can be accessed from anymental ray shader. Maya exports them as extra texture spaces for the shape, so they are available in the tex_list arrayofthestatestructure.

Todeterminetheindiceswhichneedtobeusedtoaccesstheweights,shaderwritersmustsearchfora maya_vertexdataobjectinthemeshdata(magicnumber1298749048)andlookforentriesnamed RfWeightsX,whereXisanumberfrom0tothenumberoffluidsminusone.Theentrieswillcontain the offsets which need to be applied to the tex_list array for each fluid. The weights have one component,sotheywillbeavailableinthexmemberofthetex_listentries.

Advanced:obtainingfluidweightsfrom3rdpartypluginsandrenderers
Therearetwomethodsforreachingthefluidweightsfroma3rdpartyMayaplugin: They are available as pervertex blind data on the mesh object. Use the polyQueryBlindDataMELcommandortheMFnMesh::getDoubleBlindData()API functiontoaccessthem.Forthistowork,FluidWeightsAsBlindDatamustbecheckedinthe AEofthemeshobject. WhenExportFluidWeightsFormentalrayisenabled,theweightsareattachedtotheobject as custom attributes of type doubleArray. One attribute is created for each fluid. The attributesarecalledmiCustomTexRfWeightsX,whereXisthefluidnumber.Theweightsare storedpervertex,sothenumberofelementsineacharrayequalsthenumberofverticesofthe mesh.