AssetLib Mel API

Asset Library MEL API:

The MEL API of MG-Asset Library. You could use these mel global procedures to create, manage and use the asset libraries in your own mel scripts.

The main usages are to use it to batch adding asset records, or making MA files.

Prerequisite:

Your Maya has MGTools Pro3 or later version installed.

The global procedures in API: ( Sample codes provided at the end )

global proc int MGAssetLib_initAPI ( );

Description: Initialize asset library MEL API. This ensure all the global procedures below are sourced and usable.

Return Value: 0 if error happened, 1 if success.

global proc int MGAssetLib_doesProjectExist ( string $projectName );

Description: Search an asset library project named $projectName in local side, which is the folder: My Document/Maya/MGTools_GlobalData/MG_AssetLib.

Note: If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

Return Value: 0 if found, else 1;

global proc string MGAssetLib_getLocalProjectFile ( string $projectName );

Description: Get the full path of the .assetproj file for the project named $projectName. Which probably is My Document/Maya/MGTools_GlobalData/MG_AssetLib/$projectName/$projectName.assetproj.

Note: If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

Return Value: The full path string of the .assetproj file, even if it does not exist.

global proc string MGAssetLib_createProject ( string $projectName,

string $ProjectAnnoatation,

string $globalPath,

string $statePresets [] );

Description: Create an asset library project at local side.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

$ProjectAnnoatation: The descriptive text for the project.

$globalPath: The global asset library folder.

$statePresets: An array contains states settings for the project.

Each element of the array is compose of: stateName stateColorR stateColorG stateColorB

The state color ranges within 0-1, it is decimal.

Return Value: Return the full path of the newly created .assetproj file if succeed, an empty string if failed.

global proc int MGAssetLib_doesCategoryExist ( string $projectName ,

string $category );

Description: Test if a category exists in an asset library project at local side.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

$category: The category you want to test the existence.

Return Value: Return 1 if the category exists, else 0.

global proc string MGAssetLib_getLocalCategoryFile ( string $projectName,

string $category );

Description: Get the full path of the .asset file within the the asset library project at local side.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

$category: The category you want to get its full path.

Return Value: Return the full path of the category's .asset file, no matter it exists or not.

global proc int MGAssetLib_addCategory ( string $projectName,

string $category );

Description: Add a category to the asset project. A .asset file is actually created in the project folder.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

$category: The category you want to add into the project.

Return Value: Return 1 if the category been added successfully, else 0.

global proc int MGAssetLib_clearCategory ( string $projectName,

string $category );

Description: Clear a category in the asset project. The .asset file is actually cleared in its content.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

$category: The category you want to clear the content.

Return Value: Return 1 if the category been cleared successfully, else 0.

global proc int MGAssetLib_addStates ( string $projectName,

string $stateList [] );

Description: Add state presets into the asset project.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

$stateList: The state array been added. Each element of the array is compose of: stateName stateColorR stateColorG stateColorB

The state color ranges within 0-1, it is decimal.

Return Value: Return 1 if the states been added successfully, else 0.

global proc string[] MGAssetLib_getProjectStates ( string $projectName );

Description: Get all the state presets of the asset project.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

Return Value: Return the state string array. Each element of the array is compose of: stateName stateColorR stateColorG stateColorB

The state color ranges within 0-1, it is decimal.

global proc string[] MGAssetLib_getProjectCategories ( string $projectName );

Description: Get all the categories of the asset project.

Parameters: $projectName: the project name. If the $projectName parameter contains characters other than English letter, digit and under-bar, these characters will be converted into under-bar automatically.

Return Value: Return the categories string array.

global proc int MGAssetLib_compareTwoFileDates ( string $file1, string $file2 );

Description: Utility precedure. Compare two files' modification date and give the result.

Return Value: If both files does not exist, return 0.

if $file1 exists but $file2 doesn't, return 1, if $file1 does not exists but $file2 does, return -1;

if both exist, then if file2 is newly modified than file2, return 1, they have same modification date, return 0, if file2 is newer than fiel1, return -1;

global proc string[] MGAssetLib_searchPreviewImagesFromDirectory ( string $searchDirectory,

string $imageExtensionList [],

int $searchDepth );

Description: Utility precedure. Search a directory recursively for a certain type of files.

Parameters: $searchDirectory: The target search directory. Should exist.

$imageExtensionList: A list contains all the file types you want to search for, eg. {"*.jpg", "*.bmp"}

$searchDepth is the depth of the searching, if you do not want to search the sub-folders, use 1 instead.

The value 0 or less than 0 indicates that the search is unlimited in depth.

Note: if the elements in the array $imageExtensionList, not start with "*." , the tool will add "*." automatically.

Return Value: The matched files' full path within the $searchDirectory.

global proc string[] MGAssetLib_searchMayaFilesFromDirectory ( string $searchDirectory,

int $searchMA,

int $searchMB,

int $searchDepth );

Description: Utility precedure. Search a directory recursively for MB/MA files.

Parameters: $searchDirectory: The target search directory. Should exist.

$searchMA decides whether to search MA files, 1 stands for searching, 0 stands not.

$searchMB decides whether to search MB files, 1 stands for searching, 0 stands not. If both $searchMA and $searchMB are 0, an empty array will be returned.

$searchDepth is the depth of the searching, if you do not want to search the sub-folders, use 1 instead.

The value 0 or less than 0 indicates that the search is unlimited in depth.

Return Value: The MB/MA files' full path within the $searchDirectory.

global proc int MGAssetLib_addAssetRecords ( string $projectName,

string $category,

string $mayaFiles[],

string $namespaces[],

string $states[],

string $previewImageStrList[],

string $notes[] );

Description: Add multiple asset items into the asset project in one go.

Parameters: $projectName: the asset library name.

$category is the category which contains these asset items.

$mayaFiles is the asset maya file full path array.

$namespaces is the asset name array.

$states is the states setting array for all the asset items. Each element of the array should only be composed of state name. No color info needed.

$previewImageStrList is the preview images array for each asset items. One element corresponds to one asset item.

Within each element, multiple image file paths could be used, as long as they are separated with ";".

$notes is the notes array for each asset item. No character limitation for each element, you can use any string.

Note: The array parameter should store their elements in the same order, the tools judge the asset items count from the length of $mayaFiles parameter.

If other array parameters has no elements correspond to the element in $mayaFiles, an empty string will be used.

Except the $namespaces array, the base name of the maya file will be used instead a empty string.

Return Value: 1 if no error happened, 0 if any.

global proc int MGAssetLib_deleteAssetRecords ( string $projectName,

string $category,

string $mayaFiles [] );

Description: Erase multiple asset items from the asset project in one go. It is based on the asset file paths.

Parameters: $projectName: the asset library name.

$category is the category which contains these asset items to erase.

$mayaFiles is the asset maya file full path array.

Return Value: 1 if no error happened, 0 if any.

global proc int MGAssetLib_makeMayaAsciiFile ( int $overrideIfExist,

string $MAFile,

string $referenceFiles [],

string $namespaceList [],

int $deferList [] );

Description: Make MA files, based of the referenced info provided.

Parameters: $overrideIfExist decide if you want to override the target file if it already exist.

$MAFile is the target ma full path.

$referenceFiles is the array contains the maya files, which will be referenced in the ma file.

$namespaceList is the reference namespace array.

$deferList is the defer value array of the reference.

Return Value: 1 if no error happened and the MA file is made, 0 if error happened.

Tips: If you want to upload / download the asset library in your script, use another two global procedures provided by MGTools: ( No need to call MGAssetLib_initAPI beforehand )

global proc int MG_CopyFolder ( string $targetFolder,

string $sourceFolder,

string $progressBarControl,

string $textControl,

int $returnAtFirstError,

int $autoHideProgressBarWhenIsDone );

Description: Copy all files and sub-folders from the source folder, to the target folder.

Parameters: $targetFolder is the target folder you want to copy the folders&files to, no matter if the target folder does not exist.

$sourceFolder is the source folder to copy from. should exist beforehand. If you input a file path, will skip and return.

$progressBarControl is an option progressBar control name, if assigned and exist, then will refresh the progress while copying the file & folders.

You can use an empty string for this parameter and the call will not care about this parameter.

$textControl is an option text control name, if assigned and exist, will refresh the copying info in the text control.

You can use an empty string for this parameter and the call will not care about this parameter.

$returnAtFirstError decides if there once be an error happened, the tool should return immediately or skip the error and continue.

$autoHideProgressBarWhenIsDone decides when the copy is finished, the progress bar control should be hidden or not.

Return Value: 1 if no error happened, 0 if error happened.

global proc int MG_DeleteFolder ( string $deleteFolder,

string $progressBarControl,

string $textControl,

int $returnAtFirstError,

int $autoHideProgressBarWhenIsDone );

Description: Delete all files and sub-folders from the target folder, along with the target folder itself.

Parameters: $deleteFolder is the target folder you want to delete.

$progressBarControl is an option progressBar control name, if assigned and exist, then will refresh the progress while deleting the file & folders.

You can use an empty string for this parameter and the call will not care about this parameter.

$textControl is an option text control name, if assigned and exist, will refresh the deleting info in the text control.

You can use an empty string for this parameter and the call will not care about this parameter.

$returnAtFirstError decides if there once be an error happened, the tool should return immediately or skip the error and continue.

$autoHideProgressBarWhenIsDone decides when the deleting is finished, the progress bar control should be hidden or not.

Return Value: 1 if no error happened, 0 if error happened.

Example Code:

//Open MG-Asset Library beforehand, so you can view what happening while you execute the codes.

//First we should init the mel api global procedures:

MGAssetLib_initAPI;

//create a asset project:

MGAssetLib_createProject "Mel_API" "A asset project created by mel API" "Z:/TNT/temp/Miguel/test/Lib_MelAPI" {"Pending 1 0 0", "Working 0 0 1", "Approved 0 1 0"};

//create a category called Character:

MGAssetLib_addCategory "Mel_API" "Character";

//test if the category been created successfully or not:

print ("The category \"Mel_API\" exists or not: " + `MGAssetLib_doesCategoryExist "Mel_API" "Character"` + "\n");

//clear the library. Not necessary because we just create it:

MGAssetLib_clearCategory "Mel_API" "Character";

//add state presets to the project:

MGAssetLib_addStates "Mel_API" {"Hi_Res 0.5 0.8 0.5", "Lo_Res 0.8 0.5 0.5"};

//test if the state presets been added:

print `MGAssetLib_getProjectStates "Mel_API"`;

//now search the asset files and images files:

string $mayaFiles[] = `MGAssetLib_searchMayaFilesFromDirectory "D:/temp" 1 0 0`;

print $mayaFiles;

string $images[] = `MGAssetLib_searchPreviewImagesFromDirectory "D:/temp" {"*.jpg","*.bmp"} 0`;

print $images;

//do some preview images and maya file matching things here:

// ....

//now we are ready to add the asset records:

MGAssetLib_addAssetRecords "Mel_API" "Character"

{"D:/temp/myAsset1.ma","D:/temp/myAsset2.ma","D:/temp/myAsset3.ma"}

{"namespace1","namespace2"}

{"Pending","Approved","Approved"}

{}

{"Note for fist item","note for sec item","third note"};

//try deleting one asset record via the asset path:

MGAssetLib_deleteAssetRecords "Mel_API" "Character" {"D:/temp/myAsset2.ma"};

//Now try making a ma file!

MGAssetLib_makeMayaAsciiFile (1, "D:/temp/test.ma", {"namespace1","namespace2"},

{"D:/temp/myAsset1.ma","D:/temp/myAsset2.ma","D:/temp/myAsset3.ma"},

{0,1,1} );