Creating a Velocity Node in Maya

22/03/2014

In Maya nodes are not meant to have any knowledge of the scene outside of their inputs and outputs. They are supposed to act like functionality deterministic black boxes. This is a good design for users as it means they can be effectively composed, and used in different combinations, without too much worry that if the nodes are put together in a certain bad combination, things might break.

I really like this design, but it does cause limitations, which Maya is fairly strict on enforcing.

In the connection graph there must be no loops. The reason for this is fairly clear. Any loops in the connection graph result in a node's computation requiring exactly the value it is trying to compute. Interaction with the scene is discouraged because it might also cause this indirectly. If a node tried to get a value which depended on it's own output, this would fire up another evaluation of the node's compute method, and so on to infinity.

Sometimes this makes creating nodes we might like to create impossible even if technically we know they wont cause any trouble.

One example of this might be a node that needs to access information about the scene that can't be found from a normal connection. For example access of values at a different time. A typical node that needs to do this might be one that computes the velocity of some object.

Another example of this is a node that uses the output of some system, to decide what to input into it next. For example we may want a node that tries to find some ideal setting for some complex system such as a character rig. To do this it repeatedly changes the input value of the system and observes the output. It uses the output to decide the next input to set. This is a feedback loop, which cannot be expressed in the node graph without causing a connection loop, and therefore an error. Nor can you make compute method manually read the outputs from the scene, because this will just call another iteration to fetch it, and cause an infinite loop in that way.

Here is a hack I've discovered in Maya that allows one to create these kinds of nodes. Although this hack is fairly clean and stable - it is still a hack, and not how Maya is supposed to be used, and so I can't promise it wont break other systems if you have a complex setup. Nor can I promise that it will work in all cases.

That said, I am quite proud of this little discovery! I hope you manage to make use of it as I hopefully will.


To show how it works let us try to create a velocity node. As input it should take some scalar value, and as output it should return the change in that value over time. Typically this would be impossible in Maya as it relies on having information about the scene from a separate point in time, but using this trick it is made possible.

We start by creating an empty node with a single float input and output, who's compute method just sets the output to clean without doing anything.

import maya.OpenMaya as OpenMaya
import maya.OpenMayaAnim as OpenMayaAnim
import maya.OpenMayaMPx as OpenMayaMPx

class VelocityNode(OpenMayaMPx.MPxNode):
    
    id   = OpenMaya.MTypeId(0x0000FB16)
    name = "velocityNode"
    classification = 'utility/general'
    
    input  = OpenMaya.MObject()
    output = OpenMaya.MObject()
    
    def __init__(self):
        OpenMayaMPx.MPxNode.__init__(self)
        
    def compute(self, plug, db):
        db.setClean(VelocityNode.output)
        
    @staticmethod
    def creator():
        return OpenMayaMPx.asMPxPtr(VelocityNode())
        
    @staticmethod
    def initializer():
        num_attr = OpenMaya.MFnNumericAttribute()
        
        VelocityNode.input  = num_attr.create('input',  'i', 
            OpenMaya.MFnNumericData.kFloat, 0.0)
        VelocityNode.output = num_attr.create('output', 'o', 
            OpenMaya.MFnNumericData.kFloat, 0.0)
        
        VelocityNode.addAttribute(VelocityNode.input)
        VelocityNode.addAttribute(VelocityNode.output)
        VelocityNode.attributeAffects(VelocityNode.input, VelocityNode.output)

As standard, we can register and deregister this node using the following functions.

def initializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject, "Daniel Holden", "1.0")
    mplugin.registerNode(
        VelocityNode.name, VelocityNode.id,
        VelocityNode.creator, VelocityNode.initializer, 
        OpenMayaMPx.MPxNode.kDependNode, VelocityNode.classification)


def uninitializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject)
    mplugin.deregisterNode(VelocityNode.id)

Now for the trick.

Instead of doing our logic in the compute method like a normal node, we do it instead in a callback function we'll call compute_callback, which we setup to be called when any of the input plugs become dirty. This happens just before the compute method is called by Maya, and by using this fact we can emulate almost exactly the compute method, but with one great benefit; we can prevent infinite recursion. Instead of reading from the data handles, we can read and write directly to the plugs of the node.

Using this approach we can write to the output plugs as many times as we want. We can even read the plugs from some node downstream, and get updated outputs to see what has happened in the scene.

If our node's compute method is called, it doesn't matter, as the method does nothing. What is important is that compute_callback wont be called recursively, because until we are finally done with our callback, the inputs wont be set to clean.

Even if we do find a weird situation where compute_callback is called again we can always set a variable indicating that compute_callback is going to be re-entered, and if we encounter that variable being active then return instantly, manually halting any recursion.

To setup the callback we need to add the following code to the node. This registers the callback just after the node is created and removes it just before the node is deleted. The callback allows for some user data to be passed in with it. For this we use the self variable of the current node.

    def postConstructor(self):
        self.callback = OpenMaya.MNodeMessage.addNodeDirtyPlugCallback(
            self.thisMObject(), VelocityNode.compute_callback, self)
        
    def __del__(self):
        OpenMaya.MMessage.removeCallback(self.callback)

We can now write our callback compute_callback. This gets and sets inputs and outputs manually by finding their plugs from the attributes. As we are building a velocity node, we want compute_callback to get the values of the inputs to this node at some different points in time, compute the velocity, and set this result to the output.

    @staticmethod
    def compute_callback(node, plug, self):
        
        if plug == VelocityNode.input:
            
            input  = OpenMaya.MPlug(self.thisMObject(), VelocityNode.input)
            output = OpenMaya.MPlug(self.thisMObject(), VelocityNode.output)

            time = OpenMayaAnim.MAnimControl.currentTime()
            
            value_prev = input.asFloat(OpenMaya.MDGContext(time-1))
            value_curr = input.asFloat(OpenMaya.MDGContext(time  ))
            value_next = input.asFloat(OpenMaya.MDGContext(time+1))
            value = ((value_next - value_curr) +
                     (value_curr - value_prev)) / 2
            
            output.setFloat(value)

After this callback finishes, compute will be called, which will set the output to clean, completing the DAG evaluation for our node.

That's it! Everything should now work as planned. A single warning. In the case of the velocity node, if the connection going into input requires a lot of computation, you now have a node which runs that computation three times, every time it needs a single value. So make sure your inputs are not complicated.

Other than that, hope you find some cool uses for this node!

As well as allowing us to build nodes like velocity nodes, this approach is ultimately a very powerful template for new nodes of all different kinds. Essentially it lets us create nodes that act like commands, and interact with the scene as they please.

I am already intending to try and use this approach on a couple of nodes that have before seemed impossible. If you manage to use this idea to create any interesting nodes of your own I would really love to hear.


Now for a more complex example of this pattern. Let us try to create a node which takes some initial input, and performs some iterative process on the scene, before setting some final result as output. This example is a bit more contrived, but it acts as a proof of concept for nodes which need to do real tasks in the same pattern.

The idea behind this node is similar to before, but a little more complicated. Like before we start with an empty node, but this time with the extra attribute feedback, which also affects the output attribute.

import maya.OpenMaya as OpenMaya
import maya.OpenMayaMPx as OpenMayaMPx

class FeedbackNode(OpenMayaMPx.MPxNode):
    
    id   = OpenMaya.MTypeId(0x0000FB17)
    name = "FeedbackNode"
    classification = 'utility/general'
    
    input    = OpenMaya.MObject()
    output   = OpenMaya.MObject()
    feedback = OpenMaya.MObject()
    
    def __init__(self):
        OpenMayaMPx.MPxNode.__init__(self)
        
    @staticmethod
    def creator():
        return OpenMayaMPx.asMPxPtr(FeedbackNode())
        
    @staticmethod
    def initializer():
        num_attr = OpenMaya.MFnNumericAttribute()
        
        FeedbackNode.input    = num_attr.create('input',    'i', 
            OpenMaya.MFnNumericData.kFloat, 0.0)
        FeedbackNode.output   = num_attr.create('output',   'o', 
            OpenMaya.MFnNumericData.kFloat, 0.0)
        FeedbackNode.feedback = num_attr.create('feedback', 'f', 
            OpenMaya.MFnNumericData.kFloat, 0.0)
        
        FeedbackNode.addAttribute(FeedbackNode.input)
        FeedbackNode.addAttribute(FeedbackNode.output)
        FeedbackNode.addAttribute(FeedbackNode.feedback)
        FeedbackNode.attributeAffects(FeedbackNode.input,    FeedbackNode.output)
        FeedbackNode.attributeAffects(FeedbackNode.feedback, FeedbackNode.output)

Then we define our compute method. This time, instead of just setting the output to clean, we instead read from either the input attribute or the feedback attribute, and directly pass either of these to the output. To decide which one to read from we're going to use an internal variable self.feedback, which we will set later.

    def __init__(self):
        OpenMayaMPx.MPxNode.__init__(self)
        self.feedback = False

    def compute(self, plug, db):
        
        feedback = db.inputValue(FeedbackNode.feedback).asFloat()
        input    = db.inputValue(FeedbackNode.input).asFloat()
        output   = db.outputValue(FeedbackNode.output)
        
        if self.feedback:
            output.setFloat(feedback)
            output.setClean()
        else:
            output.setFloat(input)
            output.setClean()
        
        self.feedback = False

Now for the callback. This callback has a few stages. First it gets the value at the output attribute. This triggers a call to the node's compute method which, as self.feedback is not set, copies the value from the input connection to the output attribute and returns it.

Next comes the part of the node which iteratively interacts with the scene. Five times we modify the node's output variable, changing the scene, and then reading back in it's new value. It might seem pointless to read in a value we've just set, but this action signifies the fact that this node could read back in anything downstream from the output attribute, and use that to set the next value.

Finally we set the self.feedback flag to True, and set the final value we wish to use into the feedback attribute. After this callback terminates there is one last call to compute, which this time copies over the value we just set into feedback to the output.

    @staticmethod
    def compute_callback(node, plug, self):
        
        if plug == FeedbackNode.input:
        
            input    = OpenMaya.MPlug(self.thisMObject(), FeedbackNode.input)
            output   = OpenMaya.MPlug(self.thisMObject(), FeedbackNode.output)
            feedback = OpenMaya.MPlug(self.thisMObject(), FeedbackNode.feedback)
        
            value = output.asFloat()
            
            for i in xrange(5):
            
                value = value + 0.1
                output.setFloat(value)
                value = output.asFloat()
            
            self.feedback = True
            feedback.setFloat(value)
        
    def postConstructor(self):
        self.callback = OpenMaya.MNodeMessage.addNodeDirtyPlugCallback(
            self.thisMObject(), FeedbackNode.compute_callback, self)
        
    def __del__(self):
        OpenMaya.MMessage.removeCallback(self.callback)

These iteration nodes nodes can be used to perform tasks in Maya which require some sort of mathematical optimisation. These sort of tasks typically mean trying to find the optimum input to some system, without having a clear understanding of how that system works (if we did know how it worked, it is likely we could find some analytical solution to what input to set). Therefore they try many different values and attempt to see if they can guess how the system interacts to find the best value.

In my research this is hopefully how we are going to make use of this technique, to applying standard animation techniques to generate animations for character rigs, at interactive rates.

Both of these nodes, and the code in this post, is licensed under BSD3. If you have any more questions don't hesitate to get in contact.