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 xgenm as xg

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

import xgenm.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 获得。

创建和删除

对象访问

属性访问

FX 模块

消隐

绑定信息

文件 IO

事件回调

消息

一般功能

  • 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]
    • 烘焙编辑到导向，因此移除所有调整
父主题： XGen 技术文档