NAME: TVIMAGE PURPOSE: This purpose of TVIMAGE is to enable the TV command in IDL to be a completely device-independent and color-decomposition- state independent command. On 24-bit displays color decomposition is always turned off for 8-bit images and on for 24-bit images. The color decomposition state is restored for those versions of IDL that support it (> 5.2). Moreover, TVIMAGE adds features that TV lacks. For example, images can be positioned in windows using the POSITION keyword like other IDL graphics commands. TVIMAGE also supports the !P.MULTI system variable, unlike the TV command. TVIMAGE was written to work especially well in resizeable graphics windows. Note that if you wish to preserve the aspect ratio of images in resizeable windows, you should set the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works equally well on the display, in the PostScript device, and in the Printer and Z-Graphics Buffer devices. The TRUE keyword is set automatically to the correct value for 24-bit images, so you don't need to specify it when using TVIMAGE. AUTHOR: FANNING SOFTWARE CONSULTING: David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: davidf@dfanning.com Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Graphics display. CALLING SEQUENCE: TVIMAGE, image INPUTS: image: A 2D or 3D image array. It should be byte data. x : The X position of the lower-left corner of the image. This parameter is only recognized if the TV keyword is set. If the Y position is not used, X is taken to be the image "position" in the window. See the TV command documenation for details. y : The Y position of the lower-left corner of the image. This parameter is only recognized if the TV keyword is set. KEYWORD PARAMETERS: BACKGROUND: This keyword specifies the background color. Note that the keyword ONLY has effect if the ERASE keyword is also set or !P.MULTI is set to multiple plots and TVIMAGE is used to place the *first* plot. ERASE: If this keyword is set an ERASE command is issued before the image is displayed. Note that the ERASE command puts the image on a new page in PostScript output. _EXTRA: This keyword picks up any TV keywords you wish to use. HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row and column on either side, rather than the default of one full row/column at the ends of the array. If you are interpolating images with few rows, then the output will be more consistent with this technique. This keyword is intended as a replacement for MINUS_ONE, and both keywords probably should not be used in the same call to CONGRID. KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the specified position in the window. If you prefer, you can force the image to maintain its aspect ratio in the window (although not its natural size) by setting this keyword. The image width is fitted first. If, after setting the image width, the image height is too big for the window, then the image height is fitted into the window. The appropriate values of the POSITION keyword are honored during this fitting process. Once a fit is made, the POSITION coordiates are re-calculated to center the image in the window. You can recover these new position coordinates as the output from the POSITION keyword. MARGIN: A single value, expressed as a normalized coordinate, that can easily be used to calculate a position in the window. The margin is used to calculate a POSITION that gives the image an equal margin around the edge of the window. The margin must be a number in the range 0.0 to 0.333. This keyword is ignored if the POSITION or OVERPLOT keywords are used. It is also ignormed when TVImage is executed in a multi-plot window, EXCEPT if it's value is zero. In this special case, the image will be drawn into its position in the multi-plot window with no margins whatsoever. (The default is to have a slight margin about the image to separate it from other images or graphics. MINUS_ONE: The value of this keyword is passed along to the CONGRID command. It prevents CONGRID from adding an extra row and column to the resulting array, which can be a problem with small image arrays. NOINTERPOLATION: Setting this keyword disables the default bilinear interpolation done to the image when it is resized. Nearest neighbor interpolation is done instead. This is preferred when you do not wish to change the pixel values of the image. This keyword must be set, for example, when you are displaying GIF files that come with their own non-IDL color table vectors. NORMAL: Setting this keyword means image position coordinates x and y are interpreted as being in normalized coordinates. This keyword is only valid if the TV keyword is set. OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored and the image is positioned in the location established by the last graphics command. For example: Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95] TVImage, image, /Overplot POSITION: The location of the image in the output window. This is a four-element floating array of normalized coordinates of the type given by !P.POSITION or the POSITION keyword to other IDL graphics commands. The form is [x0, y0, x1, y1]. The default is [0.0, 0.0, 1.0, 1.0]. Note that this can be an output parameter if the KEEP_ASPECT_RATIO keyword is used. TV: Setting this keyword makes the TVIMAGE command work much like the TV command, although better. That is to say, it will still set the correct DECOMPOSED state depending upon the kind of image to be displayed (8-bit or 24-bit). It will also allow the image to be "positioned" in the window by specifying the coordinates of the lower-left corner of the image. The NORMAL keyword is activated when the TV keyword is set, which will indicate that the position coordinates are given in normalized coordinates rather than device coordinates. Setting this keyword will ensure that the keywords KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION are ignored. OUTPUTS: None. SIDE EFFECTS: Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image may not have the same aspect ratio as the input data set. RESTRICTIONS: If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are used together, there is an excellent chance the POSITION parameters will change. If the POSITION is passed in as a variable, the new positions will be returned in the same variable as an output parameter. If a 24-bit image is displayed on an 8-bit display, the 24-bit image must be converted to an 8-bit image and the appropriate color table vectors. This is done with the COLOR_QUAN function. The TVIMAGE command will load the color table vectors and set the NOINTERPOLATION keyword if this is done. Note that the resulting color table vectors are normally incompatible with other IDL-supplied color tables. Hence, other graphics windows open at the time the image is display are likely to look strange. EXAMPLE: To display an image with a contour plot on top of it, type: filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat') image = BYTARR(360,360) OPENR, lun, filename, /GET_LUN READU, lun, image FREE_LUN, lun TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $ YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10 To display four images in a window without spacing between them: !P.Multi=[0,2,2] TVImage, image, Margin=0 TVImage, image, Margin=0 TVImage, image, Margin=0 TVImage, image, Margin=0 !P.Multi = 0 MODIFICATION HISTORY: Written by: David Fanning, 20 NOV 1996. Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF. Removed BOTTOM and NCOLORS keywords. This reflects my growing belief that this program should act more like TV and less like a "color aware" application. I leave "color awareness" to the program using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF. Fixed a small bug that prevented this program from working in the Z-buffer. 17 April 1997. DWF. Fixed a subtle bug that caused me to think I was going crazy! Lession learned: Be sure you know the *current* graphics window! 17 April 1997. DWF. Added support for the PRINTER device. 25 June 1997. DWF. Extensive modifications. 27 Oct 1997. DWF 1) Removed PRINTER support, which didn't work as expected. 2) Modified Keep_Aspect_Ratio code to work with POSITION keyword. 3) Added check for window-able devices (!D.Flags AND 256). 4) Modified PostScript color handling. Craig Markwart points out that Congrid adds an extra row and column onto an array. When viewing small images (e.g., 20x20) this can be a problem. Added a Minus_One keyword whose value can be passed along to the Congrid keyword of the same name. 28 Oct 1997. DWF Changed default POSITION to fill entire window. 30 July 1998. DWF. Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF. Added limited PRINTER portrait mode support. The correct aspect ratio of the image is always maintained when outputting to the PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF Added a MARGIN keyword. 18 Oct 1998. DWF. Re-established Device, Decomposed=0 keyword for devices that support it. 18 Oct 1998. DWF. Added support for the !P.Multi system variable. 3 March 99. DWF Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF. Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF. Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF. Added the OVERPLOT keyword to allow plotting on POSITION coordinates estabished by the preceding graphics command. 11 Oct 99. DWF. Added automatic recognition of !P.Multi. Setting MULTI keyword is no longer required. 18 Nov 99. DWF. Added NOINTERPOLATION keyword so that nearest neighbor interpolation is performed rather than bilinear. 3 Dec 99. DWF Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF. Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF. Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF. Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF. Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF. Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF. Added BACKGROUND keyword. 20 April 2000. DWF. Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF. Rearranged the PLOT part of code to occur before decomposition state is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF. Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF. Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF. Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to display images. 8 June 2001. DWF. Fixed small problem with multiple plots and map projections. 29 June 2003. DWF. Converted all array subscripts to square brackets. 29 June 2003. DWF. Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF. Small modification at suggestion of Karsten Rodenacker to increase size of images in !P.MULTI mode. 8 December 2004. DWF. Minor modifications on Karsten Rodenacker's own account concerning margination and TV behaviour. 8 December 2004. KaRo