Description:

Note: If you have worked with script objects prior to amira version 3.0, please read the compatibility notes at the end of this file.

amira is fully scriptable via its built-in Tcl interface (see Section 5 (Scripting)). The ScriptObject module allows the user or a custom solution provider to create scripts that fit seamlessly into the amira user interface, and define their own user interface components.

A script object is an object showing up in the Pool similar to an OrthoSlice or an Axis module. It can have ports, like sliders or buttons. The ports are defined by Tcl code and the reaction to a change of the ports is also implemented in Tcl. The Tcl code consists of a portion for initialization and a Tcl procedure that is called whenever the script has to react to changes of input parameters, the compute procedure.

Any amira script can be turned into a script object by putting a special header line into the script. Write an amira script (using your favorite text editor) and put a special header for script objects in the first line:

  # Amira-Script-Object V3.0
  echo "Hello world, a script is called."

Load this file into amira. A blue icon appears. Each time you click on the Restart button, the script will be read and executed and the above message appears in the console window.

During the execution of a script object, the global variable $this always contains the name of the currently active script object. This allows to easily access object-specific commands, the so-called methods. Declaring a method is very similar to declaring an ordinary Tcl procedure:

  $this proc name args body

Just like the Tcl command proc, you can declare a method by using $this proc. Methods can be executed by calling $this name args. The syntax is completely analogous to global Tcl procedures (see Section 5.2 (Introduction to Tcl)). The special point about a method is that inside the method the $this variable is set appropriately. Example:

  # Amira-Script-Object V3.0
  $this proc sayHello {} {
     echo "module $this is greeting you"
  }

If you load this script object, nothing will happen visibly. However, if your script object is called MyScript.scro, you can type

  MyScript.scro sayHello

in the amira console window, and you will get a personalized greeting line as the result.

There are several methods with a special meaning:

• $this proc constructor {} {...} defines a method that is called when the script object is created. This is used for creating user interface elements and initializing the object.
• $this proc destructor {} {...} defines a method that is executed when the object is deleted or restarted. Used for cleaning up or terminating communications.
• $this proc compute {} {...} defines a method that is called whenever a user interface component of the script object is changed by the user. See examples below.

Here is an example that uses the constructor and compute methods in order to define a simple user interface and to query the current state of that user interface:

  # Amira-Script-Object V3.0

  $this proc constructor {} {
    $this newPortIntSlider myValue
    $this myValue setLabel "Value:"
  }

  $this proc compute {} {
    set val [$this myValue getValue]
    echo "The value is $val"
  }

In the example, the constructor creates a new port, an integer slider which will appear in the user interface. The port has the internal name myValue and its visible label is set to Value. Whenever the user modifies the value of the slider, the compute method is called, and outputs the current port value.

In addition to defining methods, a script object also allows to define member variables. Analogous to Tcl variables, a member variable is a placeholder for a certain value, but a member is local to each script object. If you have two script objects A and B, both can have a member variable x, and the values of these two variables is kept separately. In order to define and query member variables, use the commands $this setVar and $this getVar (see below).

You can save amira networks containing script objects. When loading the saved network into amira, the following things will happen:

• the script object is created
• the saved value of all member variables is restored
• the constructor method is called
• the compute method is called
• the value of all ports is restored
• the compute method is called again

Connections:

Data [optional]
Can be connected to any data object. Can be used by the script.

Ports:

Script

This port is available for any script object. The Restart button deletes all dynamically created ports, sets the isFirstCall flag to 1 and calls the script. The text field indicates the location of the script file.

Commands:

newPortButtonList <name> <number-of-buttons>
Creates a new button list port.

newPortButtonMenu <name> <number-of-buttons> <number-of-options>
Creates a new button menu port.

newPortColormap <name>
Creates a new colormap port.

newPortDoIt <name>
Creates a new DoIt port.

Note: Starting with amira 4.0, a green Apply button is displayed by default, rather than the usual DoIt port. See the DoIt port documentation for further details.

newPortFilename <name>
Creates a new filename port.

newPortFloatSlider <name>
Creates a new float slider port.

newPortFloatTextN <name> <number-of-fields>
Creates a new float text port.

newPortMultiMenu <name> <num-options-1> [<num-options-2> ...]
Creates a new multi menu port.

newPortInfo <name>
Creates a new info port.

newPortIntSlider <name>
Creates a new integer slider port.

newPortIntTextN <name> <number-of-fields>
Creates a new integer text port.

newPortRadioBox <name> <number-of-toggles>
Creates a new radio box port.

newPortSeparator <name>
Creates a new separator port.

newPortText <name>
Creates a new text port.

newPortTime <name>
Creates a new time port.

newPortToggleList <name> <number-of-toggles>
Creates a new toggle list port.

newPortConnection <name> <type-name>
Creates a new connection port. The type name specifies what type of objects can be connected to the port. The type name of an existing object can be obatined using the Tcl command getTypeId.

deletePort <name-of-port>
Deletes a port which has been created using one of the newPort commands.

proc name args body
Define a Tcl member procedure (see above). The syntax is analogous to the global Tcl proc command. This command is not specific to the ScriptObject, but it is available in all amira objects.

setVar <variable> <value>
Variables stored in this way keep their values between successive calls of the compute procedure. Ordinary Tcl variables get lost. This command is not specific to the ScriptObject, but it is available in all amira objects.

getVar <variable>
Returns the value of a variable set using setVar. This command is not specific to the ScriptObject, but it is available in all amira objects.

testBreak
This commands checks if the stop button has been pressed. If so the execution of the script is automatically terminated. Use this command inside long animation loops or similar constructs.

In addition to the script object extensions, each script objects inherits a number of methods from the general amira object type.

Compatibility Note: The semantics of script objects has slightly changed with amira 3.0 compared to older amira versions. If the first line of the script contains the line "# Amira-Script-Object V0.1", the old behavior is enforced.