|
|
|
|
|
|
|
|
|
|
|
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
|
||||||||||||||||||||||
|
|
The MEDx ImageScript Reference PageThe goal of ImageScript is to provide users with a simple, easy to use scripting language interface to the MEDx image processing engine. The primary goal is to provide script writers with access to the complete functionality of MEDx that is available through the user interface. To that end we have chosen Tcl as the basis for the scripting language since the style and nature of programming in Tcl is very similar to that of existing shell scripting languages which many scientists currently use.
Important Tcl functionsNot only does Tcl provide generic programming constructs such as control loops and procedures, it is also easily extended and can be embedded in other applications. It provides an interpreter-based programming environment which allows for rapid prototyping and development. Learning to script is a combination of becoming familiar with the basic Tcl functions, understanding the main Tcl and ImageScript data types, and learning how to develop a script. One of the advantages of Tcl is that it is an interpreted language which allows a user to enter a command and see the affect the command. The main Tcl functions that you will want to be come familiar are set, expr, and various control functions. The set function assigns a value to a variable. The expr function computes a mathematical expression. For example, the following command will compute which slice is the middle slice of a volume:
In this case, the expr function divides the variable NumSlices by 2 and this result is assigned to another variable called MiddleSlice. Any command enclosed in brackets is executed first and the result of that command is used in the evaluation of the outer command. Also notice that the value of a variable is de-referenced by preceding it with a dollar sign. The various Tcl control functions allow you to write scripts that loop over a set of functions as well as make decisions based on a test-condition. This category of functions includes: for, foreach, while, and if-else. For example, to open a set of 10 images you can use a for loop:
The for loop has four components: an initialization command, a test-condition, a loop completion command, and a loop body. Upon entering a for loop, the initialization command is executed. The test-condition is then evaluated. If the test-condition is not true then the command in the the loop body are executed. After executing the loop body, the loop completion command is executed. The loop body will continue to be evaluated until the test-condition is true. In the above example, the variable i is used as a counter to keep track of the number of times the loop is executed. On each iteration of the loop, the variable n is set equal to the value of i plus one. The incr command is used in the loop completion command to increment i by one in preparation of the next iteration of the loop. On the first iteration of the loop i is equal to zero and n is set equal to 1. In this iteration the named nec1.hdr is opened into a folder referenced by the variable Folder. The result of opening this image is assigned to the 0th element of the array called Volume. The other looping functions (foreach and while) work in a similar fashion. Tcl and ImageScript Data TypesTcl supports four main data types: strings, numbers, arrays, and lists. The fundamental data type in Tcl is a string. A string is simply an arbitrary set of characters. The string nees to be enclosed in quotes if it contains any white space characters such as a space, tab, or return. For example, the following command will create a variable whose value is Registered Scans:
Numbers can be either traditional integers or floats. It is important to remember that calculations performed on numbers which do not include a decimal point are performed using integer arithmetic. Thus, in the following example i will have a value of 0 and x will have a value of 0.5:
Tcl also support arrays. An array is a variable which is indexed by some value. Typically, the value used is an integer. But since Tcl supports associative arrays the index can be any arbitrary string. In the following example, the indices to the array Volume are integers:
While in the next example the indices are strings:
Multidimensional arrays are also supported in Tcl. It is important to use a consistent format for the indices. For example, the extra spaces in the second use of the MxOpenImage will result in two different elements to the array Volume:
vs.
Another important Tcl data type is the list. A list is an ordered collection of elements where each element is any Tcl data type. The elements of a list can also be of mixed data types:
Keyed lists are a special type of list that provide a structured data type similar to structs in the C programming language. A keyed list is a list in which each element contains a key and value pair. For example the ImageScript function MxGetPageProperties will return the properties of a particular page in a keyed list:
results in:
Using the keyed list functions, keylget, keylset, and keylkeys it is easy to manipulate keyed lists. For example, to the value of the Name key in the above example one can use the keylget function:
which will return MRI.img. The ImageScript functions use keyed lists are used to pass parameters to functions which have a large number of optional parameters. For example, the function MxReslice has 15 different parameters many of which will not be changed from their defaults on any given call. By using a keyed list to pass only those parameters for which a non-default value will be specified, the user does not have the burden of specifying all 15 parameters on every call. In addition, keyed lists are used to pass back large amounts of data such as property lists. In the example above, MxGetPageProperties returns a keyed list with all of the properties of a page. Other keyed list manipulation functions include:
The result of keylkeys is a list of the keys in the keyed list:
The final set of properties after performing the above keyed list functions are:
Magic CookiesImageScript adds an additional data type called "magic cookies" to the native set of Tcl data types. A magic cookie is a reference to a MEDx object such as an image, folder, page, or graphic. The basis of magic cookies comes from the X server model of object naming. In the X model of object naming, whenever a program creates an object the X server passes back a magic cookie which the program uses to refer to that object. In the server there is a table mapping magic cookies to objects. A similar model has been implemented in ImageScript. MEDx maintains a mapping of magic cookies to their corresponding windows, folders, pages, images, volumes, and graphics. Every time a script creates a new object MEDx passes back to the script the magic cookie which refers to that object. For example, when a new folder is created two new objects are created: a folder and a window on that folder.
In the above example, the variables Folder and Window are assigned the magic cookies for the folder and the window that are created respectively. The variable Folder can be used later in the script to tell MEDx into which folder an image should be opened. For example,
The image nec1.hdr is opened into the flder created above. At the same time a new magic cookie for this image is returned in Volume. Magic cookies provide scripts with references or handles to all of the objects in MEDx. How to Develop a ScriptDeveloping a script is simply a matter of determining which functions in ImageScript will perform the same operations that you normally perform interactively. Your script will consist of a set of ImageScript functions with perhaps additional Tcl commands to repeatedly perform a set of functions. There are a number of ways to find the functions for your script. First, the documentation for ImageScript can be found from the help page in the ImageScript dialog box. In this documenation, there is an alphabetical list of all of the ImageScript functions. In addition, the functions are broken down by category. Second, our web-site also contains a search engine. The names of ImageScript functions all begin with Mx and are related to the operation they perform. Probably most convient way to find a function is to use the ImageScript Logging facility described below. When testing your script, it is best to use an interactive shell (this is one of the options in the ImageScript dialog box). The shell will allow you to enter your script a line at a time. Since each function will be performed immediately after you have entered it, you will be able to get instant feedback as to whether the function worked as you had expected. Logging - Automatic Script GenerationThe MEDx User Interface provides an automatic Tcl script file generation facility using the Tcl Logger. The Tcl Logger records all the actions performed by the user via the user interface in the Tcl scripting language. The script generated by the Logger is written in Tcl using calls to functions in the MEDx extensions to Tcl. The script file generated by the Logger reproduces the actions performed the user when interacting through the user interface. This feature provides script writers with a very easy method for writing scripts. As an example, suppose a script is need to perform a single subject PET analysis for 10 subjects. Suppose further the steps of the analysis is to load the data into a new folder, group it and apply a paradigm file followed by intensity normalization, a t-test, application of a LUT, and running the local min/max finder saving the folder in the subjects directory when done. The script writer can perform these steps interactively and the following script would be automatically generated by the Logger: Sample Log
By simply adding a for loop to the automatically generated script and replacing the references to subject S1 with the loop variable Subj, the following script can be used to analyze the all 10 subjects at once. Final Script
Error HandlingThere are two levels of error handling in ImageScript. Syntax errors are treated as unrecoverable and as such the Tcl error handling mechanism is invoked. In these instances, Tcl will halt execution of the script and dump the Tcl stack when executing a script. If the script is executed without an interactive shell the dump is displayed in the window in which MEDx was started. All other errors are considered recoverable and the Mx functions return a success or failure status ("0" and "1" respectively). The cause of the most recent recoverable MEDx error can be determined by calling MxReportError which will return a description of the error and the function which caused the error. The example in the description of MxReportError shows how this function can be used to test for and respond to errors. Some Example ScriptsThe example scripts listed below illustrate the wide range of tasks that can be easily scripted.
Tcl/Tk References
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|
|
|
|
