The "it" Python module
The "it" Python module
"it" Module Objects
Here we describe the principle classes and functions in the "it" Python module. When "it" is started this module has already been initialized in Python, so you can type help(it) and dir(it) in the Console window to get useful information, in addition to what's contained within that module.
It3ImageElement
The most central object to the "it" application is the Image Element. Its actual type in Python is It3ImageElement, but for the most part that's a detail you can ignore. The purpose of an Image Element is to hold one image or one sequence of images. Each Image Element also has a number of properties that can be retrieved from a script. Some of the properties can also be set, for example, the notes field.
If you render Arbitrary Output Variable images (AOVs) to "it" you will see that Image Elements are organized hierarchically such that AOVs are nested under the main image, and the main image is nested under the Catalog. The terminology is that the AOVs are children of the main image, and the main image is a child of the Catalog. This hierarchy is accessible and modifiable from the scripting API.
Note:
The "it" module also contains useful functions that are not object methods, such as it.GetCurrentElement(), which returns whatever the current element displayed is.
It is important to remember that an Image Element is not an ice.Image type. It is a container of an ice.Image, not an image itself. In contrast, the ice.Image type is purely about performing image operations and has no concept of child or parent. An Image Element also carries with it extra information about detailing color spaces and optional user interface information like current zoom, pan, and crop window.
It3ImageElement is a subclass of It3Element.
It3Catalog
Catalogs are just containers of Image Elements. They are similar to folders or directories. They have a label that is displayed in the user interface. Image Elements can be dragged from one Catalog to another. スクリプト can also move Image Elements from one catalog to another.
To get a hold of a Catalog, a script can ask an Image Element for its parent, or, instead, ask the application object for the current Catalog with a call to it.app.GetCurrentCatalog.
Just like It3ImageElement the It3Catalog class is a subclass of It3Element.
ItApp
This is the main application object and is a subclass of the Qt object QApplication, so anything that you can do to that class via Qt signals will apply here (see the Qt4 documentation on signals and QApplication). This object is created before any script runs and appears as it.app.
It3MainWindow
This is the object that represents the main window of "it". It is a subclass of Qt's QMainWindow. This class implements most of the main UI functions, so, for example, if you want your script to initiate the image open dialog you could call the OpenFiles() method. スクリプト can get a hold of the main window object with it.app.GetMainWindow().
It3ImageWindow
The Image Window is the widget that actually displays the images. One reason a script might want to interact with this widget is to receive mouse clicks or move events. The object is a subclass of the Qt QGLWidget, so any of that class's signals and slots will be available.
"it" Module Functions
Along with objects in the "it" module there exist some useful functions that script writers can use. These include the following:
GetCurrentElement
This will return the current Image Element, or None if there isn't one. If you want the actual ice.Image that this element contains you can extract that with the GetImage() method.
AddImage
If your script generates a new image in some fashion and you want that image to show up in the "it" UI, you can call AddImage to create a new Image Element and add it to the current Catalog. This is the only way for scripts to create It3ImageElement objects. スクリプト are free to move Image Elements around either to re-parent them or change sibling order.
GetCurrentCrop
Returns the crop coordinates of the current Crop Window. These are returned in a Python tuple in the standard RenderMan order of (xmin, xmax, ymin, ymax). The coordinates are normalized zero to one. If there is no crop window this routine returns (0.0,1.0,0.0,1.0).
"it" Sub-Modules
Within the "it" module there are a few sub-modules that are useful.
it.util
The util module is where factory-supplied functions appear, e.g. the built-in Ramp function. Ramp provides a convenient way for creating ramp images, which you can use by typing in the Console window:
it.util.Ramp()
There are many optional parameters to Ramp(), use Python's help() call to discover them with help(it.util.Ramp).
it.extensions
If you write extensions loaded from .ini files with the LoadExtension command they are loaded into this module. You might need to know this if you write one extension that wants access to another.