The Super-Easy Guide to Scripting in XSI


Table of contents

Introduction

Scripting in XSI is easy. Really easy. You don’t need a Ph.D. in Computer Science. You don’t need to know C or C++ or any programming language. You don’t need to know anything about object models. You don’t even have to know how to program your VCR.

But don’t take my word for it. Let me show you how easy it is. Take a look at these four lines of XSI object model code:


set Layout = Application.Desktop.ActiveLayout
set WikiView = Layout.CreateView( "NetView", "Softimage Wiki" )
WikiView.SetAttributeValue "url", "http://softimage.wiki.avid.com" 
WikiView.Resize 960, 640


Can you figure out what this code does in XSI?

Scripting uses language that for the most part is already familiar to you (if you are familiar with XSI). For instance, ActiveLayout is the current layout, and CreateView opens a new view, in this case a NetView (just like the View > General > NetView menu command).

In these four lines of code, we open a NetView window, point it to the URL of the external wiki, and then resize the NetView window.

Lesson 1: Hello World

The traditional starting point for programming tutorials is the “Hello, world” program. So here’s a "Hello, world" script:

LogMessage "Hello World" 	' VBScript
LogMessage ( "Hello World" );	// JScript
Application.LogMessage ( "Hello World" )	# Python

Pretty simple, eh? To run this script, all you have to do is type this one line into the Script Editor and click Run. The message "Hello, world" is logged in the History window of the Script Editor, and on the XSI status bar.

Description

LogMessage can be very useful when you’re trying to figure out what’s going on in a script. By logging information, you can track changes in values and get a better idea of how a script works. However, logging messages slows down scripts.

The Script Editor is your main work area for scripting:

  • The window title bar displays the name of the file you are editing, and the current scripting language.
  • The Script Editor has a History pane (which displays the output of LogMessage and logs a history of everything a user does in XSI) and an Editing pane (where you edit scripts).
  • XSI supports four scripting languages: VBScript, JScript, Python, and PerlScript. To change the current scripting language, right-click in the Editing pane and then click one of the Set to <Scripting Language> commands.
PerlScript is supported, but few people use it. And our Wizards (which generate scripting code for commands, menus, properties, filters, and operators) do not generate PerlScript code.

Hands-on Challenge #1

  • Use LogMessage to display a message in a Message Box.
  • Figure out how to display Verbose messages.



Lesson 2: A Tutorial Introduction to Scripting

Variables

Variables are used to store values. A variable has a name, and you use that name to refer to the value stored in the variable. For example:

var sMessage = "Hello,world";
LogMessage( sMessage );

In the above code, we declare a variable named sMessage and assign the string value "Hello, world" to sMessage. Then we use the variable in LogMessage.

Like most scripting languages, JScript and VBScript are loosely-typed—that is, variables have no declared data type, and can change type dynamically. To change a variable's type, you simply assign it a value of different type, like this:

var x;
x = 10;
LogMessage( x );
x = "ten";
LogMessage( x );

Variables can store strings, numbers, booleans (true and false values), and objects. Jscript also has the special values null and undefined, while VBScript has Null, Nothing, and Empty.

Operators

Operators are things like +, -, *, =, and == that are used to peform arithmetic, assignments, and comparisons. For example:

' VBScript
x = 2 + 3
LogMessage x

' VBScript
x = 3
y = 2
if ( x <>  y ) then	' Comparison operator <> tests for inequality
	LogMessage x = y 
End if

x = y
LogMessage x 
// JScript
var sGreeting= “Hello”;
var sWho = “world”;
LogMessage( sGreeting + “, “ + sWho );

var x, y;
x =2;
y = 33;
LogMessage( x == y );

Controlling Program Flow

Program flow is the order in which the lines of scripting code are executed. Normally, the lines are executed from top to bottom, one after other. But you can control program flow with conditional statements and loops.

Conditional Statements

Conditional statements like if and if..else allow you execute code only if certain conditions are true. For example, this code snippet displays a message if there is nothing selected:

if ( Selection.Count == 0 )
{
	LogMessage( “Please select at least one object” );
}

The expression Selection.Count == 0 evaluates to either true or false. If the expression is True, then LogMessage statement is executed; otherwise, if Selection.Count is greater than 0, LogMessage is not executed.

The if..else construct allows you to do something in either case:

if ( Selection.Count == 0 )
{
 	sMsg = “Goodbye cruel world”;
	nMsgType = siFatal;
}
else
{
	sMsg = “Hello, world”;
	nMsgType = siInfo;
}
LogMessage(  sMsg, nMsgType );

Loops

Loops allow you to repeatedly execute a series of statements. For example, this for loop creates ten cubes in a row along the X axis. Note how i, the loop counter, is used to specify the X position of the new cube.

for i=1 to 10
 	CreatePrim "Cube", "MeshSurface"
 	Translate , i * 8, 0, 0, siAbsolute, siPivot, siObj, siX, , , , , , , , , , 0
next

Here’s a JScript version of a for loop:

var i;
var MAX = 10;
var sum = 0;
for (i = 0; i < MAX; i++) 
{
	LogMessage( i );
	sum = sum + i;
}
LogMessage( "The total is " + sum );

Do you know what "i++" means? ++ is the increment operator: it increments that value of a variable by 1. So if i is equal to 1, then i++ is equal to 2.

Similarly, this sum = sum + i is the same as this sum += i.

Functions

A function is a group of statements that can be executed from different points in a script. For example, at various points in a long script you may need to check the distance between two points in 3D space. Instead of repeating the same code everytime you want to check, you can put the code in a function, like so:


LogMessage( distance( 1,1,1,2,2,2 ) );
LogMessage ( distance( 0,1,1,2,3,4 ) );

function distance( x1, y1, z1, x2, y2, z2 )
{
	var d = Math.sqrt( 
				Math.pow( x2 - x1, 2) + 
				Math.pow ( y2 - y1, 2) + 
				Math.pow ( z2 - z1, 2)
				);
	return d;

}

Lesson 3: XSI Commands

Pretty much everything you do in XSI logs a command to the History Window. For example, create a cube and then translate it. You should see something like this in the History:

CreatePrim "cube", "MeshSurface"
Translate , -3, 0, 0, siRelative, siView, siObj, siXYZ, , , , , , , , , , 0

CreatePrim and Translate are XSI commands. In the above example, the Translate command applies to the currently selection, which in this case is the cube you created just before (remember that when you create an object it is automatically selected). A Translate command that applies to the object named cube21 would look like this:

Translate "cube21", -3, 0, 0, siRelative, siView, siObj, siXYZ, , , , , , , , , , 0

Commands use string expressions to specify which scene elements the commands apply to. For example, create a cube and then change the name of the cube to MyCube. Then change the name back to the cube’s original name.

SetValue("cube2.Name", "MyCube", null);
SetValue("MyCube.Name", "cube2", null);

In the first SetValue command, the string expression cube2.Name specifies that you want to set the value of the Name parameter of an object named cube2. Properties and parameters are specified using a dot notation. For example, open the Kinematics property page for the cube (Alt+right-click and then click Kinematics). Change the local SRT values. You should see something like this in the command history:

SetValue "cylinder.kine.local.posy", 14.894 SetValue "cylinder.kine.local.rotz", 13.277

This string represents a path through the scene hierarchy where:

  • "cylinder" is the name of a 3D object.
  • "kine" is the scripting name of the Kinematics property.
  • "kine.local" is the scripting name of the Local Transforms property.
  • "posy" is the scripting name of the Y position parameter.

A property (sometimes called a property set) is a container for a group of related parameters. For example, the Local Transforms (local) property contains the X, Y, and Z position parameters. A property can also contain other properties. For example, the Kinematics property contains the Local Transforms, Global Transforms, and Constraints property.

Hands-on Challenge #3

Try running some commands to figure out what the following string expressions evaluate to? (For example, cube* evaluates to any object name that starts with the characters cube.)

  • "cube*"
  • "Model.cube*"
  • "cone[12]"
  • "cone?"
  • "cone*,cube*"
  • "*Eff"
  • "*.#model"
  • "*"
  • "*.#3dobject"
  • "*.#3dobject*"
  • "*.polymsh"
  • "*.visibility"
  • "Beck.*.visibility"

Lesson 4: A Quick Look Under the Hood

The more scripting you do more, the more you look at an XSI scene the same way the Explorer does (or the Schematic view). In fact, scripters often work in a custom layout where they do not even see the 3D viewports. An XSI scene is just a hierarchy of 3D objects, where the hierarchy is based on the parent-child relationships between 3D objects. A common scripting task is to apply some operation to specific 3D objects in this hierarchy (for example, to all models, or to all lights). This means you often have to traverse the hierarchy looking for objects.


Objects-only view in the Explorer
Objects-only view in the Explorer

A 3D object (such as a polygon mesh) has other objects nested underneath it. These other objects include things like primitives, properties, and materials.


Nested data under a 3D object
Nested data under a 3D object

Finally, there are parameters, the things that have actual values. For example, the X, Y, and Z position of a 3D object in local space:

Parameters in the Explorer
Parameters in the Explorer

Lesson 5: Getting Objects

So how do you get objects from a scene? A common approach is to get the objects selected to the user. In scripting, you use the Selection object to access the current selection:

LogMessage Selection.Count
LogMessage Selection(0)

Selection.Count is the number of selected objects, and Selection(0) is the first object in the list of selected objects.

You can use a for each loop to do something with each selected object.

for each oObj in Selection
	LogMessage oObj.fullname 
next

Don’t remember the syntax for a loop? Right-click in the Script Editor, click Syntax Help, and then click Loop on Selected Objects. This pastes a for each loop into your script.

Hands-on Challenge #5

Write a script that logs information about the polygon meshes in the selection list. Make sure that your script can skip any non-polygon meshs in the selection.

This page was last modified 06:55, 7 Sep 2007.
This page has been accessed 17638 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy