emReader

(version
Last edited on October 3rd, 2016)

Introduction

Introduction

Read me first:
emReader is available for Fabric Engine, Softimage, Maya, Cinema 4D and Modo.
Since this documentation covers the emReader versions for all the above 3D applications certain parts that concern only a specific application will be marked like this: [3D App].

[Fabric] This extension for Fabric Engine provides functions in KL as well as presets in Canvas to load and manipulate cached geometry sequences as well as particle cache files.

[Maya] This plugin for Maya is a node to load and manipulate cached geometry sequences.

[Modo] This plugin for Modo is a procedural item to load and manipulate cached geometry sequences.

[C4D] This plugin for Cinema 4D is generator object to load and manipulate cached geometry sequences.

[Softimage] This plugin for Softimage is a custom operator that loads and manipulates cached geometry sequences.

 

On the emReader web page you can:

  • download the demo version of this plugin.
  • download demo and tutorial scenes.
  • purchase the full version of this plugin.

Note: 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.

Tip: Check out the following sites for more information, videos and discussions:
Fabric Engine Forum - the official Fabric forum
si-community.com - the unofficial Softimage community
softimage.tv - the Softimage user based video library
luxology forum - the official Luxology forum
SimplyMaya - a site dedicated to teaching Maya
CGTalk (Cinema 4D) - the Cinema 4D specific forum of CGTalk

Installation [Fabric]

Please see the following video on how to install extensions for Fabric Engine:

Fabric Engine Tutorial 01 - Installing Mootzoid Extensions

Installation [Maya]

The following files belong to the plugin:

  • emReader.mll
    This is the compiled C++ code of the main emReader node.
  • AEemReaderTemplate.mel
    This MEL script controls how the node parameters are displayed in Maya's attribute editor.
  • vcomp.dll
    A dynamic library.

There are many ways to install plugins in Maya, here are two of them:

  1. simply copy all the files that belong to the plugin into Maya's plugin directy, for example:
    "C:\Program Files\Autodesk\Maya2012\bin\plug-ins"

  2. put all the plugin's files into some folder of your choice (e.g. "D:\MyMayaPLugins\emReader\") and then define and set the following Maya environment variables accordingly:

    • MAYA_PLUG_IN_PATH = "D:\MyMayaPLugins\emReader\".
    • MAYA_SCRIPT_PATH = "D:\MyMayaPLugins\emReader\".

Once you installed the plugin you will have to go into Maya's plugin manager and enable "Loaded" and/or "Auto load".

Please check out the Maya documentation for more information on how to install / uninstall plugins or ask your system administrator or TD to help you.

Installation [Modo]

This plugin comes as a so-called "kit".
There are several ways to install a kit, here is one of them:

   Simply copy the entire "emReader" folder into Modo's user config folder.

FAQ:
   "Where is Modo's user folder??"

ANSWER (Windows):
   "assuming your username is "John" then the user folder is:
   C:\Users\John\AppData\Roaming\Luxology\Configs"

ANSWER (OS X):
   "assuming your username is "John" then the user folder is:
   /Users/John/Library/Application Support/Luxology/Configs"

To check if the kit was successfully installed simply start Modo and then go into the menu "Help -> Kit Version". There you should see "emReader (version 1.xx)".

Please check out the Modo documentation or perhaps a Modo forum for further information concerning kits, plugins and how to install / uninstall them.

Installation [C4D]

The easiest way to install the plugin is to copy the emReader folder into Cinema 4D's plugin folder.
Alternatively you could also copy the emReader folder somewhere else and then set the environment variable C4D_PLUGINS_DIR accordingly.

To check if the plugin was successfully installed simply start Cinema 4D and then go into the menu "Plugins". There you should see "Mootzoid - emReader".

Please check out the Cinema 4D documentation or perhaps a Cinema 4D forum for further information concerning plugins and how to install / uninstall them.

Installation [Softimage]

Installing the addon:

  1. Open the "Plugin Manager". It is located under "File -> Plugin Manager":

  2. To install the plugin into the user directory simply right-click onto the folder "User Root" and choose "Install .xsiaddon...":

  3. A browser dialogue will be displayed: go to where you copied the .xsiaddon file, select it and click on "OK". The addon is then automatically installed.

  4. Close Softimage. The plugin is now fully installed and ready to be used. For more information concerning addons and how to install / uninstall them please check the chapter "Working with Addons" in the Softimage documentation.

Demo Version Restrictions [Fabric]

If you are using the full version of this plug-in then you can skip this chapter. If not, please read the following list of restrictions of the demo version:

  • meshes will have the text "Demo Version" contained in the geometry.

  • particles will have 8 additional particles located at the bounding box corners.

Demo Version Restrictions [Modo / Maya / C4D]

If you are using the full version of this plug-in then you can skip this chapter. If not, please read the following list of restrictions of the demo version:

  • the plugin will only load and display geometry between frame 0 and frame 100.

  • the text "Demo Version" is contained in the geometry.

Quick Setup [Fabric]

To create an emReader polygon mesh:

  • Use the Tab search to add a "LoadMesh" preset to your graph.
  • Adjust the filename and fileindex.
  • Plug the output port into a PolygonMesh port of, say, a "DrawMesh" preset.

Quick Setup [Softimage]

To create an emReader polygon mesh:

  • Choose "Model -> Poly.Mesh -> emReader".
    The property page of the freshly created emReader mesh pops up.
  • Adjust the path, filename and fileformat or use the "Browse" button.

Quick Setup [Maya]

To create an emReader setup:

  • Execute the command "emReaderCreate" in the command line.
  • Adjust the path, filename and fileformat attributes of the emReader node.

Quick Setup [Modo]

To create an emReader item:

  • Get a cube item: "Item -> Primitive -> Cube".
  • Change the cube's item type: "Item -> Change Type -> Mootzoid -> emReader".
  • Adjust the item's path, filename and fileformat or use the "Browse" button.

Quick Setup [C4D]

To create an emReader object:

  • Choose "Plugins -> Mootzoid - emReader".
  • Adjust the object's path, filename and fileformat.

The Parameters

File

File

Contains all file relevant parameters, such as the path, filename and extension of the geometry files. Some additional parameters let you enable/disable the loading of data such as motion vectors, normals, etc.

  • The Parameters:

    • Active [Softimage, Maya, Modo]
      Enable/disable the plugin.

    • Verbose [Softimage]
      Defines the verbose level into the history log.

    • Path
      The path where the cache files are located.

    • Browse [Modo]
      This button executes a little script that will display a dialogue so that you can browse for the file sequence:
      Simply select and open the first file of the sequence. The script will then automatically set the path, the filename and the fileformat.

    • ... [Softimage]
      Use this button to browse for a file sequence, then select and open the first file of the sequence. The path, the filename and the format are then automatically set.

    • Filename
      The filename (without extension) of the cache files. Surplus you specify the padding of the file indices using the character '#'.
      Examples:

      • Geo_# refers to Geo_1, Geo_2, .. , Geo_128, .. , Geo_1024.
      • Geo### refers to Geo001, Geo002, .. , Geo128, .. , Geo1024.
      • Geo.##### refers to Geo.00001, Geo.00002, .. , Geo.00128, .. , Geo.01024.
    • Fileformat
      The fileformat of the cache file sequence.

    • Index Mode
      Defines in which way the indices of the cache file sequence are handled:

      • Use Idx Value (Round)
        The file index is the rounded value of the parameter "Idx Value".
      • Use Idx Value (Floor)
        The file index is the downward-rounded value of the parameter "Idx Value".
      • Use Idx Value (Ceil)
        The file index is the upward-rounded value of the parameter "Idx Value".
      • Use current Frame [Softimage]
        The file index is equal the current frame.
    • Idx Value
      A custom index that is used depending on the value of the parameter "Index Mode".

    • Idx Fraction Strength
      If motion vectors are available and if this value is greater than zero then the fraction of the Idx Value will be used to move the vertices along the motion vectors.

    • Load Normal Vectors
      Loads the normal vectors that are contained in the cache file. If the cache file does not contain any normal vectors then this has no effect.

    • Load Motion Vectors
      Loads the motion vectors that are contained in the cache file. If the cache file does not contain any motion vectors then this has no effect.
      Note: you must enable this if you want to have deformation blur or if you want to use the parameter "Idx Fraction Strength".

    • Load UVWs
      Loads the UVWs (texture coordinates) that are contained in the cache file. If the cache file does not contain UVWs then this has no effect.
      Note [Maya/Modo]: emReader reads 2D and 3D texture coordinates, but only the 'u' and 'v' are used by Modo/Maya.

    • Load Colors
      Loads the colors that are contained in the cache file. If the cache file does not contain colors then this has no effect.
      Note [C4D]: vertex colors are not supported by Cinema 4D. Therefore the RGBA values are stored in four vertex maps called "R", "G", "B" and "A" respectively. These maps can then be used by shaders for the rendering.

Data

Data

This group of parameters can be used to alter the data that is connected to the geometry (i.e normal vectors, motion vectors, texture coordinates).

Note: these operations are performed before the geometry operations (see Geometry).

  • The Parameters:

    • Scale Motion Vectors
      This can be used to adjust the motions vectors once they were loaded.

    • Blur Normals
      Blurs the normal vectors using a basic Laplacian Smooth. Blurring the normal vectors affects the behavior of certain geometry operators like push and thickness.

    • Blur Motions
      Blurs the motion vectors using a basic Laplacian Smooth.

    • Blur UVWs
      Blurs the texture coordinates using a basic Laplacian Smooth.

    • Blur Colors
      Blurs the colors using a basic Laplacian Smooth.

Geometry [Modo]

Geometry

Contains a collection of effects and operations that can be applied to the loaded geometry.

  • The Parameters:

    • Fix double Edges
      Fixes the double edges, if any.

    • Fix non-manifold Edges
      Fixes the non-manifold edges, if any.
      Note: a non-manifold edge is an edge that is used by more than two polygons.

    • Close Holes
      Closes the holes, if any.

    • Invert Polygons.
      Inverts the normal vectors.

    • Quadrangulate
      Quadrangulates the geometry.

    • Remove Interiors
      Removes the interiors of the geometry.
      ("interiors" are polygon islands with the normals all pointing inwards)

    • Push
      Pushes the vertices along the vertex normals.

    • Thickness
      Applies thickness to the geometry.

    • Triangulate
      Triangulates all or certain type of polygons.

    • Simple Smooth
      Smoothes the geometry using a basic Laplacian Smooth.

    • Convert to Left Handed System [C4D]
      Cinema 4D uses a left handed coordinate system whereas most other 3D applications use the right handed system. Enabling this parameter will convert the loaded geometry from a right handed system into a left handed system.

Data (Post)

Data (Post)

This group of parameters can be used to alter the data that is connected to the geometry (i.e normal vectors, motion vectors, texture coordinates).

Note: these operations are performed after the geometry operations (see Property Group "Geometry")

  • The Parameters:

    • Blur Normals
      Blurs the normal vectors using a basic Laplacian Smooth.

    • Disconnect all Polygons
      Enable this to disconnect all polygons, i.e. vertices are no longer shared between polygons.

Misc [Softimage]

  • The Parameters:

    • Set only Points
      Will only load and set the vertices, but not the polygons.

    • Create empty Mesh on Error
      Enable this if you wish to have an empty mesh instead of the error mesh whenever an error occurs.

Viewport [Modo]

These parameters control the display in the viewport.

  • The Parameters:

    • Display Mode
      The display mode when the item is selected or when you are hovering about it.

    • Opacity
      The opacity of the edges / points.

The ICE Data Generator [Softimage]

This compound contains a custom ICE node that takes care of the data such as the normal vectors, the texture coordintes, etc.

When creating a new emReader mesh via the menu "Create -> Poly.Mesh -> emReader" an ICE Tree with this compound is automatically generated.
In most cases one need not edit it, but certain scenarios might require to change some of the settings. For example one could chose to store the textures coordinates in a different ICE data. Furthermore one can add an additional ICE Tree above this one and modify the data.

Example:
Say you got a cache sequence with UVs from a colleague. The geometry is fine, but the UVs do not have the scaling you need. You could then create an additional ICE Tree and use the compounds "Get Data", "Multiply by Scalar" and "Set Data" to rescale the UVs to your needs.

Supported File Formats

Supported File Formats

The supported geometry cache file formats:

  1. "Proprietary, binary (.mzd)"
    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 vectors, user normals and UVWs.

  2. "Proprietary, binary (.emp2)"
    this binary proprietary file format supports vertex colors, motion vectors and user normals. These files are compatible with older emPolygonizer versions as well as the built-in Polygonizer of Softimage 2011.5 and above.

  3. "Wavefront (.obj)"
    the Wavefront obj file format is a well-known ASCII file format which is supported by most of the existing 3D packages. 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.

  4. "Proprietary, ascii (.emp2)"
    this proprietary file format is a basic ASCII format, similar to the Wavefront format. 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. These files are compatible with older emPolygonizer versions as well as the built-in Polygonizer of Softimage 2011.5 and above.

  5. "RealFlow (.bin)"
    the binary geometry format from RealFlow that can easily be imported/exported into Softimage, Maya or 3ds Max. It supports motion vectors and UVWs.

Tips and Tricks, Trouble Shooting

Tips and Tricks, Trouble Shooting

  • Tips and Tricks [Modo]:

    • Tip: How to freeze an emReader item.
      To freeze an emReader item (i.e. convert it into a "normal" mesh):
      1.) Select the emReader item.
      2.) In the main menu chose "Item -> Change Type -> Mesh".
       
  • Known Issues [Softimage]:

    • Capturing the viewport with deformation motion blur.
      Capturing the viewport with an open Render Region and deformation motion blur results in corrupt renderings. The only workaround consists of rendering a pass instead of capturing the viewport.
       

Version History

Version History

  • New in Version 1.0:

    • everything is new.
  • New in Version 1.1:

    • emReader now works with Modo 601 and 701.
    • new post data effect "Disconnect all Polygons".
    • bug fix regarding the "Browse" button.
    • geometry is now checked for any illegal polygons or unused vertices.
  • New in Version 1.2:

    • emReader is now available for Softimage 2012 / 2013 / 2014 / 2015.
    • new index modes "Round", "Floor" and "Ceil".
    • new parameter "Idx Fraction Strength":
      if the cache files contain motion vectors then one can use file cache indices that are non-integers.
    • [Softimage] new tab "Misc" and new parameters "Set only Points" and "Create empty Mesh on Error".
  • New in Version 1.22:

    • emReader is now available for Maya 2012 / 2013 / 2014 / 2015.
    • [C4D] the vertex colors are now available as four vertex maps called "R", "G", "B", "A".
    • [Fabric] emReader is now available for Fabric Engine, Windows 64 Bit and Linux 64 Bit.
    • [Maya] the normal vectors are now read and set.
    • [Softimage] bug fix regarding the motion vector ICE data.
    • [Softimage] new parameters "Load User Colors / Vectors / Floats".
    • [Softimage] fixes and revisions of the uder data's ICE Tree.
    • a few minor bug fixes.
  • New in Version 1.222:

    • [Modo] BUG FIX: emReader items could not be rendered. This has been fixed!
    • [Modo] Path aliases are now supported.
  • New in Version 1.235:

    • now uses RLM v.11.2.
    • [C4D] new tab "Wavefront".
    • [Maya] new tab "Wavefront".
    • [Maya] new parameter "Set only Vertices (and first polygon)".
    • [Modo] MODO 701 is no longer supported, only MODO 801 and above.
    • [Modo] the drop-down item names no longer have spaces.
    • [Modo] when changing the item type to "emReader" the item now has a correct name (before it was blank).
    • [Softimage] new tab "Wavefront".
  • New in Version 1.250:

    • new feature "Remove Interiors".
    • [Modo] new feature "Swap UVWs".
    • [Modo] MODO 801 is no longer supported, only MODO 901 and above.
    • [Modo] bug fix: issues with animated emReader items and V-Ray. This has been fixed.
    • [Softimage] new feature "Remove Polygons outside of Region".

Limitations and Remarks

Limitations and Remarks

  • [C4D] emReader is available for Cinema 4D 64 bit R17 and above running under Windows.
  • [Maya] emReader is available for Maya 64 bit running under Windows.
  • [Modo] emReader is available for Modo 64 bit running under Windows, Linux and OS X.