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’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.

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

You know that XSI automatically recognizes plugins when a proper file is putted under a folder like this: [workgroup or user]\Application\Plugins. We don’t need to specify anything else. Very clever and very useful especially for sharing plugins with all your colleagues.

You also know that Python can find modules and other Python scripts when they are in the same path as the file which is importing them or in a folder specified in the pythonpath. This means that if we set the pythonpath from within XSI and add to it some specific folders from our workgroups, we’ll be able to import Python files or modules in XSI (if it is connected with the workgroups) in every computer in our company, just like the XSI plugins do.

The First Step: Create An OnStartup Event

The first thing we need is create an event, a siOnStartup event, and set properly the pythonpath when XSI start.

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

# Purpose:
# Scanning all the Workgroups installed and put in the Python Path all the ...\Application\Plugins\PythonModules folders we will find.
 
import win32com.client
from win32com.client import constants
 
null = None
false = 0
true = 1
 
def XSILoadPlugin( in_reg ):
in_reg.Author = "Daniele Niero"
in_reg.Name = "Set Python Path Plug-in"
in_reg.Email = ""
in_reg.URL = ""
in_reg.Major = 1
in_reg.Minor = 0
 
in_reg.RegisterEvent("SetPythonPath", constants.siOnStartup)
#RegistrationInsertionPoint - do not remove this line
 
return true
 
def XSIUnloadPlugin( in_reg ):
	return true
 
def SetPythonPath_OnEvent( ctxt ):
	import sys
	wkgrLocations = Application.WorkGroups;
	for wkgr in wkgrLocations:
		workgroupLibFolder = XSIUtils.BuildPath( wkgr, "Application\\Plugins\\PythonModules" )
		if workgroupLibFolder not in sys.path :
			sys.path.append( workgroupLibFolder )
	userLocation = Application.InstallationPath( constants.siUserPath )
	userLibFolder = XSIUtils.BuildPath(userLocation, "Application\\Plugins\\PythonModules" )
	if userLibFolder not in sys.path :
		sys.path.append( userLibFolder )
	Application.LogMessage( sys.path, constants.siVerbose )
 
	# Return value is ignored as this event can not be aborted.
	return true

So, what did we do exactly? We have just scanned all the workgroups installed (and the user folder as well), built a path like this WorkGroup\Application\Plugins\PythonModules and appended it to the pythonpath list.

The good thing is that all the paths added to the sys.path will be removed when XSI is closed. Helping us to keep the pythonpath clean.

At this point, if we have a PythonModules folder in the Plugins folder in one of the workgroups connected with XSI, we are able to just import every file or modules saved in this PythonModules folder. Since in your company everyone have the workgroups correctly connected, they are able to import a python file or module written by someone else, without specifying or doing anything, just like standard XSI plugins!

The first test and utility python file

The first test we can do is create a file that exposes, once imported, some common and useful stuff we need when we use Python in XSI.
This file could be something like this:

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

import win32com as win
import win32com.server as winServer
 
from win32com.client import constants
from win32com.client.dynamic import Dispatch
from win32com.client import Dispatch as ComObject
from win32com.server.util import wrap
 
App = Dispatch( 'XSI.Application' ).Application
XSIFactory = Dispatch( 'XSI.Factory' )
XSIMath = Dispatch( 'XSI.Math' )
 
null = None
false = 0
true = 1

Save it as MyGlobals.py and put it in a PythonModules folder. Open XSI and just test if everything work writing just this few lines in the script editor:

1
2
3
4

from MyGlobals import *
 
App.LogMessage("note that App works, it is a global variable now!")
anXSICollection = ComObject("XSI.Collection")

If you don’t have errors form this simple testing code it means we are ready to move on the next step and create a complete class that can help us to handle a GenericProperty.

It’s my first post in here, so I take the opportunity to thank Patrick for this great XSI site!

You’ll find here some nice discoveries I made trying to use wxPython inside XSI. For that I will assume that you, dear Reader, have some knowledge of Python and UIs…

Animal Logic is also kindly giving you an example XSI Plugin that should be a good starting point if you want to implement a wxPython interface in XSI.

I apologize in advance for the technical and boring stuff ahead… it’s the unfortunate price to pay to get nice and shiny UIs!

You can download the plugin here.

But why would one do that, Custom Properties should be enough?

Mainly, the absence of a Tree widget, the clunkiness of the Grid widget, the need for finer control on callbacks for complex UIs, the difficulty of having session-persistent UI (ones that don’t get trashed on a New Scene).

The main goal of being able to write wxPython UIs inside XSI is for pipeline tools. I would not try to do better than Softimage for animation controls for example. But when it comes to streamline your pipeline, having consistent UI across your applications will save a lot of development time and user frustration.

Prerequisites

• XSI version 5.11 or 6
• WinXP 32 (win2k supported)
• Python (2.5 recommended, 2.4)
• pywin32 210
• wxPython (2.8.0.1 recommended, older supported)

A look at the plugin!

In the Python XSI plugin called wxPythonXSIExplorer.py I implemented a really crude XSI Selection Explorer. This is an highly useless tool, but it shows how this is possible to nicely interact with XSI using a set of basic wxPython widgets. Please consider the explorer itself as a proof-of-concept tool!

The interesting part of this plugin is the class called XSISubFrame. This is the class that implements all the gritty details described below, and I highly recommend you start your new wxPython XSI frame by looking at how I inherited from this class to create the XSIExplorerFrame. And how I use the XSISubFrame.create static factory method to create a new instance of the explorer.

I also implemented a SelectionChange event to detect the selection change in all the running instances of the wxPython XSI Explorer. Unfortunately there is no general hook for data change in XSI so if you move an object, the parameter value won’t update in our explorer.

And now for the gritty details…

The base trick to get a wxPython frame nicely displayed inside XSI, meaning on top of the XSI main window, but behind other XSI views when they have the focus, is to create the main frame as a child of the XSI top-level window. And for that we need to get its MS Window Handle.

The pywin32 package is here to help us: we can use it to list all the running windows and filter them by process ID, then pick the one which names begin with SOFTIMAGE. It sounds like a hack, but it’s just a small hack, believe me, MS Windows programming can get far more hacky than that!

The real magic happens when you use the AssociateHandle method on a dummy wxFrame so that wx believes that the XSI top level window is an actual wx window…

Then we just create our own sub frame using the wx.FRAME_FLOAT_ON_PARENT flag, which does what we want.

Then don’t forget to call DissociateHandle on your dummy frame, if not, XSI will not get some critical events anymore, like EVT_CLOSE, meaning you can’t close XSI anymore…

You will also need to do some cleanup when closing the wx window. The main problem is that wxWindow::Destroy does not destroy the top level window, it just waits for the
wxApp to destroy it on it’s next event loop. But as we don’t have a wx loop running, we need to destroy the top window by hand using the win32gui module again.

Some warnings!

wxPython is great, but it can crash easily if you do something wrong. In XSI 6 where there is no standard output from Python displayed in the script logging window (as there is in 5), it’s better to handle all exceptions, and display them yourself, or you might miss some important message from wxPython that causes a crash in the app (see line 370 of the plugin).

This is Windows-Only stuff for now!

Fortunately for Windows users, the wxWindows framework uses standard MS Windows event loop, and wxPython integrates amazingly well inside XSI. I haven’t tried under Linux, but the big problem over there is that wxWindows is using GTK as its UI framework, and I don’t think MainWin and GTK will go very well together unless Softimage builds a version of wxMSW using their version of Mainwin and give it to us…

BTW, wxPython works well in Maya as well, using the still experimental python for Maya plugin from cgkit, meaning that mixed pipeline could use the exact same UI in XSI and Maya!

Some native widgets have been “hacked” by Luc-Eric and his team to look better, the base TextCtrl is one of them. If you use it, its background will never refresh at all. I didn’t find an easy way of making it refresh. But you can get a nice text control by using the TE_RICH2 style, which has not been hacked. I provide a class called XSITextCtrl in my plugin that sets the style automatically as well as the background color.

Modality is a problem… The problem is that wx and XSI do not know well each other. If a wx dialog is shown modal, you can still work in XSI, and if a XSI dialog is shown modal (lik a new scene prompt), you can still do stuff in wx. And that could be really dangerous!

I worked around it by providing a custom showModalDialog method that disactivate the XSI top level window while the wx modal dialog is shown. And I implemented a EVT_ACTIVATE event to detect if there is a modal dialog running in XSI and I disable the content of the wx activated window until the top level window is activated.

This is not perfect, but it gives the right functionality!

Conclusion

This is surprisingly possible to seamlessly run wxPython UIs inside XSI!

I hope you will find some use to this and push Softimage to support this unknown feature, especially under Linux.

Have fun!

Aloys Baillet
R&D, Animal Logic

It is, of course, more useful than just an example as anyone who’s used Maya’s CommandPort can tell you. The C# example is cleverly wrapped in a timer event, allowing it to run in the background and quietly check for a connection every few seconds. More for reasons of clarity than anything else I’m just going to wrap this up in a function and let someone else decide how best to use it but I will get a little bit into timeouts and how to handle the hang you can get if there’s nothing at the other end.

Python is a really good example of just how sensible it was to use good existing scripting languages rather than writing bad new ones. You not only get the language for free, you also get most of the Open Source community too and with Python that means quite a lot of modules, allowing you to do more stuff than you could shake a stick at in a lifetime of stick shaking.

I’d done stuff like this before in Perl and C but not Python and I was interested in how long it was going to take to do this. As it turned out, around 20 minutes, which is pretty good but more testament to the other thing you get for free with Python – shedloads of free examples – than any skills I may have.

Python is pretty good at wrapping complicated stuff up and making it easy to use and this is no exception. To read something from a port the sequence of events is:

• Create a socket
• Bind to the socket
• Listen on the socket
• Accept the connection
• Read whatever’s being sent from the other end
• Optionally send something back
• Close the connection

This is all fine and dandy, except that if there’s nothing at the other end then the Accept hangs until there is. If nothing ever tries to connect we get a nasty hang that’s not easy to get out of. So we could do with something that can peek at the socket and see if there’s something there. Such a thing is a thing called “select”. In generic terms Select() is used to check any kind of file that’s open for reading to see if there’s something to read and, at least of grownup operating systems, a socket is treated in the same way as a file. We call select() on the socket just after we start listening. If select returns a list that isn’t empty then someone’s knocking at the other end and it’s safe to go ahead. If it’s not we ignore the accept call and just return nothing and bingo! no hang.

And finally, I’ve taken a slightly different slant in executing code to the C# example. It accepts commands to either log a string or run a script file. It seemed more natural to me to run a string than a file, partly because it seems such a pain creating script files all over the place but mostly because I figured if I could run a string then I could do both the other two things with the code in that string.

Here’s the code. You can test it by running the script in XSI and using telnet to connect. Either “telnet localhost 50007″ from the local machine or “telnet machine 50007″ from some other machine. At the telnet prompt type something like jscript|logmessage(“Testing”); will run logmessage(“Testing”) at the XSI end. Enjoy.

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

import socket
import select
import re
 
def ReadSocket(PORT, TimeOut=1):
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    s.bind(('', PORT))
    s.listen(1)
 
    # is someone knocking at the other end?
    #
    a = select.select([s], [], [], TimeOut)[0]
 
    # someone's there
    #
    if (a != []):
        # accept the connection
        #
        conn, addr = s.accept()
 
        # get data from the socket
        #
        data = conn.recv(1024)
 
        # parse the result
        #
        tokens = re.split('\|', data)
        if (len(tokens) != 2):
            Application.LogMessage("Useage: Language | script code")
            sRet = "Error"
        else:
            sRet = str(Application.ExecuteScriptCode(tokens[1], tokens[0]))
 
        # be polite and send something back
        #
        conn.send(sRet)
 
        # close the connection and return the result
        # of the last command
        #
        conn.close()
        return sRet
 
    # there was nobody there so return false
    #
    return False
 
###############################################################
#
# Testing on port 50007
# with a 10 second timeout.
# You can test this using "telnet hostname 50007" from any other machine
# or "telnet localhost 50007" from this machine
# typing something like 'jscript | logmessage("testing")' will run 'logmessage("testing")' in the remote XSI.
# 10 seconds should be enough time for you to run across the room and kick off a telnet. If you don't
# make it then it'll just time out.
# The connection is closed once the first string has been parsed but you can, if you wish, concatenate
#  commands, as in 'jscript|logmessage("testing")|python Application.LogMessage("Python Testing")'
#
s = ReadSocket(50007, 10)
if (not s):
    Application.LogMessage("Timeout")
else:
    Application.LogMessage("Connected: %s" % s)

A while back I talked about the print statement inside XSI. Well, at some version, I don’t remember which, it stopped working. I miss it. I miss it mainly because some of the code I write is meant to be used outside XSI as much as inside it and using a the more ubiquitous print would be nice instead of Application.LogMessage. To get that functionality back I cooked up a little recipe that makes the print statement in XSI useful again.

Some Background

What happens when you use the print statement? Python has a builtin module called sys. This module has three very usefull objects called stdin, stdout and stderr. They are respectively used to get input, send output and send errors. When you do

1

print 'Hello World!'

in Python it can be roughly interpreted as

1
2

sys.stdout.write('Hello World!')
sys.stdout.write('\n')

The Code

What my little reciepe does is replace sys.stdout with a wrapper to Application.LogMessage thus redirecting all print statements to the XSI log window. You can copy the code below to your script editor and run it.

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

import sys
from win32com.client import constants as c
 
class xsiLogger(object):
    def __init__(self, verboseCode=c.siInfo):
        self.__verboseCode = verboseCode
        self.__buffer = ''
 
    def write(self, output):
        for letter in output:
            if letter == '\n':
                self.flush()
            else:
                self.__buffer += letter
 
    def flush(self):
        Application.LogMessage(self.__buffer, self.__verboseCode)
        self.__buffer = ''
 
sys.stdout = xsiLogger()
sys.stderr = xsiLogger(c.siError)
 
print 'test\ntest2'
print 'test5',
print 'test6'
print 'test8', 'test9'
print
print >> sys.stderr, 'test3'
print 'test\ntest2'

A Few Explanations

The wrapper is implemented as a class that has a write method. Python’s print statements thus wind up calling the write method of my xsiLogger instance that then calls Application.LogMessage. The first argument to the initialization of the the class is the type of message that will be logged in XSI (siInfo, siError, etc…). Because of this we can also replace sys.stderr by an instance of the xsiLogger but this time give it c.siError as it’s verboseCode and have it spew errors instead of info messages.

Neat huh?

Now, often when you ask multi dimensional information from XSI it will return it to you in what might seem an odd manner. Let’s take some polygonal geometry for example. XSI will give you vertex data organized as three lists representing x, y and z positions with each element in the list representing a successive vertex. There is a demonstration of this situation at the Softimage Wiki. This happens well… regularly.

When you’re coding in C++ it is a rather nice and efficient way to do things. You know how many data points you have so you can use simple pointer arithmetic to walk your multiple data points. But we’re not in C++, we’re in Python and the equivalent walk would look something like this:

1
2
3
4
5
6
7

cube = Application.ActiveSceneRoot.AddGeometry("cube", "MeshSurface")
pa = cube.ActivePrimitive.Geometry.Points.PositionArray
for p in range(len(pa[0])):
    null = cube.AddPrimitive("Null")
    t = null.Kinematics.Global.Transform
    t.SetTranslationFromValues(pa[0][p], pa[1][p], pa[2][p])
    null.Kinematics.Global.Transform = t

In this example we create a cube and position eight nulls at the cube’s corners. It is a truly stupid example but it gets the point across. We first get the array of positions of the vertices, then loop over each vertex and move the appropriate null. In this first example we have to deal with XSI’s multidimensional array. Let’s get rid of that.

3D Programming in One Dimension

One way to get rid of the multidimensional array syntax is to flip it around. Instead of having data[x][v], data[y][v] and data[z][v], where x, y and z are positional components and v is a vertex we’ll convert the data to data[v][x], data[v][y] and data[v][z]. In this example flipping the data might seem trivial but in more complex scenarios I find it just fits my brain better. Maybe I just have a bizarre brain.

One way that is suggested in the Python Cookbook and that has made it’s way a few times on the XSI mailing list is a list comprehension.

1
2
3
4
5
6
7

cube = Application.ActiveSceneRoot.AddGeometry("cube", "MeshSurface")
pa = cube.ActivePrimitive.Geometry.Points.PositionArray
for p in [[r[column] for r in pa] for column in range(len(pa[0]))]:
    null = cube.AddPrimitive("Null")
    t = null.Kinematics.Global.Transform
    t.SetTranslationFromValues(p[0], p[1], p[2])
    null.Kinematics.Global.Transform = t

Alright! The multidimensional array syntax in SetTranslationFromValues is gone but we are left with a list comprehension that is utterly incomprehensible. An alternative is to zip things up.

1
2
3
4
5
6
7

cube = Application.ActiveSceneRoot.AddGeometry("cube", "MeshSurface")
pa = cube.ActivePrimitive.Geometry.Points.PositionArray
for p in zip(pa[0], pa[1], pa[2]):
	null = cube.AddPrimitive("Null")
	t = null.Kinematics.Global.Transform
	t.SetTranslationFromValues(p[0], p[1], p[2])
	null.Kinematics.Global.Transform = t

I’m feeling much better now… The zip function takes an arbitrary number of arguments, all of which must be lists. It will then create a resulting list containing all the first elements in the multiple lists, then all the second elements, then all the third elements and so on and so forth. Check out the python docs for an in depth explanation.

The Star of the Show

Check this last one out! I was really having fun here!

1
2
3
4
5
6

cube = Application.ActiveSceneRoot.AddGeometry("cube", "MeshSurface")
for p in zip(*cube.ActivePrimitive.Geometry.Points.PositionArray):
	null = cube.AddPrimitive("Null")
	t = null.Kinematics.Global.Transform
	t.SetTranslationFromValues(*p)
	null.Kinematics.Global.Transform = t

There is a special syntax in Python that you can use when calling a method. If you have a list and it contains the right number of arguments for a method call you wish to do, you can put *myList in the parenthesis of the method call instead of myList[0], myList[1], …, myList[n].

Again, the example I am using is a very trivial one but in many cases flipping the returned XSI data has been more than useful.

In case you were wondering, the performance hit is minimal. Running 500 iterations of the last flipped version of the code on this page took 63.157 seconds vs. 63.125 seconds for the first version of the code in it’s unflipped glory. And in case you were wondering it was 63.342 seconds for the list comprehension version. These are all wallclock times so minimal is hardly the word, I think at this point the difference is rather insignificant.

Its just all about typing a bit less and being a bit clearer.