Phoenix Tools was a plugin company for Softimage 3D, and I was one of the founders. We did good and bad, and we eventually closed down in 2002.

Arete had an excellent reputation for their ocean and atmospheric library, called Digital Nature Tools. I think their main business was in military simulation, however they had a part in every cg-generated ocean in the movies of the 90s.

In 2001 we joined forces to port their software under XSI (I think it was 2.0). Unfortunately, after the first version came out, both companies shut down.

8 years later, I am working on a feature animation with a few shots in water, and I realized I still had on some cd the arete psunami libraries. So, I decided to give it a try. I removed the license check from the shaders and I compiled them with good old Visual Studio 6, linking against the oldest mental ray library I could find (3.3), and in the end it worked. I was kind of touched when I finally saw the displaced grid rendering in Softimage 2010.

I think I will do no harm to anybody releasing these shaders. Both companies are dead since long, and this is my little tribute to them and the talented people who worked there.

The addon is only available for win32, and no, no chances for other platforms. That Arete library is the only one I have. If you do, use it at your own risk (and fun, i would say. There are probably better ways to do oceans nowadays).

And, you know what, I don’t even know how the full package works. I don’t have anymore the documentation, nor the scripts we provided. If my old companions will find them, I will post them later.

The basic usage however is easy. You have to connect a DNT_Ocean_Sh and DNT_Time to a DNT_Ocean_Evolver. What come out is the ocean instance, that can then go into the other nodes. Also, you want to apply DNT_Air as environment to have nice reflection and the atmosphere.

The rendertrees have all kinds of materials, with bump, transparency and reflection in place.

The most obvious approach to solve the problem is brute force: writing a script that would traverse all the materials, and substitute each material with a constant one, using as color the diffuse color of the original material, and inheriting all the subtrees for the transparency and reflection mixing. This would have required a couple of days of scripting, and, as any brute force approach, is not really elegant.

Another idea we tried was tuning the normal. We replaced all the lights with a single directional white light, pointing downward. Then, we connected a constant vector to the bump port of each material, pointing upward (0,1,0). The light has no specular contribution and the ambience is set to black. This way, only the diffuse component of the materials is returned, and since the normal always points upward, the incidence with the light is always 1, so all the materials behave like constant.

Unfortunately this method has a major disadvantage: since the direction of the reflected and refracted rays leaving a (reflecting/refracting) material depends on the normal, the result is completely wrong for secondary rays, because we are moving the normal to an arbitrary (up) direction. So, using the bump port was not a solution.

However, this failure pointed us towards a better solution.

Again, we just had to fix the diffuse component. In all the material shaders (except a few exceptions like hair, which we treat separately), the way the diffuse component is computed is as follows:

1. Get the light color
2. Multiply it by the incidence
3. Multiply the result by the diffuse color

So, if you want to get back the plain diffuse color, you just have to tell the light to return 1 (white) divided by the incidence. This way, the material shader returns diffuse * incidence * (1 / incidence) == diffuse.

This the starting case (a phong sphere – top), and our first result (bottom)

And this is the rendertree for the light

Also in light shaders, the normal can be used (it’s the lit point normal). The dot product of the normal with the light direction L0 is the incidence, which we then use to divide 1, and return the result as the intensity of the light.

That was ok for a half dome, but what about the rest? A possibility is simply to double the light, specularly to the xz plane, cloning the rendertree (and L0 becoming 0,-1,0 for the other light). That would cover 99% of the cases, being any oriented surface sample being lit only by one of the two lights at most.

The “at most” is the remaining problem. If you have a cube, its vertical faces won’t be lit by any!

So, we have to expand a bit this setup. We start setting up a minimal light rig, ensuring that al least one of the lights will always hit any oriented surface. The minimum number of lights for such a rig is 4, equally distributed in space.

So, we take a tetrahedron of radius 1, centered at the origin, and cluster constrain a directional white light to each vertex, all pointing toward the origin.

Each light has the following rendertree (with a small change for each of them)

This is the tree for light L0: the left side vectors are the four lights positions, set by expression. Since The tetrahedron has radius one, they also represent the direction toward each lights. All their incidence with the normal is computed and sent to a positivity check, and this check drives a switcher between zero and one. So, the sum of these 4 switchers is the number of lights (1 to 3) visible from the rendered point.
This number is multiplied by the light incidence and the result divides 1, as in the single light case.

Why do we need the number of visible light? Since we have 4 lights, the total amount of light that gets received by the point is
L = L0*I0 + L1*I1 + L2*I2 + L3*I3, for each positive Iight. In fact, the material shaders won’t even query a light if its incidence is negative.
So, as before, we still return 1 divided by the light incidence, but also divided by the number of visible lights, so that the overall sum of the visible lights is always 1.

The other 3 lights have the same rendertree, except the dividing incidence comes from I1, I2, I3 respectively. For instance, this is the tree for light L1.

And finally, we have our constant result. You can download the rig here.

HDRShop
HDRShop plugin Diffuse_SH.

I used to work for a 2 years at Framestore-CFC in London. That mean I use Maya and PRMan as my main application. During this year I learn a lot of thing but also hear a lot of false assumtion about rendering in general. Typically the common comment was that PRman was more suitable to render complex character and that MR was very slow for this kind of job. In fact people arguing about this doesn’t not really know what are the status of modern rendering such as MR, V-ray or any others assuming everything was frozen since 5 years or just repeating what the veteran keep repeating.

But I am not engaging a new flame wars between renderer. Actually I don’t care which is the better today in 2008 you can produce beautiful picture with any renderer available in the market ( and yes that include maya’s software render well known to be a piece of crap ;) ) The most important is the guys behind the scene. But I need to put everything in their respective context to elaborate and may be justify what and why I will describe later.

Actually mental ray is very fast, if you do things correctly. If you don’t do things correctly ( such as massive spatial and/or temporal oversampling ) it as well as any other renderer will be very slow. But I always get this "PRMan displaces faster" stuff. Of course it does…. until you actually trace a ray.
You have to know that PRMan lives in a mindset where raytracing is so slow that you avoid it at all cost. The thing is that in PRMan, if you try to shoot a ray, it too has to do all those things that a raytracer do by nature. So the minute you actually shoot a single ray, PRMan has to do what mental ray always does…. and the comparasion suddenly isn’t so much in favour of PRMan any more.

So people using PRman developed a completely different approach to same problem : Lighting and Rendering a scene while trying to avoid at all cost raytracing. That what is interesting. What will happen if I use these approach with Mentalray within XSI ? Maybe I can have a hybrid solution keep the best of the two world to render my character(s) ?

Diffuse Convolution on Environment map

What’s that ? To keep it simple you can assume that a diffuse convolved map is envmap where you apply a smart blur that will give you the result of sampling this envmap with an infinite number of rays with the Final Gathering on a perfect lambertian surface. For more information you can refer to Debevec’s research ( the father of HDR images ).

Having your envmap pre-blurred is a great advantage because you don’t need to sample it several times to get the correct illumination. Only one sample suffice to get the illumination on your surface. Actually you must cast only one ray. Otherwise you will average twice the map and the illumination will not be correct any more.

The ray direction that you will cast must also be in the same direction as your surface normal. The Xsi’s Ambient Occlusion setup correctly will do perfectly the job. You need one sample , the spread will be very small to not deviate from the normal ( 0.01 ) and the mode should be set to environement sampling. Obviously you can code a shader that do the correct environement lookup. I am using the XSI’s AO shader because it’s available out of the box.

Render Balls simple test.

Env sampling brute vs FG vs Diffuse Conv

The way I set up the scene is very simple. I tried to get the contribution of the envmap once convolved and only this. So there is no illumination model just different approach.
The HDR used for this test the one called beach.hdr that you can find at debevec’s website. The map that you download is an angular map so you have to convert it to spherical coordinate system. The easiest way is to HDRshop and convert to angular map to longitute/latitude map. Once the map ready, I put it in my scene as an environement map.
The first sphere is the result of an AO shader set to environement sampling mode with a spread of 0.8. I had to crank up the sampling to 1024 to get a smooth solution. AO env sampling is brute force approach. There is no importance sampling so that mean you have cast a lot of ray to get a smooth result specially with high dynamic range image. And obviously that be very slow. It’s the slowest render.
With the second sphere I used to FG to sample env. Same settings as before except that I use a shader that return irradiance and activate FG. FG is a lot faster that the previous method because it doesn’t sample every point with 1024 rays. Instead FG will sample a certain amount of point and interpolate the result between the point calculated. But for this comparaison I pushed the number of rays to 4096 to make sure I got enough accuracy to have fair comparaison with the quality of the next approach. Even by pushing the number of rays to 4096, it was still faster to render with FG.

With last sphere I made a diffuse convolution in HDRshop ( using the SH_diffuse plug in because it ’s a lot faster than HDRshop’s function), applied the resulting image as an environement map and use the XSI’s AO shader with the sampling set to 1 and the spread to 0.01.
The render time is ultra fast and match FG solution. It ’s actually realtime because the convolution has been already calculated once in HDRshop.

Render Balls too simple let’s try with something that got balls.

We got a exact match with the FG for a fraction of time. We can conclude that the diffuse convolution is good enough to simulate FG. But in our test we were using simple sphere. This an ideal case but we needed to check first if the lookup was correct before to move on something more serious.

I like buddha. I like him because it’s a one million polygon model that can be compared to any displaced model push out from Zbrush or Mudbox.
I have simply applied what I did with the spheres.
The first render is with an diffuse convolved envmap. It took approximately 50 sec to render with a large part of preprocessing the scene. If I had a realtime shader could get the same result ( minus anti aliasing ) in realtime. Obviously there is no occlusion calculated but that due to fact I asked only an environment lookup around the normal of the surface.
The second image is what you get if you were using FG and third one is a difference done in shake
to highlights the difference between the two renders.



As you can see only the occlusion and the FG colored bounce are missing. If you apply a simple occlusion on the top you will endup with an image that is fairly close to the FG solution but with only a fraction of the time involved by the process.

OK but in production is it worth to use it ?

Well I will say yes and no. It depand the number of shot you have to do and the time you got to complete them. This technique involve a bit of setup at the shading level while the using FG is straight foward. So if you are working on movie that need a 2K ( or more ) render then yes. Memory foot print is very low and it’s damn fast to render it specially with very heavy object like displaced object or Hair object..
At the moment you need to set this at the shader for every object. Ideally the best will be to set this as a global ambience. Unfortunately you can’t plug anything in the global ambience parameter. So the best if to use a light that cast only ambient light. And for that you need to code it so ask your favourites shader writer to do it.

Publications :

An Efficient Representation for Irradiance Environment Maps

Since XSI does not allow for shadow maps paths, this is how you can do (a ray3 standalone license is required).

After setting up a shadow mapped light, export a single frame archive (mi2) ascii file.

Edit the file with a text editor, and look for the light options section. There you find the shadowmap settings.

To have the map written, just add a line with the “shadowmap file” statement, followed by the path for the file (.zt format mandatory).

light "Spot_Root/Spot/Light" = "Spot_Root/Spot/Light/soft_light"
origin 0 0 0
direction 0 0 -1
spread 0.866025
shadowmap on
shadowmap resolution 500
shadowmap softness 0.002
shadowmap samples 20
#the following line added
shadowmap file "C:\temp\sm.zt"
energy 7500 7500.01 7500
...
end light

Save the file and render it with ray3.

To just render the shadow map and not the image, you can use the handy “-shadowmap only” option. In my case, being the archive file named C:\temp\out.mi2, I run

ray3 C:\temp\out.mi2 -shadowmap only -verbose on

Once finished, you should find the map on disk (C:\temp\sm.zt in my case), and view it by

imf_disp C:\temp\sm.zt

This is a simple sphere over a grid

The grid does not show up, not being a shadow caster itself.

So you can now check the shadow map extent, which is particularly interesting for infinite lights, being determined by the extent of the parts of the scene that cast shadows (for spot light sources, only the cone spread parameter matters).

Also, by left clicking on the image, you can read the z value for each pixel, and finally (maybe) understand the obscure bias option ;).

This is an example of how sometimes you can write a phenomenon just to downgrade a more powerful node to get what you need.

The starting point is noticing that the node that more resembles the sine and cosine look is the Wave one. By connecting it straight to the surface and setting the parameters as shown, you have something really looking like a cosine function.

To enlarge the wave period to match the cosine’s, we simply need to devide the input by 2*PI.

Now we can push everything into a single phenomenon, having just one input parameter (the cosine argument).
This is the connection section:

Node "sib_scalar_math_basic" = guid "{3843DA00-A1F4-11D3-AE51-00A0C96E63E1}";
Node "sib_scalars_to_vector" = guid "{6405C7C0-623C-11D3-8C0A-00A0243E3672}";
Node "mib_texture_wave" = guid "{5092B017-B473-11D1-90E1-0000F804EB21}";
Node "sib_color_to_scalar" = guid "{865EBB7A-BCFA-11D1-90E9-0000F804EB21}";

Connection "sib_scalar_math_basic::input1" = interface "x";
Connection "sib_scalar_math_basic::input2" = value 6.28318;
Connection "sib_scalar_math_basic::op" = value 3;

Connection "sib_scalars_to_vector::inputX" = "sib_scalar_math_basic";
Connection "sib_scalars_to_vector::inputY" = value 0.0;
Connection "sib_scalars_to_vector::inputZ" = value 0.0;
Connection "sib_scalars_to_vector::modeX" = value 1;
Connection "sib_scalars_to_vector::modeY" = value 2;
Connection "sib_scalars_to_vector::modeZ" = value 3;

Connection "mib_texture_wave::coord" = "sib_scalars_to_vector";
Connection "mib_texture_wave::amplitude_x" = value 1.0;
Connection "mib_texture_wave::amplitude_y" = value 0.0;
Connection "mib_texture_wave::amplitude_z" = value 0.0;
Connection "mib_texture_wave::offset" = value 0.0;

Connection "sib_color_to_scalar::input" = "mib_texture_wave";

Connection root = "sib_color_to_scalar";

Having the cosine, it is now easy to get the sine also, since

sin(x) = -cos(x+PI/2)

Just make up another phenomenon and “code” the identity:

Node "cos" = guid "{19671972-1008-0000-8410-6A45FDB990DD}";
Node "sib_scalar_math_basic" = guid "{3843DA00-A1F4-11D3-AE51-00A0C96E63E1}";
Node "sib_scalar_math_unary" = guid "{A0471300-AC2E-11D3-AE56-00A0C96E63E1}";

//add PI/2 to the input parameter
Connection "sib_scalar_math_basic::input1" = interface "x";
Connection "sib_scalar_math_basic::input2" = value 1.57079;
Connection "sib_scalar_math_basic::op" = value 0;

//send result to cos
Connection "cos::x" = "sib_scalar_math_basic";

//negate result
Connection "sib_scalar_math_unary::input" = "cos";
Connection "sib_scalar_math_unary::op" = value 1;

//done
Connection root = "sib_scalar_math_unary";

You can download the two spdl’s from here.

Of course you can also go further, since tan = sin/cos, cot = cos/sin, etc. Getting the inverse functions, instead, is another matter.

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.

The first step to take, was to decipher the the file structure of the FG and Photon maps. Since the files are written in binary, this wasn’t that easy. But with the help of UltraEdit, a HEX editor for Windows, and some trial and error, the main file structure mystery was unveiled. Here is an example of how this looks like in a FG map:

The blue marked part is the file type and the version of MentalRay. The green part is a 32 bit integer value which is the total FG Point count. Next comes the FG Point itself. One FG point is represented in 104 bytes in total. That’s the first bright block. The first 12 bytes are the x, y and z coordinates in 32bit floating point numbers. And so on…

Final Gathering maps have another structure than Photon maps and thus it took me twice the time to build the file structure.

Once this was done, I had a little look into OpenGL programming and had a little talk to Andrea Interguglielmi. He helped me with the Logic behind the connection between XSI and OpenGL.

What this tool does is in fact pretty simple. When the plugin is loaded, it registers a new DisplayCallback and allocates some basic memory. Then, after you select a map and press on the “Show Map” button, it reads the chosen file and creates an array of position and color values which are stored in the memory and then displayed through some basic OpenGL functions.

With this tool you have the ability to view your saved FG and Photon maps in your 3D-Viewport of XSI. After installation, you can find it under Get-> Property-> JV_MapMiner. It is provided as is and nobody is responsible in any way for any possible damage.

I hope this tool can help people to optimize their renderings and make their lives a little bit more comfortable.

You can download the .xsiaddon (tested on XSI 5.x and 6.1) and a demo project with one FG map, one GI map, one Caustic map and one GI+Caustic map combined (27mb).

You are welcome to send me bug-reports or suggestions.

FG Quicktime
GI Quicktime
Caustics Quicktime

Buddha 3D-Model courtesy of the Stanford Computer Graphics Laboratory.

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);
    }
}

In the past I have done jobs which required the use of anisotropic patterns and those had always been faked with maps and the like. But now there is no need for faking anymore. A very nice feature of the T2S_Illumination shader enables the manipulation of the anisotropy vector orientation which makes it possible to generate realistic reflection patterns over the surface.

A big thanks to the folks at Tek2Shoot for that one.

Reflect on this

Obviously we’ll be building off T2S_Illumination.

Disable the Fresnel option under the Fresnel tab. This is done to see the full reflection strength of the material – metals often don’t have any or very slight Fresnel reflections. Enable the Reflections under the Scattering tab and switch the Glossy mode to Anisotropic. Set the Shiny U/V parameter to 1 and 100. Under the Anisotropy tab change the mode to North Pole to see how the reflections could look like. Later we will switch it back to North Direction.

To make the reflections visible, create an environment which will be reflected. You can setup some objects in the scene or just use a spherical map.

Applying this material to a grid with proper UVs (Planar XZ projection), shows the nice circular anisotropic reflections as seen in your kitchen on a cauldron’s bottom.

The next step is to recreate that North Pole behavior in the direction vector. To achieve this we have to provide a vector map that manipulates the north direction, so that it points to the center of the grid.

Switch back the Anisotropy mode to North Direction.

In Photoshop, you can very easily create such a vector map. All you need to do is to make two grayscale gradients. One is from right to left in the red channel of the image and the other is from bottom to top in the blue channel. Make sure your gradients are linear and not cubic (smoothness 0 vs smoothness 100).

These colors will then be interpreted by XSI so that the full red color will point to the positive x direction and black will be pointing to the negative x direction, pos z and neg z respectively for the blue color. To do this the color channels must be split apart and remapped to a vector. By using Pick_Channel and Change_Range nodes you can easily remap color values (0 -> 255) to a vector component (-1, 1). After having done this for both red and blue channels of your picture, you can recombine the scalars into a direction vector by using a Scalars2Vector node.

One last thing to note is that even if your texture is applied locally on the object, the vector that is built with the texture’s values is defined in world space. To get proper anisotropy that will follow your object’s every transform you need to convert the vector to object space by using a Vector_Coordinate_Convertor node. Switch the Transform to to Object.

Having fun

At the beginning of this article I talked about Anisotropic Patterns and their creation. Now that we know how to create custom vector direction maps there is no limit to the anisotropy patterns we can render. For example: a typical brushed finish of stainless steel.

A very simple map can generate the same effect.

And the same thing for some really nice looking Carbon Fiber material.

I hope this article, beyond anisotropy, has helped a few people better understand the world of vector usage in the Rendertree.

You can download the project files or just the material preset.

Thank you and have fun with these tricks…