Scripts > SpeedTree SWA Importer for Maya

This Maya plug-in loads world-building data in SWA format. Its primary purpose is to reconstruct SpeedTree-generated forests in Maya.

The Maya SpeedTree SWA Importer plug-in is located in a subdirectory of the SpeedTree Modeler installation folder:
[SpeedTree Modeler Install Dir]/Scripts/Maya/SpeedSWAImporter.py

The SpeedTree SWA Importer plug-in is ideal for populating large amounts of instances, for objects such as trees, grass, rocks, or really any static or animated mesh object. The data is interpreted into a particle cloud, and objects are instanced onto these particles. This is an efficient way to instance objects, since each instance does not require an individual node.

SpeedTree SWA Importer works by loading a simple utility for getting the world-building data from the SpeedTree Modeler into Maya. World-building data is imported as 'SWA' (SpeedTree World-Building ASCII) files. The 'SWA' data is translated into Maya particles. The named entries do not necessarily correspond to names of objects in the scene. 'SWA' files are generated from the SpeedTree Modeler (exported from the “File” menu), or alternatively can be generated in other third party 3D applications such as Autodesk's 3ds Max.

Maya 2009-2014 are supported (requires a version of Maya that supports the Python API).

To install the plug-in, open up the Maya Plug-In Manager (menu item Window→Settings/Preferences→Plug-In Manager). Select the “Browse” button along the bottom and select this file – “[SpeedTree Modeler Install Dir]/Scripts/Maya/SpeedTreeSWAImporter.py”.

All associated files needed for the plug-in to function are added to Maya's search paths upon loading. The necessary associated files are listed below:

SpeedTreeSWAImporter.py

icons/out_SpeedTreeSWAImporter.xpm
icons/render_SpeedTreeSWAImporter.xpm
icons/SpeedTreeAbout.bmp
icons/SpeedTreeSWAImporter.png
templates/AESpeedTreeSWAImporterTemplate.mel

If this is your first time loading the plug-in, the SpeedTree FBX plug-in will be automatically loaded as well. This is to avoid double manual loading of each.

It is advisable to set the SpeedTree SWA Importer plug-in to auto-load with Maya. Enable the “Auto-Load” option in the 'Plug-In Manager' for this behavior.

Once the plug-in has been loaded, import a SpeedTree SWA file using the menu item File→Import…. In the “Files of type” selector, choose “SpeedTree SWA Importer”.

Additionally, SWA files can be imported using the MEL command “ImportSpeedTreeSWAImporter”, or the python command “maya.cmds.importSpeedTreeSWAImporter()” (note: for python, maya.cmds must first be imported into the main module).

The process of adding objects to the forest entries requires that the desired objects be selected first. After the desired objects are selected, SHIFT + select the desired particle set in the viewport, or CTRL + select the SpeedTree SWA Importer node in the 'Outliner'. This selection order is important.

Once an object has been assigned, the default behavior is to hide the object automatically. This is because the source object will still render unless it is hidden. The plug-in automates this process, and lets you hide and unhide all of the source nodes for an entire forest at once via the “Hide source objects” option. Object visibility is restored after an object has been removed from a forest entry.

Objects that are selected directly prior to the import of a 'SWA' file are automatically registered to the forest. Here again, the pick order matters. For a forest with three entries, the first three selected objects in the active list will be assigned to the three forest entries in the order that they were selected.

To remove an assignment to a forest entry, either press the “Remove” button next to the entry label, or simply replace the assigned object. If replaced, the old object is released back into the scnene, and made visible if it were hidden by the plug-in.

Below is a description of the various options available for the plug-in.

The 'SWA' file, which contains the forest data. Use the “browse” button to load a different 'SWA' file (or to update the contents of the current forest by reselecting the same file). Press the “Reload” button to load the data from the current 'SWA' file again, if it was edited externally.

When the forest data is changed, any assigned objects will be maintained and assigned to the new data.

When enabled, source objects are set to “hidden” after forest entry assignment. Otherwise, the source objects would remain visible in the viewport and renders. When an object is removed, its visibility is restored.

When enabled, forest data is visualized in the viewport as boxes, instead of as full meshes. Full meshes can quickly bog down the interactivity of the viewport.

Controls the visibility of the instanced objects. When disabled, only points will be visible in the viewport and renders.

The following options are available for each forest entry found in the 'SWA' file:

• Entry Name: Each entry label is taken from the data in the 'SWA' file. If the label is too long to read, hovering the mouse will reveal the whole name in a tooltip.

• Object name: The name of the assigned source node for this forest entry.

• Select Object Button: The arrow icon next to the source object label will select the source object itself, even if it is currently hidden.

• Remove: Once an object has been set to become the source for a forest entry, it can be removed via this button. If it was previously hidden, its visibility becomes restored.

• Assign Selected: Assigns the first valid selected object in the active list to this forest entry.

Please read the following suggestions for best use of the SpeedTree SWA Importer plug-in:

• This plug-in is intended for use with SpeedTree FBX files, but it works identically with any mesh, curve, NURBS, or subdiv object.

• A different 'SWA' file can be loaded in place over an existing forest. Simply change the 'SWA' filename using the “browse” button. Any object assignments will be maintained, provided that the new 'SWA' file has enough forest entries to accommodate them.

• Objects can be assigned to multiple forest entries or multiple forests simultaneously.

• Objects can be automatically assigned to a forest during import by first selecting the desired forest objects in order of the incoming forest entries directly prior to importing.

• Use the “Display as bounding boxes” option when the scene becomes bogged down with geometry. It will make the scene much more interactive.

• To edit an assigned source object, use the node link button to the right of the forest entry label. This will select the object, even if it is hidden, without needing to unhide it.

Avoid:

• Using detail or blend UV sets with mental ray. It appears that there is a limitaiton with particle instances in mental ray where only the first UV set is ever used.

• Using referenced SpeedTree FBX files that have oscillating wind shorter than the length of the final animation. The oscillation feature does not carry over to references.

• Importing very large forests all in the same file. Forests can be divided up into groups of similar objects and exported as multiple SWA files. Since SWA is an ASCII format, reading in large data files is not fast, like with binary files. Additionally, Python code must be converted to C++ by Maya, which adds additional overhead.

• Manually deleting forest particle sets, particle instancer nodes, or SpeedTree Forest nodes themselves without deleting all three.

• Long object names when exporting forests. There is limited room in the UI for displaying the name labels, so shorter ones work better.

• Better particle and startup particle caching. Saving files with new filenames should continue to find cached particles.

• Added “Forest visible” option to disable rendering of the forest data.

• Fixed reloading bug in the case of multiple SWA forests. Previously, the first SpeedTree SWA Importer node was always incorrectly reloading.

• Fixed template display in old versions of Maya (2009-2010).

• Removed collapsing group around forest entries, which works better in the case of multiple SpeedTree SWA Importer nodes.

• Added a check for associated skeletons when hiding source objects.

SpeedTree Forest plug-in for Maya released with SpeedTree Cinema and Studio v6.1.3.

Known Issues:

• Extra texture sets (detail, blend, and detail blend) do not render correctly on instanced particles when using mental ray. This appears to be a mental ray limitation. Instead, disable branch blending and detail texture export if using mental ray.

• Reloading of SWA files has been disabled for Maya 2009 and Maya 2010, because the old interface was creating issues with reloading the attribute editor template.