Create a custom heads-up display readout


Use the headsUpDisplay MEL command to create or edit a custom readout in the heads-up display.

The following explains the basics of using the command. Read the headsUpDisplay command documentation in the online help for a full explanation of the command’s usage and flags.

Related topics



Create a MEL procedure that returns the information you want to show in the heads-up display.

Update event

Decide when Maya needs to update the display item. For example, if your display item shows some information about the selected object, Maya only needs to change it when the selection changes. This is the event that triggers a display update.

Maya has a number of events you can listen for. Use headsUpDisplay -listEvents to see the list of all events.

If you update on a selection-based event (“SelectionChanged” or “SomethingSelected”), you can refine the event listening to only fire on a specific type of change to the selected nodes using the -nodeChanges flag.

-nodeChanges "attributeChange" fires when any attribute on a selected node changes.

-nodeChanges "connectionChange" fires when any input or output on a selected node changes.

-nodeChanges "instanceChange" fires when any selected instanced node changes.

Section and block position

Select a column for the item to appear in. This is called the section. The following chart shows the number the command uses to refer to each column. 0 is the upper-left corner, 9 is the bottom-right corner of the screen.











Select a line within the section on which the display item appear. This is called the block.


Select the label that appears before the information on the display line, for example “Position:”.

The command

To create a heads-up display item:

 -section <section number>
 -block <block number>
 -label "<label>"
 -command "<procedure()>"
 -event "<event>"
 <object name>;

Then, to show the item:

headsUpDisplay -edit -visability 1 <object name>;

Or to hide the item:

headsUpDisplay -edit -visability 0 <object name>;

See the example below.

The command has many more options than are described here, especially for changing the appearance of the display item and checking the usage of blocks. Read the headsUpDisplay command documentation for more information.

Make the change permanent

Add the commands that create the heads-up display item (and any associated user interface) to userSetup.mel to have them permanently added to your copy of Maya.


For example, if you want to show the XYZ coordinates of the selected object in the heads-up display, create a MEL procedure (for example, objectPosition() ) that returns the XYZ coordinates of the selected object.

objectPosition procedure

global proc float[] objectPosition ()
 string $selectedNodes[] = `selectedNodes`;
 float $position[3];
 if (size($selectedNodes) > 0)
 string $mainObject = $selectedNodes[ (size($selectedNodes) - 1) ];
 $position[0] = `getAttr $mainObject.translateX`;
 $position[1] = `getAttr $mainObject.translateY`;
 $position[2] = `getAttr $mainObject.translateZ`;
 $position[0] = 0;
 $position[1] = 0;
 $position[2] = 0;
 return $position;

headsUpDisplay command

Then use the headsUpDisplay command to create the heads-up display object, and add a user interface to turn the display item on or off.

// Create custom HUD objects
// To create a script like this for testing, see the command documentation
// for the headsUpDisplay command.
 -section 4
 -block 5
 -label "Position:"
 -command "objectPosition()"
 -event "SelectionChanged"
 -nodeChanges "attributeChange"
// Add menu items to control the custom items
global string $gHeadsUpDisplayMenu;
// Add a divider to separate Maya items from custom items
menuItem -parent $gHeadsUpDisplayMenu -divider true;
// Add one menu item per heads up display object created above
menuItem -parent $gHeadsUpDisplayMenu
 -checkBox true
 -label "Object Position"
 -command "headsUpDisplay -e -vis 1 HUDObjectPosition"
 -annotation "Object Postion: Toggle the display of object position"\

Creative Commons License Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License