Utils

Application

saveCurrentScene()

Save current scene

Checks if the file has already been saved. Returns “save”, “discard” or “cancel”.

If not saved opens “save”, “discard” or “cancel” window. Returns the button pressed if “discard” or “cancel”

If “save” is clicked it will try to save the current file, if cancelled will return “cancel”

Returns

The button clicked returned as a lower case string “save”, “discard” or “cancel”

Return type

str

restartMaya(force=False, delay=3)

Restarts maya with the same environment.

Add delay in case maya takes a while to close and save.

Returns

Env

getMayaLocation(mayaVersion)

Gets the generic maya location where maya is installed

Parameters

mayaVersion (int) – The version of maya to find

Returns

The folder path to the maya install folder

Return type

str

mayaScriptPaths()

Returns a list of maya script paths, received from the MAYA_SCRIPT_PATH environment

Return type

list(str)

mayaModulePaths()

Returns a list of maya module paths, received from the MAYA_MODULE_PATH environment

Return type

list(str)

mayaPluginPaths()

Returns a list of maya plugin paths, received from the MAYA_PLUG_IN_PATH environment

Return type

list(str)

pythonPath()

Return a list of paths, received from the PYTHONPATH evironment

Returns

a list of paths

Return type

list(str)

mayaIconPath()

Returns the xbmlangpath environment as a list of path

Return type

list(str)

getEnvironment()

Gets maya main environment variable and returns as a dict

Returns

dict

printEnvironment()

logs the maya environment to the logger

mayapy(mayaVersion)

Returns the location of the mayapy exe path from the mayaversion

Parameters

mayaVersion (int) – the maya version the workwith

Returns

the mayapy exe file path

Return type

str

isMayapy()

Returns True if the current executable is mayapy

Returns

bool

isMayaBatch()
isInteractive()
mayaVersion()

Returns maya’s currently active maya version ie. 2016

Returns

maya version as an int with no updates (decimals) ie. 2016

Return type

int

apiVersion()

Returns maya’s currently active maya api version ie. 201610 as an int

Returns

Maya api version as an int ie. 201610

Return type

int

mayaVersionNiceName()

Returns maya’s currently active version and api (update) as a str for users ie. “2016.1”

Uses two strings to create the version number including the update (API version) as a float:

“2016” and “20160100” = 2016.1

Accounts up to update 29 eg “2016.29”

Returns

Maya api version in nice name form ie. 2016.1 that can be converted to float

Return type

str

globalWidthHeight()

Returns the Scene global render width and height

Returns

The width and height values returns from the “defaultResolution” node

Return type

tuple(int, int)

Fbx

Utilities for handling FBX related operations

availableFbxVersions(ignoreBeforeVersion=None)

Returns the current available fbx versions in the form of [(“FBX202000”, “FBX 2020”)].

Parameters

ignoreBeforeVersion (str) – If provided then any version before the specified will be ignore ie. if in 2020 provide ignoreBeforeVersion=”2018” will ignore 2017 below.

Returns

zip object contain a tuple of (version,version label)

Return type

zip[tuple[str, str]]

currentFbxExportVersion()

Files

exportContext(rootNode)
exportMultiContext(nodes)
newScene(force=True)

Creates a new maya scene.

Parameters

force (bool) – Whether to force the creation of a new scene.

Returns

The name of the new scene usually “untitled”.

Return type

str

saveScene(path, removeUnknownPlugins=False)
openFile(path, selectivePreload=False, force=True, modified=False)

Opens the maya file.

Parameters
  • path (str) – The absolute path to the maya file

  • selectivePreload (bool) – If True the preload reference dialog will be shown if there’s references

  • force (bool) – Force’s a new scene

  • modified (bool) – If True then the scene state will be set to True, this is the same as cmds.file(modified=True)

importScene(filePath, force=True)
referenceFile(filePath, namespace=None)
exportSceneAsFbx(filePath, skeletonDefinition=False, constraints=False)
exportAbc(filePath, objectRootList=None, frameRange='1 1', visibility=True, creases=True, uvSets=True, autoSubd=True, dataFormat='ogawa', userAttr=None, userAttrPrefix=None, stripNamespaces=False, selection=False)
Exports and alembic file from multiple objects/transform nodes, could be multiple selected hierarchies for

example objectRootList is the list of objects who’s hierarchy is to be exported.

Note

Since the cmds.AbcExport does not support spaces in filepaths, this function saves in temp and then moves the file to the correct location.

Parameters
  • filePath (str) – the full file path to save to.

  • objectRootList (list) – a list of objects that are the root object, under each transform gets exported, None is scene.

  • frameRange (str) – frame range (to and from) separated by a space.

  • visibility (bool) – export visibility state?

  • creases (bool) – export creases? autoSubd needs to be on.

  • uvSets (bool) – export with uv sets?.

  • creases – export creases? autoSubd needs to be on.

  • autoSubd (str) – Must be on for crease edges, crease vertices or holes, mesh is written out as an OSubD.

  • userAttr (tuple) – will export including Maya attributes with these custom strings in a list.

  • userAttrPrefix (tuple) – will export including Maya attributes with these prefix’s, custom strings in a list.

  • stripNamespaces (bool) – will strip the namespaces on export, if duplicated names it will fail.

  • selection (bool) – will export selected nodes only, given they are under the root list.

getCamGeoRootsFromScene(exportGeo=True, exportCams=True, returnWorldRoots=True)

Returns the root objects of ge and cams (so that objects can’t be doubled) top most node/s in a scene. This is for .abc exporting where the root nodes need to be given and not doubled

Parameters
  • exportGeo (bool) – find roots of all geo in the scene?

  • exportCams (bool) – find roots of all cameras in the scene?

  • returnWorldRoots (bool) – instead of returning the object roots, return the full scene roots, bottom of hierarchy

Return objectRootList

all root object names (objects can’t be doubled) of the scene with cams or geo

Rtype objectRootList

list

exportAbcSceneFilters(filePath, frameRange='1 1', visibility=True, creases=True, uvSets=True, dataFormat='ogawa', noMayaDefaultCams=True, exportGeo=True, exportCams=True, exportAll=True, userAttr=None, userAttrPrefix=None)

Export alembic whole scene settings

Parameters
  • filePath (str) – the full file path to save to

  • frameRange (str) – frame range (to and from) separated by a space

  • visibility (bool) – export visibility state?

  • creases (bool) – export creases? autoSubd needs to be on

  • uvSets (bool) – export with uv sets?

  • dataFormat (str) – Alembic can save is a variety of formats, most commonly “ogawa”

  • noMayaDefaultCams (bool) – If True don’t export Maya’s default cams such as persp, top, side, front etc

  • exportGeo (bool) – Export geometry?

  • exportCams (bool) – Export cameras?

  • exportAll (bool) – exports everything in the scene

  • userAttr (tuple) – will export including Maya attributes with these custom strings in a list

  • userAttrPrefix (tuple) – will export including Maya attributes with these prefix’s, custom strings in a list

Return filePath

the full file path to save the alembic

Rtype filePath

str

Return objectRootList

list of the root object to export, alembic requires root objects/transforms to export

Rtype objectRootList

list(str)

exportAbcSelected(filePath, frameRange='1 1', visibility=True, creases=True, uvSets=True, dataFormat='ogawa', userAttr=None, userAttrPrefix=None)

Exports selected objects as alembic filetype .ABC and will auto load the plugin/s if not loaded Alembics export from the root, so filter the root of each selection hierarchy

Parameters
  • filePath (str) – the full file path to save to

  • frameRange (str) – frame range (to and from) separated by a space

  • visibility (bool) – export visibility state?

  • creases (bool) – export creases?

  • uvSets – export with uv sets?

  • dataFormat (str) – abc format type, usually “ogawa”

Returns

the full file path to saved.

Return type

str

exportObj(filePath, sceneNode)
loadAbcPlugin(message=True)

Loads the AbcImport and AbcExport plugins, also autoloads the alembic plugins

Parameters

message (bool) – Report the message to the user?

importAlembic(filePath, message=False)

Loads an alembic file (.ABC) and will auto load the plugin/s if not loaded

Parameters
  • filePath (str) – The full filepath to the file

  • message (bool) – Report the message to the user?

Returns

the filepath loaded

Return type

str

importObj(filePath)
importFbx(filepath, cameras=False, lights=False, skeletonDefinition=True, constraints=True)
exportFbx(filePath, exportNodes, skeletonDefinition=False, constraints=False, **kwargs)
Parameters
  • filePath (str) – The absolute file path

  • exportNodes (list or str) –

  • skeletonDefinition (bool) –

  • constraints (bool) –

  • kwargs (dict) –

Returns

Return type

class ModFile(path)

Bases: object

pluginPath = ''
version = ''
pluginName = ''
scriptsPath = ''
property resolvedScriptsPath
mayaFileType(message=True)

Returns the current Maya file type

Returns

General

General maya functions

Example use:

from zoo.libs.maya.utils import general
lockSelectedNodes(unlock=False, message=True)
mayaUpVector()

Gets the current world up vector

Return type

om1.MVector

upAxis()

Returns the current world up axis in str form.

Returns

returns x,y or z

Return type

str

isYAxisUp()

Returns True if y is world up

Returns

bool

isZAxisUp()

Returns True if Z is world up

Returns

bool

isXAxisUp()

Returns True if x is world up

Returns

bool

loadPlugin(pluginPath)

Loads the given maya plugin path can be .mll or .py

Parameters

pluginPath (str) – the absolute fullpath file path to the plugin

Return type

bool

unloadPlugin(pluginPath)

unLoads the given maya plugin name can be .mll or .py

Parameters

pluginPath (str) – Maya plugin name

Return type

bool

isPluginLoaded(pluginPath)

Returns True if the given plugin name is loaded

getMayaPlugins()
loadAllMayaPlugins()
unLoadMayaPlugins()
removeUnknownPlugins(message=True)

Removes unknown plugins from the scene.

Parameters

message (bool) – report the message to the user

Returns

A set of the removed plugins

Return type

set[str]

deleteUnknownNodes(message=True)

Deletes nodes of unknown type, usually plugins that are missing or not installed.

Also see removeUnknownPlugins()

Parameters

message (bool) – Report a message to the user?

Returns

Unknown nodes that were deleted and not deleted.

Return type

tuple[[str], [str]]

deleteTurtlePluginScene(removeShelf=True, message=True)

Removes Turtle from the scene, unloads the plugin and deletes the shelf too.

Parameters
  • removeShelf (bool) – If True delete the Turtle shelf

  • message (bool) – report a message to the user?

Returns

If True Turtle was removed

Return type

bool

deleteShelf(name)

Deletes maya shelf

Parameters

name (str) – Name of shelf

Returns

Returns true if deleted, False otherwise

lockSelectedNodes(unlock=False, message=True)

Locks or unlocks the selected nodes, Maya locked nodes are nodes that can’t be deleted.

Parameters
  • unlock (bool) – unlock the nodes instead of locking?

  • message (bool) – Report a message to the user?

Returns

nodes that were unlocked

Return type

list(str)

namespaceContext(namespace)

Context manager which temporarily sets the current namespace, if the namespace doesn’t exist it will be created.

Parameters

namespace (str) – The maya Namespace to use, ie. “MyNamespace” or “:MyNamespace”

tempNamespaceContext(namespace)

Creates a temporary namespace that only lives for the life time of the scope

Parameters

namespace (str) – The Temporary maya Namespace to use, ie. “tempNamespace” or “:tempNamespace”

generateUniqueNamespace(name)

Generates a unique namespace based on the current scene state in the form of name, name01, name02.

If the provided namespace is already unique it will be returned as is.

Parameters

name (str) – The prefix for the namespace

Returns

The unique name.

Return type

str

isolatedNodes(nodes, panel)

Context manager for isolating nodes in maya model panel

Parameters
  • nodes (seq(str)) – A list of node fullpaths to isolate

  • panel (str) – The maya model panel

maintainSelectionContext()

Context manager which maintains the current selection

maintainSelectionDecorator(func)

Decorator to maintain the current selection.

undoDecorator(func)

Allows all cmds, mel commands perform by the the func into a single undo operation.

@undoDecorator
def myoperationFunc():
    pass
undoContext(name=None)

Context manager for maya undo.

with undoContext:
    cmds.polyCube()
    cmds.sphere()
openUndoChunk(name=None)

Opens a Maya undo chunk

closeUndoChunk(name=None)

Opens a Maya undo chunk

createRepeatCommandForFunc(func, *args, **kwargs)

Function which updates mayas repeat last command with the provide function.

Note

Only functions/staticmethods/classmethods are supported.

def testFunction(argOne, keyword=None):
    print(argOne, keyword)

createRepeatCommandForFunc(testFunction, "helloworld", keyword=0)
Parameters
  • func (callable) – The function for the user repeat(hotkey: g or editMenu: repeat Last)

  • args (tuple) – The arguments to pass to the repeat function

  • kwargs (dict) – The keyword arguments to pass to the repeat function.

createRepeatLastCommandDecorator(function)

Decorator function which updates the maya repeat command with the decorated function.

Note

All args/kwargs of the decorated function will be passed to the repeat command

Note

Only functions/staticmethods/classmethods are supported.

@createRepeatLastCommandDecorator
def testFunction():
    print("test function")
userShelfDir()

Path to shelf

Returns

mayaAppDir()

The Maya preference folder

Windows Vista, Windows 7, and Windows 8

Users<username>DocumentsMaya Mac OS X

~<username>/Library/Preferences/Autodesk/Maya Linux (64-bit)

~<username>/Maya

Returns

Gui

inViewMessage(header, message, type_=0, fadeStayTime=1000)

Smaller wrapper function for nicely formatting maya inview message, INFO,WARNING,ERROR message types supported. Each message type will have a set color.

Parameters
  • header (str) – The main header title for the message , ideally one word

  • message (str) – The message to display

  • type (int) – gui.INFO,gui.WARNING, gui.ERROR

  • fadeStayTime (int) – the fade time

refreshContext()
selectedChannelboxAttributes()
swapOutgoingConnectionsOnSelectedAttrs()

Mayamath

aimToNode(source, target, aimVector=None, upVector=None, worldUpVector=None, constrainAxis=MockExt.OpenMaya.MVector)

Function to aim one node at another using quaternions.

Parameters
  • source (om2.MObject) – node to aim towards the target node

  • target (om2.MObject) – the node which the source will aim at

  • aimVector (om2.MVector) – the om2.MVector for the aim axis defaults to om2.MVector(1.0,0.0,0.0)

  • upVector (om2.MVector) – the om2.MVector for the upVector axis defaults to om2.MVector(0.0,1.0,0.0)

  • worldUpVector (om2.MVector) – Alternative World Up Vector.

  • constrainAxis (om2.MVector) – The axis vector to constrain the aim on. ie. om2.MVector(0,1,1) will set X rotation to 0.0. Same deal as mayas aim constraint.

lookAt(sourcePosition, aimPosition, aimVector=None, upVector=None, worldUpVector=None, constrainAxis=MockExt.OpenMaya.MVector)

Function to aim one node at another using quaternions.

Parameters
  • sourcePosition (om2.MVector) – source position which acts as the eye.

  • aimPosition (om2.MVector) – The target position to aim at.

  • aimVector (om2.MVector) – the om2.MVector for the aim axis defaults to om2.MVector(1.0,0.0,0.0)

  • upVector (om2.MVector) – the om2.MVector for the upVector axis defaults to om2.MVector(0.0,1.0,0.0)

  • worldUpVector (om2.MVector) – Alternative World Up Vector.

  • constrainAxis (om2.MVector) – The axis vector to constrain the aim on. ie. om2.MVector(0,1,1) will set X rotation to 0.0. Same deal as mayas aim constraint.

Return type

om2.MQuaternion

Scene Node Structure:

             + (upVector)
           /
          /
(sourcePosition) o------ + (aimVector) (aimPosition)
                             +
quaterionDot(qa, qb)

Computes the dot product of two quaternions.

Parameters
  • qa (om2.Quaternion) – The first quaternion.

  • qb (om2.Quaternion) – The second quaternion.

Returns

The dot product of the two quaternions.

Return type

float

slerp(qa, qb, weight)

Interpolates between two quaternions using a spherical linear interpolation.

Parameters
  • qa (om2.Quaternion) – The starting quaternion.

  • qb (om2.Quaternion) – The ending quaternion.

  • weight – the weight of the second quaternion in the interpolation

:type weight:float :return: The interpolated quaternion. :rtype: om2.Quaternion

toEulerXYZ(rotMatrix, degrees=False)

Convert rotation matrix to Euler XYZ angles.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • degrees (bool) – A flag to indicate if the output angles should be in degrees or radians

Returns

The converted Euler XYZ angles

Return type

om2.MEulerRotation

toEulerXZY(rotMatrix, degrees=False)

Convert rotation matrix to Euler XZY angles.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • degrees (bool) – A flag to indicate if the output angles should be in degrees or radians

Returns

The converted Euler XZY angles

Return type

om2.MEulerRotation

toEulerYXZ(rotMatrix, degrees=False)

Convert rotation matrix to Euler XZY angles.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • degrees (bool) – A flag to indicate if the output angles should be in degrees or radians

Returns

The converted Euler XZY angles

Return type

om2.MEulerRotation

toEulerYZX(rotMatrix, degrees=False)

Convert rotation matrix to Euler YZX angles.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • degrees (bool) – A flag to indicate if the output angles should be in degrees or radians

Returns

The converted Euler YZX angles

Return type

om2.MEulerRotation

toEulerZXY(rotMatrix, degrees=False)

Convert rotation matrix to Euler ZXY angles.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • degrees (bool) – A flag to indicate if the output angles should be in degrees or radians

Returns

The converted Euler ZXY angles

Return type

om2.MEulerRotation

toEulerZYX(rotMatrix, degrees=False)

Convert rotation matrix to Euler ZYX angles.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • degrees (bool) – A flag to indicate if the output angles should be in degrees or radians

Returns

The converted Euler ZYX angles

Return type

om2.MEulerRotation

toEulerFactory(rotMatrix, rotateOrder, degrees=False)

A factory function that returns the corresponding euler angles based on the provided rotate order.

Parameters
  • rotMatrix (om2.MMatrix) – The rotation matrix to convert.

  • rotateOrder – The order of rotation for the euler angles. Can be one of

(kXYZ, kXZY, kYXZ, kYZX, kZXY, kZYX) :type rotateOrder: om2.MTransformationMatrix.kXYZ :param degrees: A flag to indicate if the output angles should be in degrees or radians :type degrees: bool :return: The converted Euler angles :rtype: om2.MEulerRotation

mirrorXY(rotationMatrix)

Mirror a rotation matrix on the XY plane.

Parameters

rotationMatrix (om2.MMatrix) – the rotation matrix to mirror

Returns

the mirrored rotation matrix

Return type

om2.MMatrix

mirrorYZ(rotationMatrix)

Mirror a rotation matrix on the YZ plane.

Parameters

rotationMatrix (om2.MMatrix) – the rotation matrix to mirror

Returns

the mirrored rotation matrix

Return type

om2.MMatrix

mirrorXZ(rotationMatrix)

Mirror a rotation matrix on the XZ plane.

Parameters

rotationMatrix (om2.MMatrix) – the rotation matrix to mirror

Returns

the mirrored rotation matrix

Return type

om2.MMatrix

angleBetween3Points(a, b, c)

Compute the angle between three points in degrees.

Parameters
  • a (om2.Vector) – The first point

  • b (om2.Vector) – The second point

  • c (om2.Vector) – The third point

Returns

The angle between the three points

Return type

float

evenLinearPointDistribution(start, end, count)

Generator function which evenly distributes points along a straight line.

Each returned point is the vector.

Parameters
  • start (zapi.Vector) – The start vector

  • end (zapi.Vector) – The end vector

  • count (int) – the number of points to distribute

Returns

The distributed vector

Return type

zapi.Vector

firstLastOffsetLinearPointDistribution(start, end, count, offset)

Same behaviour as evenLinearPointDistribution() but offsets the first and last point by the ‘offset value’

Each returned point is the vector.

Parameters
  • start (zapi.Vector) – The start vector

  • end (zapi.Vector) – The end vector

  • count (int) – the number of points to distribute

  • offset – The value to offset the first and last points. The offset is calculated from the fraction(direction*(fraction*offset))

Returns

The distributed vector

Return type

tuple[zapi.Vector, float]

averagePosition(nodes)

Returns the average position on all provided nodes in workspace.

Parameters

nodes (list[zapi.DagNode]) –

Returns

Return type

om2.MVector

averageNormalVector(nodes, axis)

Computes and returns the averaged normal based on the provided nodes rotations.

Parameters
  • nodes (list[zapi.DagNode]) – The nodes to average

  • axis (om2.MVector) – The axis to rotate around ie. om2.MVector(1,0,0)

Returns

The normalized averaged rotations as a vector.

Return type

om2.MVector

twoPointNormal(pointA, pointB, normal)

Based on two points and an additional normal vector return the plane normal.

Parameters
  • pointA (om2.MVector) – First Vector

  • pointB (om2.MVector) – Second Vector

  • normal (om2.MVector) – Additional normal which will be crossed with the distance vector

Returns

Plane Normal

Return type

om2.MVector

threePointNormal(pointA, pointB, pointC)

Same As twoPointNormal() but for three points.

Parameters
  • pointA (om2.MVector) – First Vector

  • pointB (om2.MVector) – Second Vector

  • pointC (om2.MVector) – Third Vector

Returns

Plane Normal

Return type

om2.MVector

closestPointOnPlane(point, plane)

Returns the closet point on the given Plane(projecting the point on the plane).

Parameters
  • point (om2.MVector) – The point to project on to the plane.

  • plane (om2.MPlane) – The plane instance to get the closest point.

Returns

The closest point.

Return type

om2.MVector

indexOfLargest(iterable)

Returns the index of the largest absolute valued component in an iterable.

Parameters

iterable (iterable) – An iterable of floating point values to search.

Return type

int

axisInDirection(matrix, compareVector, defaultAxis)

Returns the axis in integer form 0, 1, 2, 3, 4, 5

0-2 is positive x,y,z while 3,4,5 is negative x,y,z

The defaultAxis is returned if the compareVector is zero or too small to provide meaningful directionality.

Parameters
  • matrix (om2.MMatrix) – The source matrix

  • compareVector (om2.MVector) – the direction vector to compare the matrix to. ie. zapi.Vector(0,0,1)

  • defaultAxis (int) – The default axis index to use when ZeroDivisionError is raised

Return type

int

basisVectorsFromMatrix(matrix)

Returns 3 orthonormal basis vectors that represent the orientation of the given object.

Parameters

matrix (om2.MMatrix) – The matrix to return the orthonormal basis from

Rtype matrix

tuple[om2.MVector, om2.MVector, om2.MVector]

alignToWorldAxis(matrix, rotationAxis=1, forwardAxis=MockExt.OpenMaya.MVector, defaultAxisDirection=2)

Returns the minimal viable single axis rotation to align to the forward axis.

Parameters
  • matrix (om2.MMatrix) – The reference Matrix to pull the rotation from commonly this is the worldMatrix

  • rotationAxis (int) – The axis to rotate on. Defaults to YAXIS

  • forwardAxis (om2.MVector) – The forward vector representing the axis, defaults to ZAXIS_VECTOR

  • defaultAxisDirection (int) – The default forwardAxis to use when a ZeroDivisionError occurs.

Return type

:class:` om2.MEulerRotation`

perpendicularAxisFromAlignVectors(aimVector, upVector)

Given an aim and up vector return which axis isn’t being used and determine whether to get positive values from an incoming attribute whether it needs to be negated.

result = driverAxisFromAimUpVectors(om2.MVector(1,0,0), om2.MVector(0,1,0))
# (2, True)  # 2 is the axis number therefore Z
Parameters
  • aimVector

  • upVector

Returns

Return type

tuple[int, bool]

isVectorNegative(vector)

Whether the sum of the vector(x+y+z) is less then 0.0 :param vector: :return:

primaryAxisNameFromVector(vector)

Internal function which returns the string name of the vector ie. X,Y,Z

Parameters

vector (zapi.Vector or tuple) – The vector to check

Returns

Vector Axis Name ie . X, Y or Z

Return type

str

primaryAxisIndexFromVector(vector)

Internal function which returns the string name of the vector ie. X,Y,Z

Parameters

vector (zapi.Vector or tuple) – The vector to check

Returns

Vector Axis index

Return type

int

nonPrimaryAxisNamesFromVector(vector)

Given a vector, returns a list of the non-primary axes. The primary axis is the one with the largest absolute value.

Parameters

vector (om2.MVector) – The input vector.

Returns

List of non-primary axis names

Return type

list

convertToSceneUnits(value)

Converts the value to the current maya scene UI unit. ie. meters, inches.

Note

Only current supports meters, inches and feet

Parameters

value (float or int or om2.MVector) – value to convert to the scene units.

Returns

The newly converted value.

Return type

float or int or om2.MVector

convertFromSceneUnits(value)

Converts the value from the current maya scene UI unit back to centimeters. ie. meters to cms, inches.

Note

Only current supports meters, inches and feet

Parameters

value (float or int or om2.MVector) – value to convert to the scene units.

Returns

The newly converted value.

Return type

float or int or om2.MVector

Scene

findAdditionalSceneDependencies(references=True, textures=True)

Find additional dependencies from the scene by looking at the file references and texture paths

findSceneTextures()
findTextureNodePairs()
iterTextureNodePairs(includeReferences=False)
findSceneReferences()
isolatedNodes(nodes, panel)

Context manager for isolating nodes in maya model panel

hasUnknownNodes()

Checks to see if there are any unknown nodes

Type

bool

hasUnknownPlugins()

Checks to see if there are any unknown plugins

Return type

bool

isCentimeters()

Returns True if the current scene is in centimeters.

Return type

bool

isFeet()

Returns True if the current scene is in centimeters.

Return type

bool

isInches()

Returns True if the current scene is in inches.

Return type

bool

isKilometers()

Returns True if the current scene is in kilometers.

Return type

bool

isLast()

Returns True if the current scene is in last.

Return type

bool

isMeters()

Returns True if the current scene is in meters.

Return type

bool

isMiles()

Returns True if the current scene is in miles.

Return type

bool

isMillimeters()

Returns True if the current scene is in millimeters.

Return type

bool

isYards()

Returns True if the current scene is in yards.

Return type

bool

Shelves

class Shelf(name='Animation')

Bases: object

A simple class to build shelves in maya. Since the build method is empty, it should be extended by the derived class to build the necessary shelf elements. By default, it creates an empty shelf called “customShelf”.

Parameters

name (str) – Name of the shelf

setAsActive()

Set the shelf as active in maya

shortName()

The shelf name without the full path.

Return type

str

createShelf()

Create the shelf in maya

addButton(label, tooltip=None, icon='commandButton.png', command=None, doubleCommand=None, Type='python', style='iconOnly')

Adds a shelf button with the specified label, command, double click command and image.

Parameters
  • label (str) – label of the button

  • tooltip (str) – tooltip text to display when hovering over the button

  • icon (str) – file path to image file for button icon

  • command (str) – command to execute on button press

  • doubleCommand (str) – command to execute on button double-press

  • Type (str) – type of command (python or mel)

  • style (str) – the layout of the button (iconOnly, textOnly, or iconAndText)

Returns

The shelfButton UI path

Return type

str

static addMenuItem(parent, label, command='', icon='')

Adds a menu item with the specified label, command, and image. :param parent: The parent menu where the item should be added. :type parent: str :param label: The label of the menu item. :type label: str :param command: The command that should be executed when the menu item is clicked. :type command: str :param icon: The path to the icon that should be used for the menu item. :type icon: str :return: The menu item that has been created. :rtype: str

static addSubMenu(parent, label, icon=None)

Adds a sub menu item with the specified label and icon to the specified parent popup menu.

Parameters
  • parent (str) – The parent menu where the sub menu should be added.

  • label (str) – The label of the sub menu.

  • icon (str) – The path to the icon that should be used for the sub menu.

Returns

The sub menu that has been created.

Return type

str

static addMenuSeparator(parent, **kwargs)

Adds a separator(line) on the parent menu.

This uses the cmds.menuItem to create the separator

Parameters

parent (str) – The full UI path to the parent menu

addSeparator()

Adds a maya shelf separator to the parent shelf

Returns

The full path to the separator

Return type

str

cleanOldShelf(shelfName, deleteShelf=True)

Checks if the shelf exists and empties it if it does

primaryShelfLayout()

Returns the main maya shelf layer path.

Have to mel globals here, the hell?

Returns

The shelf layout path

Return type

str

activeShelf()

Returns the currently active maya shelf as a Shelf object.

Returns

Return type

Shelf

MayaColors

Functions and constants related directly to Maya’s color handling.

Example use:

from zoo.libs.maya.utils import mayacolors
mayacolors.setColorSpaceAces()
renderSpaceColor = mayacolors.displayColorToCurrentRenderingSpace(displaySpaceColor)
displaySpaceColor = mayacolors.renderingColorToDisplaySpace(renderingSpaceColor)
setColorSpaceLinear(message=True)

Sets color space color management settings to be linear as per older versions of Maya in 2022 and above

setColorSpaceAces(message=True)

Sets color space color management settings to be ACES as per the new defaults in Maya in 2022 and above

setColorSpaceAcesNoTone(message=True)

Sets color space color management settings to be ACES (no tone map) in Maya in 2022 and above

setRenderingSpace(renderSpace='linear', message=True)

Sets the renderspace for Maya, use only in 2022 and above.

Parameters
  • renderSpace (str) – linear or aces

  • message (bool) – Report a message to the user?

setViewTransform(view='noToneMap', message=True)

Sets the view transform (grade/tone-map) inside Maya.

Parameters
  • view (str) – “noToneMap” or “sdrVideo”

  • message (bool) – Report a message to the user?

displayColorToCurrentRenderingSpace(displayColor, setCurrentViewSpace=False, viewSpace='Un-tone-mapped')

Converts display space color to the current rendering space using Maya’s API

The Maya commands function cmds.colorManagementConvert() is useless.

Only works in Maya 2023 and above. Issues in 2022 unfortunately.

If lower than 2023 will return the color linearized instead.

viewSpace should be “Un-tone-mapped” if importing in JSON data, also for conversions to figure render space color.

Parameters
  • displayColor (list(float)) – display color (usually srgb color) as a float [0.1, 0.4, 0.6]

  • setCurrentViewSpace (str) – Sets the viewspace as the current viewspace. If True kwarg viewSpace is ignored.

  • viewSpace (str) – What view to output? ‘ACES 1.0 SDR-video’, ‘Un-tone-mapped’, ‘Unity neutral tone-map’, ‘Raw’ etc

Return color

color in maya’s native rendering space as a float

Rtype color

list(float)

renderingColorToDisplaySpace(renderColor, setCurrentViewSpace=False, viewSpace='Un-tone-mapped')

Converts rendering space color to the current display space using Maya’s API

The Maya commands function cmds.colorManagementConvert() is useless.

Only works in Maya 2023 and above. Display colors are Un-tone-mapped. Issues in 2022 unfortunately.

If lower than 2023 will return the color linear to srgb instead.

viewSpace should be “Un-tone-mapped” if importing in JSON data, also for conversions to figure render space color.

Parameters
  • displayColor (list(float)) – display color (usually srgb color) as a float [0.1, 0.4, 0.6]

  • viewSpace (str) – what grade to output? ‘ACES 1.0 SDR-video’, ‘Un-tone-mapped’, ‘Unity neutral tone-map’, ‘Raw’ etc

Return color

color in maya’s native rendering space as a float

Rtype color

list(float)

renderingColorToDisplaySpaceLegacy(renderingSpaceColor)

Converts rendering space color to the current display space color using cmds.colorManagementConvert (not great)

This is depreciated, use renderingColorToDisplaySpace() as it supports the viewspace.

Parameters

renderingSpaceColor (list(float)) – color in maya’s native rendering space as a float [0.1, 0.4, 0.6]

Return displayColor

display color (usually srgb color) as a float [0.1, 0.4, 0.6]

Rtype displayColor

list(float)

Maya Test Utils

class BaseMayaTest(methodName='runTest')

Bases: BaseUnitest

Base class for all maya based unitests, provides helper methods for loading and loading plugins

keepPluginsLoaded = False
loadedPlugins = {}
application = 'maya'
newSceneAfterTest = False
classmethod loadPlugin(pluginName)

Loads a given plugin and stores it on the class :param pluginName: str, the plugin to load

classmethod unloadPlugins()

Unload all the currently loaded plugins

tearDown(**kw)

Hook method for deconstructing the test fixture after testing it.

classmethod tearDownClass()

Calls on cls.unloadPlugins()

Tooltips

tooltipState()

Get the maya tooltip state

Returns

Return type

bool

setMayaTooltipState(state)

Set the maya state to show the tooltips or not.

Parameters

state – bool

Returns