ENVISION commands


PROGRAM NAME

putimage - Non-Interactive Image Display

DESCRIPTION

Putimage is a visualization program that displays image data. It provides no mechanism for image interaction or modification; it simply takes input data and displays it as an image on the screen.

The input file containing the data to be displayed as an image is monitored by default; the file is checked every 2 seconds for change, and if it has been modified, the image display is updated accordingly. The interval at which the input file is checked for modification may be specified using the [-update] option. A value of 0 disables checking.

A clip mask may be used to dictate the portion of the data that is displayed using the [-clip] argument. Clip masks are discussed in Chapter 1 of this volume, Introduction to the Envision Toolbox Manual.

An alternate input color map may be used to change the current color map using the [-cmap] argument. Colormaps are discussed in Chapter 1 of this volume, Introduction to the Envision Toolbox Manual

The horizontal and vertical offsets within the image display window can be specified using the [-xoffset] and [-yoffset] arguments. These offsets specify the upper left corner of the image that appears in the display window. For small images which fit entirely within the image display window, this will always be (0,0). However for large images that must use a pan icon because the image will not fit entirely within the image window, the x and y offsets may be any value ranging from 0 to the width/height of the image display window.

When displaying images of data type complex, a complex conversion value may be specified which dictates how complex data is converted for display using the [-complex] argument. There are nine different complex conversion types:

"" 1 - Real
2 - Imaginary
3 - Phase
4 - Magnitude
5 - Log Magnitude + 1
6 - Log Magnitude
7 - Log Magnitude Sqrt + 1
8 - Log Magnitude Sqrt
9 - Magnitude Sqrt

When displaying image data, it is possible to specify how data is normalized for display using the [-normaltype] argument. Before images are displayed by the image object, normalization must be done in order to ensure that the pixel values of the image fall within a certain range. Normalization can be one or two types: local or global. With local normalization, the normalization procedure is performed locally using the maximum and minimum values of each of the red, green, and blue map columns. For global normalization, the normalization procedure is performed globally over all of the three columns displayed as red, green, and blue.

When data is normalized for display, it is possible to specify the algorithm that defines how data is normalized by using the [-normalmethod] argument. Normalization may be a simple stretch over the values that may be displayed on a workstation, or any of three variations on a standard deviation normalization may be used. For a simple normalization of values to within displayable intensity bounds, set "Range: Maximum". Alternatively, images can have contrast increased or reduced using one of the standard deviation normalizations. The four different normalization methods are:

"" 1 - Range: Maximum
2 - Range: +/-1 Standard Deviations
3 - Range: +/-2 Standard Deviations
4 - Range: +/-3 Standard Deviations

When a colormap is present, it is possible to define which column (or columns) in the color map is displayed as red, green, and blue using the [-redcol], [-greencol], and [-bluecol] arguments. An image with a simple colormap has three map columns associated with it, where the pixels in the image are used to index into the map columns; the first map column defines the red values, the second map column defines the green values, and the third map column defines the blue values. In this way, the color for each pixel in the image is defined. However, for images that may have multiple map columns present, such as a clustered image, it may be useful to view any of the map columns as red, green, or blue.

Similar to specifying which map column(s) are displayed as red, green, and blue, it is possible to define a function representing the colors using the [-redfn], [-greenfn], and [-bluefn] arguments. With images having colormaps made up of more than three columns, such as those produced by clustering algorithms, it is often informative to be able to apply a function to the values in those map columns in order to define the values that will be displayed for each of the red, green, and blue columns. For example, in an image having 6 map columns, you might define the red intensity of pixel 10 as (map column 2)[10]+ (map column 3)[10]/ map columns 4)[10]. In this case, the "Red Function" may be set to the string defining the function to be applied in order to produce the values that will be used as red. Functions must have only variable M, where M stands for "map column"; following each M must be a number starting at zero and ranging to N-1, where N is the number of map columns available in the image. For example, a valid function for red might be: (M2 - M3)/(M2 + M3) or (M0 + M1 + M2)/(M3 - M4). Equation values follow the standard rules of precedence; evaluation proceeds from left to right, and use of parentheses is fully supported.

In a more simple use, the "Red Function" may also be the variable representing the map column which is to be used to specify the red values of the pixels in the image. For example, if you wanted the fourth map column to define the red values of the pixels in the image, (remember that map column numbering begins at 0), you could set "Red Function" to: M3. You can also set the "Red Function" to a constant, if desired. For example, if you wanted the red values of all the pixels in the image to be 200, you could set "Red Function" to 200.

By default, the "Red Function" is set to M0, or the first map column, the "Green Function" is set to M1, or the second map column, and the "Blue Function" is set to M2, or the third map column. Thus, the defaults produce results that you would normally expect for an image with a colormap where no function was being applied.

By default, Putimage will share its colormap with all other applications running at the same time; that is, it does not not use a "private colormap", but rather makes use of the "default colormap". It is possible to specify that Putimage allocate its own private colormap or "grab" all available colors for its own use. This is done using the [-priv] argument. When [-priv] is specified, moving the mouse pointer into the display window will cause the display to have its private colormap installed; moving the pointer out of the display window will cause the private colormap to be de-installed. This results in the "technoflashing" phenomenon characteristic of private colormap installation.

Color allocation can also be controlled and set to either "read-only" or "read/write" using the [-alloc] argument. When set to "read-only", once a color cell has been allocated, it can have its color set only once; from then on, the color cell can be shared by multiple applications, but not changed. If Putimage requires the color displayed to change, it must re-allocate the color cell, forcing a re-display of data. This can be an expensive procedure. In contrast, after a read/write color cell is allocated, it can have its color changed at any time without re-allocation; the data being displayed does not need to be redisplayed, and the color update process is much more efficient. However, the colors used in Putimage cannot be shared by other applications.

On creation, the image display window may be placed manually (the default method), or placed automatically. For automatic placement of the image window, specify the desired location in device (screen) coordinates using the [-x] and [-y] arguments.

While the image display window should be created with a default size that is appropriate to display the data, a width and height for the window can be specified explicitly using the [-width] and [-height] arguments. Note that the interactive resizing of the image display window using the window manager is currently NOT supported.

REQUIRED ARGUMENTS

-i
type: infile
desc: File containing image

OPTIONAL ARGUMENTS

-cmap
type: infile
desc: File containing alternate colormap filename
default: {none}
-clip
type: infile
desc: File containing clip mask
default: {none}
-xoffset
type: integer
desc: Specifies the horizontal offset within the image display
default: 0
bounds: 0 < [-xoffset] < 10000
-yoffset
type: integer
desc: Specifies the vertical offset within the image display
default: 0
bounds: 0 < [-yoffset] < 10000
-complex
type: list
desc: Specifies the conversion type for complex data
default: 5 "Log Magnitude + 1 "
-normaltype
type: cycle
desc: Specifies how data is normalized for display
default: 1 "Global"
-normalmethod
type: list
desc: Defines the algorithm used in data normalization
default: 1 "Range: Maximum"
-redcol
type: list
desc: Specify which column in a map is to be displayed as red
default: 1 "Map Column 0"
-greencol
type: list
desc: Specify which column in a map is to be displayed as green
default: 2 "Map Column 1"
-bluecol
type: list
desc: Specify which column in a map is to be displayed as blue
default: 3 "Map Column 2"
-redfn
type: string
desc: Provides an equation that specifies the red map column
default: M0
-greenfn
type: string
desc: Provides an equation that specifies the green map column
default: M1
-bluefn
type: string
desc: Provides an equation that specifies the blue map column
default: M2
-priv
type: boolean
desc: Use private colormap
default: false
-alloc
type: cycle
desc: Color allocation policy
default: 1 "Read Only"
-x
type: integer
desc: X location for GUI autoplacement
default: -1
bounds: -1 < [-x] < 1000
-width
type: integer
desc: Window width
default: 512
bounds: -1 < [-width] < 1000
-y
type: integer
desc: Y location for GUI autoplacement
default: -1
bounds: -1 < [-y] < 1000
-height
type: integer
desc: Window height
default: 512
bounds: -1 < [-height] < 1000
-update
type: float
desc: How often to check input file for modification
default: 2
bounds: value >= 0.0

EXAMPLES

% putimage -i image:ball

% putimage -i image:mandril

SEE ALSO

putdata(1)

RESTRICTIONS

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.