This chapter will describe the image capabilities of WIP. The first section focuses on the image files and file formats. The next section details the commands WIP uses to select or exclude parts of the image. The following section identifies some techniques commonly used to get the image in the right location and at the right aspect ratio. The last section concentrates on the WIP commands that generate plots using image data and the WIP commands that can be used to enhance these types of plots.
Currently, there are a number of image file formats that WIP can recognize. The number will change as more image file format drivers become available to WIP and are included in the distribution. The currently acceptable formats are:
In the current configuration of WIP, only one active image may be present at any one time. This is primarily because of the current way that WIP reserves memory for the image and also because of the limitation on memory space that many images can impose.
The image command is used to ``load'' an image into WIP. The command has three arguments but only the first one is required. The required first argument is the image file name. How the image file name is specified may be dependent on the format of the image (this will be explained in the section that follows). The second argument is optional and selects the plane number to read. This defaults to the first plane if this argument is not present or a non-existent plane is requested. The third argument is also optional and specifies a mask value. If the image has masked (undefined) data, WIP will set the masked data (e.g. magic numbers) to a value of -99 unless the third argument is present. If the mask value is present, then all masked data will be set to the requested value.
When the image command is called, WIP attempts to open the image file based on the different types of drivers available. If WIP can identify the image type, it will attempt to read the header information (if present) and then load the image into memory.
When an image has more than 3 dimensions,
the plane number argument (
) may take on any value in the range:
where 
is the total number of dimensions in the data set
and 
is the dimension size of the ith axis.
Hence, WIP will be able to correctly assign the plane number
if a plane from a higher dimension is desired.
Miriad images are a subset of the Miriad data set format. Currently, the Miriad image is one ``item'' of the full data set and the header information is also stored as individual ``items.'' Refer to the BIMA Project manuals for a more detailed description of Miriad and its data structure.
The FITS file format
is a standard data transfer format used to pass data
between different computers.
In general, FITS images will contain a header section followed by the
image data (in binary form).
WIP expects that the header will be in standard 80 character format and
must contain the standard keywords: SIMPLE, BITPIX, NAXIS,
NAXISi (for 
, NAXIS), and END.
WIP will only recognize FITS files with
BITPIX set to 16 (16 bit integers), 32 (32 bit integers),
or -32 (32 bit floating point).
In addition to the standard keywords,
WIP requests the following keywords
(but does not require them to be present):
BSCALE, BZERO, BLANK,
DATAMAX, and DATAMIN.
Also, the keywords
CRVALi,
CRPIXi,
CDELTi,
and
CTYPEi, (where i is either 1 or 2)
are searched to help set up the transformation matrix.
If the optional keywords are not found,
then reasonable default values are assigned.
Basic images
are simple binary files that contain a
multi-dimensional array along with (possibly) optional
header information at the beginning of the file.
Most image file formats will be structured something like this,
so the Basic file format should suffice if a particular image driver has not
yet been written.
The necessary information needed to load the Basic file is contained in
the file name argument to the
image
command.
The name syntax is:
filename`columnsXrows[`offset]
where filename is the name of the file on the disk, columns is the number of columns (in pixels), and rows is the number of rows (in pixels). The single character X defines the pixel data type and separates the columns value from the rows value. The character X may be only one of the following characters:
Some machines byte-swap their data. For all image types except Basic, the data is byte-swapped as needed. However, since Basic images are usually created and stored locally, they are probably already stored in the machine's native format. Hence, by default, Basic images are not byte-swapped. If however, on those machines, there are images that need to be byte-swapped when loaded into WIP, byte-swapping can be forced by using an upper case character to identify the pixel data type. For example, use `L' to force byte-swapped a signed 4 byte integer array. NOTE: Machines that are not byte-swapped will always ignore this byte-swapping option.
This section describes the methods WIP uses to associate a pixel in an image with a world coordinate position, how to select a subsection of the image, how to specify contour levels, and how to access the image header file.
All of the plotting commands discussed in Section 5.4 require a transfer function . Put simply, the transfer function tells WIP where a given pixel should be located relative to the world coordinates . The command to specify the transfer function is transfer . This command has six arguments that define the mapping from image pixel to world coordinate. If (I, J) corresponds to a position in the image array (a particular pixel), then (x, y), the corresponding position in world coordinates, is related by:
The constants a, b, c, d, e, and f are the six arguments to the transfer command. As an example, if the limits of a plot are the same as the number of pixels in an image (i.e. limits 1 Nx 1 Ny), then the default transfer function constants of (0, 1, 0, 0, 0, 1) will correctly map the image onto the display. This configuration is particularly useful for images with large limits and very small step sizes (e.g. very high resolution astronomical images).
Another simple example deals with images that are flipped in one direction. For an image with the y-axis flipped and the world coordinates set as in the example above, a transfer function with constants (0, 1, 0, (Ny + 1), 0, -1) will dynamically orient the image correctly.
If, however, you have loaded an astronomical image with the world coordinate limits set by the image header variables CRVAL, CRPIX, and CDELT, then a more useful set of values for the transfer function would be:
This transfer function can be, in fact, set up for the user via the command header when these header variables are present in the image file. If these header variables are not present in the image header, they may be set manually by the user (since they are standard user variables ). The user must set these user variables after the image is read into WIP but before the header command.
Using the command transfer without any arguments will automatically reset the transfer function to the default value of (0, 1, 0, 0, 0, 1).
Some images do not have the cdelt keywords but rather specify the pixel step sizes in a matrix. An example of that is a FITS image file that contains the keywords CD1_1, CD1_2, CD2_1, and CD2_2. To set up the transfer function (and the limits) for this type of FITS image like the header rd command would, a macro could be written as follows:
Two commands exist that allow easy selection of a sub-portion of an image. The command subimage sets the range of the indices such that only a subimage is displayed (regardless of the range of the transfer function or the limits). The other command, quarter (which should be called right after the image command) is used to select a particular quadrant of the current image. By default, the quarter command selects the inner quarter of the image, but may be requested to select other quadrants.
If the user would like as much of the image as possible to be displayed, but only the part that fits within a particular region, then the user should not specify the sub portion of the image (i.e. do not use the two commands subimage or quarter) but rather fix the world coordinates to the desired range. This method of fixing the world coordinates to clip the image is very powerful; especially when overlaying several image plots (see Section 5.3 below and the example in Section E.12).
Currently, there are two commands used to specify the contour levels and one command that can be used to scale the contour levels. The commands to specify contour levels are levels and autolevs. The arguments to levels are the individual contour level values. The arguments to autolevs are the number of levels desired, the type of contour levels (linear or logarithmic), and, optionally, the minimum and maximum over which to range the computed levels. If the minimum and maximum are not specified, they default to the minimum and maximum of the current image.
The command slev permits the user to scale the contour level array by a fixed amount. There are two arguments to slev; the first required and the second optional. The first argument is a string which specifies the type of scaling to perform and may be either absolute or percent. The type absolute is the default and specifies that the scaling value be multiplied directly; type percent means to use the scaling value as a percentage of the peak intensity of the plot. The second (optional) argument defines the scaling value and defaults to 1 (no scaling). As an example, the commands
The command header allows the user to read in certain header variables and set up particular defaults for the current image. The defaults established by a call to header are the transfer function and the world coordinates. The transfer function is set relative to the user variables CRVALX, CRVALY, CRPIXX, CRPIXY, CDELTX, and CDELTY (see the examples above). The limits (or world coordinates) are set by the header variables and the range of the indices specified by either subimage or quarter.
If the image header does not contain the proper header values or the image type does not allow them to be retrieved, the user may specify them using the set command. This, however, should be done after the image is loaded and before the header command is called.
Sometimes, it will be helpful to be able to annotate a halftone plot with a wedge. These are useful in that they help to delineate the gray or color range displayed. This is done with the wedge command. The arguments to wedge command are similar to the mtext command. There are required arguments which specify which side of the current viewport to display the wedge (this also fixes the orientation); the displacement from the viewport edge (in character height units); and the thickness of the wedge (also in character height units). If the displacement is negative, the wedge will appear inside the viewport; if it is positive, the wedge will be outside. Optional arguments include the minimum and maximum values to be used to display as the extremes of the wedge and a label which will be displayed on the outside of the wedge. If a label is desired, the minimum and maximum must be specified. If the minimum and maximum are not given, the wedge command will display the wedge in such a way that the entire range of values displayed by the most recent halftone command will be visible.
Sometimes the raw image is not desired to be displayed; the image needs to be mapped differently. For example, often it is useful to display the logarithm of the image. The command itf facilitates this. There are currently three types of image transfer functions available:
For halftone plots (see below), the default is to use a gray scale ramp. On devices that permit the use of colors beyond the color index 15, different color lookup tables may be used. The palette command loads a new palette. On some interactive devices, the change is immediately displayed. However, the user must be careful to be sure to load the desired palette prior to displaying a halftone on a hardcopy device. There are several pre-defined palettes available. The palette command has one required argument which is the number of the palette desired. The list below identifies the current list of pre-defined palettes.
If a pre-defined palette is not acceptable, one may be defined by the user using the lookup command. The lookup command maps the values in the X array to the red colors, the Y array to the green colors, and the ERR array to the blue colors. The data in the PSTYLE array identifies the ramp intensity level for the corresponding RGB values. The value in each of the four arrays must be between 0 and 1. Colors on the ramp are linearly interpolated from neighboring levels. An optional argument to lookup may be used to flip the resulting color table. For example, a trivial gray scale ramp is defined below:
Sometimes the hardest job in dealing with images is getting it to fit properly with the rest of the plot. In the previous section, many commands were identified that help to specify how the image pixel maps onto the world coordinate system . This section goes one step further by dealing with how a particular image should map onto the viewport of a particular window . In other words, this section will discuss how to correctly set the aspect ratio of the figure.
At first glance, it might be thought that the best place for WIP to control the aspect ratio of an image is within the header command. After all, it loads the coordinate transfer function and sets the world coordinate limits based on the information from the image header. This would be fine if only one image was ever dealt with on a plot. But this will fail whenever one image is to be overlaid on top of another image and the two images have different dimensions. Hence, it was decided to keep this task under the user's control. Unfortunately, this means more work for the user.
The rest of this section will introduce the commands necessary to set the aspect ratio for one image and try to illustrate how to properly set the aspect ratio for multiple (overlaid) images. Additional examples of these techniques will be found in Appendix E.
In general, the image plot should be displayed in such a way that the size of a pixel in the x-direction is the same as the size of a pixel in the y-direction. The winadj command permits the user to reconfigure the viewport such that the scale in the x- and y-directions are equal. This command must be used after the image is loaded and before the header command is called (i.e. before the world coordinates of the plot window are set). To illustrate, suppose we have an image named ``myimage'' which is dimensioned 80 by 33. The following commands constrain the viewport so that the halftone plot fits properly (i.e. has an aspect ratio of 80:33):
pixels.
In order for this to be true,
the range of values in the x-direction
must be from 0 to nx.
(likewise for the y-direction).
One of the most common mistakes in generating image plots is that user will (a) forget to adjust the window aspect ratio; or (b) call the winadj command after the header , transfer , or limits commands. Because the winadj command changes both the viewport and world coordinates, it is important that the limits (world coordinates) of the image be established after this command is called.
To illustrate how to correctly use the winadj command with the panel command, consider an example where two images should be displayed side by side. Because the two images have the same dimensional range, and for this example, it is desired that there should not be any gap between the images (i.e. the boxes should butt up against each other). The following macro definition and list of commands might be used:
The reason for the gap is because of the call to winadj. Remember that the winadj command sets the world coordinate system limits and then attempts to adjust the viewport coordinate system to have the same aspect ratio. The panel command has established a viewport (which, for this example, is split into two vertical halves). Next, the winadj command tries to adjust the aspect ratio of this viewport to match the image. In general, the resulting viewport from panel will not match the aspect ratio desired by the winadj command and the viewport will adjust to obtain the proper ratio. As a result, either the top or the right edge (or both) will need to move inward.
The correct solution to the problem above is to find the aspect ratio desired for one image and then to scale it by the number of images in each direction. Adjusting the initial viewport to this range will not only correct the problem seen in the example above but also remove the need for the call to the winadj command inside the macro. In this example, there are two panels in the x-direction and only one panel in the y-direction. Hence, the commands that will produce the properly scaled plot with the boxes butted together is shown in the listing that follows (with the winadj command removed from the definition of the mytask macro above):
A common plotting task is to overlay one image graph on top of another. Many times, the two (or more) images will have the same dimensions and this will present no problem. However, there are many examples where a smaller image is overlaid on top of a larger image (or vice-versa) or one image has a completely different scaling (resolution) than another. Making sure that the aspect ratio of these two images is maintained does not have to be difficult.
The simple case is when one image is used to define the limits of the world coordinates. Since the aspect ratio is defined by one image and its limits specify the world coordinate range of the plot, there is no need to compute the aspect ratio for the other image. The world coordinate limits need to be saved, however, and then loaded after the second image's header variables are read and transfer function defined. The following is an example of this method (the user variables \1--\4 are discussed in Chapter 8):
The more complicated case is when none of the images define the limits of the world coordinates of the plot. In this case, the limits need to be established by the user. If these limits are simple (i.e. not astronomical coordinates), then the winadj command can be used to establish the world coordinates and the aspect ratio. When astronomical coordinates are used, the aspect ratio must be calculated based on the plot range. In other words, determine the aspect ratio range using similar coordinate systems (e.g. in arcsec offsets) and then set the limits in the absolute coordinate system. The technique shown in the example above of saving the world coordinates and then reloading them can be well utilized for this case.
This section presents the various ways of generating a plot with an image. Each of the commands below requires that certain characteristics are defined prior to being called. Most of the image characteristics are described in Section 5.2.
Before any contour plots may be generated, the user must specify the contour levels using one or more of the techniques discuss in Section 5.2.
There is only one command in WIP to generate a contour plot: contour. This command, however, permits access to many different methods to use for drawing the contour plots. There are up to three optional arguments to the contour command.
The first (optional) argument specifies the method used to draw the contour plot. By default (or if the method s is selected), WIP draws a very simple contour plot. Selecting contour method t means the plot will be drawn with continuous contour lines (i.e. it starts a contour line and follows it until it ends). Contour method b means that the contour should be drawn (just like contour method s) but also allows a blanking value to be specified. Contour method l draws the same contour plot as method t except that it includes contour level labeling. The second and third optional arguments are ignored by the contour methods s and t.
The contour method t will draw positive contours values with solid lines (lstyle 1 ) and negative contour values with dashed lines (lstyle 2). This change of line styles may be overridden by specifying the contour method as -t. Using the method -t will mean that the contour command will draw both positive and negative contour values with the same (i.e. the current) line style. Note that the other two methods of drawing contour plots always uses the current line style regardless of the value of the contour level.
If contour method b is selected, an additional optional argument may be given that specifies the blanking value (image array values equal to this blanking value are ignored in the plot). The blanking value, if omitted, defaults to 0.
If contour method l is selected, the second (optional) argument may be provided to specify the spacing along the contour between labels (in grid cells) and the third (optional) argument is used to specify the minimum number of cells that must be crossed before drawing the first contour label. If not present, the second argument defaults to 16 and the third to 8.
Gray scale and color image plots are generated in WIP using the halftone command. By default, a gray scale halftone is generated. To create color, the display or hardcopy device must be capable of handling color maps and one must be loaded either with the palette or lookup command (see Section 5.2). The halftone command has two optional arguments that may be used to delimit the minimum and maximum intensity range of the gray scale. By default, the minimum and maximum of the image are used.
Currently, WIP uses the most recently loaded lookup table when displaying a halftone. Some devices permit this to be changed after the halftone is displayed but since this is not the case for hardcopy devices, the user should be careful to insert the desired palette prior to calling halftone when generating a hardcopy plot.
Halftones will only be drawn if the device is capable of accessing color indices larger than 15. Use the command `echo cmin cmax' to display the current values of CMIN and CMAX ).
There is a crude cross section plot available in WIP. It is the hi2d command. Each cross section slice consists of a hidden line histogram. A bias is applied to each successive slice in order to raise it ``above'' (the y-direction) the previous slice. This bias is the only required argument and is entered in the same units as the image data.
Two other optional arguments may be specified to control the display of the cross section plot. The first optional argument controls the slant of the plot by acting as an offset to successive cross sections in the x-direction. If this argument is positive (> 0), it creates a plot that appears to slant to the right; if negative (< 0), slant left. The default value for this argument is no slant effect (argument is 0). The last (optional) argument is a flag to specify whether the indices in the x-direction are centered or represent the left edges of the bins. The default value for this argument is to center the bins (argument is 0).
The beam command was created because many astronomical image files contain information about the beam size and orientation used to observe the source. This information can be used to display the beam providing a graphical presentation of the resolution of the image. The beam command draws a beam at the current cursor position (with an optional offset). This beam is outlined in the current color using the current line properties. The required arguments are the beam major axis, the minor axis, and the position angle. As in all astronomical images, the position angle is defined as 0 degrees towards the north and increases counter-clockwise.
The optional arguments include offsets, a scaling factor, a fill color
index, and a background rectangle color index.
The offsets permit the center of the beam to be shifted relative to the
current cursor position.
The scaling factor provides greater control over the aspect ratio.
By default, the scaling factor (or if it is provided and is negative) is
set to 
(which is proper for RA-Dec type scaling).
The fill color index is used to draw the beam with a filled color.
The background color index (if greater than or equal to zero)
is used as the color to draw the (filled) bounding box of the beam.
The optional offsets are provided in units of the width and height of the beam. This permits the user to easily shift the beam location. As an example of how to use the optional offsets, consider drawing a beam in the lower right corner of the window. Rather than computing the position and then guessing how much to move it so it is slightly offset from the box (and then having to redo it all again if the coordinates need to be changed!), the offsets permit an easy alternative: