API Guide > Example Plug-ins >

# 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

Produces dependency graph node spAnimCube.

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

Produces an objectSet node spBasicObjectSet.

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.

basicShape

Produces a surface shape node spBasicShape.

This plug-in implements a proxy surface shape node that will display rectangles, triangles and circles using standard OpenGL calls. To create one of these nodes, enter the following commands after the plug-in is loaded:

    import maya.cmds as cmds
    cmds.createNode("spBasicShape")

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.

To use this plug-in, select a dependency node, and then issue the command:

    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

Produces dependency graph node spCircle.

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

Produces dependency graph node spCustomImagePlane.

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.

For example:

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

customNodeFileTranslator

Produces file translator spCustomNodeTranslator.

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 All 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

Produces dependency graph node spFootPrint.

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

Produces a dependency graph node spGeomShader.

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

Produces Python command spHelix.

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

Produces Python command spHelloWorld.

This is a simple demonstration on how to use a Python plug-in.

    maya.cmds.spHelloWorld()

A "Hello World" text is output to the script editor window.

mathTableControl

Produces Python command spMathTableControl.

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.

To create a table with rows and columns, execute the following commands:

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

A new window named Math Table appears with three columns and five rows.

motionTraceCmd

Produces Python command spMotionTrace

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

Produces Python command spMoveManipCtxCmd to create the example context.

To use this plug-in, execute the command:

    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.

Note: You must have a Shelf1 tab before executing the commands.

moveTool

Produces Python commands spMoveToolCmd and spMoveToolContext

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.

Note that at this time, the plug-in can translate:

- transforms
- NURBS curve CVs
- NURBS surface CVs
- polygonal vertices

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

To use this plug-in, execute the command:

    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.

Note: You must have a Shelf1 tab before executing the commands.

narrowPolyViewer

This example demonstrates how to use the MPx3dModelView and MPxModelEditorCommand classes to implement a viewer. The viewer will highlight narrow polygons and as a result must be given geometry that is triangulated. To use this example, do the following:

- Load the plug-in
- Create mesh geometry and triangulate it
- Select the mesh geometry
- Execute the script showNarrowPolyViewer.py
- Manipulate a vertex to create a narrow polygon. Narrow polygons as defined by the tolerance set in the plug-in will be shaded.

parentAddedMsgCmd

Produced a Python command spParentAddedMsg.

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.

After loading the plug-in, you can run the following commands:

    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

Produces a custom transform node spRockingTransformNode.

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.

The plug-in contains two pieces:

1. The custom transform node -- rockingTransformNode

2. The custom transformation matrix -- rockingTransformMatrix

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

For example, execute the commands:

    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

Produces dependency graph node 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

Produces a simple image file plug-in.

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.

You can use this example to demonstrate the use of this plug-in:

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

simpleSolverNode

Registers IK solver 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")

Moving the handle in the x-y plane will rotate the joint.

The command:

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

can be used to determine which solver a handle is using.

simpleSpring

Produces dependency graph node 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

Produces dependency graph node spSineNode

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

Produces the dependency graph node spSlopeShader.

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.

You can use this example to demonstrate the usage of this plug-in:

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

The angle attribute can be adjusted to see different results.

splitUVCmd

Produces Python command spSplitUV.

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

Produces a dependecy graph node spTorusField.

The spTorusField node implements an attraction-and-repel field.

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

Produces Python command spWhatIs.

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.

For each object, the following information will be printed:

- name of the object
- API type for the object
- API function sets that could be used on the object. Note that not every function set listed actually exists.

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()

The command results in the following output in the script editor:

Name: nurbsSphere1

Type: kTransform

Function Sets: kBase, kNamedObject, kDependencyNode, kDagNode , kTransform

yTwistNode

Produces dependency graph node spyTwistNode.

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.

To use this node, create a sphere (or some other object):

    maya.cmds.sphere()

Select the sphere, then enter the command:

    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

Produces Python command spZoomCamera.

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.

To use this plug-in, do the following:

1. Create any object for the scene.
2. Select the Rendering menu item > Create > Cameras > Camera.
3. Direct the camera to face an object in the scene.
4. Select Panels > Perspective > camera1.

When you are in a view that looks through the camera, execute the command:

    maya.cmds.spZoomCamera()

and your view through the camera will zoom-in by a factor of 2.