List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
CLOSE_DEVICE
PURPOSE:
CLOSE_DEVICE closes the PostScript device and spawns
a print job to the printer specified by the user or
it can be used to close a graphics window.
CATEGORY:
Graphics
CALLING SEQUENCE:
CLOSE_DEVICE [,OLD_DEVICE] [, Keywords ]
INPUTS:
OLD_DEVICE -> Name of device that shall become the active
plotting device. If omitted, "X", "WIN" or "MAC" will
be set depending on !VERSION.OS_FAMILY. Hence,
specification of OLD_DEVICE is only rarely needed.
This parameter works together with the OLD_DEVICE
parameter of OPEN_DEVICE which returns the device name
before the postscript device (or a graphics device) is
opened. The OLD_DEVICE parameter can be misused to set
the output device to anything! Therefore, it's probably
safest to not use it and stick with the operating system
dependent default.
KEYWORD PARAMETERS:
LABEL -> a string that contains an annotation for a postscript
plot (usually a user name and/or filename). The current
data and time will be appended if TIMESTAMP is set.
NOTE: TIMESTAMP will produce an annotation even if LABEL
is not provided. The annotation is only added to
postscript plots and only if the ps file is actually
open.
/TIMESTAMP -> add date and time to the LABEL on the plot.
If no LABEL is provided, the username and filename
(value of FILENAME will be used or the filename of the
current postscript file will be added). The timestamp
is only added to postscript plots and only on the last
page.
PRINTER -> Name of the printer queue to send output to.
Default is 'none', i.e. the postscript file will only
be closed and can then be manually printed e.g. using
the Unix lpr command. Direct printing only works in
Unix environments.
WINDOW -> window number to be closed (or -1 if current)
_EXTRA=e -> any additional keywords to CLOSE_DEVICE will
be passed on to STRDATE which is used to format the
date and time string. Possible values are: /SHORT,
/SORTABLE, /EUROPEAN.
LCOLOR -> the color value for the LABEL (default 1).
LPOSITION -> the position of the LABEL in normalized
coordinates (a two-element vector with default
[0.98,0.007]).
LSIZE -> the charcter size of the LABEL (default 0.7).
LALIGN -> the alignment of the LABEL (default 1).
FILENAME -> name of the PostScript file. This is actaully
obsolete now because the PostScript filename is
determined at the time the file is opened (e.g. in
routine OPEN_DEVICE)
OUTPUTS:
If postscript device is active, a *.ps file will be closed
and optionally sent to the printer.
SUBROUTINES:
External Subroutines Required:
================================
STRDATE (function)
REQUIREMENTS:
Requires routines in the
NOTES:
The WINDOW keyword is only evaluated if the current device
supports windows [!D.FLAGS AND 256) GT 0]. If you only want
to close a postscript file and don't fuss around with your
screen windows then simply don't set this keyword.
EXAMPLES:
(1)
CLOSE_DEVICE
; Closes a postscript file (if opened) and resets the
; current plotting device to 'X', 'WIN', or 'MAC'
; depending on the OS_FAMILY.
(2)
CLOSE_DEVICE, PRINTER='hplj4', LABEL='mgs', /TIMESTAMP
; If current device name is PS then the postscript
; file will be closed, a user, date and time label will
; be added and the file will be spooled to the printer
; queue 'hplj4'. NOTE: Printing of the file fails if you
; specified FILENAME as a relative path in the OPEN_DEVICE
; command and you changed your working directory while
; the device was opened.
(3)
CLOSE_DEVICE, WIN=-1
; If current device name is PS then the postscript file
; will be closed. If the current device is a screen
; device (that supports windows), then the active window
; will be deleted.
MODIFICATION HISTORY:
bmy, 18 Aug 1997: VERSION 1.00
bmy, 19 Aug 1997: VERSION 1.01
mgs, 20 Aug 1997: VERSION 1.02
mgs, 08 Apr 1998: VERSION 2.00
- automatic filename detection
- default device depending on OS_FAMILY
mgs, 21 May 1998:
- added L.. keywords to control label
and timestamp output
mgs, 18 Nov 1998:
- added output of username as default in timestamp
bmy, 28 Jul 2000: TOOLS VERSION 1.46
- cleaned up a few things
bmy, 24 May 2007: TOOLS VERSION 2.06
- Updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/close_device.pro)
NAME:
GIF2PS
PURPOSE:
Translates GIF images to PostScript format.
CATEGORY:
Graphics
CALLING SEQUENCE:
GIF2PS [, FILENAME [, Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the input GIF file.
If FILENAME is omitted then GIF2PS will prompt
the user to supply a file name via a dialog box.
FILENAME may contain wild card characters.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the output PostScript file.
Default is "idl.ps".
/FLIP_BW -> Set this keyword to turn black pixels into
white pixels and vice-versa. This is useful for
creating PostScript files of GIF images that have a
dark background color.
XOFFSET, YOFFSET (optional) -> Set these keywords to specify
the X and Y Margins in inches. Defaults are
XMARGIN = 0.5 inches and YMARGIN = 0.5 inches.
_EXTRA=e -> Picks up extra keywords for OPEN_DEVICE,
TVIMAGE, and CLOSE_DEVICE.
OUTPUTS:
Sends output to a PostScript file, whose name is given
by the OUTFILENAME keyword.
SUBROUTINES:
External Subroutines Required:
==============================
EXTRACT_FILEPATH (function)
DIALOG_PICKFILE (function)
TVIMAGE
REQUIREMENTS:
None
NOTES:
(1) Image processing options are limited to flipping the
black and white pixels. This should be good enough
for most purposes.
(2) XMARGIN and YMARGIN assume that we are printing out for
standard USA 8.5 x 11" page. Device sizes listed below
are also in inches.
EXAMPLE:
(1)
GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps'
; Translates the image in "my_gif.gif" to
; the PostScript file "my_ps.ps".
(2)
GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps', /FLIP_BW
; Same as in (1), but also changes all black
; pixels to white and vice-versa.
(3)
GIF2PS, 'my_gif.gif', OUTFILENAME='my_ps.ps', /FLIP_BW, $
XMARGIN=0.5, YMARGIN=0.5
; Same as in (2), but also will "pad" the image with
; 0.5" of white space around each side.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.45
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/gif2ps.pro)
NAME:
JPEG2PS
PURPOSE:
Translates JPEG images to PostScript format.
CATEGORY:
Graphics
CALLING SEQUENCE:
JPEG2PS [, FILENAME [, Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the input JPEG file.
If FILENAME is omitted then JPEG2PS will prompt
the user to supply a file name via a dialog box.
FILENAME may contain wild card characters.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the output PostScript file.
Default is "idl.ps".
/FLIP_BW -> Set this keyword to turn black pixels into
white pixels and vice-versa. This is useful for
creating PostScript files of JPEG images that have a
dark background color.
XOFFSET, YOFFSET (optional) -> Set these keywords to specify
the X and Y Margins in inches. Defaults are
XMARGIN = 0.5 inches and YMARGIN = 0.5 inches.
_EXTRA=e -> Picks up extra keywords for OPEN_DEVICE,
TVIMAGE, and CLOSE_DEVICE.
OUTPUTS:
Sends output to a PostScript file, whose name is given
by the OUTFILENAME keyword.
SUBROUTINES:
External subroutines required:
------------------------------
EXTRACT_FILEPATH (function)
DIALOG_PICKFILE (function)
TVIMAGE
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
(1) Image processing options are limited to flipping the
black and white pixels. This should be good enough
for most purposes.
(2) XMARGIN and YMARGIN assume that we are printing out for
standard USA 8.5 x 11" page. Device sizes listed below
are also in inches.
(3) Refer to the READ_JPEG procedure manual pages for
JPEG image handling options.
EXAMPLE:
(1)
JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps'
; Translates the image in "my_jpg.jpg" to
; the PostScript file "my_ps.ps".
(2)
JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps', /FLIP_BW
; Same as in (1), but also changes all black
; pixels to white and vice-versa.
(3)
JPEG2PS, 'my_jpg.jpg', OUTFILENAME='my_ps.ps', /FLIP_BW, $
XMARGIN=0.5, YMARGIN=0.5
; Same as in (2), but also will "pad" the image with
; 0.5" of white space around each side.
MODIFICATION HISTORY:
bmy, 28 Jan 2000: VERSION 1.45
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/jpeg2ps.pro)
NAME:
OPEN_DEVICE
PURPOSE:
If hard copy is to be generated, OPEN_DEVICE opens the
PostScript device. Otherwise OPEN_DEVICE opens an Xwindow.
CATEGORY:
Graphics
CALLING SEQUENCE:
OPEN_DEVICE [,OLD_DEVICE] [,keywords]
INPUTS:
OLD_DEVICE -> This is now obsolete, and is only maintained
for backwards compatibility.
KEYWORD PARAMETERS:
/PS -> will send PostScript file to printer
FILENAME -> The name to be given the PostScript file.
Default: idl.ps
/LANDSCAPE -> will enable PostScript landscape mode
/PORTRAIT -> will enable PostScript portrait mode
XOFFSET, YOFFSET -> Keywords for the DEVICE command. XSIZE
specifies the horizontal offset (in inches) of the page,
and YSIZE specifies the vertical offset (in inches) of
the page. Defaults are as follows:
Plot type XOFFSET YOFFSET
-------------------------------------------------
Portrait 0.25 0.25
Landscape 0.75 0.75
XSIZE, YSIZE -> Keywords for the DEVICE command. XSIZE
specifies the horizontal size (in inches) of the page,
and YSIZE specifies the vertical size (in inches) of
the page. Defaults are as follows:
Plot type XSIZE YSIZE
-------------------------------------------------
Portrait 8.0 10.0
Landscape 11 - 2*XOFFSET 8.5 - 2*YOFFSET
/COLOR -> will enable PostScript color mode
WINPARAM -> An integer vector with up to 5 elements:
WINPARAM(0) = window number (if negative, a window
will be opened with the /FREE option.
WINPARAM(1) = X dimension of window in pixels (width)
WINPARAM(2) = Y dimension of window in pixels (height)
WINPARAM(3) = X offset of window (XPOS)
WINPARAM(4) = Y offset of window (YPOS)
TITLE -> window title
/Z -> If set, will initialize the Z-buffer device. If WINPARAM
is specified, then the size of the Z-buffer region will be
WINPARAM[1] x WINPARAM[2] pixels. If WINPARAM is not
specified, then the size of the Z-buffer region will be
set to a default size of 640 x 512 pixels.
NCOLORS -> If /Z is set, NCOLORS specifies the number of colors
that will be made available to the Z-buffer device.
_EXTRA=e -> additional keywords that are passed to the call to
the DEVICE routine (e.g. /ENCAPSULATED)
OUTPUTS:
OLD_DEVICE -> stores the previous value of !D.NAME for
use in CLOSE_DEVICE. Note that CLOSE_DEVICE will automatically
set the default screen device if OLD_DEVICE is not provided,
hence it will only rarely be used.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
If PS=0 then
Open Xwindow WINPARAM(0), which is WINPARAM(1) pixels wide
in the X-direction, and WINPARAM(2) pixels wide in the
Y-direction.
If PS=1 then
depending on /PORTRAIT or /LANDSCAPE and /COLOR
postscript is enabled in either portrait or landscape
mode as color or b/w plot
The key parameter which determines whether to open a postscript
file or a screen window is PS. Therefore, e.g. in a widget
application, you can pass a standard set of parameters for both,
postscript and screen, to this routine, and determine the device
to be chosen by a button state or checkbox which is passed into PS.
Also is currently hardwired for 8.5 x 11 inch paper (US
format). Need to extend this to European A4 paper soon.
EXAMPLES:
(1)
OPEN_DEVICE, WINPARAM=[0,800,800]
; opens a screen window of size 800x800
; pixels at the default position
(2)
OPEN_DEVICE, /LANDSCAPE, FILENAME='myplot.ps'
; opens a postscript file named myplot.ps in
; b/w and landscape orientation
(3)
OPEN_DEVICE, PS=PS, /PORTRAIT, /COLOR, WIN=2
; depending on the value of PS either a color
; postscript file named idl.ps is opened or screen
; window number 2 in default size.
(4)
OPEN_DEVICE, /Z
; Opens the IDL Z-buffer device. The current
; color table will be preserved in the Z-buffer device.
MODIFICATION HISTORY:
bmy 15 Aug 1997: VERSION 1.00
bmy, 19 Aug 1997: VERSION 1.01
mgs, 20 Aug 1997: VERSION 1.02
mgs, 09 Apr 1998: VERSION 1.10
- added 2 more parameters for WINPARAM
and TITLE keyword
bmy, 28 Jul 2000: VERSION 1.46
- now make XSIZE, XOFFSET, YSIZE, YOFFSET keywords
- cosmetic changes, updated comments
bmy, 30 Jan 2001: VERSION 1.47
- added /Z and NCOLORS keywords for the Z-buffer
- updated comments
bmy, 26 Jul 2001: VERSION 1.48
- use default window size of 640 x 512 for
the Z-buffer, if WINPARAM isn't specified.
bmy, 27 Aug 2001: - now call DEVICE with XSIZE, YSIZE,
XOFFSET, YOFFSET for /LANDSCAPE plots
- Updatedd comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/graphics/open_device.pro)
NAME:
SCREEN2BMP
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a BMP file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2BMP, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the BMP file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> If FILENAME is not specified, then the byte
image returned from the screen capture will be passed
back to the calling program via THISFRAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2TIFF is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2TIFF, 'myplot.bmp'
; Creates a simple plot and writes it to a TIFF file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2TIFF, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2TIFF, 'myplot.bmp'
CLOSE_DEVICE
; Creates a simple plot and writes it to a TIFF file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- adapted from SCREEN2GIF
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2bmp.pro)
NAME:
SCREEN2GIF
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a GIF file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2GIF, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the GIF file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> Returns to the calling program the
byte image captured from the screen.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
TVREAD (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2GIF is now a wrapper for TVREAD. David Fanning's
TVREAD function does the screen capture better than
the algorithm in the old SCREEN2GIF.
EXAMPLES:
PLOT, X, Y
SCREEN2GIF, 'myplot.gif'
; Creates a simple plot and writes it to a GIF file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2GIF, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2GIF, 'myplot.gif'
CLOSE_DEVICE
; Creates a simple plot and writes it to a GIF file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 24 Jul 2001: TOOLS VERSION 1.49
bmy, 02 Dec 2002: TOOLS VERSION 1.52
- now uses TVREAD function from D. Fanning
which works on both PC's & Unix terminals
bmy, 30 Apr 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- now call TVREAD correctly if we omit FILENAME
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2gif.pro)
NAME:
SCREEN2JPG
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a JPEG file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2JPG, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the JPEG file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> If FILENAME is not specified, then the byte
image returned from the screen capture will be passed
back to the calling program via THISFRAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
Requires routines from the TOOLS package.
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2JPG is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2JPG, 'myplot.jpg'
; Creates a simple plot and writes it to a JPG file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2JPG, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2JPG, 'myplot.jpg'
CLOSE_DEVICE
; Creates a simple plot and writes it to a JPG file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 25 Sep 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2jpg.pro)
NAME:
SCREEN2PNG
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a PNG file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2PNG, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the PNG file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> Returns to the calling program the
byte image captured from the screen.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2PNG is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2PNG, 'myplot.png'
; Creates a simple plot and writes it to a PNG file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2PNG, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2PNG, 'myplot.png'
CLOSE_DEVICE
; Creates a simple plot and writes it to a PNG file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 25 Sep 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2png.pro)
NAME:
SCREEN2TIFF
PURPOSE:
Captures an image from the X-window or Z-buffer device and
saves the image to a TIFF file. Handles 8-bit and TRUE
COLOR displays correctly.
CATEGORY:
Graphics
CALLING SEQUENCE:
SCREEN2TIFF, FILENAME [ , Keywords ]
INPUTS:
FILENAME -> Name of the TIFF file that will be created.
FILENAME may be omitted if you wish to only return
the image (via the THISFRAME keyword).
KEYWORD PARAMETERS:
THISFRAME -> If FILENAME is not specified, then the byte
image returned from the screen capture will be passed
back to the calling program via THISFRAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
TVREAD (function)
REQUIREMENTS:
None
NOTES:
(1) Should work for Unix/Linux, Macintosh, and Windows.
(2) SCREEN2TIFF is just a convenience wrapper for TVREAD.
EXAMPLES:
PLOT, X, Y
SCREEN2TIFF, 'myplot.tif'
; Creates a simple plot and writes it to a TIFF file
; via capture from the screen (X-window device).
PLOT, X, Y
SCREEN2TIFF, THISFRAME=THISFRAME
; Creates a simple plot and saves the screen
; capture image to the byte array THISFRAME.
OPEN_DEVICE, /Z
PLOT, X, Y
SCREEN2TIFF, 'myplot.tif'
CLOSE_DEVICE
; Creates a simple plot and writes it to a TIFF file
; via capture from the Z-buffer device.
MODIFICATION HISTORY:
bmy, 25 Sep 2003: TOOLS VERSION 1.53
- Bug fix in passing file name to TVREAD
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- now pass _EXTRA=e to TVREAD
- updated comments
phs, 3 Feb 2009: GAMAP VERSION 2.13
- Use the NoDialog keyword in call to
TVREAD
(See /n/home09/ryantosca/IDL/gamap2/graphics/screen2tiff.pro)
NAME:
STR_SIZE
PURPOSE:
The purpose of this function is to return the proper
character size to make a specified string a specifed
width in a window. The width is specified in normalized
coordinates. The function is extremely useful for sizing
strings and labels in resizeable graphics windows.
CATEGORY:
Strings, Graphics
CALLING SEQUENCE:
thisCharSize = STR_SIZE(thisSting, targetWidth)
INPUTS:
thisString: This is the string that you want to make a specifed
target size or width.
OPTIONAL INPUTS:
targetWidth: This is the target width of the string in normalized
coordinates in the current graphics window. The character
size of the string (returned as thisCharSize) will be
calculated to get the string width as close as possible to
the target width. The default is 0.25.
KEYWORD PARAMETERS:
INITSIZE: This is the initial size of the string. Default is 1.0.
STEP: This is the amount the string size will change in each step
of the interative process of calculating the string size.
The default value is 0.05.
OUTPUTS:
thisCharSize: This is the size the specified string should be set
to if you want to produce output of the specified target
width. The value is in standard character size units where
1.0 is the standard character size.
EXAMPLE:
To make the string "Happy Holidays" take up 30% of the width of
the current graphics window, type this:
XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
MODIFICATION HISTORY:
Written by: David Fanning, 17 DEC 96.
Added a scaling factor to take into account the aspect ratio
of the window in determing the character size. 28 Oct 97. DWF
(See /n/home09/ryantosca/IDL/gamap2/strings/str_size.pro)
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:
GAMAP Internals, Graphics
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 ignored 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 keyword is ALSO
an output keyword. That is to say, upon return from TVIMAGE
this keyword (if passed by reference) contains the actual
position in the window where the image was displayed. This
may be different from the input values if the KEEP_ASPECT_RATIO
keyword is set, or if you are using TVIMAGE with the POSITION
keyword when !P.MULTI is set to something other than a single
plot. One use for the output values might be to position other
graphics (e.g., a colorbar) in relation to the image.
Note that the POSITION keyword should not, normally, be used
when displaying multiple images with !P.MULTI. If it *is* used,
its meaning differs slightly from its normal meaning. !P.MULTI
is responsible for calculating the position of graphics in the
display window. Normally, it would be a mistake to use a POSITION
graphics keyword on a graphics command that was being drawn with
!P.MULTI. But in this special case, TVIMAGE will use the POSITION
coordinates to calculate an image position in the actual position
calculated for the image by !P.MULTI. The main purpose of this
functionality is to allow the user to display images along with
colorbars when using !P.MULTI. See the example below.
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
To display four image in a window with associated color bars:
!P.Multi=[0,2,2]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 0
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 2
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 3
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 5
TVImage, image, Position=p
Colorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
!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
There was a small inconsistency in how the image was resized for PostScript as
opposed to the display, which could occasionally result in a small black line
to the right of the image. This is now handled consistently. 3 January 2007. DWF.
Made a small change to CMCONGRID to permit nearest-neighbor interpolation for 3D arrays.
Previously, any 24-bit image was interpolated, no matter the setting of the NOINTERP
keyword. 22 April 2007. DWF.
Updated the program for the 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF.
Added new POSITION keyword functionality for !P.MULTI display. 9 Sept 2007. DWF.
(See /n/home09/ryantosca/IDL/gamap2/internals/tvimage.pro)
NAME:
TVREAD
PURPOSE:
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
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
CALLING SEQUENCE:
image = TVREAD(xstart, ystart, ncols, nrows)
The returned image will be a 2D image on 8-bit systems and
a 24-bit pixel interleaved true-color image on 24-bit systems.
A -1 will be returned if a file output keyword is used (e.g.,
JPEG, TIFF, etc.).
OPTIONAL INPUTS:
XSTART -> The starting column index. By default, 0.
YSTART -> The starting row index. By default, 0.
NCOLS -> The number of columns to read. By default, !D.X_Size - XSTART
NROWS -> The number of rows to read. By default, !D.Y_Size - YSTART.
KEYWORD PARAMETERS:
BMP -> Set this keyword to write the screen dump as a color BMP file.
CANCEL -> An output keyword set to 1 if the user cancels out of a
filename dialog. Set to 0 otherwise.
COLORS -- If a 24-bit image has to be quantized, this will set
the number of colors in the output image. Set to 256 by
default. Applies to BMP, GIF, PICT, and PNG formats
written from 24-bit displays. (See the COLOR_QUAN
documentation for details.)
CUBE -> If this keyword is set to a value between 2 and 6 the
color quantization will use a cubic method of
quantization. Applies to BMP, GIF, PICT, and PNG formats
written from 24-bit displays. (See the COLOR_QUAN
documentation for details.)
DITHER -> If this keyword is set the quantized image will be
dithered. Applies to BMP, GIF, PICT, and PNG formats
written from 24-bit displays. (See the COLOR_QUAN
documentation for details.)
FILENAME -> The base name of the output file. (No file extensions;
they will be added automatically.) This name may be
changed by the user.
image = TVREAD(Filename='myfile', /JPEG)
No file will be written unless a file output keyword is
used (e.g., JPEG, TIFF, etc.) in the call. By default
the FILENAME is set to "idl". The file extension will be
set automatically to match the type of file created.
GIF -> Set this keyword to write the screen dump as a color
GIF file.
JPEG -> Set this keyword to write the screen dump as a color
JPEG file.
ORDER -> Set this keyword to determine the image order for
reading the display. Corresponds to !Order and set to such
as the default.
PICT -> Set this keyword to write the screen dump as a color
PICT file.
PNG -> Set this keyword to write the screen dump as a color
PNG file.
TIFF -> Set this keyword to write the screen dump as a color
TIFF file.
TRUE -> Set this keyword to the type of interleaving you
want. 1 = Pixel interleaved, 2 = row interleaved,
3 = band interleaved.
TYPE -> Can be set to the type of file to write. Use this
instead of setting BMP, GIF, JPEG, PICT, PNG, or TIFF
keywords: TYPE='JPEG'. The primary purpose of this is to
make event handlers easier to write.
QUALITY -> This keyword sets the amount of compression for
JPEG images. It should be set to a value between 0 and
100. It is set to 75 by default. (See the WRITE_JPEG
documentation for details.)
WID -> The index number of the window to read from. The
current graphics window (!D.Window) is selected by
default. An error is issued if no windows are
currently open on a device that supports windows.
_EXTRA -> Any keywords that are appropriate for the
WRITE_*** routines are also accepted via keyword
inheritance.
COMMON BLOCKS:
None
RESTRICTIONS: Requires IDL 5.2 and higher.
MODIFICATION HISTORY:
Written by David W. Fanning, 9 AUG 2000.
Added changes to make the program more device independent. 16 SEP 2000. DWF.
Removed GIF file support for IDL 5.4 and above. 18 JAN 2001. DWF.
Added NODIALOG keyword. 28 MAR 2001. DWF.
Added an output CANCEL keyword. 29 AUG 2001. DWF.
Added ERROR_MESSAGE code to file. 17 DEC 2001. DWF.
Added ORDER keyword. 25 March 2002. DWF.
Now create 24-bit PNG files if reading from a 24-bit display. 11 May 2002. DWF.
Now create 24-bit BMP files if reading from a 24-bit display. 23 May 2002. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Unleashed the GIF code for IDL 6.2 and above. 10 Nov 2005. DWF.
Rolled back previous change to IDL 6.1. 24 Jan 2006. DWF.
Fixed a problem in which 16-bit displays were treated as 24-bit displays,
and as a result could not produce WHITE colors. Now all 16-bit displays
are treated as 8-bit displays. It is an ugly trade-off. 24 Jan 2006. DWF.
Added TYPE keyword 27 Sep 2006. DWF.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Removed /NODIALOG keyword
- Only pop up a dialog box if FILENAME
isn't passed and we are writing a file
- Updated comments, cosmetic changes
phs, 13 Feb 2009: GAMAP VERSION 2.13
- Restored the /NODIALOG keyword
(See /n/home09/ryantosca/IDL/gamap2/graphics/tvread.pro)