
viewimage(1)                 Khoros                  viewimage(1)

PROGRAM
     viewimage - interactive imagery/elevation display package

SYNTAX
     viewimage

     -i             input image filename

     [-e]           image with alternate elevation coordinates

     [-x]           x value of upper-left corner of image

     [-y]           y value of upper-left corner of image

     [-update]      initial update time

     [-display]     host:display.screen

     [-cmap_image]  image with alternate colormap filename

     [-use_cmap]    use colormap?

     [-prop]        use proportional plotting (makes the data be
                    a unit cube)

     [-fn]          Specifies the font for viewimage (use %
                    xlsfonts for available fonts)

     [-jr file.jp]  Creates a journal recording for viewimage

     [-jp file.jp]  Executes a journal playback for viewimage

     [-V]           Gives the version for viewimage

     [-U]           Gives the usage for viewimage

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called viewimage.ans
                    or file1

     [-a [file1]]   Uses viewimage.ans or file1 as the answer
                    file

DESCRIPTION
     Viewimage is an interactive imagery/elevation display pack-
     age; it is a new application that combines capabilities of
     the xprism3 plotting package and the editimage display pack-
     age.  The main purpose of viewimage is to take a Khoros viff
     file and use its image data as the imagery.  This data pro-
     vides the "picture" that is displayed, draped over the
     elevation data that is provided via another Khoros viff
     file.  It is very important that the viff file used for the
     imagery and the viff file used for the elevation data be of
     the same size - that is, they must have the same number of
     rows and the same number of columns.

     Viewimage accepts any Khoros viff file as its imagery input,
     and will convert the data type of the input image when
     necessary. Currently, viewimage can utilize a maximum of 256
     colors.  Any image that has more than this number of colors
     is converted to fit into the available number of colors with
     the vgamut program.  Note that this conversion will normal-
     ize the image to the total number of colors that are avail-
     able to be displayed on the workstation being used.  For the
     elevation data, viewimage will accept Khoros viff files of
     type Byte, Short, Integer, Float, and Double.  Note that the
     same viff file may be used as both the imagery data and the
     elevation data;  in this case, only the -i option flag is
     used.

     Viewimage provides all of the same plot types for represent-
     ing elevation data that xprism3 does: 3D, Scatter, Impulse,
     Wireframe, Mesh, Horizon, Surface, 3D Contour, 2D Contour,
     and Color Mesh.  However, when the elevation data is
     displayed as Color Mesh or Surface, the imagery data is used
     to fill in the plot rather than the colors that are used in
     xprism3.  If the display of colors is desired instead, the
     "Use Imagery" option on the "Attributes" subform may be
     turned off.

     The viewimage package also provides three of the same
     display utilities that are available with editimage: the
     PseudoColor and Interactive LookUp Table utilities for
     changing colormap values in the imagery data, as well as
     access to a variety of predefined Colormaps.

     Command Line Options

     -i {input image filename}
          This is the input VIFF image that will serve as the
          imagery data.  It must be a Khoros VIFF file.  The VIFF
          file may be of any data type except complex. If a
          colormap is to be used, the input image must have a map
          type of SHARED. If the map type is not SHARED the map
          will be ignored.

     [-e {input image with alternate elevation coordinates}]
          This is the input VIFF image that will give the eleva-
          tion data.  It must be a Khoros VIFF file.  The VIFF
          file may be of any data type except complex.

     [-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 graphical user
          interface to appear.

     [-update {update time}]
          Suppose that while you are displaying an image with
          viewimage, the Khoros VIFF file that is currently
          displayed is over-written.  Viewimage will automati-
          cally 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.    It must be specified "-update float-
          value", where floatvalue is a floating point value
          which must be greater than zero.

     [-display {display}]
          You may execute viewimage on one workstation, but
          display it on another.  If you wish to do this, you
          must specify the display on which viewimage will
          appear.  It must be specified as "-display
          host:screen".

     [-cmap_image {VIFF image w/ alternate colormap}]
          If desired, another image may be input, and its color-
          map will be used with the imagery data, instead of the
          input image's colormap.

     [-use_cmap {t/f}]
          While the default action of viewimage is to use the
          colormap associated with the imagery data, no colormap
          is required to be used.  If the colormap associated
          with the input image is not wanted, AND the "-
          cmap_image filename" is not used, specify "-use_cmap
          0", or "-use_cmap false".  In this case, the default
          colormap associated with the screen on which viewimage
          is being run will be used. NOTE:  when "Use Colormap"
          is specified as false, the "-cmap_image filename"
          option detailed above WILL NOT TAKE EFFECT.

     [-prop {t/f}]

     [-V {t/f}]
          The "Version" argument will print out the current ver-
          sion of viewimage.

     [-U {t/f}]
          The "Usage-" argument will print out the usage for
          viewimage, in much less detail than is given here.

     [-P {t/f}]
          The "Prompt" argument will give interactive prompting
          for each of the arguments listed above.

     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 "viewimage.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.

     [-a {filename.ans}]
          Use the answer file named "filename.ans" if the
          filename option is specified, or named "viewimage.ans"
          if no filename is given.  Viewimage will use the answer
          file to get values for all arguments listed above.  No
          other arguments should be necessary when the "-a" argu-
          ment is used.

          For much more detailed information on the viewimage
          display program, see chapter 8 of the User's Manual.

REQUIRED ARGUMENTS
     -i     type: infile
            desc: input image filename

OPTIONAL ARGUMENTS
     -e     type: infile
            desc: image with alternate elevation coordinates

     -x     type: integer
            desc: x value of upper-left corner of image
            default: -1
            bounds: -1 < [-x] < 1000

     -y     type: integer
            desc: y value of upper-left corner of image
            default: -1
            bounds: -1 < [-y] < 1000

     -update
            type: float
            desc: initial update time
            default: 2
            bounds: value > 0.0

     -display
            type: string
            desc: host:display.screen
            default: null

     -cmap_image
            type: infile
            desc: image with alternate colormap filename

     -use_cmap
            type: boolean
            desc: use colormap?
            default: true

     -prop  type: boolean
            desc: use proportional plotting (makes the data be a
            unit cube)
            default: true

EXAMPLES
     % viewimage -i feath.eye -e flow.eye

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lviewimage(3)
     editimage(1), xprism3(1)

RESTRICTIONS
     Viewimage provides three of the same display utilities that
     are available with editimage;  all of these work with
     respect to the RGB, CMY, HSV, HLS, UVW, XYZ, YIQ, and GREY
     color spaces.  In order to fully understand the information
     imparted by the display utilities of viewimage, it is impor-
     tant for you to have an understanding of the operation of
     each of these color spaces, as well as a feeling for how
     each of the available colorspaces relates to the others.
     Viewimage was written with the assumption that the user has
     the knowledge necessary to correctly interpret visual
     results generated and to recognise when those results are
     not valid.  Invalid results can be generated when the
     colorspace of the imagery does not match the colorspace of
     the display;  however, viewimage follows the philosophy that
     it is better to allow the uneducated user to generate
     incorrect results than to limit the experimenting researcher
     with rigid errorchecking.

COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

