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:
TAU2YYMMDD (function)
PURPOSE:
Converts a tau value (elapsed hours between
the current date/time and the beginning of an epoch) into a
calendar date and time value.
CATEGORY:
Date & Time
CALLING SEQUENCE:
RESULT = TAU2YYMMDD( TAU, [ NYMD0, NHMS0 ] )
INPUTS:
TAU -> the tau value to be converted (type long)
NYMD0 (long) -> YY/MM/DD for the start of the epoch
default is {19}850101 which is the GEOS-1 start
NHMS0 (long) -> HH/MM/SS for the start of the epoch
will be defaulted to 000000
KEYWORD PARAMETERS:
/NFORMAT --> produce 2-element vector instead of structure
The result will be NYMD and NHMS with NYMD as YYYYMMDD.
/SHORT --> produce 2-element vector with 2-digit year format.
(implies NFORMAT=1)
/GEOS1 -> use 1985/01/01 as epoch start
/GISS_II -> use 1980/01/01 as epoch start
OUTPUTS:
RESULT -> The function returns the calendar date and time as
either a structure with tags YEAR, MONTH, DAY, HOUR,
MINUTE, SECOND or a 2 element array with NYMD and NHMS
long values.
SUBROUTINES:
NYMD2STRU -> extracts year, month, day, hour, minute
and seconds from NYMD and NHMS values.
REQUIREMENTS:
None
NOTES:
Function NYMD2STRU is also embedded in NYMD2TAU function. This should
be kept in mind when changes are necessary.
Function STRDATE can be used to produce a formatted string from
the structure returned by TAU2YYMMDD.
EXAMPLE:
; get calendar structure from tau value for 1994/01/01 (GEOS)
print,tau2yymmdd(78888,/GEOS1)
result (structure with Year, Month, Day, Hour, Minute, Second):
{ 1994 1 1 0 0 0}
... and in the format of NYMD, NHMS
print,tau2yymmdd(78888,/GEOS1,/NFORMAT)
print,tau2yymmdd(78888,/GEOS1,/NFORMAT,/SHORT)
results (array with 2 elements):
19940101 0
940101 0
MODIFICATION HISTORY:
mgs, 26 Mar 1998: VERSION 1.00
mgs, 16 Mar 1999: - now allows floating point tau values
CAUTION: Use double for second precision !
bmy, 27 Jul 1999: VERSION 1.42
- updated comments
bmy, 03 Jan 2000: VERSION 1.44
- updated comments
bmy, 23 Mar 2005: GAMAP VERSION 2.03
- renamed internal function NYMD2STRU to
T2N_NYMD2STRU to avoid conflict with
similar function in "tau2yymmdd.pro";
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/date_time/tau2yymmdd.pro)
NAME:
TESTPATH
PURPOSE:
Set !PATH variable to a limited set of directories for test
purposes (or restore the initial value)
CATEGORY:
File & I/O
CALLING SEQUENCE:
TESTPATH [,pathstring] [,/restore]
INPUTS:
PATHSTRING -> a string with the test directory name(s)
The !PATH variable will contain this string plus the
standard IDL library search path [which is hardwired
and may have to be changed after future updates].
Note: This parameter is ignored if the /RESTORE keyword
is set.
KEYWORD PARAMETERS:
/RESTORE -> restore initial value of !PATH. This is always
the value before the very first call to testpath! Use
of this keyword overrides the PATHSTRING parameter.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
testpath,'~mgs/IDL/test3d'
; sets !PATH to the given name + standard IDL libraries
testpath,/restore
; resets !PATH variable to original value
MODIFICATION HISTORY:
mgs, 16 Jun 1998: VERSION 1.00
mgs, 02 Nov 1998: - changed IDL path from idl5 to idl
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/testpath.pro)
NAME:
TEST_MET
PURPOSE:
Prints out the name, time, and min/max of data of GMAO or
GISS/GCAP met data files which are used as input to GEOS-Chem.
CATEGORY:
GAMAP Utilities
CALLING SEQUENCE:
TEST_MET, MODELINFO [, Keywords ]
INPUTS:
MODELINFO -> Structure from CTM_TYPE which defines the model
name, resolution, and other parameters. NOTE: If the
met field files contain an IDENT string then TEST_MET
will ignore the MODELINFO structure passed and instead
will parse the IDENT string to obtain the model name
and resolution. (NOTE: GEOS-4, GEOS-5, and GCAP met
fields contain an identification string which is read in
to determine the proper model name. For these met fields
you won't need to supply MODELINFO.)
KEYWORD PARAMETERS:
FILENAME -> Name of the binary met field file to examine. If
FILENAME is not passed, then the user will be prompted
to supply a file name via a dialog box query.
/VERBOSE -> If set, then will echo extra information
to the screen.
XINDEX -> A 2-element vector containing the minimum and
maximum longitude indices (in FORTRAN notation) which
define the nested model grid.
YINDEX -> A 2-element vector containing the minimum and
maximum longitude indices (in FORTRAN notation) which
define the nested model grid.
XRANGE -> A 2-element vector containing the minimum and
maximum box center longitudes which define the nested
model grid. Default is [-180,180].
YRANGE -> A 2-element vector containing the minimum and
maximum box center latitudes which define the nested
model grid. Default is [-90,90].
PLOTLEVEL -> If specified, then TEST_MET will plot a lon-lat
map of the given vertical level of the data. Useful for
debugging purposes.
_EXTRA=e -> Picks up extra keywords for OPEN_FILE.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
================================
OPEN_FILE CTM_GRID (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
TEST_MET, CTM_TYPE( 'GEOS3', res=2 ), FILE='20010115.i6.2x25'
; Prints out information from the 2 x 2.5
; GEOS-3 I-6 met field file for 2001/01/15.
MODIFICATION HISTORY:
bmy, 24 May 2005: GAMAP VERSION 2.04
- now renamed from "test_dao.pro"
- added fields for GISS/GCAP model
- now looks for an IDENT string
bmy, 12 Dec 2006: GAMAP VERSION 2.06
- Modifications for GEOS-5 met fields
- Added XINDEX, YINDEX keywords
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added extra GEOS-5 fields
bmy, 21 Feb 2008: GAMAP VERSION 2.12
- Now be sure to swap the endian when
opening the file on little-endian
machines
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Added modifications for MERRA data
bmy, 17 Aug 2010: - Added SEAICE** fields for MERRA
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/test_met.pro)
NAME:
TRIANGLE
PURPOSE:
Converts a vector with corner coordinates into X and Y
vectors for a triangle shape. The output vectors can be
used with PLOTS, POLYFILL, or similar IDL plotting commands.
CATEGORY:
Plotting
CALLING SEQUENCE:
TRIANGLE, CORNERS, XVEC, YVEC [, Keywords ]
INPUTS:
CORNERS -> A 1-D vector with [ X0, Y0, X1, Y1 ] coordinates.
(X0,Y0) is the bottom left corner of the plot region and
(X1,Y1) is the top right corner of the plot region.
KEYWORD PARAMETERS:
EXPAND -> A value that will be used to expand the size
of the triangle by the same amount on all sides.
Default is 0.
OUTPUTS:
XVEC -> A 1-D vector with the X-coordinates listed in the
proper order for the POLYFILL or PLOTS commands.
YVEC -> A 1-D vector with the X-coordinates listed in the
proper order for the POLYFILL or PLOTS commands.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; Get a plot position vector from MULTIPANEL
MULTIPANEL, 2, POSITION=POSITION
PRINT, POSITION
0.112505 0.0874544 0.466255 0.956280
; Convert to X and Y vectors for PLOTS input
TRIANGLE, POSITION, XPOINTS, YPOINTS
PRINT, XPOINTS
0.112505 0.466255 0.466255 0.112505 0.112505
PRINT, YPOINTS
0.0874544 0.0874544 0.956280 0.956280 0.0874544
; Call PLOTS to draw a box
PLOTS, XPOINTS, YPOINTS, THICK=2, COLOR=1, /NORMAL
MODIFICATION HISTORY:
cdh, 19 Nov 2007: GAMAP VERSION 2.11
- Adapted from "rectangles.pro"
(See /n/home09/ryantosca/IDL/gamap2/plotting/triangle.pro)
NAME:
TROP_CUT
PURPOSE:
Reads a CTM data block and then only saves data from the
surface up to the maximum tropopause level. (e.g. the
field MODELINFO.NTROP, returned from function CTM_TYPE).
CATEGORY:
Regridding
CALLING SEQUENCE:
TROP_CUT [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the file containing data to be regridded.
If INFILENAME is not specified, then REGRIDH_RESTART
will prompt the user to select a file via a dialog box.
OUTFILENAME -> Name of the file which will contain the regridded
data. Default is INFILENAME + '.trop'.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
CTM_GET_DATA CTM_MAKE_DATAINFO (function)
GETMODELANDGRIDINFO UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages
NOTES:
None
EXAMPLE:
TROP_CUT, INFILENAME='data.geos3.4x5', $
OUTFILENAME='trop_data.geos3.4x5'
; Reads data from "data.geos3.4x5". Saves data
; from the surface up to level MODELINFO.NTROP
; and writes to file trop_data.geos3.4x5".
MODIFICATION HISTORY:
bmy, 31 Oct 2002: VERSION 1.00
bmy, 25 Sep 2003: VERSION 1.01
- Call PTR_FREE to free the pointer heap memory
bmy & phs, 20 Jun 2007: GAMAP VERSION 2.10
- Use FILE_WHICH to locate surf prs files
(See /n/home09/ryantosca/IDL/gamap2/regridding/trop_cut.pro)
NAME:
TSDIAG
PURPOSE:
Reads and plots CTM time series (station) data. The
data are returned in a structure together with longitude,
latitude, altitude, and time information. TSDIAG tries to
construct a time vector from the TAU information stored
in the file. This may not always work (e.. it is assumed
that time steps are 1 hour).
While reading, TSDIAG displays a '.' for each new station
encountered, and a '+' if a station is continued. If you want
more detailed output, set the /VERBOSE flag.
%%% NOTE: May need updating %%%
CATEGORY:
GAMAP Utilities, GAMAP Data Manipulation, GAMAP Plotting
CALLING SEQUENCE:
TSDIAG [,RESULT] [,keywords]
INPUTS:
None
KEYWORD PARAMETERS:
FILENAME -> Path of the input file containing CTM
Data data.
SCALE -> A global scale factor that will be applied to all
data. Default is 1. Note that concentration data is
stored as v/v, hence for ppt you should set
SCALE=1.E-12.
/VERBOSE -> display detailed information on what is being read.
/PLOT -> set this flag to produce quick-and-dirty plots of the
time-series data.
OUTPUTS:
RESULT -> A structure containing LON, LAT, ALT and Data data
together with TRACER and a "global" TIME array.
SUBROUTINES:
OPEN_DEVICE CLOSE_DEVICE
CTM_TRACERINFO FILE_EXIST (function)
STRSCINOT (function)
REQUIREMENTS:
NOTES:
Lines with the Data data (Header = 'TB' or 'DV') will be
read from disk. Statistics are ignored for now.
EXAMPLE:
; read time series data from file and return result structure
; in variable TSDATA
tsdiag, TSDATA, FILENAME='ctm.ts'
MODIFICATION HISTORY:
bmy, 06 May 1998: VERSION 1.00
bmy, 07 May 1998: VERSION 1.01
- added PPBC and INTERVAL keywords
- now calls FILE_EXIST to make sure
the input file exists
bmy, 27 May 1998 - now uses CTM_DIAGINFO to return
the proper tracer offset
bmy, 28 May 1998 - now uses SCALE, UNIT, and MOLC information
as returned by CTM_TRACERINFO.
- now uses EXP_STR to compute a
power-of-ten string for the plot title
bmy, 29 May 1998 - now calls CLEANPLOT to initialize
all system variables
bmy, 02 Jun 1998 - now uses STRSCI and STRCHEM string
formatting functions
mgs, 11 Jun 1998: - couple of bug fixes
mgs, 15 Jun 1998: - default tick interval now 48 h
mgs, 22 Jun 1998: - added Data and CSTEPS keywords
mgs, 20 Nov 1998: - now uses convert_unit
hsu, 22 Mar 1999: - increased MAXSTEPS and changed input format
mgs, 04 May 1999: - added MS as a tracer offset (100*MS)
mgs, 05 May 1999: - ... and a little bug fix
mgs, 19 May 1999: - updated comments
- default SCALE factor now 1 instead of 1.E-12
- CLEANPLOT no longer called
mgs, 24 May 1999: - added VERBOSE keyword
- fixed at least two bugs
- improved output. Now need to say /VERBOSE in
order to get details.
mgs, 25 May 1999: - new format had MS and N swapped.
bmy, 27 Jul 1999: GAMAP VERSION 1.42
- updated comments
bmy, 30 Jan 2002: GAMAP VERSION 1.50
- Now use STRBREAK to split each line into
elements of data
- Also no longer restrict data to be > 0
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsdiag.pro)
NAME:
TSPLOT
PURPOSE:
Create a plot of station data time series using the
data structure as returned from TSDIAG.PRO. This routine
is a simple outline for how to use this structure and
not meant to produce publisheable plots. Tip: use
MULTIPANEL.PRO to save paper.
%%% THIS MAY NOW BE OBSOLETE %%%
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TSPLOT, TSSTRU, INDEX, SCALE=SCALE
INPUTS:
TSSTRU -> The data structure as returned from TSDIAG.PRO
INDEX -> A vector with station indices that are to be plotted.
If no index is given, the program will loop through all
records.
KEYWORD PARAMETERS:
SCALE -> A scaling factor to be applied to the dat abefore plotting.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
; read station data
TSDIAG,TSSTRU,FILE='ctm.ts'
; set page for 16 panels
MULTIPANEL, 16
; plot data from all stations as pptv
TSPLOT, TSSTRU, SCALE=1.e12
; turn multipanel off
MULTIPANEL, /OFF
MODIFICATION HISTORY:
mgs, 30 Jun 1999: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tsplot.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:
TVMAP
PURPOSE:
TVMAP produces one of the following plots:
(1) A color-pixel image, overlaid with a world map
(2) A line-contour plot, overlaid with a world map
(3) A filled-contour plot, overlaid with a world map
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TVMAP, Data, [ Xarr, YArr [ [, keywords ] ]
INPUTS:
DATA -> 2-D array of values to be plotted as a color map.
The first dimension is longitude, the second is latitude.
XARR, YARR -> If plotting a line-contour map or filled-contour map,
then XARR is the array of X-axis values, and YARR is the
array of Y-Axis values that are needed to construct the
the contours. XARR and YARR are not needed to produce a
color-pixel image map; however, if XARR and YARR are
passed, TVMAP will be able to label the longitude and
latitude lines accordingly and set the proper default limits.
KEYWORD PARAMETERS:
BLACK -> The color index corresponding to black.
Default is !MYCT.BLACK.
/CONUS -> a Lambert's azimuthal equal area projection for
CONtiguous U.S., w/ specific LIMIT and P0lat, P0lon, Rot.
MAX_VALID -> maximum valid data value for color-pixel plots
Data above MAX_VALID will be shown in white, unless
TOPOUTOFRANGE is set to another color index.
MIN_VALID -> minimum valid data value for color-pixel plots.
(or minimum contour level for contour plots). Data
below MIN_VALID will be shown in white, unless
BOTOUTOFRANGE is set to another color index.
TOPOUTOFRANGE ( BOTOUTOFRANGE ) -> color index to indicate
data above MAX_VALID (below MIN_VALID). Default is
white. The color is also shown with a box (or TRiangle)
near the colorbar (if any). If negative, the box is not
shown with the colorbar.
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. /NOERASE is automatically turned ON when the /OFF
keyword is given. NOTE: On the PostScript device, when
the page is filled, it automatically places the next plot
on the next page. You can use the /NOERASE keyword to
suppress this behavior, especially if you are manually
placing plots on the page.
CSFAC -> Character size for the map labels and X, Y titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
TCSFAC -> Character size for the top title. Default
settings for TCSFAC vary according to the number
of plots per page and type of plot device.
/NOADVANCE -> Set this switch to prevent TVMAP from advancing
to the next plot panel on the page. This is useful if
you desire to overplot something atop the pixel map or
contour map.
/POLYFILL -> to use IDL POLYFILL routine instead of MAP_IMAGE
to do the pixel plot (see /SAMPLE). Use this keyword
with default cylindrical projection only. Use it also if
you think that MAP_IMAGE does not neatly reproduces the
boxes.
/RECTANGLE -> to plot a rectangle around the map. Default is
to have one for non-polar projection, and none for polar
projection. Set to 0 or 1 to override default. NOTE:
setting the /HORIZON keyword will disable this option.
/SAMPLE -> to do "pixel plot" (ie grid boxes are colored)
instead of contour.
/HORIZON -> Set this switch to call IDL routine MAP_HORIZON
to draw a horizon line around the boundaries of the map.
Use this feature if the map projection you are using is
elliptical or interrupted. NOTE: /HORIZON will override
override the /RECTANGLE keyword setting.
WINDOWPOSITION -> Returns the position of the plot window
in normal coordinates to the calling program. This can
be used by a subsequent call to PLOT if you want to
overplot symbols atop the contour or pixel plot created
by TVMAP.
_EXTRA=e -> Picks up extra keywords (not listed below, unless
noted) for BYTSCL, COLORBAR, TVIMAGE, MAP_SET, MAP_GRID,
MAP_CONTINENTS, MAP_LABELS and CONTOUR.
Keywords passed to both BYTSCL and COLORBAR:
============================================
MAXDATA -> Maximum value of the DATA array to use in the
byte scaling. Default is max( DATA ).
MINDATA -> Minimum value of the DATA array to use in the
byte scaling. Default is min( DATA ).
BOTTOM -> The lowest color index of the colors to be used
for byte-scaling the color map and colorbar. Default
is 20 (or !D.N_COLORS-1 if 20 is too large).
NCOLORS -> This is the maximum color index that will be used.
Default is 120 (or !D.N_COLORS-BOTTOM, if 120 is too large).
/LOG -> Will create a color-pixel plot with logarithmic
scaling. /LOG has no effect on line-contour or
filled-contour plots, since the default contour levels
are quasi-logarithmic.
Additional keywords passed to COLORBAR:
=======================================
/CBAR -> If set, will plot a horizontal colorbar below the
map in the position specified by CBPOSITION. Default is
to NOT plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (see above).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. CBPOSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08].
CBUNIT -> Passes the Unit string to COLORBAR, which will be
plotted to the right of the color bar.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
CBMIN, CBMAX -> Explicitly sets the min and max values of
the colorbar range. If not set, TVMAP will set
CBMIN = min( DATA ) and CBMAX = max( DATA ).
CBTICKLEN -> Specifies the color bar tick length as a
fraction of the colorbar height (for horizontal
colorbars) or width (for vertical colorbars).
CBVERTICAL -> If set, will plot a vertical bar on the right
side of the map.
CBSCALE -> If set, then the printed tick labels are scaled by
powers of 10 to minimize overlap.
DIVISIONS -> Number of labels for the colorbar. Default is 4.
/TRIANGLE -> to replace box that indicate Out Of Range data
with a triangle.
TOPLEVELVALUE -> to define the last annotation of the
colorbar when using the C_LEVELS keyword
Keywords passed to MAP_SET:
===========================
COLOR -> Color index of the map outline and title characters.
Defaults to BLACK (see above).
MPARAM -> A 3 element vector containing values for
[ P0Lat, P0Lon, Rot ]. Default is [ 0, 0, 0 ].
Elements not specified are automatically set to zero.
/ISOTROPIC -> If set, will produce a map with the same scale
in the X and Y directions. Default is not to plot an
isotropic-scale map. Note, however, that if TVMAP is
called from CTM_PLOT, the default is to plot a map that
keeps the aspect ratio (which is about the same as
isotropic).
LIMIT -> A four-element vector which specifies the latitude
and longitude extent of the map. The elements of LIMIT
are arranged thus: [ LatMin, LonMin, LatMax, LonMax ].
Default is to set LIMIT = [ -90, -180, 90, 180 ] (i.e.
to include the entire globe). P0Lon will be computed
to fit into the LIMIT range unless it is explicitely
requested in MParam.
POLAR -> Plot a polar stereographic projection. If set and
equal 1 then the plot goes from the pole to a latitude
defined by either the extend of the data or by the user
through the LIMIT keyword. If set and equal to 2, then
the full hemisphere is plot, regardless of the data or
LIMIT settings.
Note that setting the /STEREOGRAPHIC keyword wouldn't
work.
POSITION -> A four-element array of normalized coordinates
that specifies the location of the map. POSITION has
the same form as the POSITION keyword on a plot.
Default is [0.0, 0.15, 1.0, 1.0] with Horizontal Color
Bar, and [0., 0., 0.82, 1.0] with Vertical CBar.
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.03, 0.07 ].
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
SCALEMAPSET -> To pass the SCALE keyword to MAP_SET.
TITLE -> The title string that is to be placed atop the
plot window. TITLE is passed explicitly to avoid keyword
name duplication in the _EXTRA=e facility.
Keywords passed to MAP_LABELS:
==================================
LATS, LONS -> Array of latitudes (longitudes) used to
construct the map labels. If LATS has one element, the
LATS vector is build with LATS+n*DLAT, with as n as
needed to cover the map range. If it has more than one
element, it is not modified and it is the final grid.
DLAT, DLON -> Latitude (longitude) interval between grid
lines. Passed with _extra.
Keywords passed to MAP_CONTINENTS:
==================================
/CONTINENTS -> If set, will call MAP_CONTINENTS to plot
continent outlines or filled boundaries. Default is 0.
/COUNTRIES -> If set, will call MAP_CONTINENTS to draw the
political boundaries of countries as of 1993.
/COASTS -> If set, will call MAP_CONTINENTS to draw the coast
lines of continental regions.
CCOLOR -> The color index of the continent outline or fill
region. Default is BLACK (see above).
CFILL -> Value passed to FILL_CONTINENTS keyword of MAP_CONTINENTS.
If CFILL=1 then will fill continents with a solid color
(as specified in CCOLOR above). If CFILL=2 then will fill
continents with hatching.
/USA -> Set this switch to turn on US State boundaries.
Keywords passed to MAP_GRID:
============================
/BOX_AXES -> If set, then MAP_GRID will print alternating
light & dark regions with the lon & lat labels around
the border of the plot. This is passed directly to
MAP_GRID. NOTE: BOX_AXES is the default for the CONUS
option.
/GRID -> If set, will call MAP_GRID to plot grid lines and
labels. Labels can be turned off with /NOGLABELS.
Default is _not_ to plot grid lines.
GCOLOR -> The color index of the grid lines. Default is
BLACK (see above).
/NOGXLABELS -> If set, TVMAP will suppress printing longitude
labels for each grid line.
/NOGYLABELS -> If set, TVMAP will suppress printing latitude
labels for each grid line.
Keywords passed to CONTOUR:
===========================
/CONTOUR -> Will produce a line-contour map instead of the
default color-pixel image map.
/FCONTOUR -> Will produce a filled-contour map instead
of the default color-pixel image map.
C_LEVELS -> Vector containing the contour levels. If not
specified, will use preset default levels.
C_ANNOTATION -> Vector containing the contour labels.
Default is to use string representations of C_LEVELS.
C_FORMAT -> Format string used in converting C_LEVELS to
the default C_ANNOTATION values. Default is '(f8.1)'.
C_COLORS -> Index array of color levels for contour lines or
fill regions. If not specified then will use uniformly
spaced default color levels. If C_COLORS is set to a
scalar value, then all contour lines will have the same
color value.
C_LABELS -> Specifies which contour levels should be labeled.
By default, every other contour level is labeled. C_LABELS
allows you to override this default and explicitly
specify the levels to label. This parameter is a vector,
converted to integer type if necessary. If the LEVELS
keyword is specified, the elements of C_LABELS
correspond directly to the levels specified, otherwise,
they correspond to the default levels chosen by the
CONTOUR procedure. Setting an element of the vector to
zero causes that contour label to not be labeled. A
nonzero value forces labeling.
/C_LINES -> Will overplot a filled-contour map with contour lines
and labels instead of plotting a colorbar. This was the old
default behaviour but has been changed with the advent of
"discrete" colorbars. The old NOLINES keyword is kept
for compatibility reasons but doesn't do anything.
/NOLABELS -> Will suppress printing contour labels on both
line-contour and filled-contour maps.
OVERLAYCOLOR -> Color of the solid lines that will be
overlaid atop a filled contour map. Default is BLACK.
Keywords passed to MAP_IMAGE (prior: to REBIN):
==============================================
/SAMPLE -> Used to rebin the byte-scaled image array to a
larger size. If /SAMPLE is set, then MAP_IMAGE will use
nearest-neighbor sampling rather than bilinear
interpolation.
Keyword passed to TVIMAGE:
===============================================
SCALEMAPIMAGE -> Sets the number of pixels per graphic coordinate
in PostScript and other devices with scalable
pixels. Larger values produce better resolution output,
but much larger file sizes. The default value is
0.04. Use a larger number for higher resolution if your
image does not exactly fit on the map projection.
OUTPUTS:
None
SUBROUTINES:
External subroutines required:
------------------------------
COLORBAR ( by Martin Schultz & David Fanning )
TVIMAGE ( by David Fanning )
RECTANGLE ( by Martin Schultz )
CONVERT_LON ( by Martin Schultz )
INV_INDEX ( function, by Martin Schultz )
MAP_LABELS ( by Martin Schultz & Bob Yantosca )
LOGLEVELS ( by Martin Schultz )
GET_DEFAULTFORMAT ( by Martin Schultz )
MYCT_DEFAULTS ( by Bob Yantosca )
REQUIREMENTS:
Assumes that a MYCT colortable has been loaded.
NOTES:
(1) The _EXTRA facility now picks up keywords for multiple
routines (this is a new feature in IDL v. 5.0+!!)
(2) Some keywords are saved in local variables with
slightly different names (e.g. MCONTOUR for /CONTOUR)
to prevent confusion with routine names and/or keywords
that are picked up by the _EXTRA=e facility.
(4) For contour plots, contour labels will be specified
using the C_ANNOTATION keyword. The downside is that
by using C_ANNOTATION, this disables the C_LABELS keyword
and so one cannot specify which contour lines will get
labels. The solution would be to expand the C_LABELS
vector so that it has the same number of elements as
C_ANNOTATION, and then to individually zero the
corresponding elements of C_ANNOTATION before making
the contour plot. Don't have enough time for this now,
but maybe can deal with this at a later time...
(5) Now references the !MYCT system variable. This should
be defined at the start of your IDL session when "myct.pro"
is called from "idl_startup.pro".
LIMITATIONS:
(1) The case of plot over the dateline is working fine only if
LIMIT[3] is negative and LIMIT[1] is positive. Other cases are
not specifically handled and results may not be reliable.
(2) Since we are using MAP_IMAGE, pixel plots do start and end
at longitude and latitude centers of the grid by default,
like contour plots. More map coverage is done in three cases:
(2a) Data sets that cover the globe will fill the map with
coarse pixel plots.
(2b) Data sets that cover the globe will fill the map only
in the longitude direction with smooth pixel and contour
plot. Plots start and stop at the first and last latitudes
centers.
(2c) Data sets that do not cover the globe will start and
end at grid edges with coarse pixels, only if the limit of
the map is less than half grid size away from the the
first/last latitude and longitude centers. This limitation
is due to the method used to pad the data outside the
domain delimited by X/Y arrays.
(3) MAP_IMAGE assumes that an evenly spaced data set is
passed. If X or Y array is not evenly spaced, pixels plots are
flawed and not reliable. Contour plots are ok.
EXAMPLE:
(1)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC
/SAMPLE, TITLE='O3 at 10 km'
(2)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC
TITLE='O3 at 10 km'
; Plots a 2-D "smooth" pixel map.
(3)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC $
/FCONTOUR, TITLE='O3 at 10 km', $
C_LEVELS=[10,20,30,40,50,60,70,80,90,100]
; Plots a 2-D filled contour map.
(4)
MAXDATA = MAX( DATA, MIN=MINDATA )
TVMAP, DATA, XMID, YMID, $
MAXDATA=MAXDATA, MINDATA=MINDATA, CBUNIT='v/v', $
/CBAR, DIVISIONS=4, FORMAT='(F6.2)', $
/CONTINENTS, /GRID, /ISOTROPIC $
/FCONTOUR, TITLE='O3 at 10 km', $
C_LEVELS=[10,20,30,40,50,60,70,80,90,100], $
/NOGXLABELS, /NOGYLABELS, /BOX_AXES
; Same as Example (3), but prints prints box-style
; axes via the /BOX_AXES feature of MAP_GRID.
MODIFICATION HISTORY:
bmy, 13 Apr 1998: VERSION 1.00
bmy, 11 Jun 1998: - now returns if there is
nothing to plot
mgs, 15 Jun 1998: - bug fix: n_elements instead of
keyword_set
bmy, 22 Sep 1998: VERSION 1.10
- Now use _EXTRA=e to pass keywords to
BYTSCL, TVIMAGE, MAP_SET, and COLORBAR
- added MAPTITLE and UNIT keywords to
avoid keyword name duplication in
_EXTRA=e.
bmy, 25 Sep 1998: VERSION 2.00
- now calls MAP_CONTINENTS and MAP_GRID
- keywords renamed for consistency
- reduced default size for CBPOSITION
bmy, 28 Sep 1998: VERSION 2.01
- MPOSITION renamed to POSITION, MCOLOR to
COLOR, MTITLE to TITLE for consistency
- LONSHIFT renamed to LSHIFT to avoid
problems with ambiguous keyword names
bmy, 07 Sep 1998: VERSION 3.00
- now can plot contour map or color-pixel
map (added CONTOUR and FCONTOUR keywords,
and XARR and YARR parameters)
- The colorbar is now optional, and is
turned on via the /COLORBAR switch.
bmy, 12 Nov 1998: VERSION 3.01
- added ISOTROPIC, SAMPLE, KEEP_ASPECT_RATIO,
C_LABELS, and C_FORMAT keywords
- now isotropic-scale color-image plots
and isotropic-scale contour plots are
handled correctly
- Use mgs-style default levels & colors for
contour and filled-contour maps.
bmy, 13 Nov 1998: - updated comments
- renamed C_LEVELS to C_ANNOTATION to
prevent keyword name confusion
- added NOLINES, NOLABELS, C_LABELS,
and OVERLAYCOLOR keywords
- contour lines and labels can be
suppressed correctly
- added mgs fix so that PostScript
pixel-maps appear smoother
- a border is now plotted around the
map window, without inserting any of that
annoying "cushion" space.
- added LOG keyword for logarithmic
contours and/or pixel colors
- use KEYWORD_SET more often
mgs, 17 Nov 1998: - re-arranged calls to map_set and tvimage
in order to maximize size
- output of title now seperate from map_set
- added CBFormat keyword
mgs, 19 Nov 1998: - CBFormat now handled in colorbar.pro
mgs, 20 Nov 1998: - bug fix for map_set for contour plots
mgs, 03 Dec 1998: - filled continents now added before contours
- CFILL keyword checked for consistency
bmy, 08 Feb 1999: - If /LOG is set, make sure that we don't
take the log of zero and incur a math error
- add call to function INV_INDEX
bmy, 23 Feb 1999: - added /GLABELS keyword to turn on/off printing
of labels for each grid line on the map
- added call to CONVERT_LON for longitudes
that straddle the date line
bmy, 26 Feb 1999: - added LIMIT as an explicit keyword
- now uses MAP_LABELS to construct grid labels
- updated comments
bmy, 04 Mar 1999: - added DEBUG keyword for debug output
mgs, 17 Mar 1999: - some cleaning:
- LSHIFT, DLON, and GLABELS made obsolete
- new keyword NOGLABELS
- P0Lon now computed from LIMIT information.
- Updated call to map_labels
- For contour plots: XArr, YArr no longer
mandatory (although they should be provided)
- much smarter default contour levels
mgs, 22 Mar 1999: - added multi-panel ability through use of
the new MULTIPANEL routine. This alters the
meaning of MPosition and CB_Position: they now
refer to positions in the current plot panel!
mgs, 23 Mar 1999: - fixed a few minor things
- charsize is now adjusted according to number
of panels on page
bmy, 25 Mar 1999: - If CBAR=0, then print unit string below
plot (formerly was done in CTM_PLOT)
- now use updated GET_DEFAULTFORMAT
- updated comments
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
mgs, 23 Apr 1999: - added CBMin and CBMax keywords for
tighter colorbar control
mgs, 19 May 1999: - title shifted a little higher if it has
more than 1 line.
bmy & mgs, 26 May 1999: - added POLAR keyword and respective support.
bmy, 27 May 1999: - bug fix for isotropic contour plots
mgs, 27 May 1999: - added support for discrete colorbars and
changed default behaviour for filled
contour plots: now plots a colorbar and
no lines.
bmy, 03 Jun 1999: - For polar plots, if the latitude range
spans more than 60 degrees, only plot
labels for [ 30, 60, 90 ] degrees.
mgs, 03 Jun 1999: - CFill now also allowed for filled contours
or pixel plots (data will be overplotted)
bmy, 09 Jun 1999: - Set CBUnit to '' if nothing passed
bmy, 21 Jun 1999: - Added MIN_VALID keyword.
bmy, 06 Jul 1999: - bug fix for min_valid: ge replaces gt.
bmy, 07 Jul 1999: - Save C_COLORS in a temp variable. Also
define C_COLORS so that grayscales won't
appear in Postscript plots
- multi-panel plots are now well-separated
from each other (for PostScript output)
bmy, 08 Jul 1999: - more minor fixes
bmy, 18 Nov 1999: - increase default left margin by a little
bmy, 31 Mar 2000: GAMAP VERSION 1.45
- make CSFAC and TITLECSFAC into keywords
bmy, 10 May 2000: - make sure XARR and YARR (if passed) are 1D vectors
- now use XARR, YARR to set default limits
- rearranged keyword settings code for clarity
- added more debug output (when /DEBUG is set)
bmy, 26 May 2000: - updated comments
bmy, 13 Jun 2000: - added /COUNTRIES and /COASTS keywords.
Setting /COUNTRIES, /COASTS, or /CONTINENTS
will now invoke routine MAP_CONTINENTS
bmy, 30 Jan 2001: GAMAP VERSION 1.47
- if NOGLABELS=0 and GRID=0, will print out
grid labels w/o printing out grid lines
- added MARGIN keyword for MULTIPANEL
- also allow coarse plots with /SAMPLE
when using the Z-buffer device
bmy, 07 Jun 2001: - removed some obsolete code & comments
bmy, 02 Jul 2001: GAMAP VERSION 1.48
- added /NOGXLABELS and /NOGYLABELS keywords
to suppress printing either lon or lat
grid labels, if so desired.
bmy, 13 Jul 2001: - bug fix: remove _EXTRA=e from MAP_SET call
when making pixel plots. This prevents extra
grid lines from being drawn on the map.
bmy, 23 Jul 2001: - now call MYCT_DEFAULTS to specify default
values for BLACK, BOTTOM, NCOLORS, etc
if these keywords are not passed explicitly.
bmy, 31 Oct 2001: GAMAP VERSION 1.49
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
bmy, 08 May 2002: GAMAP VERSION 1.50
- If the data array has more than 100,000 elements,
then assign it a dithering factor of 1, so that
we don't run out of memory when trying to plot it
bmy, 20 Jun 2002: GAMAP VERSION 1.51
- added WINDOWPOSITION keyword to return
the position vector of the plot window
region to the calling program
bmy, 28 Sep 2002: - now gets MYCT default parameters from the
!MYCT system variable
bmy, 10 Oct 2002: - bug fix: MCOLOR=!MYCT.BLACK setting has
now been restored (was left commented out)
bmy, 14 Nov 2002: GAMAP VERSION 1.52
- If GLABELS=0, then this also sets GXLABELS=0
and GYLABELS=0.
- Removed obsolete keywords
- Removed reference to MYCT_DEFAULTS.
bmy, 02 Mar 2004: GAMAP VERSION 2.02
- added OMARGIN keyword so that we can put
an outer margin around all plot panels
bmy, 28 May 2004: - Now returns the modified value of
C_COLORS to the calling program
- added CBTICKLEN keyword to specify the
color bar tick length
bmy, 23 Aug 2005: GAMAP VERSION 2.04
- added MAX_VALID keyword
- now adjust MINDATA to MIN_VALID and
MAXDATA to MAX_VALID internally
- Now pass _EXTRA=e to XYOUTS
tmf & bmy, 04 Oct 2006: GAMAP VERSION 2.05
- Replace /ERASE keyword with /NOERASE
to facilitate manual positioning of
plots. Pass /NOERASE to MULTIPANEL.
bmy & phs, 18 Sep 2007: GAMAP VERSION 2.10
- Don't reset data below MIN_VALID to
MIN_VALID for contour plots
- fix MAX_VALID for contour plots.
- fix CBar behavior when C_LEVELS is passed
cdh/phs/bmy 26 Nov 2007: GAMAP VERSION 2.11
- do not modify input DATA & X/YARR
- add support for VERTICAL COLORBAR
- add support for CONUS projection
- now all map projections are supported for
all 4 types of plots.
- now data Latitudes and Longitudes (X/Yarr)
are taken into account in Pixel
plot: no more need to clip the data
before plotting, TVMAP will do it, like
it already does for Contour plots.
- added Full Hemisphere Polar plot option,
regardless of DATA range and LIMIT keyword
- added RECTANGLE keyword to overwrite
default behavior
- map plotting coordinate system active at
exit, allowing for easy oplot
- default LIMIT for small data set corrected
- various fixes for across-the-dateline plots
- remove obsolete KEEP_ASPECT_RATIO keyword
- add /HORIZON keyword to call MAP_HORIZON
- updated comments
phs, 19 Dec 2007: - new default map limit in case of
non-global smooth pixel and contour
plots.
- plots start and end at box edges in few
new cases.
- replace /CENTER with /MINUS_ONE in call
to CONGRID
phs, 12 Feb 2008: GAMAP VERSION 2.12
- Fixes for MIN_VALID and MAX_VALID
- The test for the LIMIT keyword is now to check
"if ( n_elements(limit) ne 4 )". This allows you
to disable the LIMIT keyword by also setting
LIMIT=0.
phs, 28 Feb 2008: - Couple of small padding improvements
- added SCALEMAPSET and SCALEMAPIMAGE to pass
their respective SCALE keyword to MAP_SET and
MAP_IMAGE.
- LONS and LATS keyword added, so the grid can
be specified. Work with DLAT and DLON, the
grid spacings that can be passed to MAP_LABELS
thru the _extra keyword.
cdh & phs, 21 Mar 2008: - added minimum support for LIMIT input as
8-elements vector
phs, 17 Apr 2008: - Added the TopOutOfRange and BotOutOfRange
keywords, so default color (white) for Out-Of
-Range data can be overwritten.
phs, 6 May 2008: - Added the GXLABELS and GYLABELS keywords
to specify which grid line to label.
phs, 19 Jun 2008: - Set default SCALE value for MapImage
(ScaleMapImage keyword) to 0.04 if PS device.
phs, 25 Mar 2009: GAMAP VERSION 2.13
- Added NAN_COLOR to specify color to use
for NaN and Infinite data
cdh, eml, phs, 19 Sep 2009: - Now C_LEVELS works with pixel plots and
any projection.
- Added LATS, LONS (to specify the grid), and
TOPLEVELVALUE (to specify the last level
in the colorbar when using C_LEVELS)
keywords
- fixed limit of CONUS projection
phs, 29 Oct 2009: GAMAP VERSION 2.14
- added the polyfill keyword
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tvmap.pro)
NAME:
TVPLOT
PURPOSE:
TVPLOT produces one of the following plots:
(1) A color-pixel image, overlaid atop X-Y plot axes
(2) A line-contour plot, overlaid atop X-Y plot axes
(3) A filled-contour plot, overlaid atop X-Y plot axes
CATEGORY:
GAMAP Utilities, GAMAP Plotting
CALLING SEQUENCE:
TVPLOT, Data, Xarr, Yarr, [, keywords ]
INPUTS:
DATA -> 2-D array of values to be plotted.
XARR -> array of X-axis (horizontal axis) values needed to
construct the plot. The number of elements in XARR must
equal the number of elements of the first dimension of DATA.
ZARR -> ZARR is the array of Z-axis (vertical axis) values
needed to construct the plot. The number of elements
in ZARR must equal the number of elements of the second
dimension of DATA. If ZARR[0] > ZARR[N_Elements(ZARR)-1]
then TVPLOT will assume pressure is to be plotted on the
Y-axis.
KEYWORD PARAMETERS:
BLACK -> The color index corresponding to black.
Default is !MYCT.BLACK (from !MYCT system variable.)
/NOERASE -> This keyword prevents erasing the screen (or page)
when setting a multi-panel environment or after a page was
filled. /NOERASE is automatically turned ON when the /OFF
keyword is given. NOTE: On the PostScript device, when
the page is filled, it automatically places the next plot
on the next page. You can use the /NOERASE keyword to
suppress this behavior, especially if you are manually
placing plots on the page.
CSFAC -> Character size for the map labels and plot titles.
Default settings for CSFAC vary according to the number
of plots per page and type of plot device.
/NOADVANCE -> Set this switch to prevent TVMAP from advancing
to the next plot panel on the page. This is useful if
you desire to overplot something atop the pixel plot or
contour plot.
MARGIN -> specify a margin around the plot in normalized
coordinates. This keyword does not change any IDL
system variables and will thus only become "visible"
if you use the POSITION returned by MULTIPANEL in
subsequent plot commands. MARGIN can either be one value
which will be applied to all four margins, or a 2-element
vector which results in equal values for the left and
right and equal values for the bottom and top margins,
or a 4-element vector with [left,bottom,right,top]. The
default MARGIN setting is [ 0.05, 0.04, 0.00, 0.02 ].
-> adds 0.02 to the left margin for Y-axis title
-> adds 0.03 to the bottom margin for X-axis title
-> adds 0.03 to the right margin for vertical color bar
-> adds 0.02 to the top margin for more than 2 plots/page
OMARGIN -> specify a page margin around all panels in normalized
coordinates. Works like MARGIN.
WINDOWPOSITION -> Returns the position of the plot window
in normal coordinates to the calling program. This can
be used by a subsequent call to PLOT if you want to
overplot symbols atop the contour or pixel plot created
by TVPLOT.
_EXTRA=e -> Picks up extra keywords (not listed below) for
BYTSCL, COLORBAR, TVIMAGE, MAP_SET, MAP_GRID,
MAP_CONTINENTS, and CONTOUR.
Keywords for both BYTSCL and COLORBAR:
======================================
MAXDATA -> Maximum value of the DATA array to use in the
byte scaling. Default is max( DATA ).
MINDATA -> Minimum value of the DATA array to use in the
byte scaling. Default is min( DATA ).
BOTTOM -> The lowest color index of the colors to be used
for byte-scaling the color map and colorbar. Default
is !MYCT.BOTTOM (from the !MYCT system variable).
NCOLORS -> This is the maximum color index that will be used.
Default is !MYCT.NCOLOR (from the !MYCT system variable).
/LOG -> Will create a color-pixel plot with logarithmic
scaling. /LOG has no effect on line-contour or
filled-contour plots, since the default contour levels
are logarithmic.
Additional keywords for COLORBAR:
=================================
/CBAR -> If set, will plot the colorbar below the map in the
position specified by CBPOSITION. Default is to NOT
plot a colorbar.
CBCOLOR -> Color index of the colorbar outline and
characters. Defaults to BLACK (see above).
CBPOSITION -> A four-element array of normalized coordinates
that specifies the location of the colorbar. CBPOSITION
has the same form as the POSITION keyword on a plot.
Default is [0.1, 0.05, 0.9, 0.08].
CBUNIT -> Passes the Unit string to COLORBAR, which will be
plotted to the right of the color bar.
CBFORMAT -> format to use in call to colorbar. Default is I12
if abs(max(data)) < 1e4, else e12.2 (strings get trimmed)
CBMIN, CBMAX -> Explicitly sets the min and max values of
the colorbar range. If not set, TVPLOT will set
CBMIN = min( DATA ) and CBMAX = max( DATA ).
CBTICKLEN -> Specifies the color bar tick length as a
fraction of the colorbar height (for horizontal
colorbars) or width (for vertical colorbars).
CBSCALE -> If set, then the printed tick labels are scaled by
powers of 10 to minimize overlap.
DIVISIONS -> Number of labels for the colorbar. Default is 4.
/CBVERTICAL -> Will draw a vertical colorbar instead of
a horizontal one. Default is to draw a horizontal
colorbar.
Keywords for INTERPOLATION:
===========================
/SAMPLE -> Used to get COARSE pixel plot. REBIN is called,
and uses the nearest-neighbor sampling.
Note that REBIN is used even if SAMPLE is not set, when
device is PostScript. It uses the bilinear interpolation
then.
/NOZINTERP -> set to switch off the vertical
interpolation. This can be used only if the ZARR is
evenly spaced.
Keywords for PLOT:
===================
BOTOUTOFRANGE -> Color index for data below
MIN_VALID. Default is white, or last color in color
table if !MYCT is not defined. If set to negative, the
color is used in the plot only, and not in the colorbar.
POSITION -> A four-element array of normalized coordinates
that specifies the location of the map. POSITION has
the same form as the POSITION keyword on a plot.
Default is [0.1, 0.1, 0.9, 0.9].
TITLE -> The title string that is to be placed atop the
plot window. TITLE is passed explicitly to avoid keyword
name duplication in the _EXTRA=e facility.
COLOR -> Color index for the plot window outline and titles.
Default is BLACK.
XSTYLE, YSTYLE -> Style settings for the X and Y axes. See
the "Graphics Keywords" settings man page for more info.
XSTYLE and YSTYLE are passed as explicit keywords to
avoid keyword name confusion in the _EXTRA=e facility.
XRANGE, YRANGE -> Two-element vectors for the X-axis and Y-axis
plot ranges, of the form [Xmin,Xmax] and [YMin,Ymax].
XRANGE and YRANGE are passed as explicit keywords to
avoid keyword name confusion in the _EXTRA=e facility.
XTITLE, YTITLE -> Titles for the X and Y axes. XTITLE and
YTITLE are passed as explicit keywords to avoid keyword
name confusion in the _EXTRA=e facility.
NOXLABEL, NOYLABEL -> Suppress printing tick labels for X and Y axes.
Keywords for CONTOUR:
=====================
/CONTOUR -> Will produce a line-contour map instead of the
default color-pixel image map.
/FCONTOUR -> Will produce a filled-contour map instead
of the default color-pixel image map.
C_LEVELS -> Vector containing the contour levels. If not
specified, will use preset default levels (see below).
C_ANNOTATION -> Vector containing the contour labels.
Default is to use string representations of C_LEVELS.
C_FORMAT -> Format string used in converting C_LEVELS to
the default C_ANNOTATION values. Default is '(f8.1)'.
C_COLORS -> Index array of color levels for contour lines or
fill regions. If not specified then will use uniformly
spaced default color levels. If C_COLORS is set to a
scalar value, then all contour lines will have the same
color value.
C_LABELS -> Specifies which contour levels should be labeled.
By default, every other contour level is labeled. C_LABELS
allows you to override this default and explicitly
specify the levels to label. This parameter is a vector,
converted to integer type if necessary. If the LEVELS
keyword is specified, the elements of C_LABELS
correspond directly to the levels specified, otherwise,
they correspond to the default levels chosen by the
CONTOUR procedure. Setting an element of the vector to
zero causes that contour label to not be labeled. A
nonzero value forces labeling.
/C_LINES -> Will overplot a filled-contour map with contour lines
and labels instead of plotting a colorbar. This was the old
default behaviour but has been changed with the advent of
"discrete" colorbars. The old NOLINES keyword is kept
for compatibility reasons but doesn't do anything.
/NOLABELS -> Will suppress printing contour labels on both
line-contour and filled-contour maps.
OVERLAYCOLOR -> Color of the solid lines that will be
overlaid atop a filled contour map. Default is BLACK.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==================================================
COLORBAR GET_DEFAULTFORMAT (function)
INV_INDEX (function) LOGLEVELS (function)
TVIMAGE
REQUIREMENTS:
Assumes that a MYCT colortable has been loaded.
NOTES:
(1) The _EXTRA facility picks extra keywords for BYTSCL,
TVIMAGE, PLOT and COLORBAR, etc... This is a new
feature in IDL v. 5.0+!!
(2) For contour plots, contour labels will be specified
using the C_ANNOTATION keyword. The downside is that
by using C_ANNOTATION, this disables the C_LABELS keyword
and so one cannot specify which contour lines will get
labels. The solution would be to expand the C_LABELS
vector so that it has the same number of elements as
C_ANNOTATION, and then to individually zero the
corresponding elements of C_ANNOTATION before making
the contour plot. Don't have enough time for this now,
but maybe can deal with this at a later time...
EXAMPLE:
POSITION = [0.1, 0.1, 0.9, 0.9 ] ; position for map
CBPOSITION = [0.1, 0.05, 0.9, 0.08] ; position for colorbar
TVPLOT, DATA, XARR, YARR, $
MAXDATA=MAXDATA, MINDATA=MINDATA, $
POSITION=POSITION, CBPOSITION=CBPOSITION, $
/ERASE, TITLE='Avg O3', $
XTITLE='Longitude', YTITLE='Altitude', $
DIVISIONS=4, FORMAT='(F6.2)'
MODIFICATION HISTORY:
bmy, 27 Apr 1998: VERSION 1.00
bmy, 04 Jun 1998: - now can plot separate X or Y axes
if [XY]STYLE = 4 or 8
mgs, 15 Jun 1998: - bug fix n_elements instead of keyword_set
- now does spline interpolation in the
vertical in order to get correct
altitudes
bmy, 21 Sep 1998: - Rename EXTRA1, EXTRA2, etc, to names
that have more meaning (e.g. E_BYT for
BytScl, E_TV for TVImage, etc.)
bmy, 22 Sep 1998: VERSION 1.10
- now uses _EXTRA=e facility to pass extra
keywords to BYTSCL, TVIMAGE, PLOT, and
COLORBAR.
- add PLOTTITLE (for PLOT) and UNIT (for
COLORBAR) keywords to prevent keyword
name duplication in _EXTRA=e.
mgs, 11 Nov 1998: - added CBar keyword
bmy, 16 Nov 1998: VERSION 2.00
- now can produce line-contour and filled-
contour plots as well as image plots
- now calls REBIN to rebin the byte-scaled
image array to higher resolution for
PostScript output.
- added the following keywords: /LOG,
/SAMPLE, /CONTOUR, /FCONTOUR, C_ANNOTATION,
C_LEVELS, C_LABELS, /NOLABELS, /NOLINES,
bmy, 17 Nov 1998: - For image plots, now only display plot axes
AFTER the image plot has been made. This
reduces the "apparent" wait time for the
user.
- renamed keywords to XA_TITLE, XA_RANGE,
XA_TICKNAME, etc to avoid keyword name
duplication in the _EXTRA=e facility.
mgs, 17 Nov 1998: - added CBFormat keyword
bmy, 18 Nov 1998: - also added floating point format for
CBFORMAT when abs(max(Data)) < 10
mgs, 19 Nov 1998: - CBFormat no whandled in colorbar.pro
bmy, 27 Jan 1999: - added defaults for XRANGE and YRANGE
bmy, 08 Jan 1999: - If /LOG is set, make sure that we don't
take the log of zero and incur a math error
- add call to function INV_INDEX
mgs, 18 Mar 1999: - cleaned up
- now uses loglevels and has smarter default
contour levels
mgs, 22 Mar 1999: - added multi-panel ability through use of
the new MULTIPANEL routine. This alters the
meaning of MPosition and CB_Position: they now
refer to positions in the current plot panel!
mgs, 23 Mar 1999: - fixed a few minor things
- charsize is now adjusted according to number
of panels on page
bmy, 25 Mar 1999: - now use updated GET_DEFAULTFORMAT
- if NPANELS >=2 then place the plot title
higher above the window, to allow for
carriage-returned lines
- updated comments
bmy, 27 Apr 1999: - commented out !x.charsize=csfac and
!y.charsize=csfac lines...these messed
up the plot window sizes
- updated comments
bmy, 28 Apr 1999: - added CBMin and CBMax keywords for
tighter colorbar control
mgs, 19 May 1999: - title shifted a little higher if it has
more than 1 line.
mgs, 21 May 1999: - variable name for TITLE now MTITLE as in
TVMAP.
mgs, 27 May 1999: - changed default behaviour for filled contours:
now plots "discrete" colorbar and no lines.
Keyword NoLines changed to C_Lines.
bmy, 10 Jun 1999: - CBUnit defaults to '
mgs, 06 Jul 1999: - adjusted charsize for multipanel plots
bmy, 07 Jul 1999: - Save C_COLORS in a temp variable. Also
define C_COLORS so that grayscales won't
appear in Postscript plots
- multi-panel plots are now well-separated
from each other (for PostScript output)
bmy, 08 Jul 1999: - more minor fixes
bmy, 18 Nov 1999: - increase default left margin by a little
bmy, 31 Mar 2000: GAMAP VERSION 1.45
- made CSFAC a keyword
bmy, 23 Jul 2001: GAMAP VERSION 1.48
- now call MYCT_DEFAULTS to specify default
values for BLACK, BOTTOM, NCOLORS, etc
if these keywords are not passed explicitly.
bmy, 07 Jul 2001: - removed obsolete code from 1998 and 1999
bmy, 31 Oct 2001: GAMAP VERSION 1.49
- add /NOADVANCE keyword to prevent advancing
to the next page (in case you want to overplot)
bmy, 28 Sep 2002: GAMAP VERSION 1.51
- now gets MYCT default parameters from the
!MYCT system variable
bmy, 15 Nov 2002: GAMAP VERSION 1.52
- Added MIN_VALID keyword to skip missing
data values for pixel plots
bmy, 18 Dec 2003: - For pixel plots, now linearly interpolate
when creating NDATA instead of using a
cubic spline. This is more accurate.
- Prevent NDATA from being extrapolated wildly
due to the slope at the surface and top level
of the plot.
bmy, 06 Jan 2003: - Now interpolate NDATA correctly when pressure
or altitude is on the Y-axis.
- Removed obsolete keywords XA_TITLE, YA_TITLE,
- XA_RANGE, YA_RANGE, XA_TICKNAME, YA_TICKNAME
- Now define default YRANGE = [ ZBOT, ZTOP ]
to make Y-axis labels correct for both pressure
and altitude on the Y-axis.
- Removed ZBOT, ZTOP from the keyword list;
these are now internal variables.
- updated comments
bmy, 02 Mar 2004: GAMAP VERSION 2.02
- added MARGIN keyword a la TVMAP
- added OMARGIN keyword
bmy, 28 May 2004: - Now returns the modified value of
C_COLORS to the calling program
- added CBTICKLEN keyword to specify the
color bar tick length
bmy, 30 Nov 2004: GAMAP VERSION 2.03
- added WINDOWPOSITION keyword
bmy, 12 Jul 2005: GAMAP VERSION 2.04
- added /ISOTROPIC keyword
- added /NOZINTERP keyword to prevent interpolation
to a fine grid of 100 pts in the vertical dim.
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy & phs, 26 Nov 2007: GAMAP VERSION 2.11
- Minor fix for margins w/ for new TVIMAGE
- Also reset !P.MULTI=0 when using TVIMAGE
so that it will use the internally computed
position vector. Reset after TVIMAGE call.
- Make sure to label last colorbar division
for contour plots
- Vertical colorbar options and MIN_VALID,
MAX_VALID keywords are the same as TVMAP
- Extra space is now added to the default
MARGIN values for vertical colorbar
and multiple plots per page.
- Adjust default CBPOSITION values such
that the colorbar will be placed either
0.05 below or 0.02 to the right of the plot
phs, 04 Apr 2008: GAMAP VERSION 2.12
- now produces a better coarse pixel plot
for altitude vs latitude or longitude
plots, even though the initial box size
is not exactly reproduced.
cdh, eml, phs, 24 Sep 2009: GAMAP VERSION 2.13
- fixes for LOG10 plots
- new improved interpolation scheme in Z
direction
- C_LEVELS works with /SAMPLE
- added checks on NAN when looking at
min/max, added NAN_COLOR to specify a
color for NaN
- added BOTOUTOFRANGE to set color of data
below Min_Valid
- check if !MYCT is defined
xyue & bmy, 24 Jan 2011: GAMAP VERSION 2.15
- Replace /ERASE keyword with /NOERASE
to facilitate manual positioning of
plots. Pass /NOERASE to MULTIPANEL.
This is now consistent w/ TVMAP.
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/tvplot.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)