资产库Python API:

MG-资产库提供的python的应用程序接口。你可以用这些python函数及类，通过自己编写脚本来新建，管理及使用资产库。

一个比较大的用途是用它来批量加入资产项，及自动生成ma档等。

前提条件:

当前运行的Maya有安装MGTools Pro3或以上版本。

资产库Python API模块:

Py文件路径是您的MGTools folder/invoke/MG_PyUtil/MG_AssetLibAPI.py.

在MGTools已安装的情况下，直接用下面代码来导入模块：

import MG_PyUtil.MG_AssetLibAPI as assetAPI

在这个py源文件里，每个函数或方法都有详细的注释说明。

下面对参数的说明开头，会有一个类别像 <type>的文字，这个标注了参数的类型。

一些快速链接:

辅助性函数

MGAssetProj类

MGAssetCategory类

MGAssetRecord类

示例代码

辅助性函数:

def MGAssetLibUtil_isLibraryWindowOpen ( )

说明： 测试看MG资产库工具是否被打开的

返回值： 如果打开则为True, 否则为False.

def MGAssetLibUtil_openProjectIfLibraryToolOpen ( projFilePath )

说明： 如果MG资产库工具正打开，则在工具里打开该库工程。如果工程正被打开则会重新打开。

参数： projFilePath: <str> 代表一个资产库文件的完整路径。

返回值： None

def MGAssetLibUtil_openCategoryIfLibraryToolOpen ( projectName, categoryName )

说明：如果MG资产库工具正打开，则在工具里打开该库工程及该类别。如果工程/类别正被打开则会重新打开。

参数： projName: <str> 一个已存在的库工程名称。

categoryName: <str> 一个已存在的库工程类别。

返回值： None

def MGAssetLibUtil_warning ( warnMessage )

说明： 辅助性函数，用来在Maya里打印有特定前缀的警告。

参数： warnMessage: <str> 警告内容。

返回值： None

def MGAssetLibUtil_getLocalRoot ( )

说明： 获取MG-资产库的本地根目录。

返回值： str

def MGAssetLibUtil_getLocalProjectDir ( projectName )

说明： 获取MG-资产库的本地库工程目录。

参数： projectName: <str> 要获取的库工程的名称。

返回值： str

def MGAssetLibUtil_getLocalProjectFilePath ( projectName )

说明： 获取MG-资产库的本地库工程文件的完整路径。即是一个.assetproj文件路径。

参数： projectName: <str> 要获取的库工程的名称。

返回值： str

def MGAssetLibUtil_getLocalCategoryFilePath ( projectName, categoryName )

说明： 获取MG-资产库的本地库工程下特定类别的完整路径。即是一个.asset文件路径。

参数： projectName: <str> 要获取的库工程的名称。

categoryName: <str> 要获取的类别的名称。

返回值： str

def MGAssetLibUtil_validName ( name )

说明： 用Maya节点的命名限制规则来验证一个字符窜并使字符窜符合规则:

首字母必须以'_'或英文字母开头， 其它字母可以是英文字母，数字或'_'。

如果有遇到字母不符合上面规则的，则转换为'_'。

参数： name: <str> 要验证的字符窜

返回值： str, 将是输入字符窜的合法版本。

def MGAssetLibUtil_compareTwoFileDate ( file1, file2 )

说明： 比较俩文件的修改日期。

参数： file1: <str> 文件1路径

file2: <str> 文件2路径

返回值： int.

如果俩文件都不存在，则返回0， 如果file1存在而file2不存在，则返回1，如果file1不存在而file2存在，则返回-1；

都存在的情况下，如果file1比file2旧，则返回-1，如果两者一样，则返回0， 如果file1比file2新，则返回1；

def MGAssetLibUtil_searchFilesFromDirectory ( searchDir, patternStr, searchDepthLimit, currentSearchDepth )

说明： 这是一个被下面两个函数调用的doit函数。 搜索一个目录下符号一定规则的文件。

参数： searchDir: <str> 这是要搜索的路径。

patternStr: <str> 这个样式字符窜必须是以"*."开头，如果不是以 "*." 开头的，则自动会加上 "*." 。

searchDepthLimit: <int> 是路径搜索的深度，如果不想搜索子目录，则直接将其设为1。设为0或负数则视为无限制深度。

currentSearchDepth: <int> 当前搜索深度，辅助性参数，对您说要输入1。

返回值： list of str , 如果没找到任何匹配，则返回空list.

def MGAssetLibUtil_searchPreviewImagesFromDirectory ( searchDir, imageExtensions, searchDepthLimit )

说明： 在特定目录下搜索有特定格式的文件，如图片。

参数： searchDir: <str> 这是要搜索的路径。

imageExtensions: <list / str> 这个扩展名列表的每一个元素必须是以"*."开头，如果不是以 "*." 开头的，则自动会加上 "*." 。

searchDepthLimit: <int> 是路径搜索的深度，如果不想搜索子目录，则直接将其设为1。设为0或负数则视为无限制深度。

返回值： list of str , 如果没找到任何匹配，则返回空list.

def MGAssetLibUtil_searchMayaFileFromDirectory (searchDir, searchMA, searchMB,searchDepthLimit )

说明： 在特定目录下搜索MB/MA文件。

参数： searchDir: <str> 这是要搜索的路径。

searchMA: <bool> 表示要搜索MA文件。

searchMB: <bool> 表示要搜索MB文件。如果searchMA和searchMB都是False，则直接返回空列表。

searchDepthLimit: <int>是路径搜索的深度，如果不想搜索子目录，则直接将其设为1。设为0或负数则视为无限制深度。

返回值： list of str , 如果没找到任何匹配，则返回空list.

def MGAssetLibUtil_getBasename ( filepath )

说明： 从文件路径字符窜中获取文件名。（不带扩展名）

参数： filepath: <str> 一个文件完整路径，注意如果你输入的是一个目录名而不是一个文件路径，则这个函数返回空字符窜。

返回值： str

def MGAssetLibUtil_makeMayaAsciiFile ( overrideIfExists, MAFile, referenceFiles, namespaceList=[], deferList=[] )

说明： 基于您输入的信息，生成一个MA文件。

参数： overrideIfExists: <bool> 决定当目标MA文件已存在时是否覆盖。

MAFile: <str> 目标MA档的完整路径。

referenceFiles: <list of strings> 将来在MA档里要Reference的maya文件完整路径的列表。

namespaceList: <list of strings> Namespace列表。 如果它没有提供到足够多的元素或者干脆为空列表，则会自动从maya文件路径中获取不带扩展名的文件名作为namespace.

deferList: <list of int> Reference有没有被推迟加载的列表。取值为0或1。 如果没有提供到足够多的元素或者干脆为空列表， 则默认取值为0，即不推迟加载。

返回值： bool, 成功则True, 失败为False.

类:

这个库API的对象模式很简单。包括三个级别的类：MGAssetProj > MGAssetCategory > MGAssetRecord

MGAssetProj 对象可持有多个 MGAssetCategory 对象, MGAssetCategory 对象可持有多个 MGAssetRecord 对象.

MGAssetProj类:

MGAssetProj.__init__ ( projectName='', projectAnnotation='',globalPath='',statePresets=[] )

说明： 初始化MGAssetProj 对象.

当初始化时，如果projectName参数所代表的库工程在您本地已存在，则它会忽略所有其它参数，直接以这个已存在的库工程文件初始化。

参数： projectName: <str> 库工程名称。 会验证这个名称是否合法，而使用它的合法版本。

如果这个参数为空字符窜，则您必须在稍后立即使用initFromProjctFile() 来使这个对象合法，否则该MGAssetProj 对象是不合法的。

projectAnnotation: <str> 库工程描述文字。

globalPath: <str> 一个用来指定库工程全局根目录的路径。

statePresets: <list of str> 是库工程的状态预置列表，它是一个数组或就一个字符窜，这个数组的每个元素由下面格式的字符组成( 用空格分开 )：

"状态名称 状态颜色R 状态颜色G 状态颜色B"

状态颜色的RGB数值是在0-1范围内的小数。比如: "Approved 0.2 0.6 0.2"

MGAssetProj.initExistCategories ( )

说明： 基于本地库根目录下已存在的资产库工程来自动生成已存在的类别的MGAssetCategory对象。

返回值： int. 返回自动生成的MGAssetCategory对象个数。

MGAssetProj.initFromProjectFile ( projectFilePath )

说明： 基于本地库根目录下已存在的资产库工程来初始化这个MGAssetProj 对象.

参数： projectFilePath: <str> 指向.assetproj文件的完整路径。

返回值： bool. 如果成功则返回True，否则为False。

MGAssetProj.isValid ( )

说明： 测试该MGAssetProj是否合法。

返回值： bool

MGAssetProj.doesProjectExist ( )

说明： 测试该库工程是否已存在。

返回值： bool

MGAssetProj.getName ( )

说明： 获取该库工程的名称。

返回值： str

MGAssetProj.getProjectDir ( )

说明： 获取该库工程的目录。

返回值： str

MGAssetProj.getProjectFilePath ( )

说明： 获取该库工程的 .assetproj 文件的完整路径。

返回值： str

MGAssetProj.addStates ( newStatePresets )

说明： 向该库工程添加状态预置。

参数： newStatePresets: <str / list of str> 是库工程的状态预置列表，它是一个数组或就一个字符窜，这个数组的每个元素由下面格式的字符组成( 用空格分开 )：

"状态名称 状态颜色R 状态颜色G 状态颜色B"

状态颜色的RGB数值是在0-1范围内的小数。比如: "Approved 0.2 0.6 0.2"

返回值： bool

MGAssetProj.getStates ( )

说明： 获取库工程的所有状态预置。

返回值： list

MGAssetProj.addCategory ( categoryName )

说明：向库工程添加一个类别。

参数： categoryName: <str> 类别名称，不可以是空字符窜。

返回值： None / MGAssetCategory. 如果成功，则返回创建的MGAssetCategory对象，否则返回None。

MGAssetProj.getCategoryObjects ( )

说明： 获取当前库工程对象持有的所有MGAssetCategory对象。

返回值： list of MGAssetCategory. 如果没有类别对象，则返回空列表。

MGAssetProj.getCategoryNames ( )

说明： 获取当前库工程对象的所有类别名称。

返回值： list of str. 如果没有类别对象，则返回空列表。

MGAssetProj.writeProjectToDisk ( )

说明： 将该对象持有的数据实际写入磁盘。将对本地根目录下建立库工程名称文件夹，并在其下创建库工程名称.assetproj。

如果目标文件已存在则覆盖。 如果资产库工具正打开， 则会在工具界面上打开这个库工程。

如果该MGAssetProj对象是非法的则引发异常。

返回值： bool. 如果成功则返回True, 失败则引发异常。

MGAssetProj.getCategoryObjectByName ( categoryName )

说明： 搜索特定类别名称的MGAssetCategory对象。

参数： categoryName: <str> 类别名称。

返回值： MGAssetCategory / None. 如果找到则返回MGAssetCategory对象，没有则返回None。

MGAssetProj.writeCategoryToDisk ( categoryObject )

说明： 将该类别对象的数据写入磁盘 (*.asset 文件). 如果旧的类别.asset文件已存在则会覆盖。

如果资产库工具正打开， 且正打开这个库工程，则会在工具界面上打开这个类别。

如果该MGAssetProj对象是非法的则引发异常。

参数： categoryObject: <MGAssetCategory> 应该传入一个合法的MGAssetCategory对象.

返回值： bool. 成功则返回True，否则返回False。

MGAssetProj.writeAllCategoriesToDisk ( )

说明： 将所有的类别对象的数据写入磁盘 (*.asset 文件). 如果旧的类别.asset文件已存在则会覆盖。

如果资产库工具正打开，且正打开这个库工程， 则会在工具界面上打开这些类别。

如果该MGAssetProj对象是非法的则引发异常。

返回值： bool. 成功则返回True，否则返回False。

MGAssetProj.openProjectInMGAssetLibrary ( )

说明： 如果资产库工具正打开， 则在工具界面上打开这个库工程。

返回值： bool. 成功则返回True，否则返回False。

MGAssetProj.openCategoryInMGAssetLibrary ( categoryName )

说明： 如果资产库工具正打开，且正打开这个库工程， 则在工具界面上打开这个类别。

参数： categoryName: <MGAssetCategory / str> 这个参数可以是一个MGAssetCategory对象或者是一个类别名称。

返回值： bool。 成功则返回True，否则返回False。

MGAssetProj.__str__ ( )

说明： 用来打印这个对象的函数。

返回值： str.

MGAssetProj.getLastError ( )

说明：取得上一次发生错误的文本描述。

返回值： str. 如果不曾发生错误，则返回空字符窜。

The Classes MGAssetCategory:

MGAssetCategory.__init__ ( projectObject, categoryName = '' )

说明： 初始化MGAssetCategory对象。不过一般不要直接调这个初始化函数，

而是使用 MGAssetProj.addCategory() 这个方法来创建这个MGAssetCategory对象。

或者您可以用MGAssetCategory(projectObject)来创建一个非法的对象，然后紧接着用initFromCategoryFile(categoryFile) 来使它合法。

参数： projectObject: <MGAssetProj> 这个参数应该是一个合法的MGAssetProj的对象.

categoryName: <str> 类别名称，会使用其字符合法化的版本。如myC*()&^^2g变成myC______2g。

如果这个参数是空字符窜，则你过后要使用initFromCategoryFile(categoryFile) 来用既有的类别文件来初始化它否则这个对象是非法的。

MGAssetCategory.initFromCategoryFile ( categoryFile )

说明： 使用一个已存在的类别数据文件来初始化MGAssetCategory对象。 如果对象被成功初始化则返回True, 否则为False.

参数： categoryFile: <str> 必须是一个 '*.asset' 文件的完整路径。

返回值： bool

MGAssetCategory.getName ( )

说明： 获取类别名称。

返回值： str

MGAssetCategory.isValid ( )

说明： 测试这个MGAssetCategory对象是否合法。

返回值： bool

MGAssetCategory.getCategoryFilePath ( )

说明：获取这个类别文件的完整路径。 (即 '*.asset' 文件的完整路径。)

返回值： str.

MGAssetCategory.doesCategoryFileExist ( )

说明：测试这个类别是否已经存在。

返回值： bool

MGAssetCategory.clearAssetRecords ( )

说明： 将这个类别里的资产项记录清空。

返回值： bool. 如果该类别对象是非法的则返回False， 否则返回True。

MGAssetCategory.doesAssetRecordExist ( mayaFilePath )

说明： 测试某个资产项是否在该类别里已存在，以maya路径为准来查重复性。

参数： mayaFilePath: <str> 一个maya的完整路径。

返回值： bool.

MGAssetCategory.addAssetRecords ( mayaFiles,namespaces=[],states=[],previewImages=[],notes=[], sizeDatas = [], dateDatas = [], versionDatas = [] )

说明： 创建MGAssetRecord对象并把它加入到该类别里。

如果失败，则返回空列表，否则返回一个MGAssetRecord列表。

参数： mayaFiles: <str / list of str> Maya文件的完整路径列表。

namespaces: <str / list of str> 命名空间列表。如果元素里含非法字符，会使字符合法化。

states: <str / list of str> 状态列表，每一元素只是一个状态名称，这里不要添加颜色信息。

previewImages: <str / list of str> 每个元素是每个资产的预览图，单个元素可以包含多个预览图文件路径，不同文件路径间用;号分隔。

notes: <str / list of str> 每个元素是每个资产项的注释。

sizeDatas: <str / list of str> 每个元素是每个资产项的大小字符窜，以KB为单位，比如 "1,560KB"。

如果这个参数不提供，则会自动检测生成。

dateDatas: <str / list of str> 每个元素是每个资产项的修改日期字符窜，格式 是 'DD/MM/YYYY hh:mm:ss'. 比如4/10/2014 21:55:4

如果这个参数不提供，则会自动检测生成。

versionDatas: <str / list of str> 每个元素是每个资产项的maya版本字符窜.

如果这个参数不提供，则会自动检测生成。

返回值： MGAssetRecord对象组成的列表.

MGAssetCategory.deleteAssetRecords ( mayaFiles )

说明： 根据maya场景路径来搜索并删除资产项。

参数： mayaFiles: <str / list of str> maya场景路径列表。

返回值： int. 返回实际删除的资产项的个数。

MGAssetCategory.getDataString ( )

说明： 获取该类别的数据，以字符窜形式。这也是将该类别写入磁盘时的写入内容。

当您print这个类别对象时，实际上也是print这个函数返回的数值。

返回值： str

MGAssetCategory.writeToDisk ( )

说明： 将这个类别以*.asset文件写入磁盘。

返回值： bool, 成功则返回True，否则返回False。

MGAssetCategory.__str__ ( )

说明： 用来打印这个对象的函数。

返回值： str.

The Classes MGAssetRecord:

MGAssetRecord.__init__ ( categoryObject, assetPath, assetName='', assetStateStr='', previewImageStr='', noteStr='', sizeStr='', dateStr='', versionStr = '' )

说明： 初始一个MGAssetRecord对象。不过我们一般不用直接使用这个函数，

而是使用MGAssetCategoryObj.addAssetRecords()方法来创建这个类的实例。

参数： categoryObject: <MGAssetCategory> 这个应该是一个合法的MGAssetCategory对象。

assetPath: <str> Maya文件的完整路径.

assetName: <str> Maya文件的命名空间，如果含非法字符会先合法化。如果这参数是空字符窜则会使用maya文件的文件名（去除扩展名后）。

assetStateStr: <str> 状态名称，这里只使用状态名称，不要加上颜色信息。

previewImageStr: <str> 资产项的预览图，可以包含多个预览图文件路径，不同文件路径间用;号分隔。

noteStr: <str> 资产项的注释。

sizeStr: <str> 资产项的大小，以KB为单位，如1,150KB. 如果这个参数不提供，则会自动检测生成。

dateStr: <str> 资产项的修改日期字符窜，格式 是 'DD/MM/YYYY hh:mm:ss'. 比如4/10/2014 21:55:4。如果这个参数不提供，则会自动检测生成。

versionStr: <str> 资产项的maya版本字符窜如"2015"。如果这个参数不提供，则会自动检测生成。

MGAssetRecord.isValid ( )

说明： 测试这个MGAssetRecord对象是否合法。

返回值： bool

MGAssetRecord.getAssetPath ( )

说明： 获得该资产项的maya文件完整路径。

返回值： str. 如果该对象非法，则返回空字符窜。

MGAssetRecord.getDataString ( )

说明： 获取该类别的数据，以字符窜形式。

当您print这个资产项对象时，实际上也是print这个函数返回的数值。

返回值： str. 如果该对象非法，则返回空字符窜。

MGAssetRecord.__str__ ( )

说明： 用来打印这个对象的函数。

返回值： str. 如果该对象非法，则返回空字符窜。

示例代码:

>>

>>

>>

>>

>>

>>

>>

>>

>>

>>

>>

>>

import MG_PyUtil.MG_AssetLibAPI as assetAPI

projectObj = assetAPI.MGAssetProj ( "PyAPI", "Test project for MGAssetLibrary Python API.",

'D:/temp/Miguel/test/Lib_PyAPI',

[ 'Pending 1 0 0', 'Working 0 0 1', 'Approved 0 1 0' ] )

projectObj.writeProjectToDisk() #写入磁盘，在工具界面才会有反馈

print projectObj

charCate = projectObj.addCategory ( 'character' )

print 'The category object\'s validity:', charCate.isValid ()

print charCate #现在类别是空的

assetObjs = charCate.addAssetRecords ( 'K:/Data/Char/ciggarette.ma' )

print 'The asset object\'s validity:', assetObjs[0].isValid()

print charCate #现在类别里有东东了！

projectObj.getCategoryObjects()

charCate.writeToDisk() #写入磁盘