NAME: SUBCELL AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Finds the position of a subwindow within a reference window. CALLING SEQUENCE: sub = subcell(panel, refposition) DESCRIPTION: SUBCELL finds the position of a subwindow within another window. This could be useful in cases where the position of one window is specified relative to another one. When plotting, one often wants to describe the position of the plot box with respect to another box on the screen. In that respect, the reference window can be thought of as a virtual display, and the SUBPOS as virtual a position on that display. The SUBCELL function transforms the relative coordinates of the virtual position back to normal screen coordinates. INPUTS: SUBPOS - A four-element array giving the position of the subwindow, *relative* to a reference window given by POSITION. Given as [XS1, YS1, XS2, YS2], which describes the lower left and upper right corners of the subwindow. Each value is a number between zero and one, zero being the lower/left and one being the upper/right corners of the reference window. POSITION - A four-element array giving the position of the reference window on the screen. Equivalent to the graphics keyword of the same name. OPTIONAL INPUTS: NONE INPUT KEYWORD PARAMETERS: MARGIN - If set, then a default value for SUBPOS is found using the DEFSUBCELL function. RETURNS: The position of the subwindow, in normal coordinates. PROCEDURE: EXAMPLE: SEE ALSO: DEFSUBCELL, SUBCELLARRAY EXTERNAL SUBROUTINES: DEFSUBCELL MODIFICATION HISTORY: Written, CM, 1997 Added copyright notice, 25 Mar 2001, CM $Id: subcell.pro,v 1.2 2001/03/25 18:54:31 craigm Exp $

NAME: PLOTIMAGE AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Displays an image via a "PLOT"-like interface. CALLING SEQUENCE: PLOTIMAGE, img, [xrange=xrange,] [yrange=yrange,] ... DESCRIPTION: PLOTIMAGE displays an image (or slice of an image) on the current graphics device. The syntax is very similar to the PLOT command, in the sense that an XRANGE and YRANGE for the plot can be specified. PLOTIMAGE keeps separate the notions of the image coordinate system and the displayed coordinate system, which allows any input image to be "cropped," "zoomed," or "flipped." PLOTIMAGE allows the user to express image extents in physical units rather than pixel units. The image coordinate system specifies the physical coordinates of original image data, IMG. The image is considered to be a 2D array (IMG = ARRAY(NX,NY)), where the values are attached to the midpoint of each geometric pixel. The image has NX columns and NY rows. Physical coordinates are attached to each pixel by using the IMGXRANGE and IMGYRANGE keywords. The IMGXRANGE keyword is a two-element array specifying the "left" and "right" boundaries of the image pixels in physical units; the IMGYRANGE keyword specifies the "top" and "bottom" boundaries of the image. This is illustrated in Figure 1 for a simplified case. ___ +-----------+-----------+ ^ IMGYRANGE[1] | | | | | IMG[0,1] | IMG[1,1] | | | + | + | | | | | | | | | | +-----------+-----------+ | | | | | | IMG[0,0] | IMG[1,0] | | | + | + | | | | | | | | | v +-----------+-----------+ ___ IMGYRANGE[0] | | |<----------------------->| IMGXRANGE[0] IMGXRANGE[1] Figure 1. Simplified example of a 2x2 input image, demonstrating that IMG[*,*] values refer to the pixel mid-points, and that IMGXRANGE and IMGYRANGE ranges specify the physical coordinates of the outer edges of the image extent in X and Y, respectively. The displayed plot coordinate system is entirely independent of the native image coordinates. Users can set up the plot scale using any combination of {X,Y}RANGE, {X,Y}STYLE and/or {X,Y}LOG, as they would for any IDL plot, using physical units. The input image will then be overlayed on this coordinate system. If the displayed plot coordinates are narrower than the native image coordinates, then the displayed portion of the image will be cropped to fit. If the displayed coordinates are wider than the native image coordinates, then the image will be displayed with blank spaces on either side (see Figure 2). A mirror "flip" is also possible in X and/or Y, if XRANGE or YRANGE are specified in reverse order. ___ +---------------------------------------+ ^ | ___ | | | ^ +---------------+ | | | | | | | | | | | | | | | IMGYRANGE| | IMG | | | YRANGE | | | | | | | v | | | | | ___ +---------------+ | | | |<-- IMGXRANGE -->| | | | | v +---------------------------------------+ ___ |<------------- XRANGE -------------->| Figure 2. Example of an image whose native image coordinates are embedded in a wider plot display range. The standard [XY]STYLE keywords can be used to style either axis. However at the very least [XY]STYLE=1 is always implied, i.e. the plot limits exactly obey the [XY]RANGE keyword values. If XLOG or YLOG are set, then the image is assumed to be sampled on a logarithmic grid, and logarithmic axes are displayed accordingly. PLOTIMAGE does not attempt to resample the image from linear scale to logarithmic scale, or reverse. Psuedocolor images may be of any type, but must rescaled to a byte range by using the RANGE keyword. By default the color range used in the rescaling operation is 0 to !D.N_COLORS - 3B. The extra two color values are reserved for the background and default pen colors. This behavior can be adjusted by specifying the BOTTOM and/or NCOLORS keywords. Truecolor images must always be of type BYTE and one of their dimensions must have 3 elements, corresponding to the three color planes of the image. INPUTS: IMG - Array to be displayed. For single-plane images (i.e., pseudocolor), the image must be two dimensional and of any real numeric type. For images that are not of BYTE type, the RANGE keyword must be supplied, and then PLOTIMAGE will rescale the image values to a byte range. An image declared as ARRAY(NX,NY) will be NX pixels in the x-direction and NY pixels in the y-direction. The image is resampled to fill the desired display region (and optionally smoothed). For three-plane images (i.e., truecolor) the image must be of type BYTE. One of the dimensions of the array must have three elements. Hence it must be one of BYTARR(NX, NY, 3), BYTARR(NX, 3, NY) or BYTARR(3, NX, NY). The 3-element dimension is recognized automatically. OPTIONAL INPUTS: NONE INPUT KEYWORD PARAMETERS: IMGXRANGE, IMGYRANGE - Each is a two component vector that describes the X and Y position of the outer edges of the first and last pixels. Default: IMGXRANGE = [0,NX] IMGYRANGE = [0,NY] XRANGE, YRANGE - Each is a two component vector that specifies the X and Y plot ranges, respectively. These values are not required to coincide with IMG[XY]RANGE. Default: XRANGE=IMGXRANGE YRANGE=IMGYRANGE POSITION - Position of the inner plot window in the standard graphics keyword format. Overrides PANEL and SUBPANEL. INTERP - if set, interpolate (smooth) the image before displaying. This keyword applies to the screen displays. For printed images that are coarser than MIN_DPI, the image is implicitly interpolated regardless of INTERP. PRESERVE_ASPECT - if set, preserve the aspect ratio of the original image (in pixels). The result will be the largest image that fits in the display region while maintaining approximately square pixels. However, PIXEL_ASPECT_RATIO overrides PRESERVE_ASPECT. The POSITION keyword will be reset upon output to the ultimate image position. DEFAULT: not set (image will fill POSITION rectangle) PIXEL_ASPECT_RATIO - The ratio of width to height for each pixel. If specified, then the image will be scaled so that each pixel has the specified aspect ratio. If not specified, then the image will be scaled independently in X and Y in order to fill the POSITION rectangle. NOTE: If you want to change the overall image aspect ratio, then use the POSITION keyword. DEFAULT: undefined (image will fill POSITION rectangle) MIN_DPI - if printing, the minimum dot-per-inch pixel resolution for the resulting image. Output images that would be coarser than this value are resampled to have a resolution of at least MIN_DPI, and smoothed. Some common resolutions are: screen, 90 dpi; dot matrix, 72 dpi; laser printer 300-600 dpi. Note that large values of MIN_DPI will produce very large output files. Default: 0 (i.e., the output image will not be smoothed) RANGE - a two element vector. If the image is single plane (i.e., pseudocolor) the input image can be of any real numeric type, and then must be rescaled into byte range with this keyword. In contrast, truecolor images must always be of type BYTE. Values are scaled into byte range with the following statement: RESULT = BYTSCL(INPUT, MIN=RANGE(0), MAX=RANGE(1), $ TOP=NCOLORS-1) + BOTTOM so that pixels with an intensity RANGE(0) are set to BOTTOM; those with RANGE(1) are set to the maximum color. Default: no range scaling occurs (and the image must hence be of type BYTE -- otherwise an error occurs) NCOLORS - number of color table values be used in the byte rescaling operation. Default: !D.N_COLORS - BOTTOM - 1 (for default pen color) BOTTOM - bottom-most value of the color table to be used in the byte rescaling operation. Default: 1 (for default background color) NOERASE - If set, the display is not erased before graphics operations. NODATA - If set, the image is not actually displayed, but coordinate axes may be drawn. NOAXES - An attempt is made to render the image without coordinate axes. However, it's usually more straightforward to set XSTYLE=4 or YSTYLE=4, which is the standard IDL way to disable coordinate axes. ORDER - same interpretation as the !ORDER system variable; if ORDER=0, then the first pixel is drawn in the lower left corner; if ORDER=1, then the first pixel is drawn in the upper left corner. Default: 0 PANEL, SUBPANEL - An alternate way to more precisely specify the plot and annotation positions. See SUBCELL. PLOTIMAGE will pass other keywords directly to the PLOT command used for generating the plot axes. XSTYLE=1 and YSTYLE=1 are enforced. OUTPUTS: NONE PROCEDURE: EXAMPLE: This example constructs an image whose values are found by z(x,y) = cos(x) * sin(y) and x and y are in the range [-2,2] and [4,8], respectively. The image is then plotted, with appropriate axes. x = findgen(20)/5. - 2. + .1 ; 0.1 = half-pixel y = findgen(20)/5. + 4. + .1 zz = cos(x) # sin(y) imgxrange = [-2.,2.] ; extend to pixel edges imgyrange = [4.,8.] plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange This second example plots the same image, but with a plot range much larger than the image's. xr=[-10.,10] yr=[-10.,10] plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange, $ xrange=xr, yrange=yr SEE ALSO: OPLOTIMAGE, BYTSCL EXTERNAL SUBROUTINES: SUBCELL, DEFSUBCELL MODIFICATION HISTORY: Written, CM, 1997 Correct various one-off problems, 02 Feb 1999, CM Made self-contained with some pre-processing, 17 Oct 1999, CM Corrected bug in newly introduced CONGRID functions, 18 Oct 1999, CM Correct behavior with no POSITION keyword, 17 Nov 1999, CM Simplified axis plotting, 17 Nov 1999, CM Use _EXTRA keyword in first PLOT, but with blank TITLEs, 11 Jan 2000, CM Correct implementation of X/YSTYLE in first PLOT, 11 Feb 2000, CM Correct CONGRID implementation (small effect when enlarging most images), 14 Feb 2000, CM Major changes: 19 Apr 2000 - now handle decomposed color, automatic color mapping via RANGE, and 24-bit multiplane images - new PRESERVE_ASPECT keyword to keep square pixels - removed legacy TVIMAGE code - smoothing is more configurable, esp. for printers, but is not done by default; more printers are supported Corrected INTERPOLATE behavior (thanks to Liam Gumley ), other minor tweaks, CM 20 Apr 2000 Added ability to use PRESERVE_ASPECT with POSITION, PANEL or SUBPANEL keywords CM 20 Oct 2000 Oops, a typo is now fixed, CM 23 Oct 2000 Add fix for MacIntoshes and DECOMPOSED color, Tupper, 02 Aug 2001 Better behavior with fractional pixels (ie, when the image pixels are very large compared to the screen), 23 Aug 2001 Add support for Z buffer, CM, 20 Oct 2002 Memory conservation: use REVERSE() to reverse IMG; rewrote PLOTIMAGE_RESAMP to rescale entire image instead of each color plane separately. Jeff Guerber, 30 July 2003 Add PIXEL_ASPECT_RATIO keyword, 22-25 Nov 2005 Check for the case of an 1xNXxNY 3D image and treat it as a 2D image. The "1" dimension can be anywhere, CM, 03 Sep 2006 Add the ORDER keyword parameter, CM, 20 Mar 2007 Enable XLOG and YLOG keywords, for logarithmic axes; doesn't actually resample the image from linear<->log, CM 21 Jan 2009 Documentation, CM, 21 Jan 2009 Allow reverse color scale, CM, 13 Nov 2010 $Id: plotimage.pro,v 1.15 2010/11/13 09:53:39 cmarkwar Exp $