.NH 1 "INTRODUCTION"
.XS
\s12\*(SN  INTRODUCTION\s0
.XE
.sp 2
This chapter covers other Khoros applications that are not large enough to
have an entire chapter dedicated solely to them.  These are, however, frequently
used programs that you should become familiar with.  \fBPutimage\fP is a 
non-interactive program which simply displays a VIFF image.  \fBGetimage\fP
is a utility with which you may "grab" images from your screen and create VIFF
images.  \fBIconimage\fP iconifies a VIFF image and displays it in
miniature using a sub-sampling algorithm.
.sp 3
.NH 1 "PUTIMAGE"
.XS
\s12\*(SN  PUTIMAGE\s0
.XE
.sp 
.PP
The \fBputimage\fP program is very simple.  It may be started
up with a single argument, the [-i] flag, followed by the name of the VIFF
image which is to be displayed.  \fBPutimage\fP will immediately display the 
image contained in the input VIFF file.   If the input VIFF image is
multiband, \fBputimage\fP will display the first (0th) band. 
Clicking the mouse within the displayed image will cause it to go away, and the
\fBputimage\fP program will end.  NOTE: you \fImust\fP keep the mouse STILL when
you click in the image in order to make the \fBputimage\fP program end.
.PP
When an image is too large to display within the window, \fBputimage\fP will 
display a small "pan" window.  
The white rectangle within the pan window indicates
the area that is currently displayed in the display window.  You may "pan"
about the image by pressing the mouse in the display window, holding the
mouse button down, and moving it.  Alternatively, you may perform this same
procedure in the little pan window;  the rectangle indicating the area that
is currently displayed will move with the mouse, and the display window will
update according to the location of the rectangle within the pan window.
.PP
The minimum syntax specification for \fBputimage\fP is:
.sp
\f(CW
% putimage -i {input image}
\fP
.sp 
.PP
There are many other command line options which may be specified with 
\fBputimage\fP.  A synopsis of these follows:
.sp
.IP "-i {input image filename}":
This is the only required input to \fBputimage\fP.
The file provided is must be a Khoros VIFF file.  The VIFF file may be of
any data type except complex.
.sp
.IP "[-ov {overlay image filename}":
If desired, a bit image may be specified to be overlayed onto the input
image.  It must be specified as "-ov filename" where the file provided
is a Khoros VIFF file of data type BIT. NOTE: if the VIFF image passed in is
NOT of type BIT, it will be automatically converted to type BIT, without
prompting or warning (this is only done internally - the file itself will
not be changed).  ALSO: if the VIFF data file passed in is a multiband image,
the first (0th) band will be taken as the overlay.
.sp
.IP "[-s {shape mask filename}]"
If desired, a bit image may be provided to act as a shape mask. When an image
is used as a shape mask for the currently displayed image, the only part of the
currently displayed image that will be visible is that part defined by the
pixels in the shape mask  that have a value of (1).  All other parts of
the currently displayed image will "disappear", and the background (the part
of the screen behind the image  display window) will show through.
Images work best as shape masks when they are the same size as the input data.
\f(CW$KHOROS_HOME/data/masks/\fP contains two images that make good shape masks.
To get a shape mask to go away, NULL out the "Shape Mask" parameter, and hit
<cr>.  You may have to hit the <cr> key twice.
WARNING: Only very simple BIT images should be used as shape masks.
For example, the bit image \f(CWKHOROS_HOME/data/masks/ball.bit\fP
is a good shape mask. As more complicated images are used (images with many
"holes" in them), \fBputimage\fP will become incredibly slow as the X server  
has to do much additional work in order to map the image to the window.  
WARNING: this feature will only work on X servers that support the Shape Extension.
.sp
.IP "[-c {clip mask filename}]"
If desired, a bit image may be input and used as a clip mask.
When an image is used as a clip mask for the currently displayedimage,
the only part of the input data that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current frame will appear in the background
color of the image window. Images work best as clip masks when they are the
same size as the input data.  \f(CW$KHOROS_HOME/data/masks/\fP contains two
images that make good clip masks.  To get a clip mask to go away, NULL out 
the "Clip Mask" parameter, and hit <cr>.
.sp
.IP "[-x {x value}, -y {y value}]
If your window manager does not use manual placement, or you would like to
over-ride the manual placement used by your window manager (this may not work
with all window managers), specify the (x,y) location in device coordinates
at which you would like the image to appear.
.sp
.IP "[-update {update time}]"
Suppose that while you are displaying an image with \fBputimage\fP, the Khoros
VIFF file that is currently displayed is over-written.  \fBPutimage\fP will
automatically register the fact that the input file has been changed, and
update the currently displayed image accordingly.  Using this argument, you
can determine how often the input file is checked for any potential
modifications.    The update time is a floating point value which must be 
greater than zero.
.sp
.IP "[-display {display}]"
You may execute putimage on one workstation, but display it on another.
If you wish to do this, you must specify the display on which \fBputimage\fP 
will appear.  It must be specified as "-display host:screen".
.sp
.IP "[-cmap_image {VIFF image w/ alternate colormap}]":
If desired, another image may be input, and its colormap will be used with the
input image, instead of the input image's colormap.
.sp
.IP "[-use_cmap {t/f}]":
While the default action of putimage is to use the colormap associated with
the currently displayed image, no colormap is required to be used.  If the
colormap associated with the input image is not wanted, specify "-use_cmap 0",
or "-use_cmap false".  In this case, the default colormap associated with the
screen on which putimage is being run will be used.
.sp
.IP "[-V {t/f}]"
The "Version" argument will print out the current version of \fBputimage\fP.
.IP "[-U {t/f}]"
The "Usage-" argument will print out the usage for \fBputimage\fP, in much less
detail than is given here.
.IP "[-P {t/f}]"
The "Prompt" argument will give interactive prompting for each of the arguments
listed above.
.IP "Creating an Answer file"
The "[-A {filename.ans}]" argument will create an answer file named
"filename.ans" if
the filename option is specified, or named "putimage.ans" if no filename
is given.  An answer file stores the values specified of all arguments listed
above.  Note: the "-A" argument is usually used in conjunction with the "-P"
argument.
.IP "[-a {filename.ans}]"
Use the answer file named "filename.ans"
if the filename option is specified, or named "putimage.ans" if no filename
is given.  Putimage will use the answer file to get values for all
arguments listed above.  No other arguments should be necessary when the "-a"
argument is used.
.sp 
.PP
In \fBcantata\fP, there are two representations of the \fBputimage\fP program:
\fIput_update\fP and \fIput_multi\fP.  Both of these represent executions of
\fBputimage\fP, but they differ in that the first, \fIput_update\fP, executes
\fBputimage\fP with an \fIupdate\fP argument of 2 seconds, while the second,
\fIput_multi\fP, does not use the \fIupdate\fP argument.  Thus, when the
\fIput_update\fP version is used, the image that it displays will be refreshed
whenever the input image changes;  the old image will be destroyed and the new
image will take its place.  On the other hand, the \fIput_multi\fP version will
not destroy the old image;  it will simply display a new image every time the 
input image is updated. 
.sp 3
.NH 1 "GETIMAGE"
.XS
\s12\*(SN  GETIMAGE\s0
.XE
.sp 
.PP
\fBGetimage\fP allows you to select a window from your screen running X
Windows, (X11R4), or a portion of your screen containing overlapping windows,
and turn it into a VIFF image.  \fBGetimage\fP provides a
convenient way in which to create a Khoros VIFF file from other images or 
windows that may be displayed.  It is especially useful when the raw image may 
not be readily available, but still displayable.  The raw image can be pulled
off the X11 screen using \fBgetimage\fP, and can be displayed with
\fBeditimage\fP, or processed with any of the image
processing routines provided through Khoros.
.PP
Note that the image created may not be a linear greyscale image. Since many
Khoros image routines expect to work on only linear greyscale images,
it may be necessary to linearize the image using \fBvmsquish\fP before it 
can be used properly.
.PP
\fBGetimage\fP may be used in two ways:  (1) you may get a single window
in its entirety from the screen, or (2) you may get specified portion of the
screen, regardless of the number of windows which it may include.
.PP
The first method is quite simple;  you specify the window to be made into a 
Khoros VIFF file by simply clicking the mouse on the desired window.  The 
Khoros image representation of the window will be stored in the output file
specified.  To use the first method, execute:
.sp
\f(CW
% getimage -o {output file}
\fP
.sp
.PP
The second method is also simple;  here, you specify the image to be created by first clicking the mouse on the upper left hand corner of the desired portion 
of the screen.  \fIKeeping the mouse button down\fP, move the mouse to the 
lower right hand corner of the desired portion of the screen;  the active 
portion will be indicated by rubber banding.  The rubber-banded portion of the 
screen will be extracted into a Khoros VIFF file with the name specified 
as soon as you release the mouse button.  To use the second method, execute:
.sp
\f(CW
% getimage -o outfile -e 1
\fP
.sp
.PP
There are other command line options which may be specified with 
\fBgetimage\fP.  A synopsis of these follows:
.sp
.IP "-o  output image filename"
This is the name of the Khoros VIFF image file which will be output.  It
is a required argument.
.sp
.IP "[-e {t/f, 1/0}]"
Provide a value of TRUE (1) if you want to use method (2) described above
to specify the desired region of the screen.
.sp
.IP "[-b {t/f, 1/0}]
Provide a value of TRUE (1) if you want the output VIFF image to be in 
bitmap format.
.sp
.IP "[-V {t/f}]"
The "Version" argument will print out the current version of \fBgetimage\fP.
.IP "[-U {t/f}]"
The "Usage-" argument will print out the usage for \fBgetimage\fP, in much less
detail than is given here.
.IP "[-P {t/f}]"
The "Prompt" argument will give interactive prompting for each of the arguments
listed above.
.IP "Creating an Answer file"
The "[-A {filename.ans}]" argument will create an answer file named
"filename.ans" if
the filename option is specified, or named "getimage.ans" if no filename
is given.  An answer file stores the values specified of all arguments listed
above.  Note: the "-A" argument is usually used in conjunction with the "-P"
argument.
.IP "[-a {filename.ans}]"
Use the answer file named "filename.ans"
if the filename option is specified, or named "getimage.ans" if no filename
is given.  Putimage will use the answer file to get values for all
arguments listed above.  No other arguments should be necessary when the "-a"
argument is used.
.sp 3
.NH 1 "ICONIMAGE"
.XS
\s12\*(SN  ICONIMAGE\s0
.XE
.sp 
.PP
This is a non-interactive display program which creates an iconified, or
miniature, version of an image in  Khoros VIFF format and displays it.
The image is sub-sampled according to the desired width and height, and 
displayed. Clicking the mouse within the iconified image will cause it 
to go away, and the \fBiconimage\fP program will end.
.PP
The minimum syntax specification for \fBiconimage\fP is:
.sp
\f(CW
% iconimage -i {input image}
\fP
.sp 
.PP
There are many other optional command line arguments to \fBiconimage\fP
which may be used if desired.  A synopsis of these follows.
.sp
.IP "-i {input image filename}":
This is the one required input for \fBiconimage\fP.
It must be specified as "-i filename", where the file provided is a
Khoros VIFF file.  The VIFF file may be of any data type except complex.
.sp
.IP "[-ov {overlay image filename}":
If desired, a bit image may be specified to be overlayed onto the
input image.  It must be specified as "-ov filename" where the file provided
is a Khoros VIFF file of data type BIT. NOTE: if the VIFF image  passed in is
NOT of type BIT, it will be automatically converted to type BIT, without
prompting or warning (this is only done internally - the file itself will
not be changed).  ALSO: if the VIFF data file passed in is a multiband image,
the first (0th) band will be taken as the overlay.
.sp
.IP "[-s {shape mask filename}]"
If desired, a bit image may be provided to act as a shape mask. When an image
is used as a shape mask for the input image, the only part of the
input image that will be visible is that part defined by the
pixels in the shape mask  that have a value of (1).  All other parts of
the input image will "disappear", and the background (the part
of the screen behind the image  display window) will show through.
Make sure that the input file to be used as a shape mask is of the same 
size as the iconified version of the image.
WARNING: Only very simple BIT images should be used as shape masks.
As more complicated images are used (images with many
"holes" in them), \fBiconimage\fP will become incredibly 
slow as the X server  has to
do much additional work in order to map the image to the window.  WARNING:
this feature will only work on X servers that support the Shape Extension.
.sp
.IP "[-c {clip mask filename}]"
If desired, a bit image may be input and used as a clip mask.
When an image is used as a clip mask for the input image,
the only part of the iconified data that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current frame will appear in the background
color of the image window. Make sure that the input file to be used as a 
clip mask is of the same size as the iconified version of the image.
.sp
.IP "[-x {x value}, -y {y value}]
If your window manager does not use manual placement, or you would like to
over-ride the manual placement used by your window manager (this may not work
with all window managers), specify the (x,y) location in device coordintes
at which you would like the iconified image to appear.
.sp
.IP "[-w {width}, -h {height}]
The -w and -h options allow the width (in pixels) and the
height (in pixels) of the icon image to be specified.
.sp
.IP "[-update {update time}]"
Suppose that while you are displaying an iconified image with \fBiconimage\fP,
the Khoros VIFF file that is currently displayed is over-written.  Iconimage
will automatically register the fact that the input file has been changed, and
update the currently displayed image accordingly.  Using this argument, you
can determine how often the input file is checked for any potential
modifications. The update time provided must be a floating point value which is
greater than zero.
.sp
.IP "[-display {host:screen}]"
You may execute \fBiconimage\fP on one workstation, but display it on another.
If you wish to do this, you must specify the display on which \fBiconimage\fP
will appear.  It must be specified as "-display host:screen".
.sp
.IP "[-use_cmap {t/f}]":
While the default action of \fBiconimage\fP is to use the 
colormap associated with the input image, no colormap is required to be used.  
If the colormap associated with the input image is not wanted,
specify "-use_cmap 0", or "-use_cmap false".  In this case, the default
colormap associated with the screen on which \fBiconimage\fP is being run will
be used.
.sp
.IP "[-V {t/f}]"
The "Version" argument will print out the current version of \fBiconimage\fP.
.sp
.IP "[-U {t/f}]"
The "Usage-" argument will print out the usage for \fBiconimage\fP, in much less
detail than is given here.
.IP "[-P {t/f}]"
The "Prompt" argument will give interactive prompting for each of the arguments
listed above.
.IP "Creating an Answer file"
The "[-A {filename.ans}]" argument will create an answer file named
"filename.ans" if
the filename option is specified, or named "iconimage.ans" if no filename
is given.  An answer file stores the values specified of all arguments listed
above.  Note: the "-A" argument is usually used in conjunction with the "-P"
argument.
.IP "[-a {filename.ans}]"
Use the answer file named "filename.ans"
if the filename option is specified, or named "iconimage.ans" if no filename
is given.  Iconimage will use the answer file to get values for all
arguments listed above.  No other arguments should be necessary when the "-a"
argument is used.
.sp 3
