importvtk : VTK Import Plugin for Maya®

importvtk 1.1.0 : VTK Import Plugin for Maya®

Overview
News
Download
Installation
Usage
Examples
Tips
Future Work
Acknowledgements

1. Overview

importvtk is a Maya plugin written in C++ that provides MEL and Python commands to import VTK files (binary or ASCII) containing a vtkDataSet or a live (in memory) VTK Python object. Other generic 3D converters either supported ASCII files only (inefficient for large datasets) or lacked certain contexts such as scalars, vectors, tensors and lookup tables.

importvtk currently imports vtkDataSets in the following ways:

vtkStructuredGrid -> Particles
vtkImageData -> Fluid
vtkPolyData polygons -> Mesh
vtkPolyData lines -> Nurbs Curves

I wasn't able to find such a tool on the web and I'm sure there are those that would need such a capability without having to learn the Maya C++ API.

Maya API experts may ask why the MPxFileTranslator class wasn't derived. This would've made it more convenient for GUI users, but for now this scriptable command is flexible enough with its input arguments, and besides, importing scientific models spanning hundreds of files just wouldn't be practical with a GUI.

Any ideas for a feature? Submit it here. Uncovered a bug? Submit a ticket here.

remikziemlinski att yahoo dot com

2. News

2008-05-26 Added support for live python objects and MS VCEE 9 2008.
2008-04-28 Added options for normals, version, and debug messages.
2008-04-24 Added UV texture and vertex normals import for polydata.
2008-04-23 Updated Makefile and code for Linux and Maya 2008.
2006-08-11 Project hosted by SourceForge.

3. Download

Project files: importvtk-1.1.0.tar.gz
Example VTK files: 1.0-examples.tar.gz
Latest development files: CVS instructions

4. Installation

4.1 Requirements

Compiler (GCC 4.1.2 for GNU/Linux, MS Visual C++ for MS Windows)
Maya 7+ (MEL command), Maya 8.5 (Python command)
VTK 5+

4.2 Building with Microsoft Visual C++ Express Edition 9 2008 (VCEE2008)

See this page for an excellent recipe on how to configure VCEE2008 to build and then use VTK. Basically, you'll need the VTK source code to access the header files, and then to compile the libraries. Just so you know, the VTK Windows installer from Kitware only gives you (TCL) binaries, which aren't very useful in building this project.

The project (solution) files for building importvtk are available in the download.

After building importvtk.mll, copy it to a path listed in your MAYA_PLUG_IN_PATH environment variable.

4.3 Building with Microsoft Visual C++ Express Edition 2005 (VCEE2005)

See this page for an excellent recipe on how to configure VCEE2005 to build and then use VTK. Basically, you'll need the VTK source code to access the header files, and then to compile the libraries. Just so you know, the VTK Windows installer from Kitware only gives you (TCL) binaries, which aren't very useful in building this project.

Next, download and setup the "Windows Platform SDK for Windows Server 2003 R2", then edit its include directory in the VCEE2005 IDE, which can be done from the menu with Tools | Options | Projects and Solutions | VC++ Directories | Include files list. Type in a path resembling C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include.

You can now build it (shortcut F7).

Copy the importvtk.mll file to a path listed in your MAYA_PLUG_IN_PATH environment variable.

4.4 Building with GCC on GNU/Linux

Edit Makefile to reference the correct header and library file paths.

Run `make` and copy the importvtk.so file to a path listed in your MAYA_PLUG_IN_PATH environment variable.

5. Usage

Within Maya's command line or script editor, load the plugin with this MEL command:

    loadPlugin "importvtk";

    # Or with explicit path (Windows example).
    loadPlugin "c:/rsz/projects/maya/plugins/importvtk.mll";

or with the GUI, browse to that location through the Maya menu Windows | Settings/Preferences | Plugin Manager ....

You can unload the plugin with

    unloadPlugin "importvtk";

For Python, copy "importvtk.py" to a directory listed in your PYTHONPATH. You don't want "importvtk.py" in the same directory as your "importvtk.mll" or "importvtk.so" file, because Python may complain upon import that "Error: dynamic module does not define init function (initimportvtk)" since it tries to load the DLL/SO before the python script.

6. Examples

Several test files are built by and ship with the project. Your own tests should reproduce the images below.

6.1 vtkStructuredGrid to Particles

This will import a 3D vtkStructuredGrid's points as a particle system and assign the scalars to the per particle opacity.

    # MEL version.
    importvtk -f "c:/rsz/projects/maya/plugins/importvtk/test/tmp-sgrid.vtk" -s "opacityPP";
    addAttr -is true -ln "radius" -at "float" -min 0 -max 20 -dv .1 "particleShape1";
    setAttr "particleShape1.radius" .75;

    # Python version.
    from importvtk import importvtk
    importvtk(f="/net2/rsz/i686/importvtk/dev/importvtk-1.1.0/test/tmp-sgrid.vtk", s="opacityPP")
    import maya
    maya.cmds.addAttr("particleShape1", internalSet=True, ln="radius", at="float", min=0, max=20, dv=.1)
    maya.cmds.setAttr("particleShape1.radius", .75)

The images below compare what is seen in VTK and in Maya.


vtkStructuredGrid points in VTK Opacities: Red = .1, Green =.5, Blue = .9	Converted to Maya Particle System

6.2 vtkImageData to Fluid

This imports a 3D vtkImageData as a fluid and assigns the scalars to the fluid's density. Note: Maya Unlimited is required for Fluid support.

    # MEL version.
    importvtk -f "c:/rsz/projects/maya/plugins/importvtk/test/tmp-img.vtk" -s "density";

    # Python version.
    from importvtk import importvtk
    importvtk(f="/net2/rsz/i686/importvtk/dev/importvtk-1.1.0/test/tmp-img.vtk", s="density")


vtkImageData points in VTK Opacities: Red = .1, Green =.5, Blue = .9	Converted to Maya Fluid

6.3 vtkPolyData Polygons to Mesh

This imports a polygon mesh surface with colormapped point-based scalars.

    # MEL version.
    importvtk -f "c:/rsz/projects/maya/plugins/importvtk/test/tmp-polyspt.vtk";    
    
    # Python version.
    from importvtk import importvtk
    importvtk(f="/net2/rsz/i686/importvtk/dev/importvtk-1.1.0/test/tmp-polyspt.vtk")

You'll then need to add a material, such as Blinn and enable color-per-vertex shaded display from the menu Display | Polygons | Custom Polygon Display | Color in Shaded Display.


vtkPolyData polygon surface in VTK Opacity and colors mapped to Z coordinates	Converted to Maya Mesh

Rendering the vertex colors seems to require a plugin "cvColorShader" that ships as an API example (untested), or a Mental Ray node as explained in the Maya docs (search "Render color per vertex"). In Hypershade, select from the menu Create | mental ray Textures | mentalray Vertex Colors. Then from the PolySurfaceShape connect the output color set's name "Color Set[x].Color Name" to the mental ray node's "Cpv Sets" input. Then connect the mentalray Vertex Colors node "Out Color" to the material (Blinn) "Color" input. You may need to use a "Reverse" node to properly pass the Vertex Colors node "Out Alpha" down to the material's "Transparency".

6.4 vtkPolyData Lines to Nurbs Curves

This imports lines in vtkPolyData into degree 1 nurbs curves

    # MEL version.
    importvtk -f "c:/rsz/projects/maya/plugins/importvtk/test/tmp-polyslines.vtk";

    # Python version.
    from importvtk import importvtk
    importvtk(f="/net2/rsz/i686/importvtk/dev/importvtk-1.1.0/test/tmp-polyslines.vtk")

Each line is created as its own nurbs curve.


vtkPolyData lines in VTK (with colormapped scalars)	Converted to Nurbs Curves

6.5 vtkPolyData Textured Polygons to Mesh

This demonstrates import of a polygon mesh surface with UV textured vertices.

    # MEL version.
    importvtk -f "c:/rsz/projects/maya/plugins/importvtk/test/tmp-polytextured.vtk";

    # Python version.
    from importvtk import importvtk
    importvtk(f="/net2/rsz/i686/importvtk/dev/importvtk-1.1.0/test/tmp-polytextured.vtk")

To see the effect, you'll need to add a material, such as Blinn, and apply a texture to the color channel via a 2D Textures "File" render node. The default uvSet name "map1" is used.


vtkPolyData polygon normals in VTK with PNG texture "uvgrid.png"	Converted to Maya Mesh

6.6 vtkPolyData with Shared Vertex Normals to Mesh

This demonstrates import of a polygon mesh with (shared) vertex normals.

    # MEL version.
    importvtk -normals -f "c:/rsz/projects/maya/plugins/importvtk/test/tmp-polynormals.vtk";

    # Python version.
    from importvtk import importvtk
    importvtk(f="/net2/rsz/i686/importvtk/dev/importvtk-1.1.0/test/tmp-polynormals.vtk")

To see the effect, you'll need to select the new Maya object's polySurfaceShape in the Attribute Editor, expand the Mesh Component Display section and Display Normal and use the "vtx" Normal Type.


vtkPolyData normals in VTK	Converted to Maya Mesh

6.7 Live vtkPolyData Python Object to Mesh

This demonstrates import of a polygon mesh with in situ python code. Enter this code into the Maya Python script editor:

    import vtk
    c = vtk.vtkConeSource()
    c.Update()
    p = c.GetOutput()

    from importvtk import importvtk
    # Three ways to import the polydata.
    importvtk('p')
    importvtk(r=p.__this__)
    importvtk(reference=p.__this__)

7. Tips

Automatically load the plugin by putting this command in your userSetup.mel file ($USER/maya/scripts/userSetup.mel on GNU/Linux):
```
loadPlugin "importvtk";
```

8. Future Work

Import face or per-face vertex normals for meshes.
Support multiple input scalar arrays and output to multiple maya attributes, for example an array for radius, and another for opacity.
```
    importvtk -f "file.vtk" -s "array1" "radiusPP" -s "array2" "opacityPP"
```
Make plugin a menu item with a file dialog for file import.

9. Acknowledgements

Red Hill Studios for loaning a copy of Maya and initiating the effort to animate scientific datasets.
Geophysical Fluid Dynamics Laboratory (GFDL) for resources to develop on the Linux platform and for their scientific datasets.
Everyone involved with the Visualization Toolkit (VTK) for making visualization so accessible and fun.
Microsoft for making their Visual C++ compiler and IDE free.
SourceForge for hosting this project for free and providing an excellent set of software engineering tools.
The GNU world at large.