All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdMayaUtil Namespace Reference

General utilities for working with the Maya API. More...

Classes

class  MDataHandleHolder
 RAII-style helper for destructing an MDataHandle obtained from a plug once it goes out of scope. More...
 

Typedefs

using MDagPathSet = std::set< MDagPath, _CmpDag >
 Set of DAG paths. More...
 
template<typename V >
using MDagPathMap = std::map< MDagPath, V, _CmpDag >
 Mapping of DAG paths to an arbitrary type. More...
 
using MObjectHandleUnorderedSet = std::unordered_set< MObjectHandle, _HashObjectHandle >
 Unordered set of Maya object handles. More...
 
template<typename V >
using MObjectHandleUnorderedMap = std::unordered_map< MObjectHandle, V, _HashObjectHandle >
 Unordered mapping of Maya object handles to an arbitrary type. More...
 

Functions

double ConvertMMToInches (const double mm)
 Converts the given value mm in millimeters to the equivalent value in inches. More...
 
double ConvertInchesToMM (const double inches)
 Converts the given value inches in inches to the equivalent value in millimeters. More...
 
double ConvertMMToCM (const double mm)
 Converts the given value mm in millimeters to the equivalent value in centimeters. More...
 
double ConvertCMToMM (const double cm)
 Converts the given value cm in centimeters to the equivalent value in millimeters. More...
 
PXRUSDMAYA_API double ConvertMDistanceUnitToUsdGeomLinearUnit (const MDistance::Unit mdistanceUnit)
 Converts the given value mdistance in Maya's MDistance units to the equivalent value in USD's metersPerUnit. More...
 
PXRUSDMAYA_API MDistance::Unit ConvertUsdGeomLinearUnitToMDistanceUnit (const double linearUnit)
 Coverts the given value linearUnit in USD's metersPerUnit to the equivalent value in Maya's MDistance units. More...
 
PXRUSDMAYA_API std::string GetMayaNodeName (const MObject &mayaNode)
 Get the full name of the Maya node mayaNode. More...
 
PXRUSDMAYA_API MStatus GetMObjectByName (const std::string &nodeName, MObject &mObj)
 Gets the Maya MObject for the node named nodeName. More...
 
PXRUSDMAYA_API MStatus GetDagPathByName (const std::string &nodeName, MDagPath &dagPath)
 Gets the Maya MDagPath for the node named nodeName. More...
 
PXRUSDMAYA_API MStatus GetPlugByName (const std::string &attrPath, MPlug &plug)
 Gets the Maya MPlug for the given attrPath. More...
 
PXRUSDMAYA_API MPlug GetMayaTimePlug ()
 Get the MPlug for the output time attribute of Maya's global time object. More...
 
PXRUSDMAYA_API MPlug GetMayaShaderListPlug ()
 Get the MPlug for the shaders attribute of Maya's defaultShaderList. More...
 
PXRUSDMAYA_API MObject GetDefaultLightSetObject ()
 Get the MObject for the DefaultLightSet, which should add any light nodes as members for them to take effect in the scene. More...
 
PXRUSDMAYA_API bool isAncestorDescendentRelationship (const MDagPath &path1, const MDagPath &path2)
 
PXRUSDMAYA_API int getSampledType (const MPlug &iPlug, const bool includeConnectedChildren)
 
PXRUSDMAYA_API bool isAnimated (const MObject &mayaObject, const bool checkParent=false)
 Determine if the Maya object mayaObject is animated or not. More...
 
PXRUSDMAYA_API bool isPlugAnimated (const MPlug &plug)
 
PXRUSDMAYA_API bool isIntermediate (const MObject &object)
 Determine if a Maya object is an intermediate object. More...
 
PXRUSDMAYA_API bool isRenderable (const MObject &object)
 
PXRUSDMAYA_API bool isWritable (const MObject &object)
 Determine whether a Maya object can be saved to or exported from the Maya scene. More...
 
const std::string MayaDagDelimiter ("|")
 This is the delimiter that Maya uses to identify levels of hierarchy in the Maya DAG. More...
 
const std::string MayaNamespaceDelimiter (":")
 This is the delimiter that Maya uses to separate levels of namespace in Maya node names. More...
 
PXRUSDMAYA_API std::string stripNamespaces (const std::string &nodeName, const int nsDepth=-1)
 Strip nsDepth namespaces from nodeName. More...
 
PXRUSDMAYA_API std::string SanitizeName (const std::string &name)
 
PXRUSDMAYA_API std::string SanitizeColorSetName (const std::string &name)
 
PXRUSDMAYA_API bool GetLinearShaderColor (const MFnDagNode &node, 1::VtVec3fArray *RGBData, 1::VtFloatArray *AlphaData, 1::TfToken *interpolation, 1::VtIntArray *assignmentIndices)
 Get the base colors and opacities from the shader(s) bound to node. More...
 
PXRUSDMAYA_API bool GetLinearShaderColor (const MFnMesh &mesh, 1::VtVec3fArray *RGBData, 1::VtFloatArray *AlphaData, 1::TfToken *interpolation, 1::VtIntArray *assignmentIndices)
 Get the base colors and opacities from the shader(s) bound to mesh. More...
 
PXRUSDMAYA_API void MergeEquivalentIndexedValues (1::VtFloatArray *valueData, 1::VtIntArray *assignmentIndices)
 Combine distinct indices that point to the same values to all point to the same index for that value. More...
 
PXRUSDMAYA_API void MergeEquivalentIndexedValues (1::VtVec2fArray *valueData, 1::VtIntArray *assignmentIndices)
 Combine distinct indices that point to the same values to all point to the same index for that value. More...
 
PXRUSDMAYA_API void MergeEquivalentIndexedValues (1::VtVec3fArray *valueData, 1::VtIntArray *assignmentIndices)
 Combine distinct indices that point to the same values to all point to the same index for that value. More...
 
PXRUSDMAYA_API void MergeEquivalentIndexedValues (1::VtVec4fArray *valueData, 1::VtIntArray *assignmentIndices)
 Combine distinct indices that point to the same values to all point to the same index for that value. More...
 
PXRUSDMAYA_API void CompressFaceVaryingPrimvarIndices (const MFnMesh &mesh, 1::TfToken *interpolation, 1::VtIntArray *assignmentIndices)
 Attempt to compress faceVarying primvar indices to uniform, vertex, or constant interpolation if possible. More...
 
PXRUSDMAYA_API bool IsAuthored (const MPlug &plug)
 Get whether plug is authored in the Maya scene. More...
 
PXRUSDMAYA_API MPlug GetConnected (const MPlug &plug)
 
PXRUSDMAYA_API void Connect (const MPlug &srcPlug, const MPlug &dstPlug, const bool clearDstPlug)
 
PXRUSDMAYA_API MPlug FindChildPlugByName (const MPlug &plug, const MString &name)
 Get a named child plug of plug by name. More...
 
PXRUSDMAYA_API::SdfPath MayaNodeNameToSdfPath (const std::string &nodeName, const bool stripNamespaces)
 Converts the given Maya node name nodeName into an SdfPath. More...
 
PXRUSDMAYA_API::SdfPath MDagPathToUsdPath (const MDagPath &dagPath, const bool mergeTransformAndShape, const bool stripNamespaces)
 Converts the given Maya MDagPath dagPath into an SdfPath. More...
 
PXRUSDMAYA_API bool GetBoolCustomData (const 1::UsdAttribute &obj, const 1::TfToken &key, const bool defaultValue)
 Convenience function to retrieve custom data. More...
 
template<typename T >
bool getPlugValue (const MFnDependencyNode &depNode, const MString &attr, T *val, bool *isAnimated=nullptr)
 Compute the value of attr, returning true upon success. More...
 
PXRUSDMAYA_API MMatrix GfMatrixToMMatrix (const GfMatrix4d &mx)
 Convert a Gf matrix to an MMatrix. More...
 
PXRUSDMAYA_API bool getPlugMatrix (const MFnDependencyNode &depNode, const MString &attr, MMatrix *outVal)
 
PXRUSDMAYA_API bool setPlugMatrix (const MFnDependencyNode &depNode, const MString &attr, const GfMatrix4d &mx)
 Set a matrix value on plug name attr, of depNode. More...
 
PXRUSDMAYA_API bool setPlugMatrix (const GfMatrix4d &mx, MPlug &plug)
 
PXRUSDMAYA_API bool setPlugValue (const 1::UsdAttribute &attr, MPlug &attrPlug)
 Given an usdAttr , extract the value at the default timecode and write it on attrPlug. More...
 
PXRUSDMAYA_API bool setPlugValue (const 1::UsdAttribute &attr, const 1::UsdTimeCode time, MPlug &attrPlug)
 Given an usdAttr , extract the value at timecode time and write it on attrPlug. More...
 
template<typename T >
bool setPlugValue (const MFnDependencyNode &depNode, const MString &attr, const T &val)
 sets attr to have value val, assuming it exists on depNode. More...
 
PXRUSDMAYA_API TfRefPtr
< MDataHandleHolder
GetPlugDataHandle (const MPlug &plug)
 Obtains an RAII helper object for accessing the MDataHandle stored on the plug. More...
 
PXRUSDMAYA_API bool SetNotes (MFnDependencyNode &depNode, const std::string &notes)
 
PXRUSDMAYA_API bool SetHiddenInOutliner (MFnDependencyNode &depNode, const bool hidden)
 
PXRUSDMAYA_API VtDictionary GetDictionaryFromArgDatabase (const MArgDatabase &argData, const VtDictionary &guideDict)
 Reads values from the given argData into a VtDictionary, using the guideDict to figure out which keys and what type of values should be read from argData. More...
 
PXRUSDMAYA_API VtValue ParseArgumentValue (const std::string &key, const std::string &value, const VtDictionary &guideDict)
 Parses value based on the type of key in guideDict, returning the parsed value wrapped in a VtValue. More...
 
PXRUSDMAYA_API std::vector
< std::string > 
GetAllAncestorMayaNodeTypes (const std::string &ty)
 Gets all Maya node types that are ancestors of the given Maya node type ty. More...
 
PXRUSDMAYA_API bool FindAncestorSceneAssembly (const MDagPath &dagPath, MDagPath *assemblyPath=nullptr)
 If dagPath is a scene assembly node or is the descendant of one, populates the *assemblyPath with the assembly path and returns true. More...
 
PXRUSDMAYA_API MBoundingBox GetInfiniteBoundingBox ()
 

Variables

const double MillimetersPerInch = 25.4
 
const double MillimetersPerCentimeter = 10.0
 

Detailed Description

General utilities for working with the Maya API.

Typedef Documentation

using MDagPathMap = std::map<MDagPath, V, _CmpDag>

Mapping of DAG paths to an arbitrary type.

Warning: MDagPaths refer to specific objects, so the internal fullPathName may change over time. Only use this class if you can guarantee that DAG nodes won't be renamed or reparented while class instances are alive. Otherwise, you may see inconsistent results.

Definition at line 97 of file util.h.

using MDagPathSet = std::set<MDagPath, _CmpDag>

Set of DAG paths.

Warning: MDagPaths refer to specific objects, so the internal fullPathName may change over time. Only use this class if you can guarantee that DAG nodes won't be renamed or reparented while class instances are alive. Otherwise, you may see inconsistent results.

Definition at line 89 of file util.h.

using MObjectHandleUnorderedMap = std::unordered_map<MObjectHandle, V, _HashObjectHandle>

Unordered mapping of Maya object handles to an arbitrary type.

Definition at line 114 of file util.h.

using MObjectHandleUnorderedSet = std::unordered_set<MObjectHandle, _HashObjectHandle>

Unordered set of Maya object handles.

Definition at line 109 of file util.h.

Function Documentation

PXRUSDMAYA_API void UsdMayaUtil::CompressFaceVaryingPrimvarIndices ( const MFnMesh &  mesh,
1::TfToken interpolation,
1::VtIntArray *  assignmentIndices 
)

Attempt to compress faceVarying primvar indices to uniform, vertex, or constant interpolation if possible.

This will potentially shrink the indices array and will update the interpolation if any compression was possible.

double UsdMayaUtil::ConvertCMToMM ( const double  cm)
inline

Converts the given value cm in centimeters to the equivalent value in millimeters.

Definition at line 169 of file util.h.

double UsdMayaUtil::ConvertInchesToMM ( const double  inches)
inline

Converts the given value inches in inches to the equivalent value in millimeters.

Definition at line 149 of file util.h.

PXRUSDMAYA_API double UsdMayaUtil::ConvertMDistanceUnitToUsdGeomLinearUnit ( const MDistance::Unit  mdistanceUnit)

Converts the given value mdistance in Maya's MDistance units to the equivalent value in USD's metersPerUnit.

double UsdMayaUtil::ConvertMMToCM ( const double  mm)
inline

Converts the given value mm in millimeters to the equivalent value in centimeters.

Definition at line 160 of file util.h.

double UsdMayaUtil::ConvertMMToInches ( const double  mm)
inline

Converts the given value mm in millimeters to the equivalent value in inches.

Definition at line 140 of file util.h.

PXRUSDMAYA_API MDistance::Unit UsdMayaUtil::ConvertUsdGeomLinearUnitToMDistanceUnit ( const double  linearUnit)

Coverts the given value linearUnit in USD's metersPerUnit to the equivalent value in Maya's MDistance units.

PXRUSDMAYA_API bool UsdMayaUtil::FindAncestorSceneAssembly ( const MDagPath &  dagPath,
MDagPath *  assemblyPath = nullptr 
)

If dagPath is a scene assembly node or is the descendant of one, populates the *assemblyPath with the assembly path and returns true.

Otherwise, returns false.

PXRUSDMAYA_API MPlug UsdMayaUtil::FindChildPlugByName ( const MPlug &  plug,
const MString &  name 
)

Get a named child plug of plug by name.

PXRUSDMAYA_API std::vector<std::string> UsdMayaUtil::GetAllAncestorMayaNodeTypes ( const std::string &  ty)

Gets all Maya node types that are ancestors of the given Maya node type ty.

If ty isn't registered in Maya's type system, issues a runtime error and returns an empty string. The returned list is sorted from furthest to closest ancestor. The returned list will always have the given type ty as the last item. Note that this calls out to MEL.

PXRUSDMAYA_API bool UsdMayaUtil::GetBoolCustomData ( const 1::UsdAttribute obj,
const 1::TfToken key,
const bool  defaultValue 
)

Convenience function to retrieve custom data.

PXRUSDMAYA_API MStatus UsdMayaUtil::GetDagPathByName ( const std::string &  nodeName,
MDagPath &  dagPath 
)

Gets the Maya MDagPath for the node named nodeName.

PXRUSDMAYA_API MObject UsdMayaUtil::GetDefaultLightSetObject ( )

Get the MObject for the DefaultLightSet, which should add any light nodes as members for them to take effect in the scene.

PXRUSDMAYA_API VtDictionary UsdMayaUtil::GetDictionaryFromArgDatabase ( const MArgDatabase &  argData,
const VtDictionary guideDict 
)

Reads values from the given argData into a VtDictionary, using the guideDict to figure out which keys and what type of values should be read from argData.

Mainly useful for parsing arguments in commands all at once.

PXRUSDMAYA_API bool UsdMayaUtil::GetLinearShaderColor ( const MFnDagNode &  node,
1::VtVec3fArray *  RGBData,
1::VtFloatArray *  AlphaData,
1::TfToken interpolation,
1::VtIntArray *  assignmentIndices 
)

Get the base colors and opacities from the shader(s) bound to node.

Returned colors will be in linear color space.

A single value for each of color and alpha will be returned, interpolation will be constant, and assignmentIndices will be empty.

PXRUSDMAYA_API bool UsdMayaUtil::GetLinearShaderColor ( const MFnMesh &  mesh,
1::VtVec3fArray *  RGBData,
1::VtFloatArray *  AlphaData,
1::TfToken interpolation,
1::VtIntArray *  assignmentIndices 
)

Get the base colors and opacities from the shader(s) bound to mesh.

Returned colors will be in linear color space.

If the entire mesh has a single shader assignment, a single value for each of color and alpha will be returned, interpolation will be constant, and assignmentIndices will be empty.

Otherwise, a color and alpha value will be returned for each shader assigned to any face of the mesh. assignmentIndices will be the length of the number of faces with values indexing into the color and alpha arrays representing per-face assignments. Faces with no assigned shader will have a value of -1 in assignmentIndices. interpolation will be uniform.

PXRUSDMAYA_API std::string UsdMayaUtil::GetMayaNodeName ( const MObject &  mayaNode)

Get the full name of the Maya node mayaNode.

If mayaNode refers to a DAG node (i.e. supports the MFnDagNode function set), then the name returned will be the DAG node's full path name.

If mayaNode refers to a DG node (i.e. supports the MFnDependencyNode function set), then the name returned will be the DG node's absolute name.

If mayaNode is not one of these or if an error is encountered, an empty string will be returned.

PXRUSDMAYA_API MPlug UsdMayaUtil::GetMayaShaderListPlug ( )

Get the MPlug for the shaders attribute of Maya's defaultShaderList.

This is an accessor for the "defaultShaderList1.shaders" plug. Similar to GetMayaTimePlug(), it will traverse through MFn::kShaderList objects.

PXRUSDMAYA_API MPlug UsdMayaUtil::GetMayaTimePlug ( )

Get the MPlug for the output time attribute of Maya's global time object.

The Maya API does not appear to provide any facilities for getting a handle to the global time object (e.g. "time1"). We need to find this object in order to make connections between its "outTime" attribute and the input "time" attributes on assembly nodes when their "Playback" representation is activated.

This function makes a best effort attempt to find "time1" by looking through all MFn::kTime function set objects in the scene and returning the one whose outTime attribute matches the current time. If no such object can be found, an invalid plug is returned.

PXRUSDMAYA_API MStatus UsdMayaUtil::GetMObjectByName ( const std::string &  nodeName,
MObject &  mObj 
)

Gets the Maya MObject for the node named nodeName.

PXRUSDMAYA_API MStatus UsdMayaUtil::GetPlugByName ( const std::string &  attrPath,
MPlug &  plug 
)

Gets the Maya MPlug for the given attrPath.

The attribute path should be specified as "nodeName.attrName" (the format used by MEL).

PXRUSDMAYA_API TfRefPtr<MDataHandleHolder> UsdMayaUtil::GetPlugDataHandle ( const MPlug &  plug)

Obtains an RAII helper object for accessing the MDataHandle stored on the plug.

When the helper object goes out of scope, the data handle will be destructed. If the plug's data handle could not be obtained, returns nullptr.

bool UsdMayaUtil::getPlugValue ( const MFnDependencyNode &  depNode,
const MString &  attr,
T *  val,
bool *  isAnimated = nullptr 
)

Compute the value of attr, returning true upon success.

Definition at line 431 of file util.h.

PXRUSDMAYA_API MMatrix UsdMayaUtil::GfMatrixToMMatrix ( const GfMatrix4d mx)

Convert a Gf matrix to an MMatrix.

PXRUSDMAYA_API bool UsdMayaUtil::isAnimated ( const MObject &  mayaObject,
const bool  checkParent = false 
)

Determine if the Maya object mayaObject is animated or not.

PXRUSDMAYA_API bool UsdMayaUtil::IsAuthored ( const MPlug &  plug)

Get whether plug is authored in the Maya scene.

A plug is considered authored if its value has been changed from the default (or since being brought in from a reference for plugs on nodes from referenced files), or if the plug is the destination of a connection. Otherwise, it is considered unauthored.

PXRUSDMAYA_API bool UsdMayaUtil::isIntermediate ( const MObject &  object)

Determine if a Maya object is an intermediate object.

Only objects with the MFnDagNode function set can be intermediate objects. Objects whose intermediate object status cannot be determined are assumed not to be intermediate objects.

PXRUSDMAYA_API bool UsdMayaUtil::isWritable ( const MObject &  object)

Determine whether a Maya object can be saved to or exported from the Maya scene.

Objects whose "default node" or "do not write" status cannot be determined using the MFnDependencyNode function set are assumed to be writable.

const std::string UsdMayaUtil::MayaDagDelimiter ( "|"  )

This is the delimiter that Maya uses to identify levels of hierarchy in the Maya DAG.

const std::string UsdMayaUtil::MayaNamespaceDelimiter ( ":"  )

This is the delimiter that Maya uses to separate levels of namespace in Maya node names.

PXRUSDMAYA_API ::SdfPath UsdMayaUtil::MayaNodeNameToSdfPath ( const std::string &  nodeName,
const bool  stripNamespaces 
)

Converts the given Maya node name nodeName into an SdfPath.

Elements of the path will be sanitized such that it is a valid SdfPath. This means it will replace Maya's namespace delimiter (':') with underscores ('_').

PXRUSDMAYA_API ::SdfPath UsdMayaUtil::MDagPathToUsdPath ( const MDagPath &  dagPath,
const bool  mergeTransformAndShape,
const bool  stripNamespaces 
)

Converts the given Maya MDagPath dagPath into an SdfPath.

If mergeTransformAndShape and the dagPath is a shapeNode, it will return the same value as MDagPathToUsdPath(transformPath) where transformPath is the MDagPath for dagPath's transform node.

Elements of the path will be sanitized such that it is a valid SdfPath. This means it will replace Maya's namespace delimiter (':') with underscores ('_').

PXRUSDMAYA_API void UsdMayaUtil::MergeEquivalentIndexedValues ( 1::VtFloatArray *  valueData,
1::VtIntArray *  assignmentIndices 
)

Combine distinct indices that point to the same values to all point to the same index for that value.

This will potentially shrink the data array.

PXRUSDMAYA_API void UsdMayaUtil::MergeEquivalentIndexedValues ( 1::VtVec2fArray *  valueData,
1::VtIntArray *  assignmentIndices 
)

Combine distinct indices that point to the same values to all point to the same index for that value.

This will potentially shrink the data array.

PXRUSDMAYA_API void UsdMayaUtil::MergeEquivalentIndexedValues ( 1::VtVec3fArray *  valueData,
1::VtIntArray *  assignmentIndices 
)

Combine distinct indices that point to the same values to all point to the same index for that value.

This will potentially shrink the data array.

PXRUSDMAYA_API void UsdMayaUtil::MergeEquivalentIndexedValues ( 1::VtVec4fArray *  valueData,
1::VtIntArray *  assignmentIndices 
)

Combine distinct indices that point to the same values to all point to the same index for that value.

This will potentially shrink the data array.

PXRUSDMAYA_API VtValue UsdMayaUtil::ParseArgumentValue ( const std::string &  key,
const std::string &  value,
const VtDictionary guideDict 
)

Parses value based on the type of key in guideDict, returning the parsed value wrapped in a VtValue.

Raises a coding error if key doesn't exist in guideDict. Mainly useful for parsing arguments one-by-one in translators' option strings. If you have an MArgList/MArgParser/MArgDatabase, it's going to be way simpler to use GetDictionaryFromArgDatabase() instead.

PXRUSDMAYA_API bool UsdMayaUtil::setPlugMatrix ( const MFnDependencyNode &  depNode,
const MString &  attr,
const GfMatrix4d mx 
)

Set a matrix value on plug name attr, of depNode.

Returns true if the value was set on the plug successfully, false otherwise.

PXRUSDMAYA_API bool UsdMayaUtil::setPlugValue ( const 1::UsdAttribute attr,
MPlug &  attrPlug 
)

Given an usdAttr , extract the value at the default timecode and write it on attrPlug.

This will make sure that color values (which are linear in usd) get gamma corrected (display in maya). Returns true if the value was set on the plug successfully, false otherwise.

PXRUSDMAYA_API bool UsdMayaUtil::setPlugValue ( const 1::UsdAttribute attr,
const 1::UsdTimeCode  time,
MPlug &  attrPlug 
)

Given an usdAttr , extract the value at timecode time and write it on attrPlug.

This will make sure that color values (which are linear in usd) get gamma corrected (display in maya). Returns true if the value was set on the plug successfully, false otherwise.

bool UsdMayaUtil::setPlugValue ( const MFnDependencyNode &  depNode,
const MString &  attr,
const T &  val 
)

sets attr to have value val, assuming it exists on depNode.

Returns true if successful.

Definition at line 495 of file util.h.

PXRUSDMAYA_API std::string UsdMayaUtil::stripNamespaces ( const std::string &  nodeName,
const int  nsDepth = -1 
)

Strip nsDepth namespaces from nodeName.

This will turn "taco:foo:bar" into "foo:bar" for nsDepth == 1, or "taco:foo:bar" into "bar" for nsDepth > 1. If nsDepth is -1, all namespaces are stripped.