StretchMesh / Documentation

Features
Documentation
Video Gallery
Tutorial: Attractors
Tutorial: Colliders
Sales

Introduction
Licensing Overview
Locating Your Mac Address
Plug-In Installation
Adding StretchMesh to a Polygonal surface
Adding a Collision Object to a StretchMesh
Adding an Attractor to a StretchMesh
Painting Attractor Influence
Painting StretchMesh Stiffness
Object and Attribute Definitions
Licensing Messages
Command Reference
Bugs and feedback

Introduction

StretchMesh is a new paradigm for surface deformation. By using a fast algorithm for relational vertex knowledge, smooth, skin-like character deformations can be created quickly and easily, giving excellent results. StretchMesh is implemented as a standard Maya deformer to work seamlessly with existing workflows.

Back to Top

Licensing Overview

StretchMesh requires a license file in order to load the plug-in in Maya. To generate that file, Kickstand requires the MAC address for the computer on which StretchMesh is to be used.

NOTE: After your purchase you’ll receive an e-mail, linking you to the MAC address entry page. Log in with the information provided and enter your MAC address, then send it to Kickstand. We will generate a license file and sent it to your e-mail address. If for some reason you’re unable to use this method, you can send the MAC address ALONG WITH your Transaction ID to sales@kickstandlabs.com and we’ll send you a license file. (Please see “Locating your MAC address” below if you need help.)

You’ll need to create a folder in which to place your StretchMesh License file once it’s received. The default for Windows is C:\ksLm, and the default for Mac OSX and Linux is /etc/kslm. (The default path can be changed by creating and setting a path to an environment variable called “KSLM”.)

Back to Top

Locating your Mac Address

It’s easiest to use the FlexLM Licensing Utility that was installed with Maya (Windows – Autodesk/Common Utilities. Linux |OSX – run “lmtools” from the terminal window). In the “System Settings” tab you’ll find an “Ethernet Address” section. Copy the first 12-digit code in that space to the MAC address entry page, mentioned above.

If for some reason you cannot use the FlexLM Licensing Utility, try the following:

• Windows / Open the Command Prompt and enter “ipconfig /all”. Look for the “Physical Address” under “Ethernet adapter Local Area Connection.”
• Mac OSX / Launch “System Preferences” – “Network” and double-click on “Integrated Ethernet.” In the “Ethernet” tab you’ll find the MAC address. Another way to find the MAC address in OSX is to run the command “ifconfig” in a terminal window. Look for the MAC address associated with “en0″.
• Linux / There are many varieties of Linux – try “ifconfig -a” from a terminal window. If this doesn’t work, try visiting http://www.coffer.com/mac_info/locate-unix.html for other possibilities.

To reiterate, once you have received your license, create a folder in which to place it. The default for Windows is C:\ksLm, and the default for Mac OSX and Linux is /etc/kslm.

Back to Top

Plug-in Installation

After your purchase is complete, you’ll be able to download a ZIP’d version of the plug-in according to your Operating System. You must Extract the contents to a folder, then choose the plug-in to install based on your Operating System, your version of Maya and its bit version (32-bit plug-in for 32-bit Maya, 64-bit plug-in for 64-bit Maya).

Copy the relevant StretchMesh plug-in file (stretchMesh.mll for Windows, stretchMesh.bundle for Mac OSX or stretchMesh.so for Linux) in your Maya plug-ins folder. You can find the folder path by executing the MEL command getenv MAYA_PLUG_IN_PATH inside of Maya, or see below for some common paths:

Windows

• [drive]/Program Files/Autodesk/[maya version]/bin/plug-ins
• userDirectory/My Documents/maya/[maya version]/plug-ins
• userDirectory/My Documents/maya/plug-ins

Mac

• In your Home folder, under Library/Preferences/Autodesk/maya/[maya version]
• In your Home folder, under Library/Preferences/Autodesk/maya
• /Users/Shared/Autodesk/maya/[maya version]
• /Users/Shared/Autodesk/maya
• Inside the Maya package in /Applications/Maya [maya version]/Maya.app/Contents/bin/plug-ins

Linux

• $MAYA_APP_DIR/maya/[maya version]/plug-ins
• $MAYA_APP_DIR/maya/plug-ins /usr/autodesk/userconfig/maya/[maya version]/plug-ins
• /usr/autodesk/userconfig/maya/plug-ins $MAYA_LOCATION/bin/plug-ins

Once the correct plug-in is placed in your plug-ins folder, start Maya and use the Plug-in Manager to load and/or autoload the StretchMesh plug-in.

When the plug-in is loaded a new “Kickstand” menu item will appear in the menu bar. The options are explained below.

Back to Top

Adding StretchMesh to a Polygonal surface

1. Select the surface.
2. Choose Create New StretchMesh from the “Kickstand” menu or run the stretchMesh command.
   
   If you wish to see the effect, select vertices and pull them away from the surface. Adjust the iterations attribute on the StretchMesh node to vary the falloff. Our lab technicians report that a value of 20 gives ideal results.
   

StretchMesh Attributes

• Envelope / Specifies the deformation scale factor. The normal range is from 0.000 to 1.000. You can also enter values from -2.000 to 2.000. A value of 2.000 would double the overall deformation effect. A negative value would invert the effect. Default is 1.
• Collision Step / Defines the precision of the collision calculation when a collision object is present. The fewer the collision steps, the more accurate the collision response will be. A collision step value of 1 calculates collisions on every iteration, a value of 3 calculates collisions on every third iteration, and so on. Increasing collision step is an effective way to improve interactivity on heavy models. Default is 1.
• Iterations / Defines how far deformations propagate across the surface. The more iterations the mesh computes, the more softened the response will be; the lower the iteration value, the coarser the deformation response. Increasing this step will increase calculation time. Default is 10.
• Collisions / A boolean value that dictates whether collision objects in the scene are computed or not. Temporarily Disabling collisions is an effective way to increase interactivity while animating. Default is “n” (1).
• Enable Scale Safe / A boolean value that dictates whether the object can be scaled resulting in the usual results or with an inflating effect on the surface. Default is “off” (0).

Back to Top

Adding a Collision Object to a StretchMesh

Collision objects are useful for creating the effect of skin sliding over bone or muscle. A NURBS or poly surface can act as a collision object, but NURBS objects are more calculation-intensive and thus slower. There is also the option of adding a “Curve Collider” and a “Sphere Collider”. A curve collider is a Maya curve that acts as a flexible collider. A sphere collider is a primitive sphere that is defined by a point and a radius to act as a fast calculating stand-in for a more costly polygonal sphere. These are all accessible under the Colliders menu.

When the surface of the StretchMesh comes into contact with that of the collision object, the StretchMesh vertices are displaced away from the vertices of the collision object. Note that there is a threshold; if the collision object passes into the Stretchmesh, the StretchMesh vertices will be displaced in the opposite direction.

A StretchMesh can be influenced by more than one collision object, and two StretchMesh objects can share a collision object.

1. Position the NURBS or poly object that will act as the collision object near the surface of the StretchMesh.
2. Select the StretchMesh and shift-select the collision object. In the “Kickstand” menu choose Add Mesh Collider from the Colliders menu.
3. Repeat the process for each collision object you’d like to add to the StretchMesh.

Mesh Collision Object Attributes:

• MshColliderPad
  A MshColliderPad attribute is added to the StretchMesh node for each collision object. This attribute creates a way of “inflating” the influence of each collision object to create “padding” between the collision object and its StretchMesh. Default is 0.

Curve Collision Object Attributes:

• Radius[#]
  A Radius attribute is added to the curve collider node for each vertex on the input curve. This attribute creates a way of “inflating” the influence of each section of the curve object and its associated StretchMesh. Default value for each is 1.
• Color R,G,B,T
  The Color attribute is added to the curve as a way of visually distinguishing it in the Maya UI. This three channel (plus alpha) attribute just changes the color and transparency of the curve collider’s visualization. Default value for each is 0.2 0.2 0.8 1 resulting in an opaque, blue color.

Sphere Collision Object Attributes:

• The primitive sphere collider can be attached to any transform node with its scale value acting as its radius in that dimensions value. So a locator with a scale of 1 1 1 will result in a primitive sphere collider with a radius of 1. By scaling that locator the scale of the sphere collider radius will increase.

Back to Top

Adding an Attractor to a StretchMesh

StretchMesh attractors give the user control over specific vertices on the StretchMesh surface. The associated vertices are drawn toward the position of the attractor depending on the attractor’s attractorStrength setting. Attractors can be parented to any object in the rig or scene and animated as needed.

1. Select the vertices on the StretchMesh surface you would like to control.
2. Choose Add Attractor To Selected from the “Kickstand” menu. A locator is created with a default strength of zero, and therefore does not change the position of the selected vertices.
   
3. Move the locator and adjust its attractorStrength to see the effect on the surface.
   

Back to Top

Painting Attractor Influence

By painting attractor influence(s), the user is able to adjust the area of influence for a selected attractor in the same manner she would adjust the weighting for joints in a smooth bind.

1. Select the StretchMesh surface.
2. Choose Paint Attractor Influence from the “Kickstand” menu.
3. The Paint Skin Weights tool opens. The attractor names are listed in the Influence window.
4. The user can now Add, Remove or Smooth the influence of a selected attractor using Maya’s familiar paint tool and its various settings. The interface works the same as if you were painting joint weights for a smooth bind node.
   

Back to Top

Painting StretchMesh Stiffness

StretchMesh users also have control over how much or how little vertices on a StretchMesh are influenced by neighboring vertices on the same object. This allows for more control over the stiffness of various regions on a StretchMesh.

1. Select the StretchMesh surface.
2. Choose Paint Stiffness from the “Kickstand” -> “Paint” menu.
3. The Paint Attributes tool opens. (Note the names/attributes in the two boxes. If the user reinvokes the tool with the “Y” key, they will have to manually set these.)
   
4. The user can now Add, Remove or Smooth the stiffness of the StretchMesh vertices using Maya’s paint tool.

In the examples below, StretchMesh has been applied to a poly plane, and one quadrant of vertices has been assigned to each attractor.
Each attractor’s strength has been set to 0.5.

Example 1: Each attractor has been moved away an equal distance from the mesh. The default stiffness is 0.3.

Example 2: Stiffness in upper right quadrant painted with a value of 0.5. The vertices in this area are less influenced by neighboring vertices and therefore more closely follow their attractor in the upper right corner.

Example 3: Stiffness in lower left quadrant painted with a value of 0.0. The vertices in this region are more influenced by all surrounding vertices.

Example 4: Stiffness on the left half painted with a value of 0.9. These vertices are much less influenced by neighbors and so follow their respective attractors much more closely.

Back to Top

Object and Attribute Definitions

StretchMesh

A StretchMesh surface is a polygon which has a StretchMesh deformer applied to it.

Collider

A collider object is a polygonal or NURBS object which has been designated as a collision surface.

Collider Attributes:

• Msh Collider Pad
  The collider pad is a collision offset where this value is added to the position of each vertex affected by collision adding a buffer distance between the calculated distance and the resulting vertex position. A new MshCollider Pad attribute is created on the StretchMesh node for each collision object defined. As such, each collision object can have its own pad value.

Attractor

An attractor object is a link to a collection of vertices on the StretchMesh surface. Depending on the attractor strength, the associated vertices are drawn toward the position of the attractor. This is similar to a muscle flexing and pulling connected elements towards its origin. StretchMesh provides point and curve attractors to control a collection of points across the surface of a curve.

Attractor Attributes:

• Attractor Strength
  The attractorStrength attribute can be used to change the strength of the attractor’s effect on all connected verts.

Back to Top

Licensing Messages

Could not find license file, check location: somePath
The path that it outputs is the location where your ksLicense.xml file should be. Check your permissions if the path exists. Also, you can override the license file path location using the Environment Variable “KSLM.”

Kickstand license file cannot be found. Check documentation or FAQ online.
The ksLicense.xml file could not be found or opened. It should be in the folder C:\ksLm on windows or \etc\kslm on Mac and Linux. You should also verify the permissions – the user should have at minimum read-access to the file. Try opening the ksLicense.xml in a text editor. If you cannot, change the permissions or call your network administrator.

No license found for StretchMesh version X.X
The ksLicense.xml file was found; however, there was no entry containing a license for the product StrechMesh and version X.X.

Kickstand license expired: 20080801
The license for your product has expired either because it’s a demo or beta product. Please purchase a working license from Kickstand.

Kickstand license is not valid on this machine.
A node-locked license is non-transferable and locked to a single machine through its own unique hardware ID. The ID in the license does not match any hardware ID found on your machine. Please contact Kickstand for a new license.

Kickstand license is invalid.
The license has been altered and no longer can be verified. Please contact Kickstand for a new license.

Back to Top

Command Reference

stretchMesh [-collisionStep] [-iterations] [-stiffness] [-collisions] [-addCollider] [-addAttractor] [objects]

Flags

When using the -edit flag, the command determines the SM node from the [object] argument passed to the command, if present. If not, the SM node is determined from the selected object.

Return value

[string]

MEL Examples

// to add a StretchMesh to the selected polygonal surfaces
//
stretchMesh;


// to add a StretchMesh to polygonal surfaces pSphere1 and pSphere2
//
stretchMesh pSphere1 pSphere2;


// to add a StretchMesh to the selected polygon, set the iterations to 10, and the collision step to 4
//
stretchMesh -iterations 10 -collisionStep 4;

Back to Top

Bugs and feedback

To report bugs or give general feedback regarding StretchMesh, please click here to our fill out our submission form.

Back to Top