Python API

概述

XGen 提供了 Python API，可以从 Python 壳访问内部 XGen 数据。可以在 Maya 内部或外部使用该 API。此 API 在 Maya 进行扩展，以允许适用于 Maya 但是不适用于其他位置的操作（例如，接受导向的“名称”以获得其面片）。与 XGen 的所有交互应该通过此 API 或 UI 实现。不保证通过 XGen 中存在的 MPxCommand 或 MEL 函数的任何访问。

在下面以伪语法的形式列出了这些方法，以表示返回类型和预期参数类型。调用这些方法的方式与 Python 中的普通操作相同。您可以按照顺序传递这些参数，或者使用这些名称并按照需要重新排序。

导入 API

API 分为两个部分：基本和 Maya。虽然有单独的 UI 组件，但 API 本质上是由基本 C++ 代码、构成基础 API 的 Python 层以及另一个 Python 层（该层提供必要 Maya 附加部分以及组成 Maya API 的额外 API 函数）。务必为该任务提供正确的 API，否则可能会得到意外结果。最佳方法是让 XGen 处理该决定：

import xgen as xg

这会引入 xgen 模块，该模块可检测 Maya，并根据需要提供 API 的 Maya 层。如果在 Maya 中和 Maya 外运行脚本，并从 API 的仅限 Maya 部分调用方法，您应该将这些方法放在一个条件块中。安全的处理方式是使用 XGen 的 Maya 检测：

import xgen.xgGlobal as xgg 

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

这会引入 XGen 全局模块，它可以检测 Maya。在放置该模块后，可以使用其 xgg.Maya 变量，以确定是否处于 Maya 中，并在这些条件句中保护您的 Maya 代码。

基础 API

无论在 Maya 的内部还是外部，都可以使用以下方法。它们直接在基本 XGen 数据上操作。如果需要到 XGen 的更快链接，许多还可通过 libXgAPI.so 库作为 C++ API 获得。

创建和删除

• string createDescription( string palette, string description, string primitive, string generator, string renderer, string method )()
  • 创建新的描述，然后将其放置在命名的选项板中。如果该选项板不存在，则也会创建它。
• bool deletePalette( string palette )()
  • 删除命名的选项板。这将删除其所有描述、面片、对象、fx 模块、导向等等。
• bool deleteDescription( string palette, string description )()
  • 删除命名的描述。这将删除其所有面片、对象、fx 模块、导向等等。

对象访问

• string[] palettes()
  • 列出场景中当前的选项板。
• string[] descriptions( string palette="" )()
  • 获取给定选项板的描述列表；或者，如果没有给定选项板名称，返回场景中的所有描述。
• string palette( string description )()
  • 获取给定描述的选项板。要执行此操作，将搜索每个选项板的描述列表，此操作假定所有描述具有唯一名称。
• string getActive( string palette, string description, string type )()
  • 从描述获取给定类型的活动子类型。返回值是子类型（例如，SplinePrimitive、CardPrimitive）。
• bool setActive( string palette, string description, string subtype, bool previewer=False )()
  • 设置描述的给定类型的活动子类型。给定子类型应完全命名（例如，CardPrimitive、FileRenderer）。
• string[] objects( string palette, string description, bool activeOnly=False )()
  • 获得描述的所有对象（例如，SpherePrimitive、GuideRenderer）的列表。
• bool initInterpolation( string palette, string description, string fileName="" )()
  • 为给定描述的活动基本体初始化插值。每次将导向移动到新位置、添加导向或者移除导向后，就需要执行此操作。

属性访问

• bool attrExists( string attrName, string palette, string description="", string object="" )()
  • 查询 xgen 对象上是否存在某一属性。
• string getAttr( string attrName,string palette, string description="", string object="" )()
  • 获取 xgen 对象上的某一属性值。
• bool setAttr( string attrName, string value, string palette, string description="", string object ="")()
  • 设置 xgen 对象上的某一属性值。
• string[] attrs( string palette, string description="", string object="" )()
  • 返回给定节点的属性列表。这不包括自定义属性。
• void addCustomAttr( string attrName, string palette, string description="", string object ="")()
  • 添加自定义属性。该属性应该使用此模板方案命名：custom_<type>_<name> 或 custom_<type>_<name>[#]。如果使用 [#] 扩展名指定一个阵列，则将为每个数组的元素添加一个属性。常见的用法是将属性添加到选项板或 RenderMan 渲染器，但可以指定任何对象。
• void remCustomAttr( string attrName, string palette, string description="", string object="" )()
  • 移除自定义属性。该属性应该使用此模板方案命名：custom_<type>_<name> 或 custom_<type>_<name>[#]。如果使用 [#] 扩展名指定一个阵列，则将删除该阵列的所有属性。
• string[] customAttrs( string palette, string description="", string object="" )()
  • 返回给定节点的自定义属性列表。
• string[] allAttrs( string palette, string description="", string object="" )()
  • 返回给定节点的属性完整列表。

FX 模块

• string[] fxModules( string palette, string description)()
  • 获得给定选项板和描述的 fx 模块列表。会按照执行顺序返回当前活动基本体的模块。
• string fxModuleType( string palette, string description, string name )()
  • 获取给定 fx 模块的类型。搜索该模块的活动基本体。
• string addFXModule( string palette, string description, string type, string name="" )()
  • 将新的 fx 模块添加到给定描述的活动基本体的 fx 链的末端。如果已成功添加该模块，则将返回其名称。如果失败，则返回空字符串。
• bool removeFXModule( string palette, string description, string name )()
  • 从给定描述的活动基本体删除命名的 fx 模块。如果成功，则返回值为“真”，如果失败，返回值为“假”。
• bool moveFXModule( string palette, string description, string name, int dir )()
  • 移动 FX 模块。将使用该模块名称找到给定描述的活动基本体中的模块。一旦找到，该模块将上移或下移，具体取决于“方向”的值。负值表示“向上”，正值表示“向下”。

消隐

• string[] culledPrimPatches( string palette, string description )()
  • 如果给定选项板和描述，则返回具有已消隐的基本体的面片的名称。
• int[] culledPrimFaces( string palette, string description, string patchName )()
  • 如果给定选项板、描述和面片名称，则返回具有已消隐的基本体的面片上的面。
• set(int) culledPrims( string palette, string description, string patchName, int faceId )()
  • 指定一个选项板、描述、面片名称和面 ID，将返回该面上的消隐的基本体 ID。

绑定信息

• string[] boundGeometry( string palette, string description )()
  • 指定选项板和描述，返回所有绑定几何体块的名称。在 XGen 中，这些同时也是面片名称。
• int[] boundFaces( string palette, string description, string patchName )()
  • 指定选项板、描述和面片名称，返回绑定到该面片的描述的面的列表。

文件 IO

• string importPalette( string palette, string deltas[], string nameSpace="" )()
  • 应用指定的增量文件后，从一个 xgen 文件导入选项板。可以选择将选项板放入给定名称空间。在 Maya 中，有一个可选的第四个参数，称为 wrapPatches，其默认值为“真”(True)。将此值设置为“假”(False)，则允许您引入一个选项板，而不加载其面片或导向。执行此操作，您可以引入不包含几何体的选项板，可以将其用作引用，传输到另一个元素等等。
• bool exportPalette( string palette, string fileName )()
  • 将给定选项板导出到磁盘上的 .xgen 文件。
• int createDelta( string palette, string newDelta )()
  • 将 Maya 中加载的当前选项板与增量文件列表应用后的基础选项板比较，将差异写入新的增量文件中。如果一个文件编写成功，则函数返回 1，如果成功但是没有编写任何文件（没有发现差异）则返回 0，如果出现错误则返回 -1（发现增量文件的无效更改）。
• bool applyDelta( string paletteName, string delta )()
  • 为现有选项板应用增量。
• string importDescription( string palette, string fileName )()
  • 从 xdsc 文件导入描述并插入到选项板中。将此描述放入选项板的名称空间中。将还原描述使用的任意选项板的表达式。如果存在名称冲突，则将新描述的表达式的值放入选项板表达式中，而将旧值放入该表达式的注释。
• bool exportDescription( string palette, string description, string fileName, bool guides = false )()
  • 从选项板将描述（包括可能使用的任何选项板的表达式）导出到 xdsc 描述文件。导向标志将被保留，且当前未使用。
• string importFXModule( string palette, string description, string fileName )()
  • 从 xgfx 文件导入 FX 模块，并插入到给定描述的活动基本体。
• bool exportFXModule( string palette, string description, string name, string fileName )()
  • 从给定描述的活动基本体导出命名的 FX 模块。

事件回调

• registerCallback( string name, string function )()
  • 注册发生命名的 XGen 事件时调用的函数。事件类型：PrePaletteCreate、PostPaletteCreate、PreDescriptionCreate、PostDescriptionCreate 和 CurrentDescriptionSet。
• deregisterCallback( string name, string function )()
  • 注销发生命名 XGen 事件时调用的函数。

消息

• setMessageLevel( string type, int level )()
  • 设置给定类型消息的详细级别。类型可以是调试、警告、统计信息或 quitOnError。对于前三种类型，可以将级别设置为 0 到 5，其中 5 最详细。对于 quitOnError，可以设置一个布尔值，其中 1 为打开，0 为关闭。
• int getMessageLevel( string type )()
  • 获取给定类型的消息的详细级别。类型可以是调试、警告、统计信息或 quitOnError。对于前三种类型，返回的级别为 0 到 5，其中 5 最详细。对于 quitOnError，返回的级别分别是 1 和 0，分别表示打开和关闭。

一般功能

• string version()
  • 获取当前运行的 XGen 版本的版本号。
• string rootDir()
  • XGen 根目录。
• string iconDir()
  • 包含 XGen 图标的目录。
• string globalRepo()
  • 全局存储库的位置。
• string localRepo()
  • 本地存储库的位置。
• string userRepo()
  • 用户存储库的位置。
• string promoteFunc()
  • 元素升级函数的当前值。
• string objNameSpace( string name )()
  • 获取给定对象的名称空间。
• string stripNameSpace( string name )()
  • 从一个对象去除名称空间，仅返回该对象的名称。
• string prepForAttribute( string value )()
  • 如果给定的字符串包含嵌入换行符和制表符，此函数将使用这些字符的编码版本逐一替换。这样就可以将字符串存储在一行中，要存储在 XGen 文件中或者在描述编辑器中进行编辑，必须符合此要求。此函数如果结合使用 prepForEditor，则允许使用往返字符串格式和属性存储。
• string prepForEditor( string value )()
  • 如果给定的字符串具有编码制表符和换行符，此函数将转化字符串，以还原这些字符，这样字符串可以用于多行文本编辑器。这允许将编码字符串恢复为针对该编辑器的原始格式。此函数如果结合使用 prepForAttribute，则允许使用往返字符串格式和属性存储。

Maya 扩展 API

Maya 提供了所有的基础 API 方法，但以下方法进一步扩展了 API。这些 API 不作为基础 API 的一部分提供的原因通常是在该上下文中没有意义。例如，如果一个方法在 Maya 中接受“导向名称”，并返回“面片名称”，则不适用于标准 XGen，因为其中导向没有名称，而面片只是以其几何体命名。也就是说，许多基础 API 方法在 Maya 中被覆盖，因此如果在 Maya 中，您应该始终通过 Maya API 引用该 API，以确保引用正确的层。

• string guidePatch( string guide )()
  • 获取使用给定名称的导向的面片。
• string guideDescription( string guide )()
  • 获取使用给定名称的导向的描述。
• string guideIndex( string guide )()
  • 获取描述中导向的索引。
• string[] descriptionGuides( string descr )()
  • 获取给定描述的导向。
• string[] descriptionPatches( string descr )()
  • 获取给定描述的面片。
• string[] palettePatches( string palette )()
  • 获取给定选项板中包含的所有面片的列表。
• string[] geometryPatches( string geometry )()
  • 获取绑定到给定的一块几何体的面片。
• string[] geometriesPatches( string geomList[] )()
  • 获取绑定到列表中任何几何体的面片。如果按顺序使用一系列几何体，此函数比调用 geometryPatches 有效。
• string geometryDescriptionPatch( string geometry, string desc )()
  • 如果给定一块几何体和描述，返回单一绑定面片。
• string[] geometryFacePatches( string geometry, string faceId )()
  • 给定一块几何体和面 ID，返回与该面相关的所有面片。
• modifyFaceBinding( string palette, string description, string mode="Append" )()
  • 修改当前描述的面绑定。在“附加”模式下，将选定的面添加到绑定到关联几何体的面片。如果该几何体没有任何面片，则将创建一个新面片。在“替换”模式下，选定的面将替换这些关联几何体的面片中的面。最后，在“移除”模式中，如果存在面片，则会从关联几何体的面片中移除这些面。如果生成的面片没有绑定面，则面片将被删除。
• fixPatchNames( string palette )()
  • 更新选项板中所有面片的名称。如果描述重命名，或者描述绑定到的几何体重命名，则必须同时更新这些面片的名称。
• string nodeClass( string node )()
  • 如果给定 Maya 节点，返回 XGen 对象的常规类。如果节点不是 XGen 对象，则返回“无”(None)。
• bool renderable( string node )()
  • 如果对象可以渲染则返回真。这可以用于避免将着色器分配给不可渲染的对象这类问题。
• string[] findSelectedPatches()
  • 返回与当前选择列表相关的所有 XGen 面片。导向、面片、描述、几何体等都将解析为相关的面片。
• string[] bakedGroomManagerBake( string pal, string desc )()
  • 烘焙当前修饰，直到烘焙修饰管理器的位置。这会为每个包含静态修饰的描述的边界几何体生成一个 XPD 文件。将留下该描述，而烘焙修饰管理器处于活动状态。
• setExportAsDelta( bool value, string pal=None )()
  • 控制是否将选项板导出为完整的选项板或增量文件。如果传入的值设为真，则只有当选项板更改时才会为选项板编写增量文件。如果未传入任何选项板，则场景中的所有选项板将设为新值。

Maya MPx API

以下是 MPxCommand，它们是 XGen API 的一部分，只能通过 Maya 获得。

• bool xgmGuideGeom -guide string [-numVertices] [-basePoint | -controlPoints] [-lockBasePt]()
  • 导向的基本查询。
• bool xgmPatchInfo -patch string [-description | -geometry | -faceIds | -rename string]()
  • 基本面片查询。
• bool xgmBakeGuideVertices [-resetPivots]
  • 烘焙编辑到导向，因此移除所有调整