imgtcl(1) imgtcl(1)
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
Page 1
imgtcl(1) imgtcl(1)
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>]
Page 2
imgtcl(1) imgtcl(1)
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
Page 3
imgtcl(1) imgtcl(1)
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
Page 4
imgtcl(1) imgtcl(1)
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.
Page 5
imgtcl(1) imgtcl(1)
vkview, vkviewer
malloc n
XXX obsolete?
SEE ALSO
IL(3), IFL(3), ilImage(3)
Page 6