tcl

The tcl Scripting Environment

Main Scriptable Objects

“it”
As with other RenderMan Studio applications there is one object that is always available in the scripting environment; the it object. It represents the state of the application. The “it” object is also the place to start to get a hold of other objects. You can query “it” for a list of all the available catalogs or the current catalog. Each catalog can be queried for “it”s list of images and so on.

The application object is also used to execute expressions in the IceMan environment. Catalogs become important at this stage as the IceMan expression is evaluated in a namespace defined by a given catalog. So when you refer to an image by the handle of "e0" in the IceMan expression what that specifically means is the image with the handle "e0" in a particular catalog and not any other image that might have that handle in another catalog. Also any images that are created by the expression will be created within the same catalog. If you don't specify a catalog the expression is evaluated in the "current" catalog. 'It' always has a current catalog which can be set either in the GUI or from a script by calling the “it” object's SetCurrentCatalog method.
catalog
The catalog is a container of images. Images are held as a list which you view directly in the 'hub' window in the GUI. From a script you can get a catalog's images with the GetImageList method. For convinience the Catalog object has an ExecuteIceScript method which is like the “it” object's IceExpr except it is always run within the context of that catalog.

Catalogs also have a crop window property which is set by dragging out a rectangle in the GUI. This would let the user specify a region of interest that you script might operate on. Crop coordinates can be retrieved either in RenderMan format which is a "<min x> <max x> <min y> <max y>" or in IceMan format which is "<x origin> <y origin> <x size> <y size>". Specify either "-fmt Ri" or "-fmt Ice". Ri is the default.
image
The image object in the tcl environment provides the house-keeping information about the image; handle name, file name, notes etc. From tcl there is no direct access to the pixel infomation. For that you use the IceMan environment.

An image's notes are just a simple block of text that you may use to annotate your images. If you save an It session the notes are saved as part of the session and not in the image file itself.

To support RenderMan's Arbitrary Output Variables (AOV's) within “it” each image can itself a list of sub-images. The GUI presents this relationship by indenting the AOV's icons with respect to their main image. The list is retrieved by calling GetImageList just like that of of the Catalog object. AOV's themselves would not have further sub-images at this time. AOV images may be of different type and/or ply than the main image. AOV's are arrays of pixels just like images but the values of the pixels don't necessarily represent color. The values might be scalar (like speed) or vector (like direction) so as images they may certainly be of a different type and ply than their main image.

Summary

“it” has a simple structure of images contained within catalogs, catalogs contained with the singleton application object. A good demonstration on how to retrieve and manipulate these objects for scripting purposes can be found in the Web page example in the tutorials.

Object Model Reference

it

it ClearSession: resets “it”
it SaveSession filename: saves the current “it” state to filename
it RestoreSession filename: restores the current “it” state from filename
it Shutdown: causes “it” to exit
it NewCatalog arglist: creates a new catalog
it GetCatalogList: returns a list of catalog objects
it SetCurrentCatalog cat: sets the current catalog (cat)
it GetCurrentCatalog: returns the current catalog object
it IceExpr expr: causes the IceMan expression (expr) to execute.
it SetDefaultEventHandler evt cmd: cause cmd to be executed when an event triggers. Known events include: itOpenHandler, itCloseHandler.

catalog

$cat NewImage arglist: creates a new image in the context of the named catalog.
$cat GetCurrentImage: returns the current image.
$cat GetImageList args: returns a list of images in the named catalog. args can be provided to reduce the image list. We apply standard glob-style pattern matching and currently apply two search criteria: -h pat matches the element handle, -fn pat matches the filename.
$cat DeleteImage img: Deletes the current image from the catalog.
$cat SetSequenceInfo arglist: sets the sequence control state for the named catalog.
$cat ExecuteIceManScript script: executes the IceMan script in the context of the named catalog.
$cat GetCropRegion args: Returns the current crop region associated with the current image of the named catalog. The optional argument -fmt allows you to request the format for the crop region. Valid formats include: Ri (RenderMan Format), and Ice. We default to Ri format.

image

$img GetImageList args: returns the list of subimages, often empty. As with the catalog methdod, you can use the optional args to reduce the image list.
$img GetNotes: returns the notes associated with $img
$img SetNotes str: sets the notes for $img
$img GetHandle: returns the handle used to reference the image in IceMan scripts
$img SetHandle h: sets the IceMan scripting handle, must be unique within the catalog
$img GetFilename: returns the filename string associated with $img
$img SetFilename name: sets the filename for $img.
$img GetSize: returns the image size as a Tcl list: {width height}
$img GetBox: returns the image box as a Tcl list: {xmin ymin xmax ymax}

Custom Extensions

You can extend or modify the Tcl scripting environment by loading your own .tcl files on “it” startup. In your local copy of it.ini place:

	LoadExtension tcl /my/extensionpath/MyItExtensions.tcl

Prev | Next