Python API

Overview

XGen provides a Python API that gives access to internal XGen data from the Python shell. This can be used within or outside of Maya. The API is extended within Maya to allow for operations that apply within Maya (for example, accepting the “name” of a guide to get its patch), but that don’t apply elsewhere. All interaction with XGen should be done through this API, or the UI. Any access via MPxCommands or MEL functions that might exist within XGen are not guaranteed.

The methods are listed below in a pseudo syntax to indicate the return type and expected parameter types. Calling the methods is done as you would normally do in Python. You can pass the parameters in order, or use the names and reorder them as you please.

Importing API

The API is divided into two parts: Base and Maya. There is a separate UI component, but the API is essentially made up of the underlying C++ code, a Python layer that constitutes the Base API, and then another Python layer that brings in necessary Maya additions as well as extra API functions that constitutes the Maya API. It is important to bring in the correct API for the task, or you may obtain unexpected results. The best approach is to let XGen handle the decision for you:

import xgen as xg

This brings in the xgen module which detects Maya and optionally brings in the Maya layer of the API. If your script is going to run inside and outside of Maya and you are calling methods from the Maya only portion of the API, you should put those within a conditional block. A safe way to handle this is to use XGen's Maya detection:

import xgen.xgGlobal as xgg

if xgg.Maya
    # Do something maya specific like using XGen's Maya API

This brings in the XGen global module, which has the ability to detect Maya. Once that is in place, you can use its xgg.Maya variable to determine that you are in Maya and protect your Maya code within these conditionals.

Base API

The following methods are available whether you are inside or outside of Maya. They operate directly on the underlying XGen data. Many are also available through the libXgAPI.so library as a C++ API if you need an even faster link into XGen.

Creation and Deletion

• string createDescription( string palette, string description, string primitive, string generator, string renderer, string method )()
  • Create a new description and place it within the named palette. If the palette does not exist, then it too will be created.
• bool deletePalette( string palette )()
  • Delete the named palette. This will delete all of its descriptions, patches, objects, fx modules, guides, and so forth.
• bool deleteDescription( string palette, string description )()
  • Delete the named description. This will delete all of its patches, objects, fx modules, guides, and so forth.

Object Access

• string[] palettes()
  • Get a list of palettes currently in the scene.
• string[] descriptions( string palette="" )()
  • Get a list of descriptions for the given palette; or, if no palette name is given, return all descriptions in the scene.
• string palette( string description )()
  • Get the palette for the given description. To do this, the list of descriptions for each palette is searched, which assumes that all of the descriptions are uniquely named.
• string getActive( string palette, string description, string type )()
  • Get the active subtype of the given type from the description. The return value is the subtype (for example, SplinePrimitive, CardPrimitive).
• bool setActive( string palette, string description, string subtype, bool previewer=False )()
  • Set the active subtype of the given type for the description. The subtype given should be fully named (for example, CardPrimitive, FileRenderer).
• string[] objects( string palette, string description, bool activeOnly=False )()
  • Get a list of all objects (for example, SpherePrimitive, GuideRenderer) for a description.
• bool initInterpolation( string palette, string description, string fileName="" )()
  • Initialize the interpolation for the active primitive of the given description. This should be done anytime a guide is moved to a new location, a guide is added, or a guide is removed.

Attribute Access

• bool attrExists( string attrName, string palette, string description="", string object="" )()
  • Query the existence of an attribute on an xgen object.
• string getAttr( string attrName,string palette, string description="", string object="" )()
  • Get the value of an attribute on an xgen object.
• bool setAttr( string attrName, string value, string palette, string description="", string object ="")()
  • Set the value of an attribute on an xgen object.
• string[] attrs( string palette, string description="", string object="" )()
  • Return the list of attributes for the given node. This does not include custom attributes.
• void addCustomAttr( string attrName, string palette, string description="", string object ="")()
  • Add a custom attribute. The attribute should be named using the template pattern: custom_<type>_<name> or custom_<type>_<name>[#]. If an array is specified with the [#] extension, then an attribute will be added for each element of the array. Common usage would be to add attributes to either the palette or a RenderMan renderer, but any object can be specified.
• void remCustomAttr( string attrName, string palette, string description="", string object="" )()
  • Remove a custom attribute. The attribute should be named using the template pattern: custom_<type>_<name> or custom_<type>_<name>[#]. If an array is specified with the [#] extension, then all attributes of the array will be deleted.
• string[] customAttrs( string palette, string description="", string object="" )()
  • Return the list of custom attributes for the given node.
• string[] allAttrs( string palette, string description="", string object="" )()
  • Return the full list of attributes for the given node.

FX Modules

• string[] fxModules( string palette, string description)()
  • Get a list of fx modules for the given palette and description. Modules are returned for the currently active primitive, and in the order of execution.
• string fxModuleType( string palette, string description, string name )()
  • Get the type of the given fx module. The active primitive is searched for the module.
• string addFXModule( string palette, string description, string type, string name="" )()
  • Add a new fx module to the end of the fx chain for the active primitive of the given description. If the module is successfully added, then its name will be returned. Upon failure, the empty string is returned.
• bool removeFXModule( string palette, string description, string name )()
  • Remove a named fx module from the active primitive of the given description. Success will result in a return value of ‘true’ with failure being ‘false’.
• bool moveFXModule( string palette, string description, string name, int dir )()
  • Move an FX module. The module name will be used to find the module in the active primitive of the given description. Once found, the module will be moved up or down depending on the value of ‘dir’. Negative means “up” and positive means “down”.

Culling

• string[] culledPrimPatches( string palette, string description )()
  • Given a palette and description, return the names of the patches that have culled primitives.
• int[] culledPrimFaces( string palette, string description, string patchName )()
  • Given a palette, a description and a patch name, return the faces on the patch that have culled primitives.
• set(int) culledPrims( string palette, string description, string patchName, int faceId )()
  • Given a palette, a description, patch name and a face id, return the culled primitive ids on the face.

Binding Info

• string[] boundGeometry( string palette, string description )()
  • Given a palette and a description, return the names for all of the bound pieces of geometry. In XGen, these are also the patch names.
• int[] boundFaces( string palette, string description, string patchName )()
  • Given a palette, a description, and a patch name, return a list of the faces bound to the description from that patch.

File IO

• string importPalette( string palette, string deltas[], string nameSpace="" )()
  • Import a palette from an xgen file with the specified delta files applied. The palette can optionally be placed into the given namespace. In Maya, there is an optional fourth argument called wrapPatches that defaults to True. Setting this to False will allow you to bring in a palette and not have its patches or guides loaded. Doing this lets you bring in the palette without its geometry, use it for reference, transfer it to another element, and so forth.
• bool exportPalette( string palette, string fileName )()
  • Export the given palette into a .xgen file on disk.
• int createDelta( string palette, string newDelta )()
  • Compare the current palette loaded in Maya against the base palette after the application of the list of delta files, and then write out the differences in the new delta file. The function returns 1 if a file was successfully written, 0 if successful but no file written (no differences were found), and -1 for an error (invalid changes found for a delta file).
• bool applyDelta( string paletteName, string delta )()
  • Apply delta to an existing palette.
• string importDescription( string palette, string fileName )()
  • Import a description from an xdsc file and insert into a palette. The description is placed into the palette's namespace. Any palette expressions used by the description will be restored. If there are any name conflicts, then the value of the expression for the new description will be placed into the palette expression, with the old value placed into the comment of the expression.
• bool exportDescription( string palette, string description, string fileName, bool guides = false )()
  • Export a description from a palette, including any palette expressions it might use, into an xdsc description file. The guides flag is reserved and is currently not used.
• string importFXModule( string palette, string description, string fileName )()
  • Import an FX module from an xgfx file and insert into the active primitive of the given description.
• bool exportFXModule( string palette, string description, string name, string fileName )()
  • Export the named FX module from the active primitive of the given description.

Event Callbacks

• registerCallback( string name, string function )()
  • Register a function to be called if the named XGen event occurs. Event types are: PrePaletteCreate, PostPaletteCreate, PreDescriptionCreate, PostDescriptionCreate, and CurrentDescriptionSet.
• deregisterCallback( string name, string function )()
  • Deregister a function from being called if the named XGen event occurs.

Messages

• setMessageLevel( string type, int level )()
  • Set the verbosity level for a given type of message. The type can be one of debug, warning, stats, or quitOnError. For the first three types, you can set a level of zero through five, where five is the most verbose. For quitOnError, you can set a boolean, with 1 being on and 0 being off.
• int getMessageLevel( string type )()
  • Get the verbosity level for the given type of message. The type can be one of debug, warning, stats, or quitOnError. For the first three types, the level returned will be zero through five, where five is the most verbose. For quitOnError, the level returned will be 1 for on and 0 for off.

General

• string version()
  • Get the version number for the version of XGen that is currently running.
• string rootDir()
  • The root directory for XGen.
• string iconDir()
  • The directory holding XGen icons.
• string globalRepo()
  • Location of the global repository.
• string localRepo()
  • Location of the local repository.
• string userRepo()
  • Location of the user repository.
• string promoteFunc()
  • The current value for the element promotion function.
• string objNameSpace( string name )()
  • Get the namespace for a given object.
• string stripNameSpace( string name )()
  • Strip off the namespace from an object and return only the name of the object.
• string prepForAttribute( string value )()
  • Given a string with embedded newlines and tab characters, this function will replace each with an encoded version of these characters. This allows the string to be stored in a single line, which is essential for storage in an XGen file or editing in the Description Editor. This function, when used in conjunction with prepForEditor, allows for round-trip string formatting and attribute storing.
• string prepForEditor( string value )()
  • Given a string with encoded tabs and newline characters, this function will convert the string to restore those characters so the string can be used within a multi-line text editor. This allows the encoded string to be restored to its previous format for the editor. This function, when used in conjunction with prepForAttribute, allows for round-trip string formatting and attribute storing.

Maya Extension API

All of the Base API methods are available through Maya, but the following methods extend the API further. These are not provided as part of the base API as they, in general, do not make sense in that context. For example, a method that accepts a “guide name” and returns a “patch name” in Maya doesn’t apply to standard XGen, as guides do not have names and patches are simply named after their geometry. That said, several of the Base API methods are overridden in Maya, and therefore you should always reference the API through the Maya API if you are in Maya so that the correct layer is referenced.

• string guidePatch( string guide )()
  • Get the patch for the guide with the given name.
• string guideDescription( string guide )()
  • Get the description for the guide with the given name.
• string guideIndex( string guide )()
  • Get the index of a guide within its description.
• string[] descriptionGuides( string descr )()
  • Get the guides for the given description.
• string[] descriptionPatches( string descr )()
  • Get the patches for the given description.
• string[] palettePatches( string palette )()
  • Get a list of all patches contained within the given palette.
• string[] geometryPatches( string geometry )()
  • Get the patches bound to the given piece of geometry.
• string[] geometriesPatches( string geomList[] )()
  • Get the patches bound to any of the geometries in the list. This function is more efficient than calling geometryPatches for a number of geometries in sequence.
• string geometryDescriptionPatch( string geometry, string desc )()
  • Given a piece of geometry and a description, return the single bound patch.
• string[] geometryFacePatches( string geometry, string faceId )()
  • Given a piece of geometry and a faceId, return all the patches related to that face.
• modifyFaceBinding( string palette, string description, string mode="Append" )()
  • Modify the face bindings of the current description. When in append mode, the selected faces will be added to the patch that is bound to the associated geometry. If no patch exists for the geometry, a new patch will be created. In replace mode, the selected faces will replace those in the patch for the associated geometry. And finally, in remove mode, the faces are removed from the patch for the associated geometry if a patch exists. If the resulting patch has no bound faces, then the patch is removed.
• fixPatchNames( string palette )()
  • Update the names for all of the patches in a palette. If a description is renamed, or the geometry that a description is bound to is renamed, then the patches must have their names updated also.
• string nodeClass( string node )()
  • Given a Maya node, return the general class of the XGen object. If the node is not an XGen object, then return None.
• bool renderable( string node )()
  • Return true if the object is one that can be rendered. This can be used to avoid things like assigning shaders to non-renderable objects.
• string[] findSelectedPatches()
  • Return all XGen patches that relate to the current selection list. Guides, patches, descriptions, geometry, and so forth will all be resolved into the related patches.
• string[] bakedGroomManagerBake( string pal, string desc )()
  • Bake the current groom up to the location of the baked groom manager. This will result in an XPD file for the bound geometry of each description that contains the static groom. The description will be left, with the baked groom manager active.
• setExportAsDelta( bool value, string pal=None )()
  • Control whether or not a palette should export as a full palette or as a delta file. When the value passed in is set to true, a delta file will be written for the palette only when that palette has changed. If no palette is passed in, then all palettes in the scene will be set to the new value.

Maya MPx API

The following are MPxCommands that are part of the XGen API and only available through Maya.

• bool xgmGuideGeom -guide string [-numVertices] [-basePoint | -controlPoints] [-lockBasePt]()
  • Basic queries about a guide.
• bool xgmPatchInfo -patch string [-description | -geometry | -faceIds | -rename string]()
  • Basic patch queries.
• bool xgmBakeGuideVertices [-resetPivots]
  • Bake edits into the guide, so that all tweaks are removed