Script Distribution using Maya Modules





Hi everyone!

As a TD, part of your job is to be able to create and distribute tools to the artists on your team. Sometimes, those artists may not be as tech-savvy as your average TD, and so part of the challenge is coming up with an easy way to distribute scripts and keep those scripts updated as you make changes to them.

Enter the magical ancient world of Maya’s module workflow.

In short, Maya’s module system allows scripts to be held in folders outside of the \user\maya\scripts folder. The magic of that is that you can thus put those scripts in a folder that’s shared over a network or cloud drive, which would allow for everyone on the team to be on the same page.

Here’s what you need to do:

Say you have a python script in the directory D:\sharedFolder\

What you need to do is create a folder above that that will hold the entire module.


Then, you need to create a folder in there called “scripts” just like maya’s “scripts” folder and put in it all of the scripts you want to have shared. You could also do the same with plug-ins, icons, prefs… It’s essentially mirrors the \user\maya directory structure.

So! now you have D:\sharedFolder\myModule\scripts\

And you’re almost set! Now what you need to do is in your \user\maya\modules folder, you need to create a type of file called a .mod file. This file will be used by maya to link the folder on our desktop to your maya’s path.

Just to get you started, the most basic syntax for a mod file is:

+ [module name] [version number] [full path to module folder]

for example:

+ myModule 1.0 D:\sharedFolder\myModule

Now, if you restart Maya and try to import myScript, everything should work as expected.

This kind of workflow, however, isn’t very animator friendly. That’s why I created a much quicker install method for installing a module.

  1. Download the module or add the shared folder to you shared drive.
  2. Drag a script called “” into Maya and simply browse to confirm the module file’s location.
  3. Restart Maya and you’re done.

All I’m doing in that “drag_into_maya” python file is opening up a file dialog at the location of that python file, which should already be in the module package. I then write a .mod file into the “userAppDir” path ‘s module folder.

That’s it! Once you start looking into this, you’ll realize tools like the BCS and SHAPES are already being distributed via modules. I never really thought twice about modules before but this is honestly a game changer for my workflow. Thanks Rik, my coworker on a freelance project I’m on right now, for introducing me to this 🙂


More resources


Vector-Based Wheel Rigging

Hey everyone!

First of all, I’d like to start with announcing I’ll be a Character TD intern this summer at Insomniac Games! I’m so excited for this opportunity!

Anyways, I’ve been working on a lot lately, partly for the Puppeteer Lounge and partly for just regular university stuff, but in my free time I’ve been chipping away at a car solution in Maya.


Wheel Rotation

As a high school geometry refresher, in order to do a full 360 degree rotation, a wheel must travel a distance equal to Pi times its diameter, or C = Pi*D.  Traditional Maya wheel setups will use a simple set-driven-key approach to get things done. For example, for a wheel with diameter 2, you’d go Tau units (6.283) forward on the axis and have that drive a 360 degree rotation on the wheels. That can work for a basic setup, but you’ll still get a lot of wheel sliding since it’s only a one-dimensional driver.

A better way, I found, is to use a vector-based approach. I started with this youtube video as a starting point, but I found some problems with it, including confusing equations and variable names and also the fact that his technique for dot product doesn’t account for the wheel’s individual ry control. Either way, I knew I had to figure this out on my own to figure this out.

Vector Magnitude

The magnitude of a vector is equal to the square root of the sum its squared contents. In simpler words, it’s like the quadratic formula but for n dimensions. So magnitude is a scalar (number) that comes from a vector (“array”) and can be used as distance.

Therefore, at each frame, I knew I’d need to know the previous location and the current location as a vector. This was done using empty group nodes that I parented to a top level, “static” node (could be an XTR group in a rig). This transform node’s job is simply to store the previous frame’s location.

vector $wheel_old_vector = `xform -q -t -ws “wheel_cc_old_vector”`;

I then get the wheel’s current location:

vector $wheel_vector = `xform -q -t -ws “wheel_cc_pos_vector”`;

The current vector – previous vector gives us the movement vector from the previous to the current location, (I remember this as A-B gives B to A). The magnitude of this is the distance traveled.

vector $translate_vector = ($wheel_vector – $wheel_old_vector);

float $distance = mag($translate_vector);

At this point, we know the distance traveled and can calculate from that the rotation that we need to do ( 360 * distance / (Tau*radius) ). However, this doesn’t account for forward and backwards movement and for the lessened rotation that occurs when the direction of motion is oblique to the angle of the wheels.

Wheel Direction

I therefore added two other empty transform nodes to calculate the direction of the wheel. The first was just parented below the “move” control for the wheel and projected onto the zx plane, and the other is set as follows:

matchTransform wheel_cc_forward_vector wheel_cc_pos_vector;
xform -os -r -t 1 0 0 wheel_cc_forward_vector; 

So I’m matching the rotation and translation of the forward vector to the wheel vector and then going forward in object space from there. (I’m determining +as the forward direction here). From that, we get the vector:

vector $wheel_dir_vector = ($forward_vector – $wheel_vector);

This vector “points” in the direction of the wheel.

Vector dot products

Okay, I have to be honest. I had a pretty traditional Linear Algebra professor and I never really understood how dot products were related to cosine. I understood the dot product could give orthogonality and also if two vectors are pointing in similar directions, but cosine? What?

Well, you just have to normalize them, and it all makes sense.

v1 = [1,0,0]     v2 = [0,1,0]        << two normalized (magnitude 1) vectors

v1 dot v2 = 1*0 + 0*1 + 0*0 = 0 (these vectors are orthogonal)

Oh yeah, and acos(0) is pi/2 or 90 degrees!

Another example that made me get this:

v1 = [1,0,0]     v2 = [1, 1, 0]        << v2 is not normalized. Let’s normalize it!

v2 = (1 / √2 ) * v2 = [√2 / 2 , √2 / 2, 0]

v1 dot v2 = 1*√2 / 2 + 0*√2 / 2 n + 0*0 = √2 / 2

acos(√2 / 2) is pi/4 or 45 degrees!

Okay, so how are we going to use this for our wheels? Well, all we need to do is get the dot product of the normalized wheel and wheel direction vectors and we’ll know the cosine of the angle between them. If it’s negative, we know we need to rotate backwards. If it’s 0, we shouldn’t rotate at all because the car is skidding sideways. And then everything in between.

float $dot = dotProduct($translate_vector, $wheel_dir_vector,1);

We then use that in the final equation to determine if we need to rotate forwards or backwards.

wheel_cc_rz_expr_grp.rotateZ = wheel_cc_rz_expr_grp.rotateZ + (360 * (($distance * $dot) / (-6.283 * $radius)));

And that’s it! Or the bulk of it, at least. Here’s the rest of the mel code if you want to use this expression in your own setups.


// Wheel expression
float $radius = 1.000000;
vector $wheel_old_vector = `xform -q -t -ws “wheel_cc_old_vector”`;
vector $wheel_vector = `xform -q -t -ws “wheel_cc_pos_vector”`;
matchTransform wheel_cc_forward_vector wheel_cc_pos_vector;
xform -os -r -t 1 0 0 wheel_cc_forward_vector;
vector $forward_vector = `xform -q -t -ws “wheel_cc_forward_vector”`;
vector $wheel_dir_vector = ($forward_vector – $wheel_vector);
vector $translate_vector = ($wheel_vector – $wheel_old_vector);
float $distance = mag($translate_vector);
float $dot = dotProduct($translate_vector,$wheel_dir_vector,1);
wheel_cc_rz_expr_grp.rotateZ = wheel_cc_rz_expr_grp.rotateZ + (360 * (($distance * $dot) / (-6.283 * $radius)));
xform -t ($wheel_vector.x) ($wheel_vector.y) ($wheel_vector.z) wheel_cc_old_vector;
if (frame == 1){
wheel_cc_rz_expr_grp.rotateZ = 0;

~ Ben


Documenting Python Code with Sphinx

Well, it’s been a while.

While silent here, I’ve definitely been busy elsewhere. Follow me on github to see the work I’ve been doing with the Maya API and Py.Qt. Also find me on vimeo for demos of some of the stuff I’ve been working on.

Anyways though, I’ve been meaning to address my WordPress for some time now, so what better way than to document my newly-learned skill of automatically creating documentation from docstrings using Sphinx!

Check out the Docs I created for some of my GitHub projects as an example.


Installing Sphinx is a pretty straightforward task. First of all, make sure Python is in the Path for your command prompt. If you type Python and hit enter and it gives you an error, you know it’s not. If it’s not, make sure to add the file path to the file that contains python.exe into your system’s Path environment variable.

In your favorite command prompt, navigate to the folder you have python installed on (probably something like C:\Users\Benjamin\Python\Scripts). If you open that folder in explorer, you should see an application there called easy_install. In your command prompt, while in the ~\Python\Scripts directory, run: easy_install sphinx

Python will do its thing and lots of new files will be created in the Sphinx directory (can you tell I don’t come from a computer science background yet?). You’re good to go!

Setting up a Sphinx Doc

Setting up a document in Sphinx is pretty easy too. Navigate to a folder in your command prompt and create a new folder (md folderName if you’re using the command prompt). Run the command sphinx-quickstart and it will give you lots of instructions to follow. Most of them are pretty self explanatory, but if you don’t know what some of them do just leave it at its default. You can go back and change them later.

C:\Users\Benjamin\Desktop>md sphinxTutorial

C:\Users\Benjamin\Desktop>cd sphinxTutorial

Welcome to the Sphinx 1.6.6 quickstart utility.

Some notable settings that we can set here that will save us some time later are saying y to the query:

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

This will enable us to generate our documentation into html automatically using special “docstrings”.

Setting Up a Python File for Sphinx Documentation

Besides your regular #comments, docstrings are a special type of string that Sphinx can interpret and convert into professional-looking html. According to, a docstring is “a string literal that occurs as the first statement in a module, function, class, or method definition.”

Here’s an example:

def pointInCone(meshDag, p0):
    “””Determines if/the factor by which a point is inside a polygon cone; i.e. a “Search Cone”

    :param meshDag: The dag path of a polyCone object
    :param p0: A world space vector representing the point to check
    :type meshDag: MDagPath
    :type p0: MVector
    :return: The factor by which the point is in the cone or False if it is not
    :rtype: float, False

# rest of function

It might look like a lot’s going on there, and there is some syntax to be aware of, so let’s break it down.

  • The triple quoted string must go directly after you declare a function. In PyCharm, if you make one it will automatically make the :param: and :return: bits for you.
  • The description for the function goes directly after the triple quote.
  • A blank line separates the description and the parameter descriptions.
  • :param param1: Description of parameter   (How to declare an argument)
  • :type param1: object type   (How to declare that argument’s type)
  • :return: What it returns 
  • :rtype: return type

Pretty self-explanatory, right? You could obviously go way more in depth with these so read up on the Sphinx docstring syntax if you want to learn more.

Besides your docstrings, you also need to make sure your Python file won’t do anything or throw any errors when it runs. Part of this (or at least my workaround) involves surrounding all your imports with Try/except ImportError statements, because many of the maya-specific modules I’m importing aren’t recognized by Sphinx when it goes to parse the file.

Here’s what the end result of the above code gives us in the end:

point in cone result

Setting Things up for Documentation

Okay! Now to actually make our documents. In your Sphinx project folder, find the python file called   and open it up. The first thing we need to do is make sure our python package is in Sphinx’s path, so add the line sys.path.insert(0, os.path.abspath(r”fullPathToPythonPackage”))

  • notice the raw string formatting we used with the r”” in front of the string

Next, if you forgot to do this in the setup, make sure you have “sphinx.ext.autodoc” in the extensions array in the file.

Automating the Documentation

Okay! So now we’re ready to do some documentation!  Create a new rst file called something like code.rst  … In it, give it a heading. This is the name that it will be given in our contents tree later.


Code Docs

Notice the underline under the words. Think of it like an html heading. Different symbols like === or surrounding it on both the top and bottom with symbols will give it different weights in the end.

Finally, we’re going to do what Sphinx was meant to do: autodocs!

*A simple search cone algorithm using vector angles*

.. automodule:: bm_pointInCone


  • In rst format, surrounding text with * with make it italics, and ** will make it bold.
  • After a blank line, we’re saying here that we want Sphinx to run the automodule script on the bm_pointInCone module. Remember when we gave it the full path to its package? That’s why.
  • Using the :members: tag will make documentation for any method in the module that contains docstrings.
  • rst file formats use 3 spaces for tabs instead of 4


Classes are pretty much the same; here’s a basic example:

.. autoclass:: bm_spaceSwitcher_ui.SpaceSwitcherUI

   .. automethod:: __init__


  1. Running autoclass on a class on a module we imported
  2. Making docs for every method that has docstrings on it
  3. Forcing Sphinx to make a doc for the __init__ method using the .. automethod:: function.

Finally, if you want to include a block of code in your rst file (which will eventually become a webpage), you can use:

.. code-block:: python

   import maya.cmds as cmds
   import maya.OpenMayaUI as omui

Notice the blank line after declaring the code block.


Adding Docs to our Webpage

Now that we’ve made our rst file, go to your file. You’ll find code that says

.. toctree::
   :maxdepth: 2
   :caption: Contents:

  • toctree stands for Table of Contents Tree
  • With a max depth higher than one, your contents will expand if it has anything underneath it.

Skip a line and add the name of the rst file we made with all our automodule:: stuff in it.

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Creating the html webpage

It’s as simple as opening up your command prompt again while in the sphinx project directory (C:\Users\Benjamin\Desktop\sphinxTutorial) and running make html 

This will put your web files in the _build folder Sphinx has. Under _build/html you’ll find your index.html file. That’s the “homepage” file. Double click it and see what it looks like 🙂

Don’t like the look? Want it to be mobile-ready? Download and install the readTheDocs theme.


Publishing on GitHub

Okay, so now you want people to actually  be able to see your docs. GitHub has a nice Pages feature that allows you to create webpages for either your entire profile or for a single repo.

If you’re doing it for a single repo:

  1. Create a /docs folder
  2. Put the contents of the  _build/html folder in there.
  3. ***index.html must be in the root of the /docs folder for GitHub to build the site. ***
  4. Create a blank .nojekyll file in the /docs folder so that GitHub won’t ignore the folders that Sphinx made that start with an _
  5. Publish and wait! It sometimes takes around half an hour or so to see the result published. Go for a walk. You’ve been sitting for too long!


If you’re doing it for your page:

  1. Put the contents of the _build/html folder in the root of your project repo. For user pages, GitHub requires the index.html file to be in the root of the repo.
  2. Create a blank .nojekyll file in the root of the repo so that GitHub won’t ignore the folders that Sphinx made that start with an _
  3. Publish and wait! It sometimes takes around half an hour or so to see the result published. Go for a walk. You’ve been sitting for too long!


That’s it! Again, check out my (work in progress) GitHub Page if you want to see what you can do with Sphinx.

Take care!




Making a Picker GUI for Maya with PySide and QtDesigner

The Hopps GUI in Maya 2016.5

The past few weeks have gone into the development of a new picker tool for a character rig I’m finishing up. The UI was designed in the amazing QtDesigner and all the Maya integration was done using PySide (PySide 1 that is).

QT Designer stuff:

The whole design is a QMainWindow widget, and the tabs come from the behavior of two QTabWidget objects.

  1. Do a png playblast of your character in the A or T pose you want them in. You want a nice obvious silhouette to make it easier to place the controls.
  2. Take that png into your ui file in QtDesigner and add it as the pixmap to a QLabel widget. This QLabel should be the backmost object in your design.
  3. In your python code (we’ll get to that later) you’ll have to re-connect the pixmap with the correct file path, but we will do this in QtDesigner so that we have a reference for placing our controls.
  4. Make sure you have “scaledContents” enabled.

Now it was just a matter of adding buttons.

  1. Add a button widget
  2. Give it an original objectName
  3. You can color it if you wish with the styleSheet property.
    1. background-color: rgb(80, 255, 73);\ncolor: rgb(0, 0, 0);
      1. ^^ that’s an example of the style sheet my green buttons shared. The background-color flag controls the color of the button and the color flag controls the color of the text.

The other widgets were pretty straightforward if you’ve ever done any PySide or PyQt coding. Besides QPushButton I used QLineEdit for the Namespace input and QComboBox for the dropdown menu.


Integrating with Maya:

This was one of the hardest parts of the project to figure out. A whole lot of props goes to internet heroes like Brian Kortbus who are kind enough to post information and code relating to QtDesigner and PySide integration. Here’s the problem:

QtDesigner gives you a .ui file which Maya doesn’t know how to deal with. Maya DOES however have integration with PySide, which can take ui files and convert them into objects that Python can deal with. Basically, if you’ve ever hand-coded a UI in PySide, the following code allows you to take your nice ui you made in QtDesigner and make it into something that can be easily integrated with Maya (2016.5 or below):

So for example, if we had a QPushButton object in QtDesigner named addCube_btn, line 56 would then connect its “clicked” slot to the function “someFunction”. It’s really that easy for every other button, it just takes a lot of manual connection. The nice thing is that the names for my controls won’t change much between characters so the UI will be pretty re-usable.

I said earlier we had to do something with the pixmap on our QLabel widget. This is what I did:

self.MainWindowUI.bgdImage_label.setPixmap(QtGui.QPixmap(SCRIPT_LOC + "\\hoppsGuiBody.png"))

If I didn’t do this then the background image wouldn’t show up since the folder that QtDesigner makes the image point to by default isn’t at all what you want. I know there’s a whole resource system and all in QtDesigner but considering this project needed only one pixmap I didn’t really find it necessary to get that deep into learning how to do that. Maybe later.

Connecting Widgets:

Now, there are a few things to note with selecting controls. First of all, you can’t just pass it a control like “L_shoulderFK_CTRL” because you don’t know if the rig was referenced or not. That’s where the Namespace comes in. Instead of just directly selecting my control, I made the buttons call a function that concatenates the defined namespace onto the control. In other words: + ctrl, add=1) where self.namespace is defined as self.MainWindowUI.namespaceTxt.text() in another function.

So that takes care of the selection issue. With that same code, we’re able to do things like select the entire body, reset the selection, key selection…

I think I posted this before but the code I use for a smart reset of an object’s attributes is:

sel =
for obj in sel:
    keyable = cmds.listAttr(obj, keyable=1, unlocked=1, settable=1)
    for attr in keyable:
        default = cmds.attributeQuery(attr, node=obj, listDefault=1)
        if cmds.getAttr(obj + "." + attr, settable=1) != 0:
            cmds.setAttr(obj + "." + attr, default[0])

That’s it for this post. I’ll make another post where I talk about how I tackled the fun problems of pose flipping/mirroring and IK-FK and FK-IK snapping.

A thing to note is that this is all written in PySide1, and Maya 2017 and up uses the newer version PySide2. Unfortunately, just changing the input line doesn’t fix the integration (yes I tried it) but I have seen some posts about the problem that try to fix it. So yes, this rig is for Maya 2016.5.

~ Ben Morgan



Geometry Controls using Nodes

Hi everyone!

This discovery comes directly from a Jason Schleifer video  and I really just wanted to pass it on. It’s a very simple method for creating controls that stick to geometry.

Screenshot (37)
The node layout for this setup

How it works:

  • We get our out mesh from the skin cluster and plug that into a mesh that’s the duplicate of that skinned mesh
  • However, doing that will give us double transforms. That’s where the Transform Geometry node will come in
  • We plug in the World Inverse Matrix to a Transform Geometry node, and get the skinned mesh’s out mesh from our skinned geo’s Shape
  • We then plug in the result of that Transform Geometry node into our new control’s shape.

Overall, it’s a pretty simple process that, so far, seems easy to implement. I made a quick script that does this for you. All you do is select the geometry on the skinned mesh you want to become the control and then give it a child.


RigAssembly Script/UI Test

Hi all!

It’s been a while, but I’ve been very hard at work.

This UI and script is the culmination of a few months of work. It’s a UI for an autoRig script I’ve written.


  • Add any number of arms, legs, etc and connect them to a spine
  • Stretchy ribbon limbs
  • Elbow pinning
  • Smooth twist forearms
  • Noodle arms
  • Hybrid IK/FK ribbon spine
  • Reverse foot setup
  • IK/FK blend
  • FK arm/leg stretching
  • Ability to turn off stretching on limbs


  • Automatic rig coloring
  • Ability to change rig control colors after creation
  • Auto-scaling of rig controls based on character’s height
  • Ability to minimize the amount of ribbons created (for game engine rigs)

Things I’m planning to add:

  • A functionality that will set up your rig’s hierarchy in such a way that unreal will accept it (i.e. all the joints are one hierarchy, the controls are in a totally separate group from the joints, etc. )This should be added very soon.
  • Facial rigging setup. I already have the script written for this, so I just have to implement it into the rig.
  • Ribbon tail module

Simple PySide Maya Scene Cleanup Tool


cleanup ool


Hi all!

Today I’m going to be showing a new tool I wrote using the GUI API PySide for Maya. It’s a little confusing at first, but after a while I enjoyed the level of flexibility and design I was able to get out of it compared to Maya’s simple UI tools. The goal of this project was to learn how different widgets work in PySide and to get comfortable with the process of integrating it within Maya. I learned a lot! I think I’ll be writing all my future GUIs in PySide/QT.

The tool has options for deleting history, non-deformer history, and unused nodes. It also has a re-label tool that has a dropdown menu for different labels to choose from. I chose this method because it allows me to easily predict what the pre/suffixes are that I need to replace out of the string before I append the new suffix on.

The renamer tool is pretty basic but it works. You can even press enter to run its command.

The next project I’d want to do is to figure out how to do some sort of Picker Window-type tool in PySide that’s similar to the AnimSchool picker. After some research, it seems like it’s going to be pretty complex, so I’ll need to start small.