What is a Spreadsheet Query?

The spreadsheet view displays scene information about elements and their parameters in a grid. This information is filtered and organized by queries that you create to show specific aspects of your scene in combination with sorting operations you can perform based on object data. You can then perform operations on many elements or parameters at once.

A	Each row represents a scene element. Click a row heading to select all of an element's properties. Right-click the row to select objects in your scene.
B	Each column represents a parameter. Click a column heading to select a parameter on all of the displayed objects. Right-click a heading to quickly sort elements and mark parameters for animation.
C	The intersection between a row and a column is called a cell, each of which holds one value. You can select many cells at once and modify them all simultaneously.

Using Queries

A query is a means of requesting information filtered a specific way for display in the spreadsheet. For example, you could query Softimage for a list of local rotation values for only selected objects. Queries are text files with a .query extension; default queries are located in %SI_HOME%\Application\Queries.

You can execute a query by using one of the predefined queries found in the spreadsheet's Query menu, or you can choose QueryOpen to load a query file you have created.

Once you have executed a query and the spreadsheet displays the data you have requested, you can further organize the information by sorting the table. Right-click any column heading to sort the table entries based on the column's entries. To return to the default sorting as defined in the .query file, choose QuerySort from the spreadsheet menu.

How the Spreadsheet Works

The Softimage spreadsheet builds the content of the spreadsheet using scripting, which gives you a lot of flexibility with the type of information you can display.

Types of Queries

There are two types of queries:

The single level query filters certain types of elements from the scene, and display a information about them (for example the Geometry query).
The relational query shows the relationship among different scene elements, such as showing all of the clusters that exist on all of the objects in a scene, or showing the textures and their object owner.

Types of Cells

Each cell in the spreadsheet can show two main types of information:

Softimage parameters in what are called GetValue/SetValue cells. These cells display the value of a parameter that already exists within Softimage (whether native or custom parameters), and that are accessible to standard GetValue and SetValue calls in scripts. These cells are automatically handled by the spreadsheet as long as you identify which parameter to display.
Custom information in scripted cells. The information displayed in these cells is computed by a custom script, which allows you to compute certain custom measurements and display them. These cells are read-only.

The Components of a Spreadsheet Query

A single level query is described using three elements:

A script function that tells the spreadsheet which scene elements to show on each row.
A script function that defines the columns that show the information for each row.
A query file that tells the spreadsheet which script to call for rows and columns (and where to find these scripts). This is the file that gets opened when you choose FileOpen or when you run preset queries within Softimage.

Separate row and column scripts are very useful as they allow you to reuse one or the other in different queries. For example, there's a row script called Current_Selection that is used in a few of the preset scripts and that you can use for your own queries if you need to display all of the selected elements. All spreadsheet query scripts must return elements in the form of an array.

A relational query will have the same elements as the single level query, but with the addition of two scripts.

A relation association script, which determines, for each row, the associated items. This script defines the second-level of rows (for example, a list of clusters for each of the selected elements). There can be only two levels in Softimage, that is, only one relation per query.
A column definition script, much like for single-level scripts, which defines what columns to display for the elements that are displayed at the second-level of the query.