In Softimage 2010, a new lip sync feature was added to Face Robot (here’s the doc).  In 2011 SP1, there are three new commands to get the data out into your own tools.  One of them doesn’t even require the use of Face Robot and calls the speech recognition library directly.

The commands return VBScript-compatible multi-dimensional arrays.    This is transparent in VBScript and Python, but it requires a bit of magic in JScript, so check the example in the first command if that’s what you’re using.

Getting Phonemes without Face Robot

SIExtractPhonemes

Description

Scripting Syntax

oReturn = SIExtractPhonemes( Language, FileName, GuideText );

Return Value

Parameters

Examples

//returns a VBArray object, which require using the .getItem method in Jscript because they are not
//native objects there.
//However, they work transparently like multi-dimentionnal arrays in VBscript and Python
var res = SIExtractPhonemes ("en", "s:\\here_be_dragons.wav", "Here be dragons, the map says");
arraysize = res.ubound( 1 );
logmessage( arraysize + "phonemes found" );
for (  i=0; i < arraysize; i++)
{
logmessage( "IPA#" + res.getItem(i,0)
         + "(" + res.getItem(i,3) + ") "
         + "Start Time(sec) " + res.getItem(i,1)
         + "End Time(sec) " + res.getItem(i,2) );
}

Getting Lip Sync Stuff Out of Face Robot

This allows the artists to tweak the phonemes with the Face Robot UI, but used the data outside of Face Robot, perhaps in a game engine that does phoneme blending already.

The second command even allows you to get the result of the blend algorithm of Face Robot, so you can make a simplified playback environment.

GetPhonemeFromSpeechClip

Description

Scripting Syntax

oReturn = GetPhonemeFromSpeechClip( SpeechClip );

Return Value

Parameters

Examples

phonemes = GetPhonemesFromSpeechClip ("Face.Mixer.Phoneme_Speech.SpeechAction_Clip")
LogMessage "phoneme data"
for i = 0 to UBound( phonemes )
	LogMessage "IPA # " & phonemes(i, 0) & "(" & phonemes(i, 3) & ")" & " Start (sec)" & phonemes(i, 1) & " End (sec)" & phonemes(i, 2)
next

GetPhonemeBlendFromSpeechClip

Description

Scripting Syntax

oReturn = GetPhonemeBlendFromSpeechClip( SpeechClip, [Channel], [Time] );

Return Value

Parameters

Examples

phonemes = GetPhonemeBlendFromSpeechClip ("Face.Mixer.Phoneme_Speech.SpeechAction_Clip")
LogMessage "phoneme blend"
for i = 0 to UBound( phonemes )
	LogMessage "IPA # " & phonemes(i, 0) & "(" & phonemes(i, 1) & ")" & " Weight " & phonemes(i, 2 )
next

For years I’ve been doing this and for years I’ve been meaning to get around to making it slicker but somehow there was never time. So the other day it rained – fit to burst – and I had a day inside with nothing else to do and this is what I ended up with.

Earlier attempts ended up in a puddle on the floor because for some reason the only links I could find to VSS command line building pointed me at VCBuild.exe, which is just a plain old mess. This time, though, I found a link to a list of command line options for devenv.exe – what you run to bring up the VS IDE – at the excelent codeproject.com and these are much more straightforward.

The process is fairly simple:

1. unload the plugin.
2. run a command line build using system()
3. copy over the dll (my build has this built in)
4. reload the plugin.
5. test
6. package

Step 2 involves a little bit of wrastling with .bat command line, um, features but really the code (at the end of this article) is quite simple. Because it’s scripted you can build entire plugin sets and package them in one go. The whole process takes only seconds because it’s self contained and it’s dead easy to stuff in some test code. You can easily slip back to the IDE when you need it and it makes working with a preferred text editor easier if that’s your bag.

There’s also the advantage that the build inherits the paths to libraries from the XSI version you’re working with. No more .bat file wrappers. Neat!

This example code is just a list of functions:

Build( solutionName, PluginName, forceRebuild ); // do the actual build.
GetConfig(); //gets the platform type (32/64)
Package( PluginName ); // package. Output name is hard coded in the example.

I stuff the plugin names in an array so I can build a bunch of them in one.

I also have a custom property I use with a dropdown list of my main projects along with build and package buttons.

And finally, I figure I might, next time it rains, get this working alongside package location. Who knows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

var sPlugins = new Array( "TinyCurveExtrude", "TinyCap" );
var slnName = sPlugins[0];
var sPluginName = slnName + "Plugin";
 
Build( slnName, sPluginName, false );
Package( sPluginName );
 
// build the solution. doRebuild is a boolean, forces a complete compile and build if true.
//
function Build( slnName, sPluginName, doRebuild ) {
	var oPlugin = Application.Plugins( sPluginName );
	var sPluginFileName = oPlugin.FileName;
 
	if ( !oPlugin ) {
		logmessage( "Can't find plugin to unload: " + sPluginName, siError );
		return;
	}
 
	Logmessage( "Unloading Plugin " + sPluginFileName );	
	Application.UnloadPlugin( sPluginFileName );
 
	var Cmd = BuildCmdRoot( slnName );
	var sConfig = GetConfig();
 
	var sOpt = (doRebuild) ? " /rebuild " : " /build ";
 
	if ( sConfig ) {
		system( Cmd + sOpt + sConfig + " & pause" );
	} else {
		Logmessage( "Build Failed", siError );
	}
 
	LogMessage( "ReLoading Plugin: " + sPluginFileName );
	Application.LoadPlugin( sPluginFileName );
 
} 
// get the platform type, 32 or 64 bit. Release is hard coded
//
function GetConfig() {
	var sPlatform = Application.Platform;
	Logmessage( sPlatform );
 
	if ( sPlatform.match( /win64/i ) ) return "\"Release x64|x64\"";
	if ( sPlatform.match( /win32/i ) ) return "\"Release|Win32\"";
 
	Logmessage( "Unsupported Platform: " + sPlatform, siError );
	return false;
}
 
// build the devenv.ex command line
// NOTE: this is set to work on a 64 bit system. Take out the (x86) and spaces 
// for 32 bit. Cross compile works well enough but you'll need the 64 bit libs
function BuildCmdRoot( sTargetName ) {
	var slnRoot = "c:\\fatty\\DEV\\CPP";
 
	var vcVars = "call \"C:\\Program Files (x86)\\Microsoft Visual Studio 8\\VC\\vcvarsall.bat\" x86";
 
	var slnPath = slnRoot + "\\" + sTargetName + "\\" + sTargetName + ".sln"
	var Cmd = vcVars + " & devenv " + slnPath;
	return Cmd;
}
 
// Package.
// ToDo: rebuild for package location.
//
function Package( sPluginName ) {
	logmessage( "Packaging ... " );
 
	var sOutputPath = "C:/Fatty/Dev/CPP/Release"
 
	var sPlatform = Application.Platform;
 
	var oPlugin = Application.Plugins( sPluginName );
	var sPluginFileName = oPlugin.FileName;
 
	var oAddOn = Application.CreateAddon();
 
	oAddOn.AddItem( siPluginAddonItemType, oPlugin.FileName );
 
	oAddOn.DefaultInstallationPath = siUserAddonPath;
	oAddOn.SubDirectory = sPluginName;
 
	var sPluginFileName = sOutputPath + "/" + sPluginName + "_" + sPlatform + ".xsiaddon"
 
	oAddOn.Save( sPluginFileName );
 
	logmessage( "Packaged to: " + sPluginFileName  );
}

Callbacks in XSI plugins are functions in the global scope who’s name must be defined exactly the way XSI expects to find them.

I would have preferred callbacks to be supplied by the user in a way that allows them to have any name and in a way that allows them to be changed on the fly. In all fairness, Softimage probably has some very good reasons for the way they did things.

So this is where we, as users, exploit the power that has been given to us and take things into our own hands. Here is my implementation of dynamic, interchangeable, replaceable callbacks.

Code Time!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

import win32com.client
from win32com.client import constants as c
from vg.xsi.dynamic import *
 
def XSILoadPlugin( in_reg ):
	in_reg.Author = "Patrick Boucher"
	in_reg.Name = "dynCbCommandPlugin"
	in_reg.Major = 1
	in_reg.Minor = 0
	in_reg.RegisterCommand("dynCbCommand", "dynCbCommand")
	return True
 
def XSIUnloadPlugin( in_reg ):
	strPluginName = in_reg.Name
	Application.LogMessage(str(strPluginName) + str(" has been unloaded."),c.siVerbose)
	return True
 
def dynCbCommand_Init( in_ctxt ):
	oCmd = in_ctxt.Source
	oCmd.Description = ""
	oCmd.ReturnValue = True
	return True
 
@dynamic
def dynCbCommand_Execute():
	Application.LogMessage('In original callback!')
	setCallback(dynCbCommand_Execute, callbackTwo)
	return True
 
def callbackTwo():
	Application.LogMessage('In %s!' % callback(dynCbCommand_Execute).func_name)
	setCallback(dynCbCommand_Execute, callbackThree)
	return True	
 
def callbackThree():
	Application.LogMessage('In callback three!')
	restoreCallback('dynCbCommand_Execute')
	return True	
 
setCallback(dynCbCommand_Execute, callbackTwo)

The first time you run this command it will run the code in callbackTwo and switch itself to new code. The next time it will run callbackThree and the next time it will run the original callback code. It will then, with each consecutive invocation of the command, continue on in this loop. This plugin, as you have guessed, is just a demo of the dynamic callbacks.

The lines you have to concentrate on are the following:

from vg.xsi.dynamic import *

and

@dynamic

These are the lines that provide the core of the functionality which is imported from the vg.xsi.dynamic module. Here it is…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

import sys
 
__all__ = ['dynamic', 'setCallback', 'callback', 'restoreCallback']
 
class Wrapper(object):
    def __init__(self, cb):
        self.__defaultCb = cb
        self.__cb = cb
 
    def call(self, *args, **kwargs):
        return self.__cb(*args, **kwargs)
 
    def setCallback(self, newCb):
        self.__cb = newCb
 
    def callback(self):
        return self.__cb
 
    def restoreCallback(self):
        self.__cb = self.__defaultCb
 
def dynamic(func):
    cbWrap = Wrapper(func)
    return cbWrap.call
 
def setCallback(bound, newCb):
    bound = _getCallable(bound)
    newCb = _getCallable(newCb)
    return bound.im_self.setCallback(newCb)
 
def callback(bound):
    bound = _getCallable(bound)
    return bound.im_self.callback()
 
def restoreCallback(bound):
    bound = _getCallable(bound)
    return bound.im_self.restoreCallback()
 
def _getCallable(req):
    if callable(req):
        return req
 
    if type(req) is str:
        g = sys._getframe(2).f_globals
        return g[req]

I’ve removed any comments or docstrings for the sake of brevity.

About Decorators

The import line I said was of particular interest. Well it is but only in the sense that it will allow you to use the module in which the features are implemented… Moving on quickly.

The real fun is with the @dynamic decorator. What is a decorator and what happens when we use one (or this one in particular)? Before we look at what a decorator is and does, let’s look at what happens when we define a function.

1
2

def func():
    pass

When a function is defined, what is happening is that an identifier is created in your current scope and this identifier is given the name of your function. Now let’s add the decorator. A decorator is just a simple function, but a function who’s purpose is very specific and a function that must return a callable (another function most of the time).

1
2
3

@myDecorator
def func():
    pass

What happens here is that the identifier func is still created but what lies ‘in’ this identifier is not the function itself but the result of passing said function to myDecorator. To help you visualize, the above code could just as easily been written like so:

1
2
3

def func():
    pass
func = myDecorator(func)

Let’s Get Specific

The decorator @dynamic takes your callback and wraps it inside a Wrapper object and returns the call method of this new object. When XSI tries to call what it thinks is just a simple callback it is actually calling the call method of an object that in turn calls your original callback. Whew!

This means that you now have the liberty of querying and editing the callback object and telling it to call something different depending on context. This functionality is provided by the setCallback, callback and restoreCallback functions.

These three functions either take the callback function objects or the callback’s names (as a string) as arguments.

There are some more particularities to this code such as the use of sys._getframe, the im_self attribute or the use of the call method on the Wrapper object instead of implementing __call__ but I think they might be outside the scope of this article. If there are requests for it I can expand in the comments or another post.

Meanwhile you can download the example. Drop the plugin into a plugin folder (user, factory or workgroup) and drop the vg folder somewhere in your Python path.

Cheers!

I put some effort into commenting the script accordingly, so that it may be used for learning purposes.

cheers!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

// query the geometry data
var obj = selection(0);
var geo = obj.Activeprimitive.Geometry;
var polygons = geo.Polygons;
 
// create an array to track which polygon has been visited
var polygonVisited = [];
var polygonsLeft = polygons.Count;
 
// fill up the array to say: "no polygon has been visited yet"
for(var i=0;i<polygons .count;i++)
{
	polygonVisited[i] = false;
}
 
// create some helper variables
var clusterIndices = [];
var currentRow = [];
 
// log the start of the process
logmessage("Starting with "+polygonsLeft+" polygons...");
 
// loop until there are no polygons left
// or there are still items in the cluster array
while(polygonsLeft > 0 || clusterIndices.length > 0)
{
	// if there are no items in the next row...
	if(currentRow.length == 0)
	{
		// if there are items in the cluster index array
		if(clusterIndices.length > 0)
		{
			// log the creation of the cluster
			logmessage("Creating cluster with "+clusterIndices.length+" elements...");
 
			// create a new mesh containing all of these polygons
			// first, create an array containing all pointindices
			// and two additional point hash arrays
			// of which one is used to determine if a point is already used
			// and the second one is used to map the original index to the new one
			var pointIndices = [];
			var pointUsed = [];
			var pointNewIndex = [];
 
			for(var i=0;i<clusterIndices.length;i++)
			{
				var poly = polygons.item(clusterIndices[i]);
				var pointIndexArray = poly.points.indexArray.toArray(); //(VBS to JScript conversion)
 
				// loop through all points and check if it they are used
				for(var j=0;j<pointIndexArray.length;j++)
				{
					var index = pointIndexArray[j];
					if(!pointUsed[index])
					{
						pointNewIndex[index] = pointIndices.length;
						pointIndices.push(index);
						pointUsed[index] = true;	
					}
				}
			}
 
			// now, create the array of the positions of all points of this island
			var islandPos = [];
			for(var i=0;i<pointIndices.length;i++)
			{
				var point = geo.points.item(pointIndices[i]);
				islandPos.push(point.position.x);
				islandPos.push(point.position.y);
				islandPos.push(point.position.z);
			}
 
			// now we need to create the description of the polygons
			var islandPoly = [];
			// for that we loop over the polygons of the island again
			// and record their pointindices, well, actually the remapped
			// indices (given by the pointNewIndex hash array)
			for(var i=0;i<clusterIndices.length;i++)
			{
				var poly = polygons.item(clusterIndices[i]);
				var pointIndexArray = poly.points.indexArray.toArray(); //(VBS to JScript conversion)
 
				// first add the number of points of this polygon 
				// to this polygon's description
				islandPoly.push(pointIndexArray.length);
 
				// now add the remapped index for each point to the description
				for(var j=0;j<pointIndexArray.length;j++)
				{
					var index = pointIndexArray[j];
					islandPoly.push(pointNewIndex[index]);
				}
			}
 
			obj.Parent.AddPolygonMesh(islandPos,islandPoly,obj.name+"_island");
			clusterIndices = [];
 
			// if there are no polyons left we can stop now
			if(polygonsLeft == 0)
				break;
		}
 
		// loop over the polygons and try to find 
		// one which hasn't been visited yet
		for(var i=0;i<polygons.Count;i++)
		{
			if(polygonVisited[i] == false)
			{
				currentRow.push(i);
				clusterIndices.push(i);
				polygonVisited[i] = true;
				polygonsLeft--;
				break;
			}
		}
	}
 
	// define the nextrow after the current row
	var nextRow = [];
 
	// loop over all items in the current row
	for(var i=0;i<currentRow.length;i++)
	{
		var polygon = polygons.item(currentRow[i]);
		var neighbors = polygon.NeighborPolygons();
 
		// loop through all of the neighbors and add them to the nextRow
		for(var j=0;j<neighbors.count;j++)
		{
			// check if the neighbor has been
			// visited yet
			var neighbor = neighbors.item(j).index;
			if(polygonVisited[neighbor]==false)
			{
				// add the neighbor to the next row
				nextRow.push(neighbor);
				clusterIndices.push(neighbor);
				polygonVisited[neighbor] = true;
				polygonsLeft--;
				break;
			}
		}
	}
 
	currentRow = nextRow;
}
 
selection.SetAsText(obj.name+"_island*");

I’ll also put in place a system to push central library changes to the local computers and insert the library location in the PYTHONPATH environment variable.

The XSI Wiki has a great page on the pros and cons of the module approach. One of the cons is that the Application global variable is only accessible in your script files and plugin files and not in your modules.

In the past I would put the following code at the top of my various modules:

1
2
3
4

import win32com
from win32com.client import constants as c
xsi = win32com.client.Dispatch('XSI.Application').Application
log = xsi.Logmessage

Following this would be a bunch of other shortcuts and dispatch commands for XSIUtils, XSIUIToolkit, XSIMath, etc…

Being tired of inserting these lines at the header of every module and a subset of this code (for shortcuts) at every script or plugin, I decided to centralize them and move them to their own module.

The library structure looks like so:

../libpath/
    vg/
        xsi/
            __init__.py
            xsiModule1.py
            xsiModule2.py
            [...]

In the __init__.py file I put the following code:

1
2
3
4
5
6
7
8
9
10
11
12

import win32com
from win32com.client import constants as c
xsi = win32com.client.Dispatch('XSI.Application').Application
log = xsi.Logmessage
# [... more shortcuts and dispatch commands ...]
 
def getShortcuts(g):
    g['win32com'] = win32com
    g['c'] = c
    g['xsi'] = xsi
    g['log'] = log
    # [... more shortcuts and dispatch commands scope transfers...]

This allows me to benefit from the shortcuts in the rest of the __init__.py file where some general XSI functions are kept but also start my other modules, scripts and plugins with the following two lines:

1
2

import vg.xsi as vx
vx.getShortcuts(globals())

By providing the getShortcuts function with a dict representing the global scope of my module, script or plugin, the function can edit the members of the scope and give me all the necessary symbols.

Another stupid trick rears it’s head! ;)
Happy scripting!

The weird wirings in my brain. That’s what.

Back to the beginning

At the end of last October Steven Caron sent me a plugin he wrote that allows an XSI user to drag and drop .obj files into the interface and have them import automatically according to settings in a custom preference. I was a bit swamped at the time putting up the infrastructure for a new VFX department at my new workplace. And then I totally forgot about it… Sorry Steven.

This past week Steven politely reminded me of my omission so I ran back to my email archives and installed it. Neat piece of work.

I didn’t want to just post up the tool as I don’t really see this blog being about tool distribution but about how said tools work and the neat tricks they use. With that philosophy in mind I cracked open Steven’s tool to dig out some of its sexier bits and maybe demystify them for the audience.

To my surprise there weren’t any sexy bits. Please don’t get me wrong, the tool works superbly, how much more intuitive can you get than drag and drop. The tool is also extremely well written, concise and straightforward. There just aren’t any weird tricks or convoluted syntax or things that would generally have you scratching your head.

Then I noticed this in his version trapping code (yes folks, the drag and drop event is new in XSI 6.5):

27
28
29
30
31
32
33
34
35

if int( tXSIVersion[0] ) < 6:
    xsiPrint( xsi.Version() + " doesn't support the 'siOnDragAndDrop' event!" )
    xsi.UnloadPlugin( in_reg.name, True )
    return False
else:
    if int( tXSIVersion[1] ) < 5:
        xsiPrint( xsi.Version() + " doesn't support the 'siOnDragAndDrop' event!" )
        xsi.UnloadPlugin( in_reg.name, True )
        return False

About the waste part

Bare with me…

Last week I was reading a really neat article in Wired by Chris Anderson entitled “Free! Why $0.00 Is the Future of Business”. I invite you to read it, especially the section beginning on page two: Waste and Waste Again.

…So if in the seventies you had to be really tight with your algorithms and optimizations because cpu cycles were so scarce, today I guess we can really waste them. Just the other day I setup an 8 core MacPro with BootCamp, XP x64 and XSI. Whatever I did to the machine, I swear, I could hear it yawn because it was bored.

Which brings me back to Steven’s code. Could it have been written like so:

27
28
29
30

if int( tXSIVersion[0] ) < 6 or int( tXSIVersion[1] ) < 5:
    xsiPrint( xsi.Version() + " doesn't support the 'siOnDragAndDrop' event!" )
    xsi.UnloadPlugin( in_reg.name, True )
    return False

Is it more or less readable by a programmer?
It probably executes in a few cycles less but is it worth it?
Python is interpreted so if the parser goes through this version quicker, is it worty of any mention?
Is it more maintainable?

This example is really simple but in a bigger project, or with more complex cases, should we really be worrying if today transistors and cpu cycles are so cheap as to not even matter anymore

When I'm stuck on a piece of code or when I hit that time of the afternoon where most of my energy is diverted to digesting, I'll often reread my code and tighten it, remove redundancy, put in functions instead of copying a few lines in two locations, consolidate if statements, etc... One of my colleagues used to tell me that "Premature optimization is the root of all evil."

Honestly, if I look back at a good proportion of the code I have written, it either executes in a blink of an eye on today's computers or it sits there waiting 90% of the time for user interaction. Should we, as technical XSI users, XSI scripters or TDs, even worry about optimization from a performance standpoint or a maintainability standpoint? What can be considered a good optimization and what should be considered a bad one?

And now that you're really wondering what I'm rambling about, I'll shut up and let you download Steven's addon.

Have a good weekend. ]]> http://www.softimageblog.com/archives/249/feed 19 http://www.softimageblog.com/archives/245#utm_source=rss&utm_medium=rss&utm_campaign=scripting-shaders http://www.softimageblog.com/archives/245#comments Fri, 10 Aug 2007 20:43:56 +0000 Bernard Lebel http://www.xsi-blog.com/archives/245 ABSTRACT

This article is sort of a tutorial-cookbook for scripting beginners. It discusses quick and simple techniques to script minor tasks related to shaders. We will try to focus more on Object Model techniques than Command Model ones. Please feel free to contribute to it if you know better!

SHADERS

Shader name spaces
Shaders live in name spaces. In a single name space, no two shaders can have the same name. A bit like objects under models. There are several name spaces available. The material, the override, the camera, the light and the pass are all name spaces. Some name spaces are easier to deal with than others, like materials and lights. We could probably group name spaces in two larger categories: the material type (materials, lights and overrides), and the stack type (passes and cameras). The material type is always easy to handle (well, overrides have some particularities, but we shall address them later). Stack types on the other hand a somewhat problematic, as the way they expose shaders differently depending on the context.

One more name space deserves few lines. This is the TransientObjectContainer. This space is an invisible location where unconnected pieces of data live, like unconnected shaders. Notice that when you create a new shader in the Render Tree and open its property page right away, it’s name is prefixed with “TransientObjectContainer”. As soon as you connect this shader, it is now prefixed with the material name (you may need to re-open the ppg to see the change). When a shader is disconnected from all inputs, it returns to the TransientObjectContainer space. If you close the Render Tree, the shader is destroyed.

One advantage of name spaces is that the shader name is garanteed to be unique within that name space. So if you know the name space of a shader, you can retreive it anyway you like and be sure it’s the right shader. When I talk about the name of a shader, I mean name as in the “Name” property.

Shader fullnames
Dealing with the shader fullname (as in the “FullName” property) is somewhat problematic. Only a handful of shaders have a “unique” fullname, because the fullname of a shader depends entirely from where it is read. In other word, most shaders have multiple fullnames, which are potentially all valid. A shader fullname is like a path in the render tree to that shader. It includes the name of all shaders traversed to reach this shader.

Let’s do a quick exercice.
Create an object. Create a Phong material for this object. Open the render tree for that material. Disconnect the Phong shader from the Shadow input of the material node.
Create a cell shader. Plug it in the diffuse input of the Phong shader, and in the Photon input of the material node.

Then run this code, which prints the name of shader inputs in a render tree:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

xsi = Application
 
def printShaderSources( oShader ):
 
	# Loop parameters of the shader
	for oParameter in oShader.parameters:
 
		# Check if the parameter has a source
		oSource = oParameter.source
		if oSource != None:
 
			# Check if classname of the source is a shader
			sClassName = xsi.classname( oSource )
			if sClassName == 'Shader' or sClassName == 'Texture':
 
				xsi.logmessage( oSource.fullname )
 
				# Parameter has a shader source,
				# call function again with that source
				printShaderSources( oSource )
 
# Call the function using the selected object's material
printShaderSources( xsi.selection(0).material )

This should print:

# INFO : sphere.Material.Phong
# INFO : sphere.Material.Phong.Cell
# INFO : sphere.Material.Cell

At line 16, we print the fullname of the shader currently visited. You can see in the output that we got two different values: sphere.Material.Phong.Cell and sphere.Material.Cell. They are both valid and could be used to retrieve the shader using a string. The first is the result of accessing the shader through the Phong shader, while the second one is because we read it from the material node.

The shaders that have a unique fullname are the material, the override, the light, and basically the root shaders in pass and camera shader stacks.

Collecting shaders the hard way: recursive traversal of the render tree
Aka “walking” the render tree, traversing the render tree is a very common task. There are several ways to do it, it depends on what you want to do.

In “Shader fullnames”, we’ve seen one way of doing it. This way is not clever at all. Shaders will be evaluated as many times as the number of inputs they plug in. In complex render trees, this means lots of cpu cycles can be lost. Worse, if you’re doing things like shader replacement, you may end up replacing the same shader more than once.

The trick is to remember which shader was visited. For the following examples, we’ll use a similar test scene: create a Phong material, plug a Cell shader in in its diffuse input and in the shadow input of the material. But don’t disconnect anything.

If you traverse the render tree without checking if a shader has been visited, you’ll get the same shader printed sevaral times:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

xsi = Application
 
def printShaderSources( oShader ):
 
	# Loop parameters of the shader
	for oParameter in oShader.parameters:
 
		# Check if the parameter has a source
		oSource = oParameter.source
		if oSource != None:
 
			# Check if classname of the source is a shader
			sClassName = xsi.classname( oSource )
			if sClassName == 'Shader' or sClassName == 'Texture':
 
				xsi.logmessage( oSource.name )
 
				# Parameter has a shader source,
				# call function again with that source
				printShaderSources( oSource )
 
# Call the function using the selected object's material
printShaderSources( xsi.selection(0).material )

Output:

# INFO : Phong
# INFO : Cell
# INFO : Phong
# INFO : Cell
# INFO : Cell

The simplest way to prevent this is to have a list of all shader names. Each time you visit a shader, check if its name is in the list, if not, evaluate its parameters.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

xsi = Application
 
def printShaderSources( oShader ):
 
	# Loop parameters of the shader
	for oParameter in oShader.parameters:
 
		# Check if the parameter has a source
		oSource = oParameter.source
		if oSource != None:
 
			# Check if classname of the source is a shader
			sClassName = xsi.classname( oSource )
			if sClassName == 'Shader' or sClassName == 'Texture':
 
				# Check if shader was already visited
				if not oSource.name in aShaderNames:
 
					xsi.logmessage( oSource.name )
 
					aShaderNames.append( oSource.name )
 
					# Parameter has a shader source,
					# call function again with that source
					printShaderSources( oSource )
 
aShaderNames = []
 
# Call the function using the selected object's material
printShaderSources( xsi.selection(0).material )

Output:

# INFO : Phong
# INFO : Cell

This approach has one big problem. There is one big exception to the name space rule: in a material, one shader can have the same name as the material. So if you collected the material name before all else and another shader has the same name, it will be skipped. You can deal with this in a plenty of ways, but they all come down to what to do if a name already exists. My suggestion is to simply rename the shader if it’s not of the material type. Append a 1 to its name. So all names are garanteed to be unique.

A very different approach to render tree traversal is to store all shaders in a collection that has the Unique flag enabled. You don’t even have to check if the name exists.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import win32com
xsi = Application
xsifactory = win32com.client.Dispatch( 'XSI.Factory' )
 
def getShaderSources( oShader ):
 
	# Add shader right away to the collection
	oShaders.add( oShader )
 
	# Loop parameters of the shader
	for oParameter in oShader.parameters:
 
		# Check if the parameter has a source
		oSource = oParameter.source
		if oSource != None:
 
			# Check if classname of the source is a shader
			sClassName = xsi.classname( oSource )
			if sClassName == 'Shader' or sClassName == 'Texture':
 
				# Parameter has a shader source,
				# call function again with that source
				getShaderSources( oSource )
 
# Create collection to store shaders of a material
oShaders = xsifactory.createobject( 'XSI.Collection' )
 
# Enable the Unique flag of the collection,
# which means no shader can be stored twice
oShaders.unique = True
 
# Call the function using the selected object's material
getShaderSources( xsi.selection(0).material )
 
# Finally, print all shader names
for oShader in oShaders:
	xsi.logmessage( oShader.name )

Output:

# INFO : Material
# INFO : Phong
# INFO : Cell

Collecting shaders the easy way: FindShaders()
Materials, lights and cameras implemente the FindShaders() method. It allows you to collect all shaders as a flat collection and then get them by name or index, or you can loop over the collection items.

The example in the FindShaders (Material) entry of the documentation is pretty clear on this matter. This method is an alternative to recursively traverse the render tree. I have not tested performance, though.

Storing a material’s render tree into a data structure
This is an expansion of the previous topic. If you ever have to do complex shader replacement, render tree export, or render tree reconstruction, storing the render tree in your own data structure will be essential. In this structure you will store the shaders, as well as the connections that exists between them. The following techniques I propose are based on my experience in this area, it is by no mean an absolute way of doing things.

First, each shader must be uniquely identified. That can be done using their name, although you must make sure that there is no name collision with the material. Personally I prefer to use an integer. The reason is that if you ever have to rename a shader, you may end up having to update the structure to reflect the name change. With an integer you don’t bother about this at all. For the remainder of this topic, I’ll use an integer as the master key for shaders. I’ll refer to this master key as the shader ID.

Using that ID, you’ll be able to store masses of information. You want to record the shader name, the shader object, the parameters that have a shader input, and the ID of the input shaders. The map will look like this:

dShadersByID
{
	id (integer) :
	{
		'name' : shader name (string),
		'object' : shader object (instance),
		'parameters' (dictionary) :
		{
			'parameter name' : shader id,
			'parameter name' : shader id,
			...
		}
	},
	id (integer) :
	{
		'name'  : shader name (string),
		'object' : shader object (instance),
		'parameters' (dictionary) :
		{
			'parameter name' : shader id,
			'parameter name' : shader id,
			...
		}
	},
	...
}

Let’s talk about how to populate this structure. Aside from the actual main structure, I’d have another map, where the the shader name is the key, and its ID is the value. It will be a lot easier to retreive the ID of an existing shader when one is encountered.

When a new shader is visited, each parameter is tested for the presence of a shader source. If one is found, it must be checked if the source has been evaluated already, if so, retreive its ID, and write for that parameter. Otherwise, visit that new shader.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

import win32com
c = win32com.client.constants
xsi = Application
 
def getShaderSources( oShader ):
 
	"""
	We assume that when this function is called,
	the passed shader has never been visited.
 
	The function doesn't know if the passed
	shader is just a shader or the material.
	"""
 
	# Get new ID for this shader
	global iID
	iID += 1
	iShaderID = iID
 
	# Map the ID to the shader name
	dShadersByName[oShader.name] = iID
 
	# Store this shader in the main shader structure
	dShadersByID[iID] = {
		'name': oShader.name,
		'object': oShader,
		'parameters': {}
	}
 
	# Loop parameters of the shader
	for oParameter in oShader.parameters:
 
		# Check if the parameter has a source
		oSource = oParameter.source
		if oSource != None:
 
			# Check if classname of the source is a shader
			sClassName = xsi.classname( oSource )
			if sClassName == 'Shader' or sClassName == 'Texture':
 
				# Check if the source is the material and has the same name as the material
				if oSource.type != c.siMaterialType and oSource.name == oMAT.name:
 
					# Rename source
					oSource.name = '%s1' % oSource.name
 
				# Check if that source shader has already been visited
				if oSource.name in dShadersByName:
 
					# Get the source ID
					iSourceID = dShadersByName[oSource.name]
 
					# Store the source ID for this parameter
					dShadersByID[iShaderID]['parameters'][oParameter.scriptname] = iSourceID
 
				else:
					# Source shader has never been visited
					# Visit it, and map its ID to the current parameter
					dShadersByID[iShaderID]['parameters'][oParameter.scriptname] = getShaderSources( oSource )
 
	# Return the shader ID to the caller
	return iShaderID
 
 
 
# Main data structure
dShadersByID = {}
 
# ID mapped to the shader name
dShadersByName = {}
 
# Starting ID
iID = -1
 
# Constants to indicate which shader is the material
oMAT = xsi.selection(0).material
 
# Call the function using the selected object's material
getShaderSources( oMAT )

To verify the dShadersByID structure, you can simply convert it to string and print it:

1

xsi.logmessage( str(dShadersByID) )

Using our example of the Cell shader, the output should be like this (I formatted it so it’s easier to read):

{
	0:
	{
		'object': "COMObject "unknown""(3),
		'name': u'Material',
		'parameters':
		{
			u'shadow': 1,
			u'Photon': 2,
			u'surface': 1
		}
	},

	1:
	{
		'object': "COMObject "unknown""(3),
		'name': u'Phong',
		'parameters':
		{
			u'diffuse': 2
		}
	},

	2:
	{
		'object': "COMObject "unknown""(3),
		'name': u'Cell',
		'parameters': {}
	}
}

So we got our map of the render tree. We can then use to navigate the render tree and do any operation we want without risking loosing relationships. For instance, if you wanted to replace the Phong shader, you know you have to look for ID 1. Once replaced, you can find in other shaders to which inputs is the phong connected, and perform the connections. You also know, looking at the phong entry, that ID 2 is connected into its diffuse parameter.

The next topics should help you tackle these operations.

Creating a shader
You can create a “floating” shader, that is, a shader object not connected to anything, by using the CreateObjectFromPreset() command.

1

oShader = xsi.createobjectfrompreset( "shaders/material/blinn.preset" )

To find out what string you should use as the first parameter, just create the shader in the Render Tree. This will give you the path of the preset file, and this is all you need to create the shader.
The command also accepts a second argument, for its name. Usually I don’t specify a name unless I’m creating trees that enforce the project standards.

The command returns the shader object. This object lives in the TransientObjectContainer, it’s not connected to anything. The cool thing is that contrary to unconnected shaders in the Render Tree, which are destroyed when the Render Tree is closed, TransientObjectContainer shaders created by script remain there as long as you don’t create a new scene or explicitely remove them. Remember however that because the shader is not connected, it may hard to retrieve if you destroy the variable that holds the command return value.

Connecting a shader
Once you have a shader, you may connect it into a texturable parameter. You can use the SIConnectShaderToCnxPoint() command, but personnally I find the Connect() method of the parameter object to be faster and cleaner. All you need is to have the input parameter as an object.

1

oParameter.connect( oShader )

What I usually do when building shader trees in script is to create all the shaders in one phase (using the CreateObjectFromPreset() command), and then perform all the connections in another phase.

If you are connecting the shader in a rather large amount of parameters, then perhaps using the SIConnectShaderToCnxPoint() command might be faster, as it allows you to pass a list of input parameters:

1
2
3
4
5
6
7
8
9
10

sPhong = 'Sources.Materials.DefaultLib.Scene_Material.Phong'
 
xsi.siconnectshadertocnxpoint(
   oShader.fullname,
    ','.join( [
        '%s.diffuse' % (sPhong,),
        '%s.ambient' % (sPhong,),
        '%s.specular' % (sPhong,)
    ] ),
    False)

Disconnecting a shader
As with connecting shaders, there are two ways to disconnect shaders. The first one is the RemoveShaderFromCnxPoint() command, which works like SIConnectShaderToCnxPoint() command.

The other way is to use the Disconnect() method on the parameter you want to remove the connected shader from.

1

oParameter.disconnect()

Now you have to be very careful: if you disconnect the shader and the shader is no longer connected to any parameter, it is destroyed!

Getting the “sub-parameters” after a disconnection
If you have a compound parameter, like a color or a vector, and you disconnect a shader from it, you won’t be able to access its sub-parameters (like red or x) right away, for some reason. If you try to read or write to the red parameter, for example, you’ll raise an exception.

1
2

oDiffuse.disconnect()
xsi.logmessage( oDiffuse.parameters( 'red' ).value )

Output:

# ERROR : Traceback (most recent call last):
#   File "", line 14, in ?
#     xsi.logmessage( oDiffuse.parameters( 'red' ).value )
# AttributeError: 'NoneType' object has no attribute 'value'
#  - [line 14]

The solution is to “rebind” the variable to the disconnected parameter.

1
2
3
4
5
6

oDiffuse.disconnect()
 
# Rebind parameter and variable
oDiffuse = oDiffuse.parent.parameters( 'diffuse' )
 
xsi.logmessage( oDiffuse.parameters( 'red' ).value )

Output:

# INFO : 0.699999988079071

Thanks to François Painchaud for this one.

Getting all shaders of a same kind
A common task is to change the value of a shader parameter globally. For example, you may want to enable elliptical filtering in all image shaders. Materials may have varying render trees, so using overrides would be prove very tedious.

To get all shader instances of a same kind, you can run the command FindObjects(). This is very fast and reliable.

1

oBlinns = xsi.findobjects( None, '{8FAC63AC-E392-11D1-804C-00A0C906835D}' )

This will return a XSICollection containing all shader instances as objects. The first argument is always null or None. The second argument is a shader ClassID

Getting the ClassID of a shader
To know the ClassID of a shader, you can create it in the Render Tree, open its property page, right-click on the space next to the shader name, and choose Edit.

A text page will open either in the script editor or in a floating text editor. The ClassID is generally located at the third line, it starts with Reference.

Reference = "{8FAC63AC-E392-11D1-804C-00A0C906835D}";

If you already have the shader object in your script and want to find out its ClassID, you can use the GetIdentifier() method of the DataRepository object.

1

sClassID = oRepository.getidentifier( oShader, c.siObjectCLSID )

To create a DataRepository instance in Python:

1
2
3

import win32com
xsiutils = win32com.client.Dispatch( 'XSI.Utils' )
oRepository = xsiutils.datarepository

Finding a specific kind of shader in a render tree
We’ve seen pretty much all means of getting and identifying shaders. But you might be looking for shaders of a specific type inside a shader name space. There are several ways to do that:

The first approach is to run FindObjects(). Since it works globally, you’ll have to loop each shader and check if its Root property matches the one we’re looking for. Remember that the Root property suffers from an important limitation that we hinted at in Shader fullnames and shall discuss more in PASSES.

The second approach is to use FindShaders() or recursive traversal of the render tree to collect shaders. Remember however that those last techniques also suffer from certain limitations. FindShaders() works only on materials, cameras and lights, and recursive traversal of the render tree (as it has been presented in this article so far) will work only on materials, lights and overrides. For traversal of other trees you’ll have to make important modifications to your code. More on that in PASSES.

No matter how you collect shaders, you must test their class id against the one you’re looking for.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import win32com
 
c = win32com.client.constants
xsi = Application
xsiutils = win32com.client.Dispatch( 'XSI.Utils' )
oRepository = xsiutils.datarepository
 
sPhongCLSID = '{67120BBE-C98C-11D1-9723-00A0243E3672}'
 
# Get shaders of the selected material
oShaders = xsi.selection(0).findshaders( c.siShaderFilter )
 
# Iterate shaders
for oShader in oShaders:
 
	# Get current shader classid
	sShaderCLSID = oRepository.getidentifier( oShader, c.siObjectCLSID )
 
	# Compare classids
	if sShaderCLSID == sPhongCLSID:
 
		xsi.logmessage( oShader.fullname )

Dealing with texture projections, tangents, and similar shader parameters
Shader parameters that point to scene objects like texture projections, tangent properties, color at vertices, weight maps and the likes, deserve special attention. They are not dealt with using the typical means of evaluating and setting parameters, and may get you stuck easily. Let’s look at how to use each option.

The HasInstanceValue property allows you to know if you’re dealing with that kind of parameter. So if you use very generic code that handle any kind of parameter, that should be the first thing to check.

1
2

if oParameter.hasinstancevalue:
	# do something

The next thing to do is to find out to which scene object is this parameter pointing to. This is where it gets nasty. The SDK doesn’t provide any form of relationship between such parameters and the objects they point to. You have to tests every friggin object you suspect might be used!

What you can do, if you work with a material, is to use its UsedBy property get the objects using that material. Then, you have to find the appropriate cluster properties on those objects. Finally, you can test if those cluster properties are used by the parameter.

Let’s imagine we want to know the texture projections used by a shader parameter named oParameter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Get objects using this material
oUsers = oMat.usedby
 
# Loop objects using this material
for oUser in oUsers:
 
	# Loop its clusters
	for oCluster in oUser.activeprimitive.geometry.clusters:
 
		# Check if the cluster is a sample cluster
		if oCluster.type == 'sample':
 
			# Loop the cluster properties of the current cluster
			for oClusterProp in oCluster.localproperties:
 
				# Check if the cluster property is a texture projection
				if oClusterProp.type == 'uvspace':
 
					# Test if the parameter points to this object
					sInstanceValue = oParameter.getinstancevalue( oProjection )
 
					# If returns empty string, it means it does NOT point to that object
					if sInstanceValue != '':
						# do something

Be careful. The GetInstanceValue() method has a significant limitation: it allows you to test against properties of X3DObjects only. If you pass objects like groups or partitions to the GetInstanceValue() method, it will fail. You may pass the members of those objects for the method to succeed.

Setting the parameter to point to cluster properties is done exactly the same way. You have to know in advance what cluster property to use, and then run the SetInstanceValue() method.

The last SDK doc entries worthy of mentioning are IsSupportedInstanceValue (which allows you find out what kind of cluster property does the parameter supports).

MATERIAL LIBRARIES

We can’t talk of materials without talking about material libraries. The two go together. Let’s look at few ways to deal with those.

Getting all material libraries
The object model way:

1

oLibs = xsi.activeproject.activescene.materiallibraries

The command model way:

1

oLibs = xsi.findobjects( None, "{61782E14-9177-412e-BF9B-2B44B9A668DD}" )

Now be careful with the command model way. It may return an extra library that apparently lives in the TransientObjectContainer. If you run this:

1
2
3
4

xsi = Application
oLibs = xsi.findobjects( None, "{61782E14-9177-412e-BF9B-2B44B9A668DD}" )
for oLib in oLibs:
	xsi.logmessage( oLib.fullname )

It may print:

# INFO : Sources.Materials.DefaultLib
# INFO : library_source

I suspect that the second one is an instance of the first, to be used as a pointer to the current library. But what do I know ;-)

Getting a material’s library
If you need to get the library object from the material, simply use the Library property of the material object.

1

oLib = oMaterial.library

Looping materials from libraries
It’s very straightforward:

1
2
3
4
5
6
7

# Loop over all matlibs
for oLib in xsi.activeproject.activescene.materiallibraries:
 
	# Loop materials in the current library
	for oMat in oLib.items:
 
		# do something

MATERIALS

The majority of the work done with shaders will probably be done through materials.

Creating materials
As usual, there are several means for creating materials. If you want to create a material on an object, you can use the ApplyShader() command. This, unfortunately, doesn’t give you control the library the material is created in, it’s always the current library. Alternatively, you could use the AddMaterial() method. Since it’s the Object Model approach, it’s probably going to be faster, especially if the creation is done in a loop.

Personally, I prefer to create the material in a library, and then assign it to the target object. The SICreateMaterial() command allows you not only to specify the library, but also the objects that shall use this material. But it depends a lot on performance, I usually favor the fastest execution.

Assigning materials
If you don’t use the SICreateMaterial() command, you could use SIAssignMaterial() (which is a low-level version of AssignMaterial). You could also use the CopyPaste() command (which is printed when you drag and drop a material onto an object, but personally I prefer more explicit approaches.

Unassigning materials
There is no other way than to use the UnAssignMaterial() and SIUnAssignMaterial() commands.

Getting the material of an object
It may seem very straightforward to do that, but there are a few things to talk about. The first and foremost way to get an object’s material is to use the Material property.

1

oMat = oObject.material

This will work on X3DObjects, polygon clusters, groups, layers and partitions. Basically anything that supports material assignment. However, there is a chance the object it returns is not the one you’re looking for. The Material property returns the “current” material, or that is, the inherited material. If an object is in a group that has a material, the Material property will return the group material, not the object one.

If you’re looking to get the actual material of the object and ignore inheritance, you’ll have to go through the local properties of the object.

1
2
3
4
5
6
7

import win32com
c = win32com.client.constants
xsi = Application
 
for oProp in xsi.selection(0).localproperties:
	if oProp.type == c.siMaterialType:
		xsi.logmessage( oProp.fullname )

The LocalProperties approach will also work on any object that supports material assignment.

Getting the objects using a material
A material has the UsedBy property, which returns all objects using that material.

1

xsi.logmessage( oMat.UsedBy.getastext() )

The UsedBy property, however, has always suffered from severe limitations. In the past, it would return only X3DObjects. Now it also returns polygon clusters. However, it won’t return groups, layers and partitions using that material. Instead, it will print the X3DObjects and clusters that have inherited the material from the group/layer/partition.

If you want to find the groups/layers/partitions using that material, you’ll have to look the owners of the material. The first owner is always the material library. The other owners are the objects using this material. In the case of a material assigned to a group:

1
2
3

oMat = xsi.selection(0)
for oOwner in oMat.owners:
	xsi.logmessage( '%s - %s' % (oOwner.fullname, oOwner.type) )

Output:

# INFO : Sources.Materials.MatLib - library_source
# INFO : Group - #Group

Deleting materials
To my knowledge, there is no other way to delete a material than to use the DeleteObj() command.

Shotcuts to access material components
The object model offers a few shortcuts to retrieve data of a material. You should read the Material and Shader entries of the documentation to find out about those.

PASSES

Passes are special. They support shaders through their stacks. However, passes cannot be dealt like with like materials. Two situations come to mind, both being somewhat related.

In the first situation, if you take the script presented in “Storing the render tree into a data structure”, it will fail if you supply the pass object as the starting value for the function. Passes do not allow accessing shaders through its Parameters, unlike materials. So you have to do clever things to get stack shaders from the stack.

The second situation is the opposite: if you use the Root property of a shader to get to the, well, shader tree root, you’ll get the pass object. This is wrong, for the very same reason as the preceding examples, that is, passes do not expose shaders through their Parameters.

To make things worse, if you open the render tree with a pass selected, it looks like the pass is a materials and shaders plug directly into them. This is a lie. And to seal the deal, the render tree view shows only the first shader of each stack, even though the stacks support multiple shaders at the top level. Another lie. Fortunately, the Object Model helps solving those problems.

Accessing shader stacks from passes
There is no shortcut to access a pass stack. You have lookup the pass’s NestedObjects, using the stack name. Once you get the stack object, you can check its NestedObjects to see if there are shaders. This will return a collection of the “top” shaders of the stack.

Create a pass with an environment shader, selected that pass, and run this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

xsi = Application
 
aStackNames = [
	'Environment Shader Stack',
	'Output Shader Stack',
	'Volume Shader Stack'
]
 
# Get selected pass
oPass = xsi.selection(0)
 
# Iterate pass stacks
for sStackName in aStackNames:
 
	# Get the stack object
	oStack = oPass.nestedobjects( sStackName )
 
	# Check if the stack has shaders
	if oStack.nestedobjects.count > 0:
 
		# Iterate root shaders of this stack
		for oStackShader in oStack.nestedobjects:
 
			xsi.logmessage( oStackShader.fullname )

Unfortunately, you cannot use reliable string searching. Select the Environment shader you created. It should print this line in the History Log:

1

Application.SelectObj("Passes.Default_Pass.Environment", "", "")

Now, rename the shader to something already in use in that pass, like “Background_Objects_Partition”. Select the shader again. It should print this:

1

Application.SelectObj("Passes.Default_Pass.EnvironmentShaderStack.Background_Objects_Partition", "", "")

So now you got the stack name, probably to avoid name collisions in the pass name space. Because this behavior is not constant, how can you reliably use strings to find pass shaders? If Softimage reads this, I politely invite you to correct this by putting the stack name as at all times. That will save us, poor coders, lots of trouble.

Getting the “root” shader from a shader
As previously mentioned, the Root property of a shader returns the pass object, which can be incorrect depending on how close to reality you want the information to be. To me this is very incorrect. In this case, the “root” shader is a shader visible in the stack. Because you can put multiple shaders in a stack, it means that there can be an infinite amount of root shaders for the the pass.

Walking down the render tree (down being “away from the root shader”) is easy, but walking up is not so. I don’t know any fast, clever, or elegant way of doing this. The only constant is that no two shaders can be named the same way in the pass name space(1).

For the following chunk of code, do this:

• Put an Environment shader on the default pass.
• Open the render tree, and connect a Cell shader into the tex input of the Environment shader.
• Then, create a _2D_background_color shader (output shader)
• Create another Cell shader, and plug it in the bg input of the _2D_background_color shader(2). Normally, the second Cell shader should have been renamed Cell1.

To find the root shader for a given shader, I’ve written a sort of state machine that remembers in which stack and root shader it is walking down. Run this code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

import win32com
 
c = win32com.client.constants
xsi = Application
xsifactory = win32com.client.Dispatch( 'XSI.Factory' )
 
 
class PassShaderState:
 
	def __init__( self, sPassName, sShaderName ):
 
		# CONSTANTS
 
		# Name of the shader we're looking for
		self.passname = sPassName
		self.shadername = sShaderName
 
		# Stack names
		self.stacknames = [
			'Environment',
			'Output',
			'Volume'
		]
 
 
		# VARIABLES
 
		# Shader identification
		# All point to scene objects
		self.currentstack = None
		self.currentroot = None
		self.currentshader = None
 
 
 
 
	def getroot( self ):
 
		# Get the pass object
		oColl = xsifactory.createobject( 'XSI.Collection' )
		oColl.items = 'Passes.%s' % self.passname
 
		# Did we find the pass
		if oColl.count

Storing the pass shaders into a data structure
We’ve seen already how to store a material’s render tree into a data structure. The presented approach cannot be used without modifications for pass shaders, again because of the foggy relationship that exists between the pass object, its stacks and its root shaders. Here I will not present code to achieve this task (as my solution is extremely elaborate), but rather explain what approach I use to do it. My goal was to have the ability to re-create the pass shaders simply by reading a flat XML list of shaders.

With a material it’s simple: when you get to the material, you can create anything you want the same way, and plug anything you want. With shader stacks it’s different.

The data structure I presented above works, but will need extra informations. Each shader will have to be flagged as being a stack root shader or not. The reason is that creating stack root shaders requires can only be done through the SIApplyShaderToCnxPoint() command, while creating the shaders underneath use the CreateObjectFromPreset() command, presented earlier.

Root shaders should state to which stack they belong (including the pass name, of course). When creating shaders with SIApplyShaderToCnxPoint(), you must specify the shader stack. Having this information already available as a string will make it easy. Btw, in the data structure, store the Type property of the stack, not its Name.

CAMERAS

The camera is similar to the pass, with a significant difference: it has only one stack. Once the camera shader stack is accessed, code that handles pass shader stacks should work with the camera shader stack. A word of advice: while I’m not aware of any such plans from Softimage, it would be a good idea to design your code to assume that there might be more than one stack in a camera. Let’s imagine Softimage, in some near future, adds a new stack to the camera…….

LIGHTS

Lights can be handled pretty much like a material. For instance, you can traverse the light’s render tree using the same code we used with the material one, but pass it the light’s primitive:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

xsi = Application
 
def printShaderSources( oShader ):
 
	# Loop parameters of the shader
	for oParameter in oShader.parameters:
 
		# Check if the parameter has a source
		oSource = oParameter.source
		if oSource != None:
 
			# Check if classname of the source is a shader
			sClassName = xsi.classname( oSource )
			if sClassName == 'Shader' or sClassName == 'Texture':
 
				xsi.logmessage( oSource.name )
 
				# Parameter has a shader source,
				# call function again with that source
				printShaderSources( oSource )
 
# Call the function using the selected light's primitive
printShaderSources( xsi.selection(0).activeprimitive )

Output:

# INFO : soft_light
# INFO : soft_light

Additionnally, the light object (not the primitive) have a Shaders property. This will access the shaders connected into the primitive. If you want to access the soft_light shader (or any shader connected into the light’s primitive), use:

1

xsi.logmessage( xsi.selection(0).shaders(0).fullname )

OVERRIDES

Overrides are another beast. Their implementation looks and behaves similarly to other shader implementations in XSI, although there are several differences that need to be taken care of. Here we’ll talk about creating overrides by script.

Shader overrides
You’ve probably noticed that shader overrides use strings separated by dashes. I suspect this is because the dot character is reserved to namespace notation, having it in a parameter script name would break things. Also you deal with relative names, where the material name is kind of masked by “material”. For instance, if you override the Surface input of a material, the created parameter looks like “material-surface”.

If you want to re-create a shader parameter in an override, you’ll have to format that string a little.
First, replace the dashes by dots, obviously.
Second, you’ll have to find a material among the group/layer/partition members that has the parameter you want to override, and use the material name in replacement of “material”. So “material-surface” become something like “cylinder.Material.surface”.

Absence of members
The #1 problem, in my opinion, is that you can’t create an override group/layer/partition doesn’t expose the parameter you want to override. This makes re-creating overrides by script very difficult. I know 3 solutions to this:

• Save a preset of the override. Probably the most reliable way to do it, however it requires that you create the override at least once and store a preset. Another big advantage is that this approach works even if the group/layer/partition has no members to override.
• Create temporary objects. This is easy if you have to overrides parameters such as visibility or geometry approximation, but for shaders it can become extremely elaborate. Definitely consider other solutions.
• Wait for the group/layer/partition to be populated before attempting to create the override parameters. Better than #2, but still not 100% reliable.

Refresh issues
Another problem is that when you manage to create a parameter in an override, that parameter is not always immediately available through the object model. For reasons I don’t have a clue about, there are situations where if you try to reach the created parameter through the Parameters property of the override, it would fail:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

xsi = Application
 
# Get the selected override
oOverride = xsi.selection(0)
 
# Define parameter to override
sParameterName = 'viewvis'
sParameterFullName = 'cube.visibility.%s' % sParameterName
 
# Create the override entry
xsi.SIAddEntryToOverride( oOverride, sParameterFullName )
 
# Get the created override
oOverride.parameters( sParameterName ).value = True

The solution is that once the parameter is created, use a string to retrieve it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

xsi = Application
 
# Get the selected override
oOverride = xsi.selection(0)
 
# Define parameter to override
sParameterName = 'viewvis'
sParameterFullName = 'cube.visibility.%s' % sParameterName
 
# Create the override entry
xsi.SIAddEntryToOverride( oOverride, sParameterFullName )
 
# Get the created override
oColl = xsifactory.createobject( 'XSI.Collection' )
oColl.items = '%s.%s' % ( oOverride.fullname, sParameterName )
oParameter = oColl(0)
oParameter.value = True

FURTHER SCRIPTING

There are many more topics we could cover, including texture layers, OGLTextures, shader input type, the ProgID, etc. These are all things I’m not deeply familiar with so I’ll leave it to you to learn about those.

NOTES

(1) XSI 6.01 had this nasty bug. If you select the pass, open the render tree and start connecting shaders all over the place, they would all have a unique name. So far so good. But if you selected one of the stack shaders, open the render tree and connected shaders from there, you could name a shader the same as in another stack. In the end, it means that several shaders could have the same name in the pass name space. This was corrected in XSI 6.02.
(2) If your _2D_background_shader doesn’t expose a bg input, you can modify the spdl. Simply enable the texturable flag.
(3) The real value is “COMObject “unknown”", where ” are replaced by “smaller than” and “greater than” tags.

This article discusses some of the problems and solutions involved in exporting shaders from XSI, using custom tools and custom file formats.

THE INITIAL GOALS

At Big Bang I wanted the ability to write materials to XML files (and read them back, of course). This would serve two major purposes. First, it would offer a granular set of data, which could be re-used in different contexts. I could have used preset file instead of a XML file, but the second major purpose of the project prevented that: I wanted to be able to not only read the file, but also to make modifications in it if there was ever such a need.

To be honest I was quite disappointed that after I spent so much time and effort into this project, it turned out I needed to make such edits to material files only for about 20 of them (as of this writing, there are about 3,800 such material files in the pipeline). I could have also used the XML file at other things, like building templates for standard materials, using it for the approval of shading tasks, etc. But in the end that did not happen. However, the work I did for exporting materials could be used for other things.

THE CHALLENGES OF MATERIAL EXPORT

It didn’t take too long until I felt that exporting materials can be a rocky business. At first glance it seems very straightforward: select an object, run a script to export its material. In the material file, I wanted not only the entire material described, but I also wanted to list the image clips and the image sources used by this material. Plus, I wanted to know which scene objects are using this material, including geometry, clusters, groups and partitions. So that when I import the material, I could re-create it, as well as its image clips and sources, and apply it to objects using it if they are in the scene.

Next, I wanted the code to handle inputs that consisted of more than one object. For instance, given an input of objects (either geometry, partitions, clusters, or even materials), the code had to figure out what to export and do it right. I didn’t want the script to attempt to export the material of a chain, for example. Given that input management allowed many objects to be visited, and that some of these objects could use the same material, I had to keep track of which material had already been exported.

On top of the material, the image sources, the image clips and the objects using this material, I had to write the actual shaders to the file. Afterall the goal was to be able to re-create the material from an XML file, so I needed the list of shaders. One may think that to write shaders to a file, all that is needed is to recursively walk down the material’s Render Tree and, well, write the shaders as they are visited.

Not quite. Some shaders are connected into several other inputs. Unaware recursive traversal of the Render Tree meant that entire branches could end up being written several times. That was a waste of space and CPU cycles. Plus, if many branches are being repeated, how would the importing code know that it’s actually the same branch?

So I had to find a way to organise shaders with a unique “key”. At first I considered using their FullName. I was in for a big surprise.

In the Explorer, switch to Scene Root scope. If you iterate the Properties/LocalProperties of an object, find a material, and print its FullName, it will return the name of the material with the object’s FullName prefixed. Same if you select the material under the object. However, switch the Explorer’s scope to Materials. If you select the same material and print its FullName, then you get the name of the material prefixed with the library’s FullName, which is garanteed to be unique.

I call this last one the material’s “AbsoluteName”. There might be better terms for this, however I thought of it as browsing the file system, where there can be no two absolute file name for the same file (well, it’s possible, but let’s not get carried away).

It’s easy to work out the AbsoluteName of a material, even when you get the material from the objects owning it instead of the library. But to my knowledge, it’s impossible to use the same approach for shaders under this material. The FullName of a shader changes depending on the parameter it is being read from. For example, if you have an Image shader connected into an input of a Blinn shader and the input of an another shader, logging the Image’s FullName when traversing the Render Tree will return ..Blinn.Image and …Image.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

xsi = Application
 
# Get selected object
oSel = xsi.selection(0)
 
# Get selected object's material
oMat = oSel.material
 
def walk( oShader ):
	xsi.logmessage( oShader.fullname )
 
	# Iterate the shader parameters
	for oParameter in oShader.parameters:
 
		# Get the parameter source
		oSource = oParameter.source
 
		# Check if we got a source
		if oSource != None:
 
			# Get the classname of the source
			sClassName = xsi.classname( oSource )
 
			# Check if the classname is a shader
			if sClassName == 'Shader' or sClassName == 'Texture':
				walk( oSource )
 
# Loop over material parameters
walk( oMat )

Prints:

# INFO : sphere.Material
# INFO : sphere.Material.Blinn
# INFO : sphere.Material.Blinn.Image
# INFO : sphere.Material.Blinn.Image
# INFO : sphere.Material.Blinn
# INFO : sphere.Material.Blinn.Image
# INFO : sphere.Material.Blinn.Image
# INFO : sphere.Material.Cell
# INFO : sphere.Material.Cell.Image

So this means you can’t use the shader FullName as a unique key. If you can’t rely on the shader’s FullName, then how can you make sure that you have not visited this shader already? You could possibly use the shader’s Name. Afterall, in a material, all shaders have a unique name.

But instead of using the names as the key, I preferred to give them a unique ID number (unsigned integer). Image clips would also receive such an ID. When writing the shader parameters to the file, if they had a shader or an image clip connected, it would use the previously defined ID of the shader/image clip. This meant that before writing anything to the XML file, all shaders and image clips would need to be visited. Ultimately, a map of all shaders, based on their ID and their name, could be established.

This resulted in somewhat complex dictionaries and lists, which were hard to maintain and debug. Nonetheless, I managed to make the material export work reliably. It was slow (since it’s uncompiled code), but it was totally reliable.

I should add that handling parameters such as texture projection pointers posed a challenge worthy of talking about. Those parameters are not like other parameters, they require a different handling. Of course all that is needed is available in the SDK, still, I thought I’d mention it to those attempting at writing shaders to file.

BEYOND MATERIALS

All went smooth for many many months, until we started looking into lighting and rendering. Then it occured to me that I needed the ability to export passes, so they could be re-created later on. I thought that since I had code that could write shaders to file, then surely I could reuse this code for other things than materials: overrides and pass shader stacks. Well, that’s what I thought. But my code was built entirely around the material export, so I could hardly use it for overrides and pass stacks without making drastic modifications.

Pass shader stacks
There are two major problems with pass shader stacks.

The first problem is that from all practical purposes, passes have the appearance of materials. If you select a pass and open the Render Tree, you’ll see the pass object being displayed as if it was a material. In reality, that is not quite right.

For instance, you can iterate the parameters of material, and effectively traverse the Render Tree from there. That is not happening with passes. First, passes do not have a Parameters property, and second, they do not expose shaders in any way. So the Render Tree display is highly misleading, and I had to write code to handle passes differently than materials. In short, I did not find any quick and easy way to get the stack shaders. This is illustrated by this stripped down method that collects the stack “root” shaders (see next paragraph):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

def addpass( self, oPass ):
 
	aStacks = [
		'Environment Shader Stack',
		'Output Shader Stack',
		'Volume Shader Stack'
	]
 
	# Iterate pass stacks
	for sStack in aStacks:
 
		# Get the stack object
		oStack = oPass.nestedobjects( sStack )
 
		# Check if the stack has shaders
		if oStack.nestedobjects.count > 0:
 
			# Iterate root shaders of this stack
			for oStackShader in oStack.nestedobjects:
 
				# do something with shader

The second problem is that in a pass, there can be multiple shaders living at the top-level of a stack (which I shall call “root” shaders). For instance, if you apply two volume shaders to a pass and then open the Render Tree of that pass, you’ll only see the latest volume shader. That’s another misleading aspect of the pass’s Render Tree. So it can be assumed a pass shader stack can have multiple “root” shaders, and each of them is entirely valid and must be exported if you want to fully export the pass shader stacks. The upshot is that the pass object act as a name space, just as a material: among all the shader stacks of a pass, no two shaders can share the same name. This is great, but that doesn’t solve our problem of multiple root shaders for a same stack.

Also, when importing a pass shader stack, using the typical ways of creating shaders and plugging them afterward worked for all but the “root” shaders. To import pass shader stacks, each shader had to have a “stackroot” flag in the XML file. When meeting such a flag, the script would not simply create the shader and plug it later, it would have to run the command that creates root shaders in stacks. This command is the only way to not destroy other existing root shaders!

Overrides
Overrides pose an entirely different set of problems.

They are not materials, and they are not pass shader stacks, yet they can host complex networks of shaders. There also can be more than one override per partition! An override could not be handled as a material nor a pass. Materials, in my framework, were meant to be exported as single files, overrides needed to be exported in a pass file, along the shader stacks, partitions and render options. An override doesn’t have things like the material’s UsedBy property, it is a partition property.

Also, overrides on partitions are visible only in the current pass. I thought that this was case only in the GUI, but found out that this extends to the scripting interface. If you iterate the properties of a partition not of the current pass, you’ll never catch that partition’s overrides. The only solution was to use a low-level command such as FindObjects() to collect all overrides, which works, and then organise them by pass and by partition, to later write them to file along the partition that’s being written.

Using FindObjects() to collect overrides returned a lot more overrides that what I expected. All these overrides were named VisibilityOverrideXX (“XX” being a number). I basically found out that group objects (groups, layers, partitions) implement the parameter inheritance via an override. This override is created when a parameter of the group object is not set to “no effect on members”, but remain invisible at all times, except to commands like FindObjects(). This can be tricky, because you don’t want to export this override. However you never know when a user will create an override to disable a parameter like “viewvis”, and name this override “VisibilityOverride”. The only solution when such an override name is encountered is to check that the partition parameters all set to “no effect on members”.

But the biggest problem with overrides came with the import. This article is not about shader import (which may be covered in another article), but few things are worth mentioning.

You can’t add a parameter to an override if the parameter cannot be found in the partition members. The only way to add a parameter to an override is to use SIAddEntryToOverride(), which requires a parameter FullName string. My solution was not very elegant, and is not garanteed. Basically the code tries to find the parameter among the partition members. If find its, then good, the entry can be added. Otherwise, you’re out of luck. Materials are also tricky because the override parameter name doesn’t exactly reflect the real shader parameter FullName that has to be overridden. With elaborate string manipulation this can all be worked out, but this is slow and like I said, not very reliable.

Another annoying thing is that an entry added to an override cannot be accessed right away via the object model. At least that was the case in XSI 5.11 (I tried in 6.01 and it seems to work). For instance, the following code would raise an error:

1
2
3
4
5
6
7
8
9
10
11

xsi = Application
 
# Get the selected override
oOverride = xsi.selection(0)
 
sParameterName = 'viewvis'
sParameterFullName = 'cube.visibility.%s' % sParameterName
 
xsi.SIAddEntryToOverride( oOverride, sParameterFullName )
 
oOverride.parameters( sParameterName ).value = True

So to get back the added parameters I had to use strings.

Cameras and lights
I have not talked about cameras and lights so far, simply because as the time of this writing, the need to export their shaders never arose.

In our pipeline, cameras and lights are exported as full-fledge models. Their importance is rather low compared to other models (like characters, for instance), so that exporting their network of shaders was not felt as a necessity. Also, cameras and lights are very light-weight compared to other models, so managing them always as models posed no particular problem.

My belief is that lights can be handled not too differently than materials. The catch word is “too”. The light primitive is a bit like a material, it has inputs for connecting shaders. But a light is not a material, and I’m affraid that handling lights would require yet another dedicated wrapper to hide the real nature of the light.

In the case of camera shaders, my guess is that they behave in a similar fashion as pass shader stacks do. The camera shader stack lives right under the camera primitive, and appears to be accessible only through the NestedObjects property. Just as a pass shader stack, the camera shader stacks accepts multiple shaders at its top level, but when you open the Render Tree, it shows only the first shader of the stack.

THE SHADER NAME SPACE

Obviously, trying to adapt the existing material export code to also export pass shader stacks and overrides turned out to be very tedious. So I had to make drastic changes to the framework, and implement a new interface: the shader name space.

I consider the material, the override and the pass shader stack to be shader name spaces. That is, a space where a collection of shader names live. A material, a pass and an override as all shader name spaces. Lights and cameras are also shader name spaces. As of this writing, however, my framework does not include anything to export and import lights and cameras.

The object used as the shader name space is not necessarily the “root” shader, that is, the shader of the tree where all others ultimately plug in. Materials and overrides are both name space and root, but in the case of pass shader stacks, each “root” shader of a stack is a shader name space root. So a shader name space can have multiple roots. In the shader name space, the exact nature of the name space is not really important, as it is hidden by the shader name space interface.

Treating data that way made things far more easier to work with. Low-level functions would write to file without knowing the context of use, while wrappers would handle all the specificities of the name space.

PROPOSITION OF IMPROVEMENT FOR MATERIALS

All of this hassle with shader export and shader name space made me think about how it could have been a lot easier. I had to write code to handle all types of shader name space, which resulted in significant amounts of code and increased opportunities for bugs to make it through. The shader name space is in fact an attempt at implementing something that, I believe, should be in XSI: new kinds of materials.

Lights, passes and cameras should implement a material. I don’t see any reason why not.

- Imagine if light, pass, and camera materials could be managed from the Explorer, just like other materials. Light materials could use an orange color, while pass materials could be green and camera materials could use a gray color. The color is not important, but this mean they could a lot easier to manage, especially in large amounts. They could be organised in libraries, exported, and referenced.

- The mess of pass and camera shader stacks would not be visible anymore.

- Sharing materials among lights, passes and cameras would be a breeze. Increased reusability.

- Programming-wise, they would make the process very homogenous. No matter if you select a light, geometry, or a pass, you can always use its Material property to access the material. Simple, straightforward and consistent.

I don’t really see where overrides would fit in this design. Perhaps they could be left as they are, but at least it’s only one special case to handle, not every case.

I’m strongly against the idea of having a “super” material. For instance this material could be applied to anything, however it would expose only parameters suitable for the context it’s being used in. When applied to different kinds of objects, I hardly see how it would be easy to work with. It would make scripting very inconsistent and require the same kind of tedious handling I have been discussing in this article.

Get a material and a passes file here: Material and passes XML files

ABOUT DATA INPUT MANAGEMENT IN MATERIAL EXPORT

If you think that this section title sounds redundant, you are right. I have written an article on XSI-Blog about this very subject. I talk again about it because it really is during the development of this project that the importance of data input management struck me. I think that the data input management is one of the most fundamental aspects of any larger programming project.

I wanted the material export to be easy for the user. I wanted the interactive input to be simple and predictable. Users tend to favor the simplest ways of doing things. Given a model, they would expect to export everything related to this model. They don’t really care about the details, but they know that if all components of character lives under a unique model, then they have to be able to do things by simply handing the model to the script (via selection or picking, for example). However, exporting everything under a model can generate lots of data and take considerable time, so I wanted to give the users the ability to “focus” the export: given a selected object, it would export only the object’s material(s). Or the user could even select the material and export it. Painless, fast and predictable.

But giving the users various ways of exporting things meant that I had to write considerable code to manage the data input. The code that wrote to XML files was dumb, but lives below thick wrappers that would manage all the data input from the user. When the materials to export would reach the actual exporting functions, it would have to be guaranteed to be adequate.

Here is a little chart to show the framework design to cope with this task.

- call from the user
– user data input management (objects, materials…)
– final data input management (by type of data)
– export of shader name spaces
– fetch data from structures
– write to file

The difference between “user data input management” and “final data input management” is that they used a different interface. Both interface would handle data, but with different purposes in mind. Ultimately, they would end up populating data structures that, too, served specific puroses.

The first layer of input management handled the data provided by the user to make sure it was acceptable for the export and/or the import. For example, it ould make sure that only materials, overrides and passes could make it through for an export. The interface used to perform this task is an interface used throughout the entire framework to take care of all initial data inputs.

That interface, that I called the “Chapter” (as in a chapter in the biker world) would know everything about the context: is the user exporting or importing, is he exporting/importing in a shot or in an element, things like that. Through a system of promotion and demotion, the Chapter would store “suitable” primary data into structures that could be later accessed by everyone else.

The second layer of input management, “final data input management”, as well as “fetch data from structures”, used a more specialized interface, dedicated to shader export. Its job would be to hide all the complexities in the differences that exist between materials, overrides and shader stacks.

In “final data input management”, it would extract the final data from the “suitable” primary data coming from the Chapter, and store it in data structures. In “fetch data from structures”, it would read this final data on-demand as the script goes on. The interface would make the storing and reading of that data completely homogenous, no matter if dealing with a material, a pass, or an override. While resulting in very long code (the entire interface is implemented as nested classes), it made the overall data handling incredibly easy.

PLEASE NOTE: The following python scripts require this procedure to work properly.

Facial Animation

A thread started at XSI Base simply named, facial animation (questions), many facial rigging and animation concepts were shared. The two concepts discussed mostly were your traditional shape animation controlled by in scene controllers (a la Osipa) and also using Control Splines or curves with many complex rig elements that give you the desired motion. At the end of the day shape animation gets you pretty far with many character types ( realistic and stylized ) and setup time is pretty fast. The setup time is also important here, Softimage considers this a feature for FaceRobot that they market and rightfully so. Time is money, producers know this as should you! So if you will hear me out I am going to explain a way for you to continue to use shape animation and still get the low level control over subtle face movements.

The Static KineState

What is the Static KineState? I am sure anyone spending any amount of time rigging knows something about it. So lets define it for those that don’t.

The Static KineState indicates that an envelope is applied to the skeleton element. The StaticKineState is the initial position of the skeleton when the envelope was applied, and is used for envelope calculations.

If this property is storing these initial values then I must be able to change them. This is the gem that makes this rig work.

Dorritos

Now we are going to make the rig. This is not intended to be a tutorial so I apologize if I miss steps, all the project files are included at the bottom. So lets go over the rig!

I am starting with Primitive>Character>Face Man and I first made a quick “smile” shape, followed by a typical neck, head, and jaw for the character. I used nulls instead of joints for simplicity sake.

Now I am going to make a clone of this enveloped head and immediately remove the duplicated shape cluster, envelope cluster, and the “ShapeWeights” property. The clone uses the “CopyOp”, with this we get all the deformations from the first head which include the envelope deform and shape deform. Now we need to setup the local deformers for the cloned mesh.

These local deformers use an “Object To Cluster” constraint. I like to use edge clusters but you could use any SubComponent you choose. So I picked an edge in the corner of the mouth and ran this handy script that creates the cluster, the object, constrains them, and makes the local deformer. You need to select a component on the original head, and run the script.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

#imports
import win32com.client
from win32com.client import constants
 
#globals
xsi	= win32com.client.Dispatch( "XSI.Application" ).Application
xsiPrint = xsi.LogMessage
 
def setupDorrito():
	if xsi.Selection < 1:
		xsiPrint("Select an component!",constants.siError)
		return False
 
	root = xsi.ActiveSceneRoot
 
	#create cluster constrained null, setup its look
	clsCnsNull = root.AddNull("clsCnsNull")
	clsCnsNull.primary_icon.value = 0
	clsCnsNull.size.value = 0.1
	clsCnsNull.shadow_icon.value = 7
	clsCnsNull.shadow_colour_custom.value = 1
	clsCnsNull.B.value = 1
	clsCnsNull.G.value = 0.5
 
	#make cluster from selection
	subComponent = xsi.Selection(0).subComponent
	cnsCls = subComponent.CreateCluster("cnsCls")
 
	#constrain object to cluster
	cns = clsCnsNull.Kinematics.AddConstraint("ObjectToCluster",cnsCls)
	cns.tangent.value = 1
	cns.dirx.value = 0
	cns.diry.value = -1
	cns.upvct_active.value = 1
	cns.upx.value = 1
	cns.upy.value = 0
 
	#make dorrito
	dorrito = root.AddNull("dorrito")
	dorrito.primary_icon.value = 0
	dorrito.size.value = 0.2
	dorrito.shadow_icon.value = 8
	dorrito.shadow_colour_custom.value = 1
	dorrito.G.value = 1
	dorrito.shadow_offsetX.value = 0.1
	dorrito.shadow_scaleX.value = 0
 
	clsCnsNull.AddChild(dorrito)
	dorrito.kinematics.local.transform = XSIMath.CreateTransform()
 
setupDorrito()

The result…

At work we call this controller a “Dorrito” because when the first “on the face” rig came out, one of our animators, Jason Taylor, started calling it that and it stuck. So my controller is a flat pyramid that looks like a Dorrito, so I suggest you do the same :) Now I will add an envelope to the cloned mesh and choose this Dorrito as a deformer. I now need to paint the cloned mesh’s envelope. The way I do this is add another deformer to the deformer list, set all the points to 100 % of this new deformer, and then choose the Dorrito and paint it’s influence. Once I am happy with the deformation I just remove the extra deformer from the envelope and I get zero weights except for where I painted the Dorrito’s influence. This deformer moves with the cluster constrained null, but it causes this nasty double transform when I rotate the head!

Why is this happening? Because you have the first envelope on the original head which is deforming the points based on the transformation of the deformers (neck, head, and jaw). Then you have a “CopyOp” and another envelope above that is getting transformed by the same movement so XSI just does it twice! What you want to do is subtract that first envelope transformation from the second envelope transformation. The Static KineState gives you access to that intial position. If you take your deformer’s Static KineState property and set it’s parameters equal to the global transform parameters of your cluster constrained null you will effectively be constantly reseting the deformer’s initial position. Here is a script to setup the expressions between the cluster constrained null and the local deformer. Just select cluster constrained null first, then the Dorrito.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

#imports
import win32com.client
from win32com.client import constants
 
#globals
xsi	= win32com.client.Dispatch( "XSI.Application" ).Application
xsiPrint = xsi.LogMessage
 
def setupStaticState():
	defList = []
	clsList = []
	for i in xrange(0,len(xsi.Selection),2):
		clsList.append(xsi.Selection(i))
		defList.append(xsi.Selection(i+1))
 
	for a,b in zip(defList,clsList):
		defKineState = a.Properties("Static KineState")
		clsKine = b.Properties("Kinematics")
 
		defKineState.orix.AddExpression(clsKine.FullName + ".global.rotx")
		defKineState.oriy.AddExpression(clsKine.FullName + ".global.roty")
		defKineState.oriz.AddExpression(clsKine.FullName + ".global.rotz")
		defKineState.posx.AddExpression(clsKine.FullName + ".global.posx")
		defKineState.posy.AddExpression(clsKine.FullName + ".global.posy")
		defKineState.posz.AddExpression(clsKine.FullName + ".global.posz")
 
setupStaticState()

Now you can rotate the head or jaw and the deformer just rides the mesh, you can even use shape animation and the deformer just rides on top of that with no double transform.

Viewport Capture

Closing

There are many ways to rig a face and none should be discarded from any rigger's toolbox. I hope other riggers will get some use out of this technique and will share their work with us. Before I go, I want to thank my rigging supervisor Remi McGill for suggesting the usage of the Static KineState and Blur for allowing me to share with the community. Below are the project files which includes the scripts. Thanks for reading!

Project Files

Let’s get a curve

We start by taking a poly strip, with a 100×1 subdivisions. This will be our “drawing” table. We then make a cluster of the whole set of points, and give it a weightmap. The range for the weights is set as wide as possible (-100, 100) to allow for both large positive and negative values. We then apply to the grid a custom property with a profile function curve, which you can then shape as you wish.

Here is a script that will do the steps mentioned above.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

function CreateGrid()
{
    //create a poly strand, 100x1
    var grid = CreatePrim("Grid", "MeshSurface", null, null);
    SetValue("grid.grid.ulength", 10, null);
    SetValue("grid.grid.vlength", 1, null);
    SetValue("grid.polymsh.geom.subdivu", 100, null);
    SetValue("grid.polymsh.geom.subdivv", 1, null);
 
    //create the cluster
    SelectGeometryComponents("grid.pnt[*]");
    CreateCluster(null);
    //apply a weightmap
    CreateWeightMap(null, null, "Weight_Map", null, null);
    SetValue("grid.polymsh.cls.Point.Weight_Map.red", 0, null);
    SetValue("grid.polymsh.cls.Point.Weight_Map.blue", 0, null);
    SetValue("grid.polymsh.cls.Point.Weight_Map.green", 0, null);
 
    //allow for large min and max weights
    SetValue("grid.polymsh.cls.Point.Weight_Map.weightmapop.wmin", -100, null);
    SetValue("grid.polymsh.cls.Point.Weight_Map.weightmapop.wmax", 100, null);
 
    return grid;
}
 
 
function ApplyProfile(grid)
{
    var oCPSet = grid.AddProperty("CustomProperty", false, "ProfilePSet");
    var oFCParam = oCPSet.AddFCurveParameter("ProfileFC");
 
    var oFCurve = oFCParam.Value;
 
    oFCurve.SetKeys(new Array(0, 0, 0.25, 1, 0.5, -0.5, 0.75, 0.8, 1, 0));
}
 
var grid = CreateGrid();
ApplyProfile(grid);

Sampling the curve

This is done by the following script.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

function SampleFunction(pSet)
{
    var par = pSet.NestedObjects(0);
    var fC = par.value;
 
    var pArray = [0,0];
    var vArray = [0,0];
 
    //fcurve min and max range
    var rangeMin = 0;
    var rangeMax = 1;
 
    var range = rangeMax - rangeMin;
 
    var x, y;
 
    //number of samples, equal to the grid number of points along x
    var nbSamples = 100;
 
    for (i=0; i< =nbSamples; i++)
    {
        //i-th column of points
        pArray[0] = i*2;
        pArray[1] = i*2 + 1;
 
        x = rangeMin + range * (i/nbSamples);
        y = fC.Eval(x); //value of the function at x
 
        vArray[0] = vArray[1] = y; //values for the weight map
 
        //set the weights for the i-th column of points
        PaintWeights("grid.polymsh.cls.Point.Weight_Map", pArray, vArray, 1, 0);
    }
}
 
//select the ProfilePSet first
var profilePSet = selection(0);
SampleFunction(profilePSet);

You just have to take care of setting the current range min and max correctly and then run it with the ProfilePSet. The script will simply sample the curve with the same rate as the grid subdivisions along x. The grid has 101 column of points along the x. We take the corresponding function values and stick them on the weightmap. Note that we’re using 100 samples, but we could have used much more for both the grid and the sampling rate.

Plotting the weightmap

We apply a color sampler lightmap shader. The input color to be sampled comes from a scalar lookup of the weightmap.

The writable map must be a hdr one (float .ct is my choice), in order to allow for large positive and negative values to be stored. Only the X resolution matters, since we are basically plotting a mono dimensional texture. The map is applied with a xz projection over the grid. You now just need to fire a tiny render region to have the lighmap written.

Reusing the map

As said, the map is one dimensional, so only the u matters when you look it up. So, if you pick a share vector node and connect it to an image lookup, the x coordinate of the vector acts as the input you are remapping by the original function curve. In this example, the lookup feeds the displacement, being the value to be remapped coming from a standard uv projection over the new grid.

What is important is to remember the range the function was originally sampled over, that must match the expected range of the value (the u coordinate in this example) you are going to remap.

Sampling a scripting function

As mentioned, you can also use this approach to paint any math function provided by your scripting function. Instead of using a function curve, you can simply loop and evaluate the desired function.

For instance, this is how you sample and weight paint a sin function in the -pi +pi range:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

function SampleSin()
{
    var pArray = [0,0];
    var vArray = [0,0];
 
    var rangeMin = -3.14159;
    var rangeMax = 3.14159;
 
    var range = rangeMax - rangeMin;
 
    var x, y;
 
    var nbSamples = 100;
 
    for (i=0; i< =nbSamples; i++)
    {
        pArray[0] = i*2;
        pArray[1] = i*2 + 1;
 
        x = rangeMin + range * (i/nbSamples);
        y = Math.sin(x); //value of the function at x
 
        vArray[0] = vArray[1] = y; //values for the weight map
 
        PaintWeights("grid.polymsh.cls.Point.Weight_Map", pArray, vArray, 1, 0);
    }
}