Example Scripted Plug-ins

There are scripted plug-ins in the Maya development kit that can demonstrate the use of the proxy classes of the Maya Python API.

animCubeNode

This plug-in demonstrates how to take time as an input, and create polygonal geometry for output. The compute method of the node constructs a polygonal cube whose size depends on the current frame number. The resulting mesh is passed to an internal Maya node which displays it and allows it to be positioned.

To use this node, execute the python script animCubeNode.py that contains the following commands:

import maya.cmds as cmds 
cmds.createNode("transform", name="animCube1") 
cmds.createNode("mesh", name="animCubeShape1", parent="animCube1") 
cmds.sets("animCubeShape1", add="initialShadingGroup") 
cmds.createNode("spAnimCube", name="animCubeNode1") 
cmds.connectAttr("time1.outTime", "animCubeNode1.time") 
cmds.connectAttr("animCubeNode1.outputMesh", "animCubeShape1.inMesh")

This creates a mesh node under a transform node which is hooked into the world for display. It then creates an spAnimCube node, and connects its input to the time node, and its output to the mesh node.

A cube will now appear on the screen. If the play button on the time slider is pressed, the displayed cube will grow and shrink as the frame number changes.

basicObjectSet

This plug-in implements a proxy objectSet node and a command for adding selected elements to a newly created spBasicObjectSet. To create one of these nodes, enter the following commands after the plug-in is loaded:

import maya.cmds as cmds 
cmds.createNode( ‘spBasicObjectSet’ )

An example script basicObjectSetTest.py is supplied in the developer kit. This example adds and remove objects from a spBasicObjectSet node.

blindDoubleDataCmd

Produces Python command spBlindDoubleDataCmd and user defined data type spBlindDoubleData.

This plug-in demonstrates how to create blind data (dynamic attributes) based on user defined data types. The plug-in uses a simple double value as the user data type. The use of the MPlug class to set and retrieve the value of the attribute is demonstrated, as are read and write routines that implement the storage and retrieval of the data in both Maya ASCII and Maya Binary file formats.

maya.cmds.spBlindDoubleData()

A dynamic attribute containing the double value, 3.2, will be attached to each selected dependency node. If the scene is saved in Maya ASCII format, you will be able to see the Python commands that save the value of the dynamic attribute. If the scene is reloaded, the dynamic attribute will be reattached to the applicable nodes.

circleNode

This plug-in is an example of a user-defined dependency graph node. It takes a number as input (such as time) and generates two output numbers. One number describes a sine curve as the input varies and the other number generates a cosine curve. If these two are hooked up to the x and z translation attributes of an object, the object will describe movement through a circle in the xz plane as time is changed.

The node has two additional attributes which can be changed to affect the animation, “scale” which defines the size of the circular path, and “frames” which defines the number of frames required for a complete circuit of the path. Either of these can be hooked up to other nodes, or can be simply set via the command maya.cmds.setAttr operating on the circle node circleNode1 created by the Python script. For example:

import maya.cmds as cmds 
cmds.createNode("spCircle", name="circleNode1") 
cmds.setAttr("circleNode1.scale", 3) 
# will change the size of the circle 
cmds.setAttr("circleNode1.frames", 5) 
# will cause objects to complete a circle in indicated number of frames.

Execute the circleNodeTest.py script to create a new “Circle” menu with a single item, “Move in circle”. Selecting this will build a simple model (a sphere which follows a circular path) which can be played back by clicking on the “play” icon on the time slider.

customImagePlane

Demonstrates how to create your own custom image plane based on Maya's internal image plane classes. This allows API users to override the default Maya image plane behavior. This class is similar to typical API nodes in that it can have a compute method and can contain static attributes added by the API user. This example class overrides the default image plane behavior and allows users to add transparency to an image plane using the transparency attribute on the node. Note, this code also illustrates how to use MImage to control the floating point depth buffer. When useDepthMap is set to true, depth is added to the image such that half of the image is at the near clip plane and the remaining half is at the far clip plane.

After the spCustomImagePlane node has been created, you must attach it to the camera shape that is displaying the node. Image planes are attached to cameras via the imagePlane message attribute on the camera shape. To attach this example image plane, you should connect the image plane's message attribute to the cameraShapes imagePlane attribute. The imagePlane attribute is a multi-attribute and can hold references to multiple image planes.

imageP = maya.cmds.createNode("spCustomImagePlane") 
maya.cmds.connectAttr(imageP + ".message", "perspShape.imagePlane[0]", force = True)

customNodeFileTranslator

This example implements a simple input and output file translator. The writer functionality of the translator searches the Maya scene for proxy nodes and writes out name information to the file. The reader functionality of the translator simply reads the file in and displays each line.

To use this file translator, first load the plug-in, then create some proxy nodes such as spSineNode. Then use File > Export to save the proxy node information by selecting the “Files of Type” option “spCustomNodeTranslator”.

You can select File > Import to read the information back in. When the file is read back in, output will be sent to the History panel of the Script Editor.

footPrintManip

Produces dependency graph node spFootPrintLocator and spFootPrintLocatorManip.

This example demonstrates how to use the Show Manip Tool with a user-defined manipulator. The user-defined manipulator corresponds to the foot print locator.

To use this plug-in, execute the footPrintManip.py script to create a foot print locator, select the foot print, and then click the Show Manip Tool.

footPrintNode

This example demonstrates how to create a user-defined locator. A locator is a DAG object that is drawn in the 3D views but that does not render. This example plug-in defines a new locator node that draws a foot print. The foot print can be selected and moved using the regular manipulators.

To use this plug-in, execute the footPrintNode.py script to create a foot print locator.

geomShade

This node is an example of a evaluating the geometric xyz position on an object.

The inputs for this node are scale and offsets depicted as sliders in the Attribute Editor for the node.

The output attribute of the spGeomShader node is called “outColor”. It is a 3 float value that represents the xyz position on the object. To use this shader, create a spGeomShader node and connect its output “outColor” to an input of a surface/shader node such as Color.

helixCmd

This script creates a NURBS curve in the shape of a Helix. The command accepts two arguments, “r” to set the radius of the helix, and “p” to set the pitch of the helix. To create a helix, execute the command:

maya.cmds.spHelix(p=0.3, r=7)

helloWorldCmd

maya.cmds.spHelloWorld()

mathTableControl

This plug-in creates a simple spreadsheet table in a separate output window. You can perform calculations within this table, such as addition and multiplication.

import maya.cmds as cmds 
window = cmds.window(title="Math Table",widthHeight=(400,150)) 
cmds.paneLayout() 
cmds.showWindow() 
cmds.spMathTableControl()

motionTraceCmd

In order to use this plug-in you must first create an object and animate it by setting keyframes. An easy way to do this is to just create a primitive, then set several keyframes on it.

Once this is done, select the animated object and invoke the spMotionTrace command. For example:

import maya.cmds as cmds 
cmds.spMotionTrace(s=1, e=100, b=2)

The object will move along its animated path under control of the plug-in and when the animation is complete, the plug-in will draw a curve into the scene that represents the motion path of the object.

The plug-in accepts s=, e=, and b= parameters to control the startFrame, endFrame and byFrame values respectively that it uses in running the animation.

moveManip

import maya 
maya.cmds.spMoveManipCtxCmd( 'spMoveManipContext1' ) 
maya.cmds.setParent( 'Shelf1' ) 
maya.cmds.toolButton( 'spMoveManip1', cl='toolCluster', t='spMoveManipContext1', 
i1="moveManip.xpm" )

This creates a new entry in the "Shelf1" tab of the tool shelf, called "moveManip". Create a sphere and click on the moveManip icon on the shelf. A free point triad manipulator will appear when the object is selected.

moveTool

This is an example of a selection-action tool. When nothing is selected, this tool behaves in exactly the same way as Maya’s selection tool. Once an object is selected, the tool turns into a translation tool.

This plug-in will only perform translation in orthographic views. Undo, redo, and journaling are supported by this tool.

maya.cmds.spMoveToolContext("spMoveToolContext1") 
shelfTopLevel = maya.mel.eval("global string $gShelfTopLevel;$temp = 
$gShelfTopLevel") 
maya.cmds.setParent("%s|General" % shelfTopLevel) 
maya.cmds.toolButton("spMoveTool1", cl="toolCluster", t="spMoveToolContext1", 
i1="moveTool.xpm")  
# Remove UI objects with 
maya.cmds.deleteUI("spMoveToolContext1") 
maya.cmds.deleteUI("spMoveTool1")

This creates a new entry in the “Shelf1” tab of the tool shelf, called “moveTool”. Click the new icon, then select an object and drag it around in an orthographic view. The left mouse button allows movement in two directions, while the middle mouse button constrains the movement to a single direction.

parentAddedMsgCmd

This plug-in demonstrates how to create and handle messages in Python. A global “parent added” message along with user defined client data is created. Invoking an operation in Maya such as creating a polygon plane will invoke the callback.

import maya.cmds as cmds 
cmds.spParentAddedMsg() 
cmds.polyPlane()

polyModifier

polyModifierCmd is designed to aid in modifying polygonal meshes. All polygons in Maya possess two features: construction history and tweaks. Both of these have a large impact on the structure of the object as well as how it can be further manipulated. However, they cannot be easily implemented, which is the why we need this abstracted class. polyModifierCmd will automatically handle the DG maintenance of construction history and tweaks on a polygonal mesh.

Please see the polyModifier.py script for detailed explanations, usage instructions and limitations of this plug-in.

rockingTransform

This plug-in implements an example custom transform that can be used to perform a rocking motion around the x-axis.

Geometry of any rotation can be made a child of this transform to demonstrate the effect.

These classes are used together in order to implement the rocking motion. Note: the rock attribute is stored outside of the regular transform attributes.

maya.cmds.file(f=True,new=True) 
maya.cmds.polyPlane() 
maya.cmds.select("pPlane1",r=True) 
maya.cmds.rotate(-15,-15,-15,r=True,ws=True) 
maya.cmds.createNode("spRockingTransform") 
maya.cmds.parent("pPlane1","spRockingTransform1") 
maya.cmds.setAttr("spRockingTransform1.rockx",55)

simpleEmitter

This node is an example of a particle emitter that emits in a direction from a single position.

There is an example Python script simpleEmitter.py that shows how to create the node and appropriate connections to correctly establish a user defined particle emitter.

simpleImageFile

This plug-in registers a new image file format against file extension ".moo". Loading any ".moo" image file will produce a procedurally generated colour spectrum including values outside of 0 to 1.

Create a poly plane.
Assign a shader to the plane.
Take any image file and name it test.moo.
Add the test.moo as a file texture to the plane.
Turn on hardware rendering.
Render the scene.

simpleSolverNode

This plug-in demonstrates how to create and register an IK-solver. Loading this plug-in will register a new IK solver with Maya as type simpleSolverNode.

To use the solver, create a single IK bone with two joints by selecting Skeleton > Joint Tool in the Animation menu set. Then enter the following command in the command window to create an IK handle which uses the new solver:

import maya.cmds as cmds 
cmds.createNode("spSimpleSolverNode", name="spSimpleSolverNode1")

cmds.ikHandle(sol="spSimpleSolverNode1", sj="joint1", ee="joint2")

simpleSpring

This node is an example of a spring node that calculates the spring behavior that Maya uses in a simulation.

There is an example Python script simpleSpring.py that shows how to create the node and appropriate connections to correctly establish a user defined spring law.

sineNode

This plug-in is an example of a user-defined dependency graph node. It takes a single input value and outputs the sine of this multiplied by 10. It is a simple example of creating a procedural animation. The number describes a sine curve as the input varies. If this number is hooked up to the x translation attributes of an object, the object will describe the move along the x-axis as time changes.

slopeShader

This plug-in implements a Maya software shader in Python. An angle attribute is used to define the space on the object that is being shaded, which is both walkable and not walkable. The walkable and non-walkable colors are set as attributes on the node. The shader will render both the walkable and non-walkable areas based on the color that has been set.

Load the slopeShader.py plug-in into Maya.
Create a polygon sphere.
Assign a shader to the sphere.
Open the Attribute Editor > Color Channel > Utilities > spSlopeShader to apply the texture on the sphere.
Software render the scene to view the results.

splitUVCmd

The splitUV command unshares or “splits” the selected UVs of a polygonal mesh. It is also a good example of how to write poly operation nodes that properly deal with history, tweaks, etc. For a thorough explanation of creating this command, refer to the splitUVCmd example in the Polygon API chapter of the Online documentation.

Note: The example in the online documentation uses a MEL script for demonstration. Please use the splitUVCmd.py script in the Maya devkit for a Python version of the example.

swissArmyManip

Produces dependency graph nodes spSwissArmyLocator and spSwissArmyLocatorManip

This is a contrived example plug-in that attaches one of every kind of user-defined manipulator to a node. It demonstrates the source code required to create each user-defined manipulator. To use it, issue the command:

maya.cmds.createNode("spSwissArmyLocator")

then click the Show Manipulator Tool icon on the side toolbar. The locator on the screen will be overlaid with one of every kind of user-defined manipulator.

torusField

The field repels all objects between itself and repelDistance attribute and attracts objects greater than attractDistance attribute from itself. This will eventually result in the objects clustering in a torus shape around the field.

Please see the torusFieldTest.py script for an example on using this node. The example creates a new field node and a particle object and connects them together.

whatIsCmd

This simple command prints a message describing the API types of Maya objects. If no Maya objects are passed to the command then it lists the types of all of the currently selected objects.

This list is essentially the class derivation list containing all parent classes of this object.

For example, create a NURBS sphere, make sure the sphere is selected and enter the command:

maya.cmds.spWhatIs()

yTwistNode

This plug-in demonstrates how to create a user-defined deformer. A deformer is a node which takes any number of input geometries, deforms them, and places the output into the output geometry attribute. This example plug-in defines a new deformer node that twists the deformed vertices of the input around the y-axis.

maya.cmds.sphere()

maya.cmds.deformer( type='spyTwistNode' )

Bring up the channel box and select the spyTwistNode1 input. You can change the Angle value to deform the geometry.

zoomCameraCmd

This is a simple plug-in which divides the horizontal field of view for the current active camera by 2.0. It is a good example of getting the current active view, and of modifying the camera.