imgtcl(1)
imgtcl - tcl-based scripting shell for the IL
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME imgtcl - tcl-based scripting shell for the IL SYNOPSIS imgtcl [filename arg1 arg2... ] DESCRIPTION The imgtcl shell provides a tcl-based scripting interface to the IL. IL operators and image files can be created, linked together, and displayed in an ilViewer or ilDisplay object. Most of the IL's classes can be be created and manipulated within imgtcl; multi-dimensional arrays can also be allocated (usually to be used as parameters to an IL function.) Invoking IL functions The various constructors and methods defined by the IL are available as imgtcl commands; default values, where defined, are supported by imgtcl. If a constructor or method has overloaded versions, then the alternative versions will have a slightly different name; these names are shown in the header file for that class. For instance, the ilFileImg object has four different constructors; in imgtcl they are named: ilFileImgOpen - opens an existing file by name ilFileImgOpenByDescriptor - opens an existing file by descriptor ilFileImgCreate - creates a new file ilFileImgCreateByDescriptor - creates a new file by descriptor if there is a return value, it will be converted to an ASCII string and returned as the value of the command. Many of the IL functions will return a pointer value; it will be converted to the string: (type-name*)address where <type-name> is the type of the pointer being returned and address is the hex address of the pointer (e.g. "(ilFileImg*)0x00100fe0"). Creating IL objects In general, class constructors are available as imgtcl commands; the syntax is: <object-type> <name> args Where <object-type> is the C++ name of the class (or an alternative, if the constructor is overloaded), <name> is a unique identifier used to name the new object, and args is a list of arguments to the constructor (default values as defined in the header file are supported). The object's name is returned as the value of the command. For example, the command: ilFileImgOpen sfoimg /images/sfo.fit will open the image file "/images/sfo.fit", create an ilFileImg object named "sfoimg" and return that name. As a side effect of creating an IL object, a new imgtcl command is created using the object's name. This command gives access to the C++ methods of that object's class and its base classes. For example, after the above call to create "sfoimg", the command: sfoimg getFileName will return the value "/images/sfo.fit", the name of the file. Any arguments should follow the method name. Function and method arguments The imgtcl interpreter is aware of the types of each functions's arguments, and will try to convert each string argument to the appropriate type. For numeric or string arguments, the conversion is simple. When an argument is an object, imgtcl will accept either the name of the object (e.g. "sfoimg") or the object's address, expressed as a string (e.g. 0x0010fe80). Care must be taken when passing literal addresses, as an incorrect address can cause a bus error (or other unpredictable problems). Viewing images To view a single image object, just type that object's name on a command line by itself; this will create an ilViewer window and display the image in that viewer. While the viewer is active, the imgtcl interpreter will be suspended; when the viewer window is closed, the imgtcl prompt will again be issued. When viewing more than one object, the "view" command may be used. For example, if there are image objects "sfoimg" and "convimg", the command "view sfoimg convimg" will bring up a viewer with those two images displayed, one on top of the other. Creating arrays with new Some methods require array arguments, and imgtcl provides the command "new" for the purpose of creating and initializing arrays. The syntax for new is: new <elem-type> [name] <dims> [= <initializer>] where <elem-type> is the C++ data type of the array elements (the simple types int, float, etc are supported, as well as many of the IL's struct types); <name> is a variable name that is to receive the address and dimension info of the array; <dims> is a list of integers defining the size of the array, and <initializer> is a list containing the values used to initialize the array. For multi-dimensional arrays, enclose each dimension in a set of braces {}. If the array elements are structs, list the field names in order. The optional <name> argument shown above can be used to retrieve and set the values stored in the array, and to delete the array. Example: imgtcl> new int {2 2} = { {1 2} {3 4} } This command creates a 2x2 int array and initializes it to contain: array[0][0] = 1 array[0][1] = 2 array[1][0] = 3 array[1][1] = 4 The next example creates an array of iflXYfloats with the indicated {x,y} values, and stores the address and dimension info in the variable "xy"; this variable is then used to print the values in the array, and then change the values stored in the array: imgtcl> new iflXYfloat xy {3} = { {0 0} {39 71} {266 271} } (iflXYfloat {3})0x1000a040 imgtcl> echo $xy (iflXYfloat {3})0x1000a040 imgtcl> $xy {0 0} {39 71} {266 271} imgtcl> $xy = { {42 268} {147 264} {265 263} } imgtcl> $xy {42 268} {147 264} {265 263} Notice that the "new" command returns the same string that the variable "xy" is set to. Built-in commands In addition to the complete external API of IL and IFL, several convenient built-in functions are provided. times times Returns the value returned by the Unix call times(2). malloc malloc n Returns the pointer resulting from malloc'ing n bytes. free free p Free the previously malloc'ed pointer. getopt getopt argc argv optspec Emulate the Unix getopt facility. The arguments to the command include the command-line arguments and a option specifier string. The command-line arguments are expected to be in conventional C form. That is, the array argv is zero-indexed with the zero-th argument being the command name. The format of the option specifier is described in getopt(3C). Here is an example: #!/usr/sbin/imgtcl # mangle args to match our getopt expectations incr argc set argv [linsert $argv 0 $argv0] # check for command line options while {[string compare [set c [getopt $argc $argv "ab:c:"]] EOF] != 0} { switch $c { a {set aFlag 1} b {set bArg $optarg} c {set cArg $optarg} } } # ... do processing ... xopendisplay xopendisplay dispName=NULL Returns the X Display pointer associated with displayName that results from the X call XOpenDisplay(3X11). xclosedisplay xclosedisplay p Returns the integer value returned by calling XCloseDisplay(3X11) with the previously-opened display pointer p. view view img1 ... Display a viewer, similar to imgview(1), one or more image objects. The viewer is retained between calls to view. Therefore, its state, such as being double- or single-buffered, or being in an RGB or pseudo color rendering mode. display display disp w h display disp img An ilDisplay object is constructed and returned as the "command" named disp. After the display is constructed, methods on ilDisplay can be invoked in the standard manner. readback readback mem img The image img is displayed and readback into a memory image. The result is readback in the RGBA unsigned byte format, regardless of the format of the image. If the input image has no alpha, the alpha channel is initialized to a constant 255. timepaint timepaint disp Precisely time the length of the paint() method call on disp. The result is returned in seconds. This function uses ilTimer(3) to time the interval. Note that the elapsed time to paint the view will not include the time to compute outstanding graphics requests. A more accurate measurement can be obtained by averaging the paint times over a long sequence of painting operations. vkview, vkviewer malloc n XXX obsolete? SEE ALSO IL(3), IFL(3), ilImage(3)