Script Module documentation

Introduction

The scripting module provides an efficient way to program effect modules, renderer modules or other post processing modules that are not present in the current version of Harmony.

This module provides access to an unlimited range of dynamically defined input and output ports. The user can also specify its own attributes for the module and access extern modules attributes. Using the scripting interface included in the module, the user can customize the behaviour of the soft render and call extern applications to easily interact with the current rendering context.

Getting Started

To create a scripting module, just drag and drop one from the I/O tab in the modules window. Initially, a scripting module is created with one input image port, one output image port and with no attributes.

Access the 'Specifications' menu to change the number of input/output ports, the attributes, as well as the script module menu widget itself. By modifying the xml description of the module, one can dynamically change the module parameters.

To add a port, add the following line to the port section:

<in type="port type"/> 

or

<out type="port type"/> 

Valid port types are:

• Image
• Image3D
• Peg

Once allocated into the module, input and output ports can be accessed through the scripting environment.

To add an attribute, add the following line to the attributes section:

<attr type="attribute type" name="name" value="default value"/> 

Valid attributes types are:

• bool
• int
• double
• String
• Text
• Colour
• Position2d
• Position3d

Once registered into the module, attributes can be fetched in the scripting environment. The script also has access to attributes from extern modules in the rendering context.

To specify a different interface to the current scripting module, add the following line to the specifications:

<editor path="$PROJECT/neweditor.xml"/>

The keyword '$PROJECT' is replaced with current project directory.

Finally, to change the default type of the current scripting module, add the following line to the specifications:

<type name="new name"/>

The type name of a module can be used in extern modules query to search for modules of the same properties.

Examples

Hello World !

// We have to begin somewhere !
MessageLog.trace( "Hello World!" );

// Copy input cel image directly into output cel.
// This is the default behaviour when script is empty.
Context.passThrough();

A more complex example

input = Context.input(0);              // retrieve first input port -- undefined if does not exist
output = Context.output(0);            // retrieve first output port -- undefined if does not exist

imread = input.workingCopy();          // retrieve temporary copy of input cel image
imwrite = new TemporaryFile( "png" );  // generate temporary file of extension png 

// Retrieve an attribute from a specific module
edge_attr = Context.Module( "module name" ).attribute( "attribute name" );
// Fetch a double value from the attribute.  If current attribute cannot be casted 
// to double, this function will return a default value.
edge_attr_value = edge_attr.doubleValue();
// Fetch a double value from the attribute at a specific frame in the timeline.
// If attribute is not linkable, this function returns value of current frame.
edge_attr_value_at = edge_attr.doubleValueAt( 4.0 );

// Retrieve an attribute from the current module
emboss_attr = Context.localAttribute( "attribute name" );
emboss_attr_value = emboss_attr.doubleValue();

// Create a new process.
// This process converts input image using ImageMagick convert application into an 
// embossed and edge emphasized image.
p = new Process( "convert", "-edge", edge_attr_value, "-emboss", emboss_attr_value, imread.path(), imwrite.path() );
p.launch();

// Save image into output port
output.setImageFile( imwrite );