This plug-in for Softimage|XSI is a custom operator for creating polygon meshes. It polygonizes scalar fields, a method that is also called "Metaballs", "Marching Cubes", etc.

On the emPolygonizer2 web page you can:

• Download the demo version of this plug-in.
• Purchase the full version of this plug-in.
• Download demo and tutorial scenes.

This documentation has the following chapters:

• Chapter 1: Introduction
• Chapter 2: Installation (Windows/Linux) and Activation
• Chapter 3: Demo Version Restrictions
• Chapter 4: The Custom Operator's PPG
  • the PPG when using "Marching Cubes"
  • the tab "Main"
  • the tab "Data"
  • the tab "Tools"
  • the tab "Caching"
  • the tab "Advanced"
  • the PPG when using "Simple as Primitives"
  • the tab "Main"
  • the tab "Data"
  • the tab "Tools"
  • the tab "Caching"
  • the tab "Advanced"
  • the PPG's hidden Parameters
• Chapter 5: The Custom Property Sets
  • Brief Overview of the common parameters
  • The Custom Property Set of Polygon Meshes
• Tips and Tricks, Troubleshooting
• Version History
• Limitations and Remarks
• Epilogue: Thanks

If you feel that something is not well explained (or not explained at all) then please write me a short e-mail.
I will then update the documentation and/or make a demo scene as quickly as possible.

On my Vimeo page are many video tutorials in which I show and explain different aspects and techniques concerning this plugin and its usage. You might also try to search for "emPolygonizer" or "emPolygonizer2" on Vimeo to find some videos made by other people.

Important info:

• This plugin (emPolygonizer2) can be installed together with its predecessor emPolygonizer.
  => you need not install your old emPolygonizer 1.xx !

This plugin comes as a so called "Add-On", here's how to install it:

1. Open the "Plug-in Manager". It is located under the "File" menu: "File ->Plug-in Manager":



2. If you have a beta version or older version of emPolygonizer2 installed then please uninstall it.
   This is really important, because if Softimage|XSI finds two times the same plug-in then one (maybe even both) might not work.
   
3. To install the plug-in into the user directory simply right-click onto the folder "User Root" and choose "Install .xsiaddon...":



4. A browser dialogue will be displayed: go to where you copied the .xsiaddon file, select it and click on "OK". The Add-on is automatically installed.
5. Restart Softimage|XSI. The plug-in is now installed and ready to be used.
   For more information concerning Add-ons and how to install / uninstall them please check the chapter "Working with Add-ons" in the XSI Guides.

Activating the plugin with a License Code

If you have a license code you can activate the demo version as follows:

• Start Softimage|XSI.
• Create an emPolygonizer2 mesh: "Model -> Create -> Poly.Mesh -> emPolygonizer2" (STEP 1 in the picture below).
• Go into the tab "Advanced" of the emPolygonizer2 property page and click on "Enter License Code ..." (STEP 2).
• Enter your license code (you can copy/paste it). (STEP 3).
• Press enter (STEP 4). You're done!

If you are using the full version of this plugin (= you activated the demo version with a license code) then you can skip this chapter. If not, please read the following list of restrictions of the demo version:

• There is a built in memory limit of 16 Megabytes, thus limiting the level of detail and the number of polygons for the output meshes.
• The operator only works between frame 1 and frame 250.
• The text “DEMO VERSION” is contained in the custom operator's property page.
• Nearly all parameters of the tab “Advanced” of the operator's property page are unavailable.
• Motion Vectors and Motion Blur are disabled.
• User Normals are disabled.

Note: while testing the demo version you most probably will encounter error messages like for example "not enough memory" or "reached memory limit". These are NOT a bugs, it's simple the demo version restriction!

This chapter covers all the tabs and parameters of the custom operator's property page.

Note:
emPolygonizer2 has two so-called algorithms for building meshes:
1) "Simple as Primitives"
2) "Marching Cubes".
The parameters and tabs of the property page change depending on which algorithm is currently active.
This fourth chapter is divided into two big parts: the first part covers the tabs and parameters when the algorithm "Marching Cubes" is active and the second part will cover the tabs and parameters for the "Simple as Primitives" algorithm. Finally, at the end of this chapter, you will find a brief description of the "hidden" parameters: these are parameters that are rarely used and which are hidden by default. They can be made visible in the "Advanced" tab.

The tab "Main" when using the algorithm "Marching Cubes"

This tab contains the custom operator's main parameters:

• Active and Refresh
  Enables/disables the operator.
  If "Active" is unchecked you can force the operator to update the mesh by clicking on the "Refresh" button.
• Progress Bar
  Display a progress bar when building the mesh.
  When working with complex setups and a high level of detail the progress bar gives you the possibility to monitor the progress and eventually to cancel the operation.
• AlgorithmID
  Let's you specify which algorithm shall be used when building the mesh. You can choose between
  "Simple as Primitives" (left icon)
  "DPOctree Marching Cubes (v.2.0)" (right icon)
  
• Level of Detail
  Defines how much detail is generated. Higher values result in more detail, but require more memory and more calculations.
• Strength (Blur Isofield)
  Blurs the isofield. When generating vertex colors, user normals or motion vectors it is recommended to set this value greater than 0.
• Iterations (Blur Isofield)
  Amount of blur iterations. Use higher values with high level of detail values.
  Note: higher value require more memory and more calculations.
• Strength (Smooth Mesh)
  Smoothes and relaxes the final mesh.
  Note: values greater than 5 only increase calculation time without significantly improving whatsoever.

The tab "Data" when using the algorithm "Marching Cubes"

It is possible to create so-called "user data" for the mesh, for example you might want to create some normal vectors in order to improve the render quality.
The following user data can be created:

• Vertex Colors
  Vertex colors are great! They make your mesh look good in the viewport and good at render time. Surplus the vertex colors can be accessed in the Render Tree thus giving you many additional possibilities when it comes to shading.
• Motion Vectors
  The motion vectors are 3D motion vectors that are encoded into RGBA values.
  It is possible to view the motion vector colors in the viewport.
  The button "Tips & Tricks" will display some important information about motion blur, e.g. how to render a "2D motion vector color pass". There also is a video tutorial about 3D/2D motion blur on my Vimeo page.
• Normal Vectors
  The normal vectors are built from the internal isofield values and usually produce better render results than the ordinary normal vectors.

The buttons:

Use "Recreate" to activate a user data, "Delete" to deactivate it. Use "Set OGL Display to Vertex Colors"
and "Set OGL Display to Motion Vector Colors" to display the respective colors in the viewport (this does not affect the rendering).

The tab "Tools" when using the algorithm "Marching Cubes"

This tab provides a set of tools to pick, connect, disconnect, select and inspect objects (nulls, curves, polygon meshes and point clouds).

Input Objects / Connections

The buttons "Add" and "Remove" let you connect/disconnect objects to/from the operator. The behavior of both buttons depends on the current selection:
If nothing is selected the a picking session is started: click on the objects you want to connect/disconnect.
If one or more objects are selected then they are immediatly connected/disconnected to the operator.

The special button "Create and connect Null" will create a null and connect it to the operator. Surplus the null has a special display for a better visual feedback.

Select connected Objects

Use these tools to select objects (all or of a special kind) that are connected to the operator.

Inspect connected Objects

These tools can be used to display the property page of the custom property sets of connected objects.

Miscellaneous

The button "Re-connect the Polygon Meshes Cluster Properties" is somewhat special:
Cluster properties and weight maps can be used to drive certain parameters (see polygon mesh custom property set).
In rare cases (i.e. after connecting a polygon mesh that already has an emPolygonizer2 custom property set, or if clusters or cluster properties were renamed) it can happen that the cluster properties are not connected to the operator.
Clicking on this button will re-connect all cluster properties to the operator.

The tab "Caching" when using the algorithm "Marching Cubes"

The parameter "Action" specifies how to cache the geometry:

• No Caching
  Disables all geometry caching (neither write nor read)
  => the geometry is always created through simulation.
• Simulate and Write
  Always simulate (=create the mesh) and write it to disk (existing files are overwritten).
• Read only
  always read cached data and never simulate. If no cached data was found then an error occurs.
• Read or Simulate
  read cached data if available, else simulate (without writing data to disk).
• Read or Simulate and Write
  read cached data if available, else simulate and write the data to disk. This is sort of a "Skip rendered Frames" mode.

The group "Range / Extrapolation" contains parameters and functions that are self-explanatory and well-known, i.e. image sequences or animation mixer clips have similar parameters.
However, it is important to know that the behaviour of the parameter "Action" can vary depending whether a frame range is used or not.

If the parameter "Use range" is checked then ..

• .. the actions "Read or Simulate" and "Read or Simulate and Write" behave exactly like the action “Read only”, in other words: nothing is simulated nor written to disk!
• .. the action "Simulate and Write" will always simulate the mesh but only write the geometry to disk if the simulation frame is within the range defined by "Start Frame" and "End Frame".

The group "File Input/Output" defines the path, file name and file format of the geometry cache files. Currently there are three supported file formats, each with their own advantages and disadvantages:

1. "Wavefront (.obj)"
   the Wavefront obj file format is a well-known ASCII file format which is supported by most of the existing 3D packages, making it a good choice if you want to re-use the cached geometry in another 3D software or maybe even edit the files with a text editor.
   The disadvantages of the obj file format are the relatively large file sizes (longer read and write times, especially in a network) as well as the fact that vertex colors and motion vectors are not supported.
2. "Proprietary, ascii (.emp2)"
   this proprietary file format is a basic ASCII format, similar to the Wavefront format.
   It has all the disadvantages of the Wavefront format (i.e. file size) and is definitely not supported by any other 3D package.
   Its two main advantages are the fact that it is an ASCII format (and therefore editable) and that this format supports vertex colors, motion vector colors, etc.
3. "Proprietary, binary (.emp2)"
   this binary proprietary file format is the default for caching geometry.
   Its file size is the smallest, making it the best choice for distributed rendering, and it supports vertex colors, motion vector colors, user normals etc.

The tab "Advanced" when using the algorithm "Marching Cubes"

This tab contains advanced parameters:

• Group "Memory Limit"
  This defines a maximum amount of memory, in megabytes, that the operator is allowed to use for creating the mesh.
  Especially when working on 32 bit systems it is recommended to use the memory limit.
• Group "DPOctree"
  "Recycle Isofield (0=OFF)" will re-use the isofield data of the previous build instead of throwing it away. Even though it's very primitive the results are often very nice.
  Isovalues below the value of "Epsilon" are considered zero.
• Group "Miscellaneous"
  "Show rarely needed Parameters": if checked then ALL parameters are displayed in the property page. This is off by default to have a better looking property page.
  "Show Refresh Button in all Tabs": if checked then the refresh button is visible in all tabs.
  "Use Text rather than Icons and Bitmaps": if checked then no icons and bitmaps are used in the property page.
  

The tab "Main" when using the algorithm "Simple as Primitives"

This tab contains the custom operator's main parameters. The top section (Active, Progress Bar, AlgorithmID, etc.) is described here, the remaining section as follows:.

• PrimitiveID
  Specifies the geometry that is to be used. Available are:
  • Tetrahedron
  • Cube
  • Dodecahedron
  • Custom Polygon Mesh(es)
  When Custom Polygon Mesh(es) is active then some additional parameters and functions appear below.
• Transforms sub-group
  These parameters are used to control the size, alignment and rotation of the elements.
• Custom Polygon Meshes sub-group
  Provides parameters to control the allocation and randomness of the elements, as well as buttons for connecting, disconnecting and selecting custom meshes.

The tab "Data" when using the algorithm "Simple as Primitives"

This tab (and its parameters, buttons and functionality) is not available when using the algorithm "Simple as Primitives".

The tab "Tools" when using the algorithm "Simple as Primitives"

This tab is identical to the "Tools" tab when using the algorithm "Marching Cubes"..

.. please go here for more information.

The tab "Caching" when using the algorithm "Simple as Primitives"

This tab (and its parameters, buttons and functionality) is not available when using the algorithm "Simple as Primitives".

The tab "Advanced" when using the algorithm "Simple as Primitives"

Only the parameters in the groups "Memory Limit" and "Miscellaneous" are available, please go here for more information on those parameters.

In the tab "Advanced" you have the possibility to check the parameter "Show rarely needed Parameters". That will display a whole bunch of parameters that are generally not used or tweaked, but in some cases you might want to experiment with them. Many tabs have one or more hidden parameters:

• hidden parameters in the tab "Main"
  • Isolevel
    Defines the isolevel limit at which geometry is generated.
  • Shrink (Smooth Mesh)
    Controls the amount of shrinking when smoothing the final mesh.
    Low values (<=0.1) are recommended for animated emPolygonizer2 meshes because higher values can result in geometry flickering.
• hidden parameters in the tab "Advanced"
  • Filter Points
    This is similar to the Softimage|XSI's "Filter Points" operator: points that lay near together are merged together. Set this equal 0 to disable point filtering and to get that "faceted" look.
    This parameter is only used by the "marching cubes" algorithm.
  • Filter Polygons
    Defines the strength of the polygon filter.
    This parameter is only used by the "marching cubes" algorithm and only has an effect if the parameter "Filter Points" is greater than zero.
  • Quadrangulation
    These parameters control the quadrangulation.
    It is highly recommended to enable quadrangulation, the advantages being:
    • less geometry -> better overall performance
    • better viewport performance
    • less memory usage
    • nicer normal vectors -> nicer renderings
  • DPOctree Pre-allocateMemory(Megabytes)
    Amount of pre-allocated memory for the octree.
  • DPOctree Isofield Cleanup / Correction
    A few parameters to "fix" the isofield before building the mesh. This can help reduce the amount of "ugly" polygons. Might not be suited for animated meshes.
  • Always evaluate Operator on Time Change
    If checked then the operator is evaluated at every frame change. This might be of some help when using emPolygonizer2 while Softimage|XSI runs in batch mode.

The tabs "Data", "Tools" and "Caching" have no hidden parameters.

All important parameters can be driven by a weight map
or a vertex color map:

Notice the button "Show/Hide Weight Map Parameters" on the top left. By default the property page looks like the left one. By clicking on the "Show Weight Map Parameters" button the weight map and color vertices options are displayed.

• 3D/2D Motion Blur
  It is recommended to cache your geometry when rendering motion blur.

• New in Version 2.0:

  emPolygonizer2 v.2.0 is not only a simple update of emPolygonizer, it is in many aspects a whole new program with many new features, a new core and an improvement work flow.

• New in Version 2.05:

  • the parameter "Isolevel" is now permanently exposed in the tab "Main".
  • bug fix: the shader compound "emPolygonizer2_MotionVectorColors" was buggy and has been removed.
    To render a 2D motion vector color pass you can use the output shader called "Motion Vector (mip)" instead.

Things you should avoid when working with emPolygonizer2:

• Do not render 2D or 3D deformation motion blur with uncached geometry! In most cases this will result in corrupt renderings due to the fact that the topology (amount of points) of emPolygonizer meshes changes from frame to frame. This is especially important when you are using a shutter speed greater or equal 1 or when you are working with "Recycle Isofield".

Known issues:

• Compatibility... and the good old XSI 7.01

  This new version of emPolygonizer2 no longer works with older XSI and Softimage versions...
  --> It will only run with Softimage 2011 SP1 or higher.
  The reason for giving up compatibility with the old versions is simple: because of the constant improvements and bug fixes of Softimage's SDK as well as the new features of emPolygonizer2 it became more and more difficult to have the plugin work properly with the older Softimage and XSI versions, especially concerning user data, motion blur and other "fancy" stuff.

Thanks to:

- my buddy Oliver Weingarten who talked my into coding this mesher.