This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Tue Aug 23 14:22:35 2011.
NAME: ABGRAD VERSION: 4.0 PURPOSE: Calculates the absolute value of the gradient of a function represented as an array of values. Works for 1-7 dimensions. CATEGORY: Array Manipulation. CALLING SEQUENCE: Result = ABGRAD( ARR [, DELTA]) INPUTS: ARR Array, numeric, number of dimensions can be 1 through 7. OPTIONAL INPUT PARAMETERS: DELTA Size of step used to calculate the numeric derivatives. The approx. partial derivative in the i-th direction is calculated as (ARR(...,I + DELTA,...) - ARR(...,I - DELTA,...))/(2*DELTA). The default value of DELTA is 1l. If provided, it is rounded to a long integer on input. KEYWORD PARAMETERS: None. OUTPUTS: Returns the absolute value of the gradient as an array of the same size and type as ARR. If ARR is not an array, returns 0. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: Due to current limitations of the MAKE_ARRAY system routine, 8 dimensions are not allowed. PROCEDURE: Creates an 7-dimensional array, with dummy leading dimensions, containing the original array. Generates the differences using the SHIFT system routine and strips the dummy dimensions at the end. Uses the functions DEFAULT and FPU_FIX from MIDL. MODIFICATION HISTORY: Created 15-NOV-1991 by Mati Meron. Modified 30-AUG-1998 by Mati Meron. Underflow filtering added. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\abgrad.pro)
NAME: ABS_MM VERSION: 4.0 PURPOSE: Calculates absolute values. A temporary fix needed since the IDL ABS function fails with very large or very small complex numbers. CATEGORY: Mathematical, general. CALLING SEQUENCE: Result = ABS_MM (X) INPUTS: X Numerical, otherwise arbitrary. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: None. OUTPUTS: Returns the absolute value of the input. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Straightforward. Calling FPU_FIX and ISNUM from MIDL. MODIFICATION HISTORY: Created 15-MAR-1996 by Mati Meron as M_ABS. Modified 30-AUG-1998 by Mati Meron. Underflow filtering added. Renamed 25-SEP-1999 by Mati Meron, to ABS_MM. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\abs_mm.pro)
NAME:
ACOSD
PURPOSE:
Return the inverse cosine of a value, in degrees rather then radians.
CALLING SEQUENCE:
deg = acosd(x)
INPUTS:
value cosine of angle
OPTIONAL INPUTS:
OUTPUTS:
Angle in degrees returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\acosd.pro_)
NAME: ADC VERSION: 4.3 PURPOSE: Interface to HISTOGRAM, simulating an Analog to Digital Converter. CATEGORY: Mathematical. CALLING SEQUENCE: Result = ADC( ARR [, keywords] ) INPUTS: ARR Array, numeric, otherwise arbitrary. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: MASK Provision for optional data mask. Needs to be an array of the same as ARR. If given, only data (in ARR) corresponding to locations of non-zero elements of MASK is considered. Equivalent to replacing ARR by ARR[ where(mask ne 0)]. BINSIZE Specifies the size of the BIN, same as in HISTOGRAM. Defaults to full range (i.e. a single channel). N_CHANNELS Number of channels to use in the binning. If BINSIZE is provided, N_CHANNELS is ignored. MIN The minimal value to consider. Same as in HISTOGRAM. The default value is min(ARR). MAX The maximal value to consider. Same as in HISTOGRAM. The default value is max(ARR). /LEFT Switch. If set, the elements within each bin are associated with the left bin boundary (i.e. with the minimum of the interval). /CENTER Switch. If set, the elements within each bin are associated with the center of the bin (i.e. with the middle of the interval). This is the default. /RIGHT Switch. If set, the elements within each bin are associated with the right bin boundary (i.e. with the maximum of the interval). NOTE!!!: Only one of the switches LEFT, CENTER, RIGHT may be set. /ROUND Switch. If set, the upper and lower boundaries are rounded (up and down, respectively) to the nearest bin. /EXTEND Switch. If set, the upper and lower boundaries are extended (up and down, respectively) by half a bin. NOTE: If BINSIZE is not set, ROUND and EXTEND are ignored. /TOP_ADJUST Switch. If set, adjusts for the possibility of the uppermost element of ARR being counted in a separate channel. /NORMALIZE Switch. If set, the output is normalized to a total sum of 1. OMIN Optional output. See below. OMAX Optional output. See below. VALUES Optional output. See below. OUTPUTS: Returns a histogram of the original array, with either binsize provided by BIN or number of channels provided by N_CHANNELS. OPTIONAL OUTPUT PARAMETERS: OMIN Name of a variable to receive the value of MIN used internally. Same as in HISTOGRAM. OMAX Name of a variable to receive the value of MAX used internally. Same as in HISTOGRAM. VALUES Returns a vector of the nominal values associated with the bins (LEFT, CENTER or RIGHT, according to the keywords). COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: ARR must be numeric and BIN must be a positive scalar. No other restrictions. PROCEDURE: Straightforward. Calls the IDL function HISTOGRAM. Also calls ARREQ, CAST, DEFAULT, FPU_FIX, ISNUM and ONE_OF from MIDL. MODIFICATION HISTORY: Created 15-MAY-1996 by Mati Meron. Modified 25-JUN-2000 by Mati Meron. Internal changes only. Modified 1-AUG-2001 by Mati Meron. Checked compatibility with Windows and added keywords MASK and ROUND. Modified 5-JAN-2002 by Mati Meron. Added keyword EXTEND and improved internal consistency.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\adc.pro)
NAME: add2history PURPOSE: This procedure adds information to the history of an ICG structure. CATEGORY: DATAFILES CALLING SEQUENCE: add2history, icg_struc [,text] INPUTS: icg_struc: Name of the ICG structure OPTIONAL INPUTS: text: String scalar or array which will be added to the history. OUTPUTS: This procedure writes information to the history of an ICG structure. The entry is as follows:[ ] EXAMPLE: icgs = read_ncdf('S:\links\idl_source\idl_work\fh_lib\examples\sfpo_oh.nc') icgs.time.param = icgs.time.param - 7200.D add2history, icgs, 'Subtracted 7200 sec from time data to convert from MESZ to UTC.' PRINT, TRANSPOSE(STR_SEP(icgs.!global.history, '!C')) MODIFICATION HISTORY: Written by: Frank Holland, 19.11.1999 22.11.1999: Changed format of history string (no leading blanks anymore) 17.03.2000: Added version information to history entry Changed code to new version of add_tag
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add2history.pro)
ROUTINE: addpath
PURPOSE:
USEAGE: addpath,pathname,cut=cut
INPUT:
pathname Name of new path to add to this session's directory path.
if pathname is already present in !path no action is taken.
This last feature allows addpath to be repeatedly executed
(e.g., within a script) without affecting !path after the
first invocation.
KEYWORD INPUT:
cut If set and pathname is set, the element of !path that
matches pathname is removed. If pathname is not
specified, the last element of !path is removed.
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLES:
addpath,'/home/paul/idl' ; add a path
addpath,'/local/idl/lib/wided',/cut ; remove a specific path
addpath,/cut ; remove last path element
addpath ; view !path
AUTHOR: Paul Ricchiazzi 04 Nov 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\addpath.pro)
NAME:
add_comment
PURPOSE:
This procedure adds a comment to an ICG structure.
CATEGORY:
ICG_STRUCT
CALLING SEQUENCE:
add_comment, icg_struc, text
INPUTS:
icg_struc: Name of the ICG structure
text: Comment to be added to the ICG structure (scalar).
KEYWORD PARAMETERS:
/OVERWRITE: If set an alread existing comment will be overwritten
OUTPUTS:
This procedure adds the (or updates an alread existing) 'COMMENT' tag
which is part of the '!GLOBAL' tag of an ICG structure.
EXAMPLE:
icgs = read_ncdf('S:\links\idl_source\idl_work\fh_lib\examples\sfpo_oh.nc')
icgs.time.param = icgs.time.param - 7200.D
add_comment, icgs, 'Subtracted 7200 sec from time data to convert from MESZ to UTC.'
PRINT, icgs.!global.comment
MODIFICATION HISTORY:
Written by: Frank Holland, 13.03.2000
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add_comment.pro)
NAME:
ADD_MARGIN
PURPOSE:
Add space to left margin and top of a text file.
CATEGORY:
CALLING SEQUENCE:
add_margin, in, out, n_left, [n_top]
INPUTS:
in = Input file. in
n_left = Number of spaces to add to left margin. in
n_top = number of blank lines to add to top. in
KEYWORD PARAMETERS:
OUTPUTS:
out = Output file. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Written by R. Sterner, 3 Mar, 1988.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\add_margin.pro)
NAME: add_quality PURPOSE: This function adds the QUALITY flag and array to a given structure of type INHALT CATEGORY: PROG_TOOLS/STRUCTURES CALLING SEQUENCE: Result=add_quality(structure) INPUTS: inhalt: the by ncdf_gr defined structure OUTPUTS: A structure type INHALT with a quality field and flag added EXAMPLE: inhalt=add_quality(inhalt) MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1998-Jun-13 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\add_quality.pro)
USERLEVEL:
TOPLEVEL
NAME:
add_tag
PURPOSE:
This functions adds a tag on an arbitrary level of a structure.
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
result = add_tag(struct, tagname, tagvalue [, sub_structure = sub_structure])
INPUTS:
struct : the structure to which the tag will be added
tagname : the name of the new tag
tagvalue: the value of the new tag
KEYWORD PARAMETERS:
sub_structure: to define the sub structure where the tag should be added.
If not given the tag will be added on the main level of the structure (see examples)
OUTPUT:
This function returns a structure with a new tag added to it.
EXAMPLE:
d = {A: 1, B: {B1: 0, B2: 1}, C: {B1: 0, B2: 1}}
help,d,/str
** Structure <1331608>, 3 tags, length=10, refs=1
A INT 1
B STRUCT -> Array[1]
C STRUCT -> Array[1]
result = add_tag(d,'ASA',11)
HELP, result, /STR
** Structure <10530e8>, 4 tags, length=12, refs=1:
A INT 1
B STRUCT -> Array[1]
C STRUCT -> Array[1]
ASA INT 11
result = add_tag(d, 'ASA', 11, sub = 'B')
HELP, result.b, /STR
** Structure <133ce88>, 3 tags, length=6, refs=1
B1 INT 0
B2 INT 1
ASA INT 11
result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = 'B.B3')
HELP, result.b, /STR
** Structure <1357758>, 3 tags, length=10, refs=2:
B1 INT 0
B2 INT 1
B3 STRUCT -> Array[1]
result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = ['B','C'])
help,result.b,/str
** Structure <1055618>, 3 tags, length=10, refs=2:
B1 INT 0
B2 INT 1
BSB STRUCT -> Array[1]
help,result.c,/str
** Structure <1056968>, 3 tags, length=10, refs=2:
B1 INT 0
B2 INT 1
BSB STRUCT -> Array[1]
result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = ['B.C1','C'])
help,result.b,/str
** Structure <1056168>, 3 tags, length=10, refs=2:
B1 INT 0
B2 INT 1
C1 STRUCT -> Array[1]
result = add_tag(d, 'BSB', {C11: INDGEN(3)}, sub = 'F')
help,result,/str
** Structure <10550f8>, 4 tags, length=16, refs=1:
A INT 1
B STRUCT -> Array[1]
C STRUCT -> Array[1]
F STRUCT -> Array[1]
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 2000-Jan-05
14.03.2000: Header edited
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\add_tag.pro)
NAME:
add_tag2
PURPOSE:
This function adds a tag to a given structure.
Both, structure and values can be arrays.
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
x = add_tag2(str, tag, value [, status])
INPUTS:
str: variable name of structure or array of structures
tag: name of tag to be added (STRING)
if tag already exists in str its deleted
value: value of tag (scalar or array)
KEYWORD PARAMETERS:
/EXPAND_VALUES: IF set, the last dimension of value is expanded along the dimension of str
/FIRST: The new tag is inserted at the beginning of str
NAME: A unique name for the new structure.
OPTIONAL OUTPUTS:
status: Status information =0: every thing worked fine;
=1: something went wrong (see messages on screen)
SIDE EFFECTS:
If an array of anonymous structures is passed into the routine an array
of named structures is returned.
EXAMPLE:
as = {Bsp1, a:0, b:'asd'}
bs = add_tag2(as, 'c', 0.46D00, /FIRST, NAME = 'Bsp2')
HELP, bs, /STR :
** Structure BSP2, 3 tags, length=24:
C DOUBLE 0.46000000
A INT 0
B STRING 'asd'
MODIFICATION HISTORY:
Written by: Frank Holland, 09. Mar. 98.
This program is based on the procedure add_tag.pro but provides additional features
27.05.98 - Type of loop variable in FOR loop changed to LONG
15.11.98: call to debug deleted
28.04.1999: tag_defined exchanged by is_tag
22.09.1999: Random structure name will only be generated if a tag is added to an
array of structures.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add_tag2.pro)
NAME:
add_tag_fh
PURPOSE:
This function can be used to add tags to a substructure of a given structure
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
result = add_tag_fh(struct, tag_name, value)
INPUTS:
struct: Input structure.
tag_name: Name of new tag (STRING).
value: Value of new tag.
KEYWORD PARAMETERS:
SUB_STR = sub_str: Name (scalar or array) of the substructure(s) under which the tag is added.
(default: '' e.g. main level)
OUTPUTS:
This function returns a structure with the tag 'tag_name' added.
EXAMPLE:
s0 = {H2O: {param: 4, units: 'mbar'}, O3: {param: 17, units: 'ppb'}}
s1 = add_tag_fh(s0, 'NO2', {param: 23.})
s1 = add_tag_fh(s1, 'units', 'ppb', SUB_STR = 'NO2')
HELP, s1, /STR
s2 = add_tag_fh(s1, 'description', 'NONE', SUB_STR = ['NO2', 'H2O', 'O3'])
HELP, s2, /STR
MODIFICATION HISTORY:
Written by: Frank Holland, 12.01.2000
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\add_tag_fh.pro)
NAME:
AdjustPosition
PURPOSE:
This is a program for interactively adjusting the plot position
coordinates. The result of the function is a four-element floating
point array of normalized coordinates, suitable for passing to the
POSITION keyword of most IDL graphics commands.
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:
position = AdjustPosition(startingPosition)
OPTIONAL INPUTS:
startingPosition - A four-element array of normalized coordinates
of the form [x0, y0, x1, y1].
OUTPUTS:
position - The adjusted plot position. A four-element array of normalized coordinates.
INPUT KEYWORDS:
GROUP_LEADER - The group leader of this program. This keyword
is required to ensure modal operation when calling from
another widget program.
TITLE - The title of the window. "Adjust Plot Position in Window..." by default.
XOFFSET - The X offset of the program on the display. Calculated from the
upper left-hand corner of the display.
YOFFSET - The Y offset of the program on the display. Calculated from the
upper left-hand corner of the display.
OUTPUT KEYWORDS:
CANCEL - Returns a 1 if the user selects the Cancel button. Returns 0 otherwise.
Note that if the use cancels, the "position" parameter is set to the value of
the "startingPosition" parameter.
DEPENDENCIES:
Reqires FSC_FIELD and FSC_PLOTWINDOW from the Coyote Library:
http://www.dfanning.com/programs/fsc_field.pro
http://www.dfanning.com/programs/fsc_plotwindow.pro
MODIFICATION HISTORY:
Written by David Fanning, March 2001.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\adjustposition.pro)
NAME:
aformat
PURPOSE:
This procedure is used by plotxy to set the axis-format.
CATEGORY:
PLOT/PLOTXY
CALLING SEQUENCE:
aformat,plot,xtickformat,ytickformat,xtype,ytype,i_xn,i_yn
INPUTS:
plot: plot-structure as defined by pl_init
i_xn: position number for one of the used x axes
i_yn: position number for one of the used y axes
OPTIONAL INPUTS:
x: name of a netCDF parameter-name containing the array of x values
y: name of a netCDF parameter-name containing the array of y values
OUTPUTS:
xtickformat: string containing the name of the function later used to format xticks
ytickformat: string containing the name of the function later used to format yticks
xtype : set to 1 if format emensch could be used
ytype : set to 1 if format emensch could be used
EXAMPLE:
aformat,plot,x='TIME',y='NO',xtickformat,ytickformat,xtype,ytype,0,0
help,xtickformat,ytickformat,xtype,ytype
XTICKFORMAT STRING = ''
YTICKFORMAT STRING = 'emensch'
XTYPE INT = 0
yTYPE INT = 1
MODIFICATION HISTORY:
Written by: Franz Rohrer August 1997
Modified 29.8.97 : plot.xtype und plot.ytype als Felder eingeführt
i_xn und i_yn im Prozeduraufruf eingeführt
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\aformat.pro)
NAME:
AIRDENS (function)
PURPOSE:
Compute air mass density for a given pressure and
temperature. If the temperature is not provided, a
temperature is estimated using the US Standard atmosphere.
CATEGORY:
Atmospheric Sciences
CALLING SEQUENCE:
idens = AIRDENS(p [,T])
INPUTS:
P -> pressure in hPa (mbar)
T -> temperature in K
KEYWORD PARAMETERS:
HELP -> print help information
OUTPUTS:
The air mass density in molec/cm^3. The result type will
match the type and array dimensions of p unless p is a scalar
and T an array.
SUBROUTINES:
REQUIREMENTS:
Uses functions USSA_ALT and USSA_TEMP
NOTES:
EXAMPLE:
print,airdens(1013.25,273.15)
; prints 2.69000e+19
p = findgen(5)*100+500
print,airdens(p,T) ; T undefined !
; prints 1.44840e+19 1.67414e+19 1.89029e+19 2.10104e+19 2.30998e+19
print,T
; prints 250.334 259.894 268.538 276.117 282.534
print,airdens(800.,T) ; T from previous calculation
; prints 2.31744e+19 2.23218e+19 2.16033e+19 2.10104e+19 2.05332e+19
MODIFICATION HISTORY:
mgs, 12 Nov 1998: VERSION 1.00
mgs, 23 Aug 2000: - changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\airdens.pro)
ROUTINE: airmass
PURPOSE: compute airmass as a function of angle, sza, including
spherical earth effects
USEAGE: result=airmass(sza)
INPUT:
sza zenith angle
KEYWORD INPUT:
OUTPUT: relative airmass,
by definition the relative airmass = 1 for sza=0.
References:
1) Kasten, F 1966: A new table and approximate formula for relative
airmass. Arch. Meteor. Geophys. Bioklimatol. Ser. B, 14, 206-223
2) Kasten and Young, 1989: Applied Optics, 28, 4735-4738
recommended by Yankee Environmental Systems (MFRSR)
EXAMPLE:
sza=findrng(0,89.,dx=.1)
plot,sza,1./cos(sza*!dtor),yran=[1,30]
plot,sza,cos(sza*!dtor)*airmass(sza)
AUTHOR: Paul Ricchiazzi 09 Jan 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\airmass.pro)
NAME:
ALIGN
PURPOSE:
Vector text justification (positioning).
CATEGORY:
CALLING SEQUENCE:
align, x,y,txt
INPUTS:
x,y = Reference point. in
txt = Text string.
KEYWORD PARAMETERS:
Keywords:
CHARSIZE=csz Character size.
AX=ax Alignment in X (fraction).
AY=ax Alignment in Y (fraction).
AX=0, AY=0 is lower left corner of text.
AX=1, AY=1 is upper right corner of text.
/DEVICE Means work in device coordinates.
/DATA Means work in data coordinates.
/NORMAL Means work in normalized coordinates.
XOUT=xx Output x position.
YOUT=yy Output x position.
xyouts,xx,yy,txt,charsize=csz.
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: Currently works only for horizontal text.
MODIFICATION HISTORY:
R. Sterner, 1994 Apr 4.
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\align.pro)
NAME:
alt_inhalt_def
PURPOSE:
This routine holds the definitons for the structure INHALT
It's an alternative to inhalt_def
CATEGORY:
DATAFILES/NETCDF
CALLING SEQUENCE:
alt_inhalt_def,inhalt_def=inhalt_def,[array_de_descriprion=array_de_descriprion]
OUTPUTS:
inhalt_def=inhalt_def: an array defining ncdf and idl names
OPTIONAL OUTPUTS:
array_de_description=array_de_description: an array holding german expressions for additional parameters
EXAMPLE:
alt_inhalt_def,inhalt_def=inhalt_def
MODIFICATION HISTORY:
Written by: R. Bauer ICG-1 , May 1997
R.Bauer 1997-Sep-16 debug added
R.Bauer 1998-Mar-3 filter extended by using uppercase definitions
R.Bauer 1998-Nov-16 added 4*s+o
R.Bauer 1998-Nov-16 added user definitions for INHALT
R.Bauer 1999-May-28 added time_description and time_de_description
R.Bauer 1999-Sep-07 median added
R.Bauer 2000-Jan-25 dataset_forecast_hours added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\alt_inhalt_def.pro)
NAME:
ames2icgs
PURPOSE:
This functions reads the nasa Ames datafiles to the icg data structure
CATEGORY:
DATAFILES/FILTER
CALLING SEQUENCE:
result=ames2icgs(file)
INPUTS:
file: name of the nasa ames file
PROCEDURE:
This routine uses the ames library interface
EXAMPLE:
struct=ames2icgs('al970626.ea1')
write_ncdf,'al970626.nc',struct
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Nov-30
This routine is not quite finished at the moment.
I will change the "cases" later on
2000-01-18 Abfrage für das Einbinden von stdev erweitert.
2000-01-21 useable fomats at the moment are: 1001, 1020, 2110
2000-01-24 short_names for some files expanded
2000-01-25 short_names for more files expanded (jug)
2000-02-24 'ALTITUDE OF OBSERVATION' added
2000-06-13 is_tag auf 'time' added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\jug_lib\ames2icgs.pro)
NAME: ANGLE_INC VERSION: 4.1 PURPOSE: Calculates the angle increments between segments of a polygonal line. CATEGORY: Mathematical. CALLING SEQUENCE: Result = ANGLE_INC( X [, Y] [, keywords]) INPUTS: X Numeric vector or [2,N] array. In the first case: 1) If Y is given, X represents the X coordinates of the vertices. 2) If Y is not given, X represents the Y coordinates and the X coordinates are generated internally as [1, 2, ...N-1] In the second case X represents both X and Y coordinates and Y should not be given. OPTIONAL INPUT PARAMETERS: Y Numeric vector, optional when X given as vector, forbidden when X is a [2,N] array. Represents the Y coordinates. KEYWORD PARAMETERS: /ABSOLUTE Switch. If set the absolute values of the angles are calculated. /CLOSED Switch. If set, the shape is closed prior to calculation (unless it is already closed. /TOTAL_ONLY Switch. If set, only the sum of the angles is returned. OUTPUTS: Returns the N-2 (or N-1, for a closed curve) external angles generated by the vertices. Note, the external angles are the angles by which each segment deviates from the previous one. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: The value of N (the vector length) must be >=3. Also, if both X and Y are given, they must be of same length. PROCEDURE: Straightforward from the geometric definitions. Calls CAST, DIF, SIGN, SPLIT_XY and TYPE from MIDL. MODIFICATION HISTORY: Created 15-MAY-2001 by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\angle_inc.pro)
NAME:
ANIMALS
PURPOSE:
Return a string array of animals.
CATEGORY:
CALLING SEQUENCE:
a = animals()
INPUTS:
KEYWORD PARAMETERS:
OUTPUTS:
a = string array of animals. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 24 Jul, 1991
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\animals.pro)
NAME:
APODIZE
PURPOSE:
Weighting array for apodizing an image. Cosine taper.
CATEGORY:
CALLING SEQUENCE:
a = apodize(w, r)
INPUTS:
w = size of square array a to make. in
r = radius of flat top as a fraction 0 to 1. in
KEYWORD PARAMETERS:
OUTPUTS:
a = resulting array. out
COMMON BLOCKS:
NOTES:
Notes: Output array is square. To convert to rectangular
use congrid to specify desired size and shape:
b = congrid(a, 100,50)
MODIFICATION HISTORY:
Written by R. Sterner, 6 Dec, 1984.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1984, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\apodize.pro)
NAME:
ARC
VERSION:
4.0
PURPOSE:
Draws a circular arc in the currently defined plot area.
Alternatively, a *SHAPE* representation (see SHAPE_VER for definition)
of the arc may be returned through the SHAPEOUT keyword. DATA
coordinates are used. The method of drawing depends on the number of
input parameters provided (see details in CALLING SEQUENCE below).
CATEGORY:
General Graphics.
CALLING SEQUENCE:
There are two possible modes of operation, and accordingly two
different calling sequences:
Mode 1:
ARC, R1, CENTER = CENT, ANGLE = ANG [, optional keywords]
In this mode an arc with angular measure ANG is drawn around the point
CENT, in the mathematical-positive direction, starting from point R1.
Mode 2:
ARC, R1, R2, {RADIUS = RAD, ANGLE = ANG} [, optional keywords]
In this mode the arc is drawn in the mathematical-positive direction,
from point R1 to point R2. The arc is either drawn with radius RAD, or
corresponding to an angle ANG (both RAD and ANG cannot be specified).
INPUTS:
R1, R2
2-dimensional vectors in the [x,y] format, representing points in the
plotting area. R1 is mandatory. The presence of R2 indicates that
Mode 2 is being used.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
CENTER
2 dimensional vector, arc center location, format [x,y].
Mandatory in Mode 1, forbidden in Mode 2.
RADIUS
Scalar, the radius of the arc. |
Forbidden in Mode 1, allowed in Mode 2. | In Mode 2
ANGLE | one and only one
Scalar, the angle measure of the arc. | needs to be provided.
Mandatory in Mode 1, allowed in Mode 2. |
/DEGREES
Switch. Indicates that the angle ANG is given in degrees (default is
radians).
/BIGARC
Switch. When drawing in Mode 2, with the radius provided, there are two
possible arcs that can be drawn, corresponding to angles smaller and
bigger than 180 degrees (the sum of both angles is 360 degrees). By
default the smaller arc is drawn. Setting BIGARC selects the bigger arc.
/SYMMETRIC
Switch. In Mode 1 causes the arc to be drawn symmetrically on both
sides of R1. Forbidden in Mode 2.
/NO_SHOW
Switch. If set, no plotting is done, but the shape is generated and
may be returned through SHAPEOUT.
SHAPEOUT
Optional output, see below.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
SHAPEOUT
When provided with the name of a variable, on return the variable
contains the *SHAPE* representation of the arc.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The arc will appear as a true circular arc only if the aspect ratio of
the X to Y axes is 1:1.
The keywords passed through _EXTRA are transferred to the PLOTS
routine. No keyword verification is performed by ARC.
PROCEDURE:
Uses calls to ONE_OF and SHAPE_COCON from MIDL.
Generates a (2,N) array containing a sufficient number of the arc
points to yield a smooth curve. N is variable, depending both on the
arc size and on the pixel size of the current output device.
MODIFICATION HISTORY:
Created 15-DEC-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Now ARC takes advantage of the
keyword inheritance property and accepts all PLOTS keywords.
Modified 15-JUN-1995 by Mati Meron. Removed the ALT_EXT keyword which
is no longer needed (_EXTRA has been fixed).
Modified 25-JUL-1999 by Mati Meron. Added keywords NO_SHOW and
SHAPEOUT.
Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arc.pro)
NAME:
ARCS
PURPOSE:
Plot specified arcs or circles on the current plot device.
CATEGORY:
CALLING SEQUENCE:
arcs, r, a1, a2, [x0, y0]
INPUTS:
r = radii of arcs to draw (data units). in
[a1] = Start angle of arc (deg CCW from X axis, def=0). in
[a2] = End angle of arc (deg CCW from X axis, def=360). in
[x0, y0] = optional arc center (def=0,0). in
KEYWORD PARAMETERS:
Keywords:
/DEVICE means use device coordinates .
/DATA means use data coordinates (default).
/NORM means use normalized coordinates.
/NOCLIP means do not clip arcs to the plot window.
COLOR=c plot color (scalar or array).
LINESTYLE=l linestyle (scalar or array).
THICKNESS=t line thickness (scalar or array).
OUTPUTS:
COMMON BLOCKS:
NOTES:
Note: all parameters may be scalars or arrays.
MODIFICATION HISTORY:
Written by R. Sterner, 12 July, 1988.
Johns Hopkins University Applied Physics Laboratory.
RES 15 Sep, 1989 --- converted to SUN.
R. Sterner, 17 Jun, 1992 --- added coordinate systems, cleaned up.
R. Sterner, 1997 Feb 24 --- Added THICKNESS keyword.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\arcs.pro)
NAME:
ARG_PRESENT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Determine whether output parameter has been passed (IDL4 compatibility)
CALLING SEQUENCE:
PRESENT = ARG_PRESENT(ARG)
DESCRIPTION:
ARG_PRESENT tests whether an argument to a function or procedure
can be used as an output parameter. The behavior of this function
is identical to that of the built-in ARG_PRESENT function in IDL
version 5 or greater, and is meant to give the same functionality
to programs in IDL 4.
An IDL procedure or function can use ARG_PRESENT to decide whether
the value of a positional or keyword parameter will be returned to
the calling procedure. Generally, if the caller did not pass the
parameter then there is no need to compute the value to be
returned.
To be a valid output parameter, the caller must have passed a
named variable into which the result is stored. If the caller
passed the parameter by value (e.g., an expression or a
subscripted array) the value cannot be returned and ARG_PRESENT
returns 0.
INPUTS:
ARG - the parameter to be tested. It can be either a positional
or a keyword parameter. Passing a normal local variable
(i.e., not a passed parameter) will cause ARG_PRESENT to
return zero.
RETURNS:
Returns a value of 1 if ARG is a valid output parameter, and a
value of 0 otherwise.
EXAMPLE:
Consider the following procedure:
PRO TESTARG, ARG1
print, ARG_PRESENT(ARG1)
END
This procedure will print 1 when an ARG1 can be used as an output
parameter. Here are some examples of the results of TESTARG.
IDL> testarg
0
IDL> testarg, x
1
IDL> testarg, findgen(10)
0
In the first case, no argument is passed, so ARG1 cannot be a
return variable. In the second case, X is undefined, but it is
still a legal named variable capable of receiving an output
parameter. In the third case, FINDGEN(10) is an expression which
cannot receive an output parameter.
SEE ALSO:
ARG_PRESENT in IDL version 5
MODIFICATION HISTORY:
Written, CM, 13 May 2000
Small documentation and bug fixes, CM, 04 Jul 2000
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\arg_present.pro)
NAME:
ARG_PRESENT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Determine whether output parameter has been passed (IDL4 compatibility)
CALLING SEQUENCE:
PRESENT = ARG_PRESENT(ARG)
DESCRIPTION:
ARG_PRESENT tests whether an argument to a function or procedure
can be used as an output parameter. The behavior of this function
is identical to that of the built-in ARG_PRESENT function in IDL
version 5 or greater, and is meant to give the same functionality
to programs in IDL 4.
An IDL procedure or function can use ARG_PRESENT to decide whether
the value of a positional or keyword parameter will be returned to
the calling procedure. Generally, if the caller did not pass the
parameter then there is no need to compute the value to be
returned.
To be a valid output parameter, the caller must have passed a
named variable into which the result is stored. If the caller
passed the parameter by value (e.g., an expression or a
subscripted array) the value cannot be returned and ARG_PRESENT
returns 0.
INPUTS:
ARG - the parameter to be tested. It can be either a positional
or a keyword parameter. Passing a normal local variable
(i.e., not a passed parameter) will cause ARG_PRESENT to
return zero.
RETURNS:
Returns a value of 1 if ARG is a valid output parameter, and a
value of 0 otherwise.
EXAMPLE:
Consider the following procedure:
PRO TESTARG, ARG1
print, ARG_PRESENT(ARG1)
END
This procedure will print 1 when an ARG1 can be used as an output
parameter. Here are some examples of the results of TESTARG.
IDL> testarg
0
IDL> testarg, x
1
IDL> testarg, findgen(10)
0
In the first case, no argument is passed, so ARG1 cannot be a
return variable. In the second case, X is undefined, but it is
still a legal named variable capable of receiving an output
parameter. In the third case, FINDGEN(10) is an expression which
cannot receive an output parameter.
SEE ALSO:
ARG_PRESENT in IDL version 5
MODIFICATION HISTORY:
Written, CM, 13 May 2000
Small documentation and bug fixes, CM, 04 Jul 2000
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmarg_present.pro)
ROUTINE: armbasetime
PURPOSE: The base_time variable provided by ARM net_cdf files is the
number of seconds since jan 1, 1970 00:00:00 UTC. This
procedure converts base_time to the current date in yymmdd
format, and the number of hours since the most recent
Grenich midnight (00:00:00 UTC).
USEAGE: armbasetime,base_time,time,yymmdd,file=file
INPUT:
bt number of seconds since jan 1, 1970 00:00:00 UTC.
KEYWORD_INPUT
file name arm net_cdf file. If this quantity is set the value
of bt is set from the value read from the file.
OUTPUT:
time time since Grenich midnight of the current day
yymmdd date string in yymmdd format
EXAMPLE:
file='/home/paul/arm/iop_97/mfrsr/sgpmfrsrC1.a1.970915.000000.cdf'
armbasetime,file=file,bt,time,yymmdd
print,bt,time," ",hms(3600*time)," ",yymmdd
AUTHOR: Paul Ricchiazzi 05 Jun 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\armbasetime.pro)
USERLEVEL:
TOPLEVEL
NAME:
arr2string
PURPOSE:
This function will combine elements of a stringarray; e.g. [' A ',' B ']->'A,B'
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
result=arr2string(array)
INPUT PARAMETERS:
strarray
KEYWORD PARAMETERS:
sep : separator, default:' '
limit: string length limit (default 32767); longer strings will be put into a stringvector
OUTPUTS:
result: str-vector; combination of elements of the array separated by a separator
undefined array will return result=''
EXAMPLE:
result=arr2string(['A','BCD','DCB'],sep=':')
result:'A:BCD:DCB'
result=arr2string()
result:''
MODIFICATION HISTORY:
Written by Reimar Bauer, Franz Rohrer Aug 1998
Modified 10.03.2000 Franz Rohrer : limit string length to 32765
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\arr2string.pro)
NAME:
array2htmltable
PURPOSE:
This functions creates a table in html from an array of numbers or text
CATEGORY:
PROG_TOOLS/HTML
CALLING SEQUENCE:
Result = ARRAY2HTMLTABLE(Array)
INPUTS:
Array: array of numbers or text
KEYWORD PARAMETERS:
MAX_ARRAY: cuts the size of the output to max_array columns and rows
MAX_COLS: cuts the size of the output to max_cols columns
MAX_ROWS: cuts the size of the output to max_rows rows
BORDER: if this keyword is set a border will be produced for each
table entry
CAPTION: if this keyword is set to a string this will be printed
as a table caption
COL_NUMBERS: if this keyword is set a column number is printed
ROW_NUMBERS: if this keyword is set a row number is printed
COL_TITLES: if an array of column title is provided they will be printed
instead of numbers
ROW_TITLES: see COL_TITLES
CORNER_TITLE: if a string is provided it wil be set in the corner created
by row an col titles
ALIGNMENT: Specifies the alignment of the caption text. An alignment
of 0.0 (the default) aligns left, 1.0 right and 0.5 centered
parsed to tab_i
SMALL: use small fonts for table entries
FIXED: use fixed fonts for table entries
NOBREAK: no line breaks in table entries
OUTPUTS:
This function returns a string array containing html-code for table
which correponds to the content of an IDL array
EXAMPLE:
see also html_example.pro and html_example2.pro
print, array2htmltable([[11,12],[21,22]])
| 11 | 12 |
| 21 | 22 |
| 11 | 12 |
| 21 | 22 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\array2htmltable.pro)
NAME:
array2textable
PURPOSE:
This functions creates a table in tex from an array of numbers or text
CATEGORY:
PROG_TOOLS/TEX
CALLING SEQUENCE:
Result = array2textable(array,[vspace=vspace],[format=format],[/table],[/grid])
INPUTS:
Array: array of numbers or text
OPTIONAL INPUTS:
vspace: a string holding the vertical space behind the table
format: the formatcode for the whole table without {}
KEYWORD PARAMETERS:
table : \table will be included before \begin {tabular}
grid: \grid will give hor and vertical lines
OUTPUTS:
This function returns a string array containing tex-code for table
which correponds to the content of an IDL array
EXAMPLE:
test=sindgen(10,4)
f=array2textable(test,/table)
print,f
\begin{table}
\begin{tabular}{rrrrrrrrrr}
0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
10 & 11 & 12 & 13 & 14 & 15 & 16 & 17 & 18 & 19 \\
20 & 21 & 22 & 23 & 24 & 25 & 26 & 27 & 28 & 29 \\
30 & 31 & 32 & 33 & 34 & 35 & 36 & 37 & 38 & 39 \\
\end{tabular}
\end{table}
MODIFICATION HISTORY:
Written by: Reimar Bauer, 1998-Jun-29
1998-Jul-05 format added
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\array2textable.pro)
NAME:
ARRAY_LIST
PURPOSE:
List an array in a form useful to cut and paste.
CATEGORY:
CALLING SEQUENCE:
array_list, a
INPUTS:
a = array to list. in
KEYWORD PARAMETERS:
Keywords:
OUT=out Returned list in a text array.
FRONT=frnt Text to add to front (def=none).
Can space in and give a variable name: ' a = '
Use spaces, not tabs, to get correct line length.
INDENT=itxt Text string used to indent continued lines.
Default is 10 spaces.
/QUIET do not display list.
MAXLEN=mx Max length before line continue (def=72).
May be one longer for continued lines.
FORMAT=fmt Format for values (def=none).
/TRIM means trim leading and trailing 0s (and spaces).
Useful with FORMAT to get minimum strings.
TYPE=typ Name of data type function (def=none).
Will apply to array. Ex: uint([1,2,3])
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1999 Nov 30
Copyright (C) 1999, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\array_list.pro)
NAME:
ARRDELETE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Remove a portion of an existing array.
CALLING SEQUENCE:
NEWARR = ARRDELETE(INIT, [AT=POSITION,] [LENGTH=NELEM])
DESCRIPTION:
ARRDELETE will remove or excise a portion of an existing array,
INIT, and return it as NEWARR. The returned array will never be
larger than the initial array.
By using the keywords AT and LENGTH, which describe the position
and number of elements to be excised respectively, any segment of
interest can be removed. By default the first element is removed.
INPUTS:
INIT - the initial array, which will have a portion deleted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
KEYWORDS:
AT - a long integer indicating the position of the sub-array to be
deleted. If AT is non-negative, then the deleted portion
will be NEWARR[AT:AT+LENGTH-1]. If AT is negative, then it
represents an index counting from then *end* of INIT,
starting at -1L.
Default: 0L (deletion begins with first element).
LENGTH - a long integer indicating the number of elements to be
removed.
OVERWRITE - if set, then INIT will be overwritten in the process of
generating the new array. Upon return, INIT will be
undefined.
COUNT - upon return, the number of elements in the resulting array.
If all of INIT would have been deleted, then -1L is
returned and COUNT is set to zero.
EMPTY1 - if set, then INIT is assumed to be empty (i.e., to have
zero elements). The actual value passed as INIT is
ignored.
RETURNS:
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
SEE ALSO:
STORE_ARRAY in IDL Astronomy Library
MODIFICATION HISTORY:
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY1 keyword, CM 04 Mar 2000
$Id: arrdelete.pro,v 1.2 2001/03/25 18:10:41 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\arrdelete.pro)
NAME: ARREQ VERSION: 4.0 PURPOSE: Compares arrays for equality. The arrays qualify as equal if: 1) They are of the same general type (num., char., or struct.). 2) Number of dimensions is the same. 3) Size of each dimension is the same. 4) Respective elements are equal. CATEGORY: Mathematical Function (general). CALLING SEQUENCE: Result = ARREQ( ARR1, ARR2 [, keywords]) INPUTS: ARR1, ARR2 Arrays, type and number of dimensions arbitrary. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /WARN Switch. If set, a warning message is issued for incompatible data types. /NOVALUE Switch. If set, only number of elements and structure are compared. OUTPUTS: Returns 1 if the arrays are equal, 0 otherwise. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Uses the SIZE function and ISNUM from MIDL to obtain information about the arrays. Compares, in order, number of dimensions, size of each dimension, data types, and (unless NOVALUE is set) individual elements. MODIFICATION HISTORY: Created 15-JUL-1991 by Mati Meron. Modified 30-AUG-1998 by Mati Meron. Scope broadened to pointer arrays. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arreq.pro)
NAME:
ARREX (function)
PURPOSE:
This function extracts a multi-dimensional subset
of an array. For each dimension the start index,
end index (or count), and stride can be specified - default
values are 0 (i.e. first start index), "all" (i.e. last end
index), and 1 (i.e. every element). A negative stride
causes reversion of the respective array dimension.
CATEGORY:
Array Tools
CALLING SEQUENCE:
Result = ARREX( Array [, Startindex=] $
[, Endindex= | Count=] $
[, Stride=] $
[, /Reform] )
INPUTS:
ARRAY -> The parent array from which the extraction shall be made.
Currently up to 6 dimensions are supported.
KEYWORD PARAMETERS:
STARTINDEX -> An array with starting indices. Each element of
startindex corresponds to one dimension of ARRAY. If
startindex has less elements than ARRAY dimensions, the
remainder is assumed 0.
ENDINDEX -> An array with ending indices. Each element of
endindex corresponds to one dimension of ARRAY. If
endindex has less elements than ARRAY dimensions, the
remainder is set to the maximum possible value for that
dimension. Endindex cannot be use together with count.
COUNT -> An array with the number of elements to be extracted
along each dimension. Count values must be greater 0 and
are automatically adjusted so that startindex +
(count-1)*stride is a valid index for that
dimension. Count and Endindex cannot be used together.
STRIDE -> An array with stride values. A stride of 1 (default)
signifies extraction of every element, 2 returns every
second element for that dimension, etc. Negative values
cause the respective dimension to be reversed and are
only allowed when the count keyword is not used.
Each value of stride corresponds to one dimension of ARRAY.
If stride has less elements than ARRAY dimensions, the
remainder is assumed 1.
/REFORM -> Set this keyword to eliminate unnecessary dimensions
in the result.
OUTPUTS:
A subset of the original array. This will have the same
dimensionality as ARRAY unless the REFORM keyword is set.
SUBROUTINES:
Function arrex_ComputeInd
REQUIREMENTS:
Uses the reverse function from the IDL library
NOTES:
Created after discussion in newsgroup idl-pvwave.
EXAMPLE:
A = indgen(10,10)
print,arrex(A,[2,1],-1,[2,4])
; yields 12 14 16 18
; 52 54 56 58
; 92 94 96 98
print,arrex(A,[10,1],[1,10],[5,5])
; yields 19 15
; 69 65
; note that stride for dimension 1 is adjusted automatically.
MODIFICATION HISTORY:
mgs, 20 May 1999: VERSION 1.00
- with a lot of input from L. Gumley, S. Vidar, and
others
mgs, 15 Aug 2000: VERSION 2.00
- added DEBUG keyword and extended for up to 6
dimensions.
- changed from arguments to keywords.
- added count keyword to enhance usability together with
netcdf type access.
- changed error behaviour. Now stops instead of returning
the unchanged array.
- changed copyright notice to Open Source.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\arrex.pro)
NAME:
ARRINSERT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Insert one array into another
CALLING SEQUENCE:
NEWARR = ARRINSERT(INIT, INSERT, [AT=POSITION] )
DESCRIPTION:
ARRINSERT inserts the contents of one array (INSERT) into
another (INIT), and returns the new array (NEWARR).
ARRINSERT will handle empty lists, which are represented as
undefined variables. If both input arrays are empty, then the
scalar -1L is returned, and the keyword COUNT is set to 0L.
INPUTS:
INIT - the initial array, into which INSERT will be inserted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
INSERT - the array to be inserted into INIT, which must be of the
same or similar type to INIT. If INSERT is empty, then
INIT is returned unchanged. Regardless of the dimensions
of INSERT, it is treated as a one-dimensional array.
KEYWORDS:
AT - a long integer indicating the position of the newly inserted
sub-array. If AT is non-negative, then INSERT will appear
at NEWARR[AT]. If AT is negative, then INSERT will appear
at NEWARR[AT + (N+1)] where N is the number of elements in
INIT, which is to say if AT is negative, it indexes from the
end side of the array rather than the beginning.
Default: 0L (INSERT appears at beginning of INIT)
OVERWRITE - if set, then the initial array INIT will be
overwritten by the new array. Upon exit INIT becomes
undefined.
COUNT - upon return, the number of elements in the resulting
array.
EMPTY1, EMPTY2 - if set, then INIT (for EMPTY1) or INSERT (for
EMPTY2) are assumed to be empty (i.e., to have
zero elements). The actual values passed as INIT
or INSERT are then ignored.
RETURNS:
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
SEE ALSO:
ARRDELETE, STORE_ARRAY in IDL Astronomy Library
MODIFICATION HISTORY:
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY keywords, CM, 04 Mar 2000
Improved internal docs, and AT keyword docs, CM, 28 Sep 2000
Doc clarifications, CM, 29 Sep 2001
$Id: arrinsert.pro,v 1.3 2001/09/30 03:17:06 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\arrinsert.pro)
NAME: ARRLOC VERSION: 4.0 PURPOSE: Converts array indices from expanded (multi dimensional) form to contracted (one dimensional) form and vice versa. CATEGORY: Array Function. CALLING SEQUENCE: Result = ARRLOC( INDS, SIZ [, keywords]) INPUTS: INDS Numeric, converted to long integer on input. Structure depends on usage mode (EXPAND versus CONTRACT) and on the input parameter SIZ, as follows: EXPAND mode : INDS can be a scalar or a vector (1-dim array). CONTRACT mode: If SIZ(0) = 0 then INDS arbitrary. Else INDS can be a scalar, vector or a 2-dim array, subject to the following restrictions: INDS is scalar: SIZ(0) must be 1. INDS is vector: SIZ(0) must equal the length of INDS. INDS is M*N array: SIZ(0) must equal M (first array dimension). SIZ Vector in the form of the standard output of the system function SIZE. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /EXPAND Switch, specifies expansion mode. This is the default. /CONTRACT Switch, specifies contraction mode. OUTPUTS: Depending on mode, as follows: EXPAND mode: Returns an M*N array, where M is the number of dimensions of the object charactarized by SIZ (i.e. SIZ(0)) and N is the number of elements in INDS. For example, if S = [2,3,8,4,24] (corresponding to a 3*8 real array) then ARRLOC(5,S) will return the vector [2,1] (the indices of the 5th element) while ARRLOC([2,5,22]) will return: 2 0 2 1 1 7 CONTRACT mode: Reverses the action of expand. When fed an array in the form of the output of ARRLOC with EXPAND, returns a vector of 1-dimensional indices. For example a call to ARRLOC using S and the output array from the example above will return: 2 5 22 In either mode, if any of the resulting indices is out of bounds for the array specified by SIZ, it is replaced by -1. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None other than those specified in the description of INDS, above. PROCEDURE: Straightforward. Calls ONE_OF from MIDL. MODIFICATION HISTORY: Created 30-MARCH-1994 by Mati Meron. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arrloc.pro)
NAME: ARRO. VERSION: 4.0 PURPOSE: Draws an arrow in the current plot area, from the FROM to the TO location. DATA coordinates are used, unless one of the keywords /DEVICE or /NORMAL is set. CATEGORY: General Graphics. CALLING SEQUENCE: ARRO, FROM = tail, TO = head [, keywords] INPUTS: None. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: FROM Two dimensional vector, start location, mandatory. TO Two dimensional vector, end location, mandatory. SIZE Scalar, specifies size of head [and tail], default is 1. /TAIL Switch. Puts a tail on the arrow. /TWOSIDED Switch. Draws a twosided arrow (heads on both ends). /DEVICE Standard IDL plotting interpretation. /NORMAL Ditto. _EXTRA A formal keyword used to pass all plotting keywords. Not to be used directly. OUTPUTS: None. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: The keywords passed through _EXTRA are transferred to the PLOTS routine. No keyword verification is performed by ARRO. PROCEDURE: Uses DEFAULT, ONE_OF, SHAPE_COCON, SHAPE_TRANS and WHERINSTRUCT from MIDL. All the coordinates are converted to DEVICE coordinates for shape generation and plotting purposes. MODIFICATION HISTORY: Created 15-JUL-1991 by Mati Meron. Modified 15-DEC-1991 by Mati Meron. Added keywords COLOR and TWOSIDED. Modified 15-DEC-1993 by Mati Meron. Now ARROW takes advantage of the keyword inheritance property and accepts all IDL plotting keywords. Modified 5-OCT-1994 by Mati Meron. Name changed to ARRO to avoid conflicts with library routines. Modified 15-JUN-1995 by Mati Meron. Utilizes WHERINSTRUCT for improved keyword inheritance. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\arro.pro)
NAME:
ARROW
PURPOSE:
Draw arrows on screen.
CATEGORY:
CALLING SEQUENCE:
arrow, xt, yt, xh, yh
INPUTS:
xt, yt = x,y of arrow tail. in
xh, yh = x,y of arrow head. in
KEYWORD PARAMETERS:
Keywords:
/DATA means use data coordinates (def).
/NORM means use normalized coordinates.
/DEVICE means use device coordinates.
COLOR=c arrow outline color (def=255).
Make same as FILL for no outline.
THICK=t arrow outline thickness (def=0).
LINESTYLE=s arrow outline line style (def=0).
FILL=f set arrow fill color (0-255, def = -1 = no fill).
LENGTH=l Arrow head length in % plot width (def = 3).
WIDTH=w Arrow head width in % plot width (def = 2).
SHAFT=s Arrow shaft width in % plot width (def = 1).
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 21 Sep, 1990
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\arrow.pro)
NAME:
ARROW2
PURPOSE:
Draw arrows on screen.
CATEGORY:
CALLING SEQUENCE:
arrow2, xt, yt, xh, yh
INPUTS:
xt, yt = x,y of arrow tail. in
xh, yh = x,y of arrow head. in
KEYWORD PARAMETERS:
Keywords:
/DATA means use data coordinates (def).
/NORM means use normalized coordinates.
/DEVICE means use device coordinates.
COLOR=c arrow outline color (def=255).
Make same as FILL for no outline.
THICK=t arrow outline thickness (def=0).
LINESTYLE=s arrow outline line style (def=0).
FILL=f set arrow fill color (0-255, def = -1 = no fill).
LENGTH=l Arrow head length in % plot width (def = 3).
WIDTH=w Arrow head width in % plot width (def = 2).
SHAFT=s Arrow shaft width in % plot width (def = 1).
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 21 Sep, 1990
R. Sterner, 11 Nov, 1993 --- renamed from arrow.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\arrow2.pro)
NAME:
arr_equal
PURPOSE:
This function returns always an array with the founded multiple values
CATEGORY:
MATH
CALLING SEQUENCE:
Result=arr_equal(array,[/sort])
INPUTS:
array: the input array
KEYWORD PARAMETERS:
sort: sorts the array
OUTPUTS:
This function returns an array with the equal values
EXAMPLE:
a=['1','2','2']
print,arr_equal(a)
2
help,arr_equal(a) STRING = Array(1)
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), June 20, 1997
2000-Feb-18 help changed to call_help
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\arr_equal.pro)
NAME:
asc2ncdf
PURPOSE:
will translate ascii data with the icg-1 experimental header into netCDF Files
CATEGORY:
DATAFILES/FILTER
CALLING SEQUENCE:
asc2ncdf,inpath, outpath, filename, [data_sep=data_sep],[kritererium=kriterium],[inhalt=inhalt],[param_zeile=param_zeile]
INPUTS:
inpath: Path where the data is
outpath: Path where the netCDF File will be saved
filename: The filename of the ascii file which should be translated
OPTIONAL INPUTS:
data_sep: separator sign for the data
kriterium: will give the posibility whith an input listfile
to translate only logical parameters into netCDF
kriterium='trans.fish.t'
OPTIONAL OUTPUTS:
inhalt: the structure inhalt for the last parameter
param_zeile: the whole Array field of the Ascii File
PROCEDURE
Examples of the two kinds of headers will be found at:
http://ich313.ich.kfa-juelich.de/netcdf/icg1_header_datum.html
and
http://ich313.ich.kfa-juelich.de/netcdf/icg1_header_sekunden.html
EXAMPLE:
asc2ncdf,'/home1/icg105/data/','/home1/icg105/data/','test.dat'
MODIFICATION HISTORY:
Written by: R. Bauer , June, 13 , 1997
R.Bauer , Aug, 21 1997 data_sep added to choose column separator
R.Bauer,1997-9-16 debug added
R.Bauer 1998-08-29 ncdf_ws mehtod changed to ncdf_w
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\asc2ncdf.pro)
NAME: ascii2html PURPOSE: This functions creates html code for a given string array input CATEGORY: PROG_TOOLS/HTML CALLING SEQUENCE: Result = ASCII2HTML(string, [/SMALL] ,[/FIXED]) INPUTS: string: array KEYWORD PARAMETERS: SMALL: use small fonts for table entries FIXED: use fixed fonts for table entries OUTPUTS: String array EXAMPLE: see html_example.pro and html_example2.pro MODIFICATION HISTORY: Written by: Theo Brauers, 1998 Modified T.B. Apr 2000 caption keyword
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\ascii2html.pro)
usage: asd_mean, tag,wvl,spec,sigma,view=view
keyword input:
tag string used to match a certain subset of scan files listed
an index file, 'asd_scan_list', which is read from the current
working directory.
Each record in 'asd_scan_list' consists of three fields
separated by white space: the name of an asd scan file,
the utc time in hours, and the tag name, for example:
spectrum.001 15.003 scan1
spectrum.002 15.102 scan1
spectrum.003 15.233 scan2
spectrum.004 15.312 scan2
setting tag to 'scan1' whould select spectrum.001 and
spectrum.002, setting tag to ' ' or 'scan' would select
all four files. Since tag is compared to the whole record
you can also select a single file by setting tag to a
particular file name or time.
view make a plot of the scan
view=f makes an overplot with color=f*(!d.n_colors-1)
output:
wvl wavelength values
spec averaged spectra
sigma standard deviation of spectral scans (same size as spec)
example:
;;
w8x11
!p.multi=[0,2,2]
asd_mean,tag='60_NE',wvl,s60ne
asd_mean,tag='zenith',wvl,s0
asd_mean,tag='60_SW',wvl,s60sw
plot,wvl,s0
oplot,wvl,s60ne
oplot,wvl,s60sw
;; dont know tag name, use menu to find the one you want
asd_mean,wvl,s00
;;
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\asd_mean.pro)
NAME:
ASIND
PURPOSE:
Return the inverse sine of a value, in degrees rather then radians.
CALLING SEQUENCE:
deg = asind(x)
INPUTS:
value sine of angle
OPTIONAL INPUTS:
OUTPUTS:
Angle in degrees returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\asind.pro_)
NAME:
ASPECT
PURPOSE:
This function calculates and returns the normalized position
coordinates necessary to put a plot with a specified aspect ratio
into the currently active graphics window. It works on the display
output window as well as in a PostScript output window.
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:
position = ASPECT(aspectRatio)
INPUTS:
aspectRatio: A floating point value that is the desired aspect
ratio (ratio of heigth to width) of the plot in the current
graphics output window. If this parameter is missing, an aspect
ratio of 1.0 (a square plot) is assumed.
KEYWORD PARAMETERS:
MARGIN: The margin around the edges of the plot. The value must be
a floating point value between 0.0 and 0.5. It is expressed in
normalized coordinate units. The default margin is 0.15.
WINDOWASPECT: The aspect ratio of the target window. If not provided,
the value is obtained from the current graphics window.
OUTPUTS:
position: A four-element floating array of normalized coordinates.
The order of the elements is [x0, y0, x1, y1], similar to the
!P.POSITION system variable or the POSITION keyword on any IDL
graphic command.
EXAMPLE:
To create a plot with an aspect ratio of 1:2 and a margin of
0.10 around the edge of the output window, do this:
plotPosition = ASPECT(0.5, Margin=0.10)
PLOT, Findgen(11), POSITION=plotPosition
Notice this can be done in a single IDL command, like this:
PLOT, Findgen(11), POSITION=ASPECT(0.5, Margin=0.10)
MODIFICATION HISTORY:
Written by: David Fanning, November 1996.
Added better error checking, 18 Feb 1997, DWF.
Added WindowAspect keyword. 10 Feb 2000. DWF
Added double precision tolerance for aspectRatio. 9 NOV 2001 BT
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\aspect.pro)
NAME: ASP_CORR VERSION: 4.0 PURPOSE: Corrects the aspect ratio of a 2-dimensional shape, in order to make up for for different scaling in the x and y dimensions. CATEGORY: Array Manipulation /General Graphics. CALLING SEQUENCE: Result = ASP_CORR( SHAPE, REFERENCE = reflin) INPUTS: SHAPE (2,*) numeric array, mandatory. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: REFERENCE Defines the scaling procedure, according to the provided character value. Accepts one of the following six values (only the first two characters matter): 'XLO' : Scale x, keeping lowest x-value constant. 'XCEN': Scale x, keeping center x-value constant. 'XHI' : Scale x, keeping highest x-value constant. 'YLO' : Scale y, keeping lowest y-value constant. 'YCEN': Scale y, keeping center y-value constant. 'YHI' : Scale y, keeping highest y-value constant. OUTPUTS: 0 in case of failure (bad or missing shape or keyword value), otherwise the transformed shape is returned as a floating array (double if the input is of type double). OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: Three dimensional shapes aren't currently accepted. PROCEDURE: Uses calls to CAST, DEFAULT, SHAPE_VER and STRMATCH_MM from MIDL. The scaling is done using the sizes of the plotting area in device coordinates, provided by the system variables !d.x_vsize and !d.y_vsize. Therefore the scaling is always proper for the current output device. MODIFICATION HISTORY: Created 15-JUL-1991 by Mati Meron. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\asp_corr.pro)
ROUTINE: autorange
PURPOSE: given a range of values find a good tick mark interval
and return a properly formatted tick label. This routine
can be used with the axis procedure to add additional
axis which are not linearly related to the original
axis (see example)
USEAGE: autorange,range,ntick,tickv,tickl,ntickmax=ntickmax,$
cv=cv,log=log,colors=colors
INPUT:
range array of values
keyword input
ntickmax maximum allowed number of tick marks (default=10)
cv if present and non-zero, the tick values will cover a bit
less than the full range. Otherwise tick values cover a
bit more than the full range. Set CV when you want exactly
NTICK contour levels to appear on a contour plot.
OUTPUT:
ntick number of tick marks
tickv array of tick values
tickl formatted tick labels
KEYWORD OUTPUT
colors vector of color values covering full color range and having
one less element than ntick
; EXAMPLE:
autorange,[.011,.022],ntick,tickv,tickl & print,tickl
0.010 0.012 0.014 0.016 0.018 0.020
; plot solar spectrum with wavenumber on the lower x axis
; and wavelength on the upper x-axis
solar,wn,f
plot,wn,f,xstyle=5,xrange=[10000,40000],ymargin=[4,4]
axis,xaxis=0,xstyle=1,xtitle='Wavenumber (cm-1)'
autorange,1.e7/!x.crange,ntick,tickv,tickl
axis,xaxis=1,xticks=ntick-1,xtitle='Wavelength (nm)',$
xtickv=1.e7/tickv,xtickname=tickl
REVISIONS:
author: Paul Ricchiazzi mar94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\autorange.pro)
FUNCTION: This procedure computes the AVERAGE of a the nk
fields stored in the array tab (nbcol,nblign,nk).
INPUTS : tab --> 3 dimensional array (nbcol x nblign x nk)
OUTPUTS : moy --> average of the fields (nbcol x nblign)
stdv --> standard deviation (nbcol x nblign)
nb --> number of points used in the average
USE : vertaver, array1, array2, outaver,outstdc,outelmts
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\average.pro)
ROUTINE: axgap,pos
PURPOSE: draw a "gap symbol" to indicate a gap in the axis number scale.
USEAGE: axgap,pos
INPUT:
pos two element vector indicating x,y data coordinates of the
axis break
KEYWORD INPUT:
one gap symbol drawn on one axis only
size size of gap symbol (default = 1, which corresponds to size
of default minor tick marks)
skew control skewness of gap symbol (default 0)
gap controls gap size (default 1)
OUTPUT:
none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
y=smooth(randomn(iseed,100),5)
plot,y,xticks=5,xtickn=['1','2','3','4','5','20']
axgap
AUTHOR: Paul Ricchiazzi 31 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\axgap.pro)
NAME: axis_2c PURPOSE: This procedure plots an axis and its title in different colors CATEGORY: PLOT CALLING SEQUENCE: axis_2c [[[, x], y], z] OPTIONAL INPUTS: x, y, z: Scalars giving the starting coordinates of the new axis. For details see the IDL AXIS routine. KEYWORD PARAMETERS: AXIS_TITLE = axis_title: Title of the axis COLOR = color: Color of the axis. TCOLOR = tcolor: Color of the title. Any other keyword parameters which are accepted by the IDL AXIS procedure. EXAMPLE: def_color_sysv PLOT, EXP(FINDGEN(10)), /YLOG axis_2c, YAXIS = 0, TCOLOR = !F.red, AXIS_TITLE = 'Y title' axis_2c, XAXIS = 0, TCOLOR = !F.green, AXIS_TITLE = 'X title' MODIFICATION HISTORY: Written by: Frank Holland, 27.10.1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\axis_2c.pro)
NAME:
AXLABEL
PURPOSE:
Put previously calculated axis labels onto the screen
at proper position. This routine was designed to work
together with LOGLEVELS to produce fancy log plots.
It involves several coordinate transformations in order
to be device independent and take into account the
character size. The user can specify a label format
and use 'external' formatting functions similar to
the [XYZ]TICKFORMAT keyword of PLOT.
CATEGORY:
General Graphics
CALLING SEQUENCE:
AXLABEL,Value [,/XAxis] [,keywords]
INPUTS:
VALUE -> A vector with the values to be labelled on the
axis.
KEYWORD PARAMETERS:
/XAxis -> If set, the labels are placed on the X achis
rather than on the Y axis
/YAxis -> Place the labels on the Y axis (this is the default,
and this keyword is there for purely aesthetic reasons)
CHARSIZE -> The character size of the label
FORMAT -> An IDL format string (used as argument to the
STRING function) or the name of a function that returns
formatted labels. This function must accept three
arguments, the third of which is the current value
(see the online help to [XYZ]TICKFORMAT for more details).
AXLABEL always passes 0 to the first two arguments.
_EXTRA keywords are passed on to XYOUTS (e.g. COLOR or
ORIENTATION). Note that the ALIGN keyword value is
determined automatically.
OUTPUTS:
Axis labels without fuss.
SUBROUTINES:
None.
REQUIREMENTS:
A DATA coordinate system must be established by a previous
PLOT command.
NOTES:
AXLABEL currently operates only on the left and bottom axes.
EXAMPLE:
xrange = [0.3,3.0] ; define axis range
yrange = [0.3,3.0]
plot,[1],xr=xrange,yr=yrange, $ ; do the plot
title='Logarithmic X axis, Logarithmic Y axis',$
xtickf='(a1)',ytickf='(a1)', /ylog,/xlog
; important: turn the tick labeling off with ?tickformat='(A1)'
xlblv = loglevels(xrange) ; get nice label values (0.5, 1., 2.)
ylblv = loglevels(yrange)
axlabel,xlblv, /xaxis ; plot the labels
axlabel,ylblv, /yaxis
MODIFICATION HISTORY:
mgs, 10 Sep 1999: VERSION 1.00
mgs, 23 Sep 1999: - bug fix for log-log plots
mgs, 23 Aug 2000: - changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\axlabel.pro)
NAME:
AXVAL
PURPOSE:
Find nice axis values.
CATEGORY:
CALLING SEQUENCE:
v = axval(x1,x2,n)
INPUTS:
x1 = Range minimum. in
x2 = Range maximum. in
n = Suggested number of divisions (def=5). in
KEYWORD PARAMETERS:
OUTPUTS:
v = array of labeled tick positions. out
COMMON BLOCKS:
NOTES:
Notes: Useful when exact axis and number of ticks
are both specified. For this case IDL forces
labeled ticks to start and end at the axis ends,
which in general gives poor tick spacing.
MODIFICATION HISTORY:
R. Sterner, 1994 Feb 8
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\axval.pro)
ROUTINE: azimuth
PURPOSE: given a smoothly varying 2d field, AZIMUTH
computes the angle between the gradient direction
of the field and the y direction (angle measured
clockwise). This is is useful for computing the
satellite or solar azimuth angle when all you know
are the satellite or solar zenith angles. For
example the relative azimuth at each point in a
satellite image is given by
relaz=abs(azimuth(satzen,1,1)-azimuth(-sunzen,1,1))
which is the angle between the satellite unit
vector and the solar ray vector, both projected
onto the surface.
CALLING SEQUENCE:
result=azimuth(image,dx,dy)
INPUT:
image smoothly varying image quantity (e.g., solar zenith angle)
dx pixel spacing, x direction
dy pixel spacing, y direction
OUTPUT:
result angle between grad(image) and downward direction
(angle increases clockwise)
LIMITATION: the image is fit by a quadratic function of x and y
which is analytically differentiated to find the
gradient directions. An image which is not well
approximated by a quadratic function may produce
weird results.
EXAMPLE:
f=cmplxgen(400,400,/center)
tvim,f,/scale
f=abs(f)^2 ; should be perfectly fit by a quadratic function
a=azimuth(f,1,1)
loadct,5
tvim,a,scale=2,range=[-180,180,45]
author: Paul Ricchiazzi apr94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\azimuth.pro)
NAME: a_and_b PURPOSE: This function applies the boolean AND operator to two vectors. It returns a vector with those elements which occur in both vectors. CATEGORY: MATH CALLING SEQUENCE: Result = a_and_b(vec1, vec2) INPUTS: vec1, vec2: The two vectors to which the AND operation should be applied. KEYWORD PARAMETERS: /NO_SORT: If set the returned vector is not sorted. However, in that case multiple instances of single elements in the shorter of the two input vectors will show up in the output vector. OUTPUTS: This function returns a vector with those elements which occur in both input vectors. In the case of an empty output vector, -1 is returned. The elements are sorted in increasing order. RESTRICTIONS: Repeated elements in the input vectors are returned only once in the output vector (see example). EXAMPLE: A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20] B = [0, 2, 2, 4, 6, 10, 12, 13] C = a_and_b(A, B) = [2, 4, 6, 13] MODIFICATION HISTORY: Written by: Frank Holland, 02.12.97 History: 29.10.98: FOR i = 0, ... changed to FOR i = 0L, ... debug statement removed 25.02.2000: New keyword parameter /NO_SORT
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_and_b.pro)
NAME: a_not_b PURPOSE: This function applies the negation of the boolean AND operator to two vectors. It returns a vector with those elements which occur in the first but not in the second vector. CATEGORY: MATH CALLING SEQUENCE: Result = a_not_b(vec1, vec2) INPUTS: vec1, vec2: The two vectors to which the negation of the AND operation should be applied. OUTPUTS: It returns a vector with those elements which occur in the first but not in the second vector. In the case of an empty output vector, -1 is returned. RESTRICTIONS: Repeated elements in the input vectors are returned only once in the output vector (see example). EXAMPLE: A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20] B = [0, 2, 2, 4, 6, 10, 12, 13] C = a_not_b(A, B) = [1, 3, 7, 8, 9, 14, 20] MODIFICATION HISTORY: Written by: Frank Holland, 02.12.97 History: 29.10.98: FOR i = 0, ... changed to FOR i = 0L, ... debug statement removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_not_b.pro)
NAME: a_or_b PURPOSE: This function applies the boolean OR operator to two vectors. It returns a vector with those elements which occur in one or the other vector. CATEGORY: MATH CALLING SEQUENCE: Result = a_or_b(vec1, vec2) INPUTS: vec1, vec2: The two vectors to which the OR operation should be applied. OUTPUTS: It returns a vector with those elements which occur in one or the other vector. In the case of an empty output vector, -1 is returned. RESTRICTIONS: Repeated elements in the input vectors are returned only once in the output vector (see example). EXAMPLE: A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20] B = [0, 2, 2, 4, 6, 10, 12, 13] C = a_or_b(A, B) = [0, 1, 2, 3, 2, 6, 7, 8, 9, 10, 12, 13, 14, 20] MODIFICATION HISTORY: Written by: Frank Holland, 02.12.97 History: 29.10.98: debug statement removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_or_b.pro)
NAME: a_xor_b PURPOSE: This function applies the boolean XOR operator to two vectors. It returns a vector with those elements which occur in one or the other vector but not in both. CATEGORY: MATH CALLING SEQUENCE: Result = a_xor_b(vec1, vec2) INPUTS: vec1, vec2: The two vectors to which the XOR operation should be applied. OUTPUTS: It returns a vector with those elements which occur in one or the other vector but not in both. In the case of an empty output vector, -1 is returned. RESTRICTIONS: Repeated elements in the input vectors are returned only once in the output vector (see example). EXAMPLE: A = [1, 2, 2, 2, 3, 4, 13, 6, 7, 8, 9, 14, 20] B = [0, 2, 2, 4, 6, 10, 12, 13] C = a_xor_b(A, B) = [0, 1, 3, 7, 8, 9, 10, 12, 14, 20] MODIFICATION HISTORY: Written by: Frank Holland, 02.12.97 History: 29.10.98: debug statement removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\a_xor_b.pro)
ROUTINE: balloon_drag
PURPOSE: compute drag on shere
USEAGE: result=balloon_drag(r,rho,v,cd)
KEYWORD INPUT:
r balloon radius in meters (default=1.0 m)
v wind velocity (mph) (default=5 m/s)
rho air density (default=1.29 kg/m3)
cd drag coefficient (default=0.2)
NOTE: 1 m/s = 3.60 km/hr = 2.23 mph = 1.94 knots
OUTPUT:
result drag force in newtons
SOURCE: Steve Robinson
NASA/MIT
stever@space.mit.edu
Drag on sphere = .5 * Cd * rho * v^2 * pi * r^2
Cd = function of sphere Reynolds number
(V*2*r)/(kinematic viscosity),
but 0.2 should be close.
EXAMPLE:
r=1. & v=10. & cd=.2
rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
print,balloon_drag(r,rho,v,cd)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\balloon_drag.pro)
ROUTINE: balloon_lift
PURPOSE: compute and print lifting capacity of a helium balloon in kg
USEAGE: balloon_lift,r=r,volume=volume,alt=alt,pres=pres,temp=temp,lr=lr
KEYWORD INPUT:
r balloon radius in meters (default=1.0 m)
volume ignor r and use this value for volume (default=4.18 m3)
alt altitude in km (default=1 km)
pres pressure in mb (default=1013 mb)
temp surface temperature in K (default=273 K)
brho balloon mass density (kg/m2) (default=0.35 kg/m2)
bwt balloon weight (kg) (default=10 kg)
trho tether mass density (kg/km) (default=6.25 kg/km, dacron)
kevlar if set use kevlar tether at 2.1kg/kg
rubberized polyvinyl 0.35 kg/m2
for dacron, 2.4 mm diam, trho=6.25kg/km, 260 lb pull
for kevlar, 1.5 mm diam, trho=2.1kg/km, 750 lb pull
english if set all the above inputs are
in units of feet or pounds (pounds/sq in for pressure)
EXAMPLE: lifting capacity of a 1 m radius helium balloon at an
altitude of 1 km.
rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
print,balloon_lift(1.,rho)
EXAMPLE: lifting capacity of a non-stretching 1 m radius helium
balloon at an altitude of 1 km. To prevent the balloon
from bursting at high altitude the balloon should not be
filled to full capacity with helium at sealevel. Assume
the helium retains its sealevel temperature (maybe less
than ambient).
balloon_lift,r=1,alt=1
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\balloon_lift.pro)
NAME:
BARGRAPH
PURPOSE:
Creates a bar graph from a vector of data points
CATEGORY:
2D Graphics
CALLING SEQUENCE:
BARGRAPH, DATA, BASELINE [,keywords]
INPUTS
DATA -> Vector of data points to be plotted as a bargraph
BASELINE -> Vector of points to be used as a baseline for DATA
(i.e. Y(I) = DATA(I) + BASELINE(I)). If BASELINE
is not specified, its default value will be an
array of zeroes.
KEYWORD PARAMETERS:
OVERPLOT -> /OVERPLOT will not cause the current plot window
to be erased. This is useful for producing
stacked bar plots with successive calls to BARGRAPH.
BARWIDTH -> The width of the bars. If BARWIDTH is not
specified, its default value will be 1.0.
BARCOLOR -> a value or an array containing the colorindex for
all boxes or each box, respectively. If a single value
is given, *all* boxes will have this color. If an array
is passed that has less elements than there are groups to
plot, the remaining colors will be filled with 15 (grey
in MYCT standard-scheme).
BARLABELS -> A string array of labels to be plotted above each
bar. If BARLEVELS may be originally set equal to the
DATA vector, and it will be converted to the string
representation of DATA, using the FORMAT statement
contained in L_FORMAT.
COLOR -> Color index for the plot axes and labels. Default
is 1 (which is BLACK for a MYCT color table).
L_FORMAT -> The FORMAT statement used to convert BARLABELS
from a numeric array to a string array.
NO_LABELS -> /NO_LABELS will suppress printing the labels
contained in the BARLABELS atop each bar. This is
useful for producing stacked bar plots.
XLABELS -> X-axis labels corresponding to each bar.
YRANGE -> YRANGE keyword for the PLOT command. If YRANGE is
not specified then YRANGE will be computed based on the
maximum value of the DATA array. For stacked plots, it
is useful to compute YRANGE in the calling program and
pass it to BARGRAPH.
_EXTRA=e -> Passes extra keywords to plot
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
(1) This routine has been modified to be more general and
more robust than the original version in the IDL 5.0 User's
Guide (p. 170).
(2) IDL 5.x array notation [] is now used.
EXAMPLE:
(1) Create a simple bar graph with bars of 3 different colors,
using a baseline of zero.
BARGRAPH, Data=[1,2,3], BarWidth=1.0, BarColor=[10,11,12]
XLabels=['Bart', 'Lisa', 'Maggie']
(2) Use successive calls to BARGRAPH to create a "stacked" bar
graph with two different data vectors. The first vector is
used as the baseline for the second. The BARLABELS array
is created from the actual data values.
Data = [2,3.5,6,7,2,1]
Data2 = 0.0*DATA + 2
BARGRAPH, Data, Xlabels=['A','B','C','D','E','F'],
XStyle=1, BarWidth=0.8
BARGRAPH, Data2, Data, BarWidth=0.8 ,/OverPlot, $
BarColor=2, BarLabels=Data+Data2, L_Format='(F8.2)'
MODIFICATION HISTORY:
bmy, 18 Nov 1997: VERSION 1.00
bmy, 19 Nov 1997: VERSION 1.01
bmy, 29 Apr 1999: VERSION 1.10
- added COLOR keyword
- eliminated help screen
- enhanced readability & updated comments
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\bargraph.pro)
ROUTINE: barplot
PURPOSE: produce a bar plot
USEAGE: barplot
INPUT:
y bar values fltarr(n)
KEYWORD INPUT:
nbar number of barplot overlays. Should only be set on the first
call to BARPLOT
over if set, overplot new bar values.
dx width of a bar (default=1). An individual bar is sized to
fill a fraction .5*DX/nn of the total plot width, where nn
is the number of elements in y. Setting DX=2 eliminates
blank space between adjacent bars.
xinc How far to move overplot bars to the left or right of the
previous bar position (in units of the bar width). Use
with NBAR and XOFF to control degree to which overplot
bars overlap previous bars. A positive value causes latter
overplots to overlap bars starting from the left and
finishing on the right. A negative value does the
opposite. (default = 0.6666)
xoff offset of bar with respect to labeled points on x-axis
(default=0). XOFF should be in the argument list and assigned
to a named variable if NBAR, DX and XINC are used to control
bar overlap in multiplots.
The xaxis labels are located at data coordinates
xlab=findgen(nn)+.5, where nn =n_elements(y)
color color index used to fill bars
xtitle string, x title of plot
ytitle string, y title of plot
title string, title of plot
xlabels vector of strings used to label bar groups
xlabvec vector of x values at which to put XLABELS.
if XLABVEC is not set, XLABELS are ploted at points
.5+findgen(n_elements(xlabels))
range of XLABVEC 0-1
grid if set, draw a y axis grid. The numerical value of grid
is used to set the grid style (1=dotted line)
yrange a two element vector specifying the y axis range
ynozero if set, y range may not include zero if all y values are
are positive.
xmargin two element vector specifies left and right margin around plot
frame in units of character width. (default = !x.margin)
ymargin two element vector specifies bottom and top margin around plot
frame in units of character height. (default = !y.margin)
OUTPUT:
DISCUSSION:
For best results try to arrange the order of overplots so that larger
values of y are ploted first. See examples.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
loadct,5
y=randomu(iseed,6)
color=[.8,.6,.3]*!d.n_colors
dx=.6
barplot,y,dx=dx,xlabels=1990+indgen(6),title='test',xtitle='Year',$
ytitle='power (Watts)',color=color(0),/grid,xoff=xoff,nbar=3
barplot,y^2,dx=dx,color=color(1),/over,xoff=xoff
barplot,y^3,dx=dx,color=color(2),/over,xoff=xoff
; A fancier example
y=randomu(iseed,5) & y=y(sort(y))
xlabels=['January','February','March','April','May']
color=[.2,.4,.6,.8]*!d.n_colors
dx=.32
barplot,y,dx=dx,xtitle='---- Month ----',$
ytitle='power (Watts)',color=color(3),yrange=[0,1.],ymargin=[5,7],$
/grid,xlabels=xlabels,charsize=1.5 ,xoff=xoff,nbar=4
barplot,y^2,dx=dx,color=color(2),/over, xoff=xoff
barplot,y^3,dx=dx,color=color(1),/over, xoff=xoff
barplot,y^4,dx=dx,color=color(0),/over, xoff=xoff
x_axis,findgen(5)+.5,1.,xtickn=(y+y^2+y^3+y^4)/4,yspace=-1.5,$
xtitle='----- Cumulative Average -----'
x_axis,findgen(5)+.5,[1,4],xtitle='Plot Title',yspace=-.5,charsize=1.2,/ext
legend,'.cSensor\\AVHRR 1\AVHRR 2\GTR-200\PSP',color=color,$
/clrbox,bg=0,/box,pos=[0.06,0.57,0.23,0.98]
; use with histogram to make nicer histogram plots
y=randomn(iseed,2000)
yy=histogram(y,binsize=.5,min=-3)
yy=yy(0:11)
xlabel=string(f='(f3.0)',findrng(-3,3,12))
;plot,findrng(-3,3,12),yy,/xsty,psym=10 ; compare to this
barplot,yy,dx=2,color=20,xlabel=['-3','-2','-1','0','1','2','3']
AUTHOR: Paul Ricchiazzi 31 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\barplot.pro)
NAME:
BASECON
PURPOSE:
Convert a number from one base to another.
CATEGORY:
CALLING SEQUENCE:
out = basecon(in)
INPUTS:
in = input number as a text string. in
KEYWORD PARAMETERS:
Keywords:
FROM=n1 Original number base (def=10).
From 2 to 36.
TO=n2 Resulting number base (def=10).
From 2 to 36.
DIGITS=n Minimum number of digits in output.
If result has fewer then 0s are placed on left.
GROUP=g Number of digits to group together (def=all).
Spaces will be placed between groups. Useful for
showing bytes or words for example.
ERROR=err error flag:
0 = ok
1 = input digit not 0-9 or A-Z.
2 = FROM base not in the range 2-36.
3 = TO base not in the range 2-36.
4 = input digit too big for FROM base.
5 = input number too big to handle.
OUTPUTS:
out = converted number as a text string. out
If an error occurs a null string is returned.
COMMON BLOCKS:
NOTES:
Notes: maximum number base is 36. Example:
out = basecon('1010',from=2,to=16) gives out='A'.
May give an array of input values.
MODIFICATION HISTORY:
R. Sterner, 5 Mar, 1993
R. Sterner, 30 Sep, 1993 --- Added DIGITS keyword.
R. Sterner, 1999 Jun 3 --- Added GROUP keyword.
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\basecon.pro)
NAME:
bc
PURPOSE:
wall to wall cross hairs to help read numbers off of plot
axis. The graphics function is set to 6 for eXclusive OR.
This allows the cross hairs to be drawn and erased without
disturbing the contents of the window. Hit RMB to exit
CALLING SEQUENCE:
bc
INPUTS/OUTPUTS: none
RESTRICTIONS:
Works only with window system drivers.
CATEGORY:
Interactive graphics.
author Paul Ricchiazzi April, 1993
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\bc.pro)
NAME:
BELL
PURPOSE:
Ring terminal bell.
CATEGORY:
CALLING SEQUENCE:
bell, [n]
INPUTS:
n = number of rings (def=1). in
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 20 Oct, 1989.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\bell.pro)
NAME: BESELK_MM VERSION: 4.0 PURPOSE: Calculates an approximation to Bessel K functions or their integrals. CATEGORY: Mathemetical Function (General). CALLING SEQUENCE: Result = BESELK_MM (X, NI [, /INTEGRAL ]) INPUTS: X Numerical, otherwise arbitrary. NI Scalar, the order of the function. OPTIONAL INPUT PARAMETERS: EPS Allowed relative error. Default is machine precision. KEYWORD PARAMETERS: /INTEGRAL Switch, if set the integral of the K function from X to infinity is calculated. OUTPUTS: Returns the value(s) of K_ni(X) or, if INTEGRAL is set, of the integral of K_ni(t) from X to infinity. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Uses the Kostroun approximation, see NIM 172, 371-374 (1980). Calls CAST, DEFAULT, FPU_FIX, ISNUM and TOLER from MIDL. MODIFICATION HISTORY: Created 1-MARCH-1993 by Mati Meron as BESELK. Modified 15-SEP-1998 by Mati Meron. Underflow filtering added. Renamed 25-SEP-1999 by Mati Meron, to BESELK_MM. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\beselk_mm.pro)
NAME:
BEST_FFT
PURPOSE:
Attempts to find size of fastest FFT from given choices.
CATEGORY:
CALLING SEQUENCE:
m = best_fft(n)
INPUTS:
n = proposed FFT size. in
KEYWORD PARAMETERS:
Keywords:
DELTA=d The range to search in samples or percent.
Default = +/-1.
/PERCENT means DELTA is in percent of n.
/DOWN Search from n down to n-DELTA.
OUTPUTS:
m = Predicted fastest FFT size within range. out
COMMON BLOCKS:
NOTES:
Notes: the selection is made based on the prime factors
of the possible values. The largest prime factor of
each candidate is determined and the value with the
smallest max prime factor is considered the best to use.
For multiple matches the one with the smallest sum
of the prime factors is selected.
MODIFICATION HISTORY:
R. Sterner, 8 Feb, 1993
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\best_fft.pro)
NAME:
binary (function)
PURPOSE:
This function returns the binary representation
of a number. Numbers are converted to LONG integers
if necessary.
CATEGORY:
General Programming
EXAMPLE:
Binary representation of 11B:
IDL> print, binary(11B)
0 0 0 0 1 0 1 1
If data extraction is used instead of conversion ->
Binary representation of pi (little endian IEEE representation):
IDL> print, format='(z9.8,5x,4(1x,8a1))', long(!pi,0), binary(!pi)
40490fdb 01000000 01001001 00001111 11011011
AUTHOR:
Kevin Ivory Tel: +49 5556 979 434
Max-Planck-Institut fuer Aeronomie Fax: +49 5556 979 240
Max-Planck-Str. 2 mailto:Kevin.Ivory@linmpi.mpg.de
D-37191 Katlenburg-Lindau, GERMANY
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\binary.pro)
NAME:
BINBOUND
PURPOSE:
For binary image return array with boundary points set to 1.
CATEGORY:
CALLING SEQUENCE:
b = binbound(bin_image)
INPUTS:
bin_image = byte binary image (only 0 or 1). in
KEYWORD PARAMETERS:
OUTPUTS:
b = array with boundary points set to 1. out
COMMON BLOCKS:
NOTES:
Notes: The boundary of a binary image is the set of points
in the image that are 1 and also touch a 0.
A binary image may be made using logical operators.
For example, if an image has both positive and negative
values the boundary between them may be found as
b = binbound(img gt 0). To put this boundary into
another image, A, do:
w = where(b eq 1) & a(w) = 255.
MODIFICATION HISTORY:
R. Sterner. 24 June, 1987.
R. Sterner, 4 Dec, 1989 --- Converted to Sun.
R. Sterner, 21 Nov, 1991 --- removed a multiply.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1987, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\binbound.pro)
NAME:
bin_data
PURPOSE:
This function returns the density function (histogram) of an array
together with the lower bound values of the single bins.
CATEGORY:
MATH
CALLING SEQUENCE:
Result = bin_data(Array)
INPUTS:
Array: Data for which the density function will be calculated.
OPTIONAL INPUTS:
B_WIDTH = bw: Set the bin width of the density function. (Default = 1)
B_MIN = bmin: Set the lower bound of the first bin. (Default = MIN(array))
B_MAX = bmax: Maximum value to consider. (Default = MAX(array))
see also IDL HISTOGRAM Function
KEYWORD PARAMETERS:
/PLOT: Set this keyword to display a plot of the histogram.
OUTPUTS:
The return value of this funktion is a structure of arrays where the
array dimension n is equal to the number of bins in the density function:
result.bin : Array with lower bound values of the single bins.
result.freq : Array with frequency of occurrence.
result.bin_width: Bin width used to calculate the frequency distribution (scalar).
In the case that B_MIN > MAX(array) the number -1 is returned.
OPTIONAL OUTPUTS:
REV_INDEX = ri: Set this keyword to a named variable to return the
reverse index vector of the density function.
ERROR = err: Set this keyword to a named variable to return the
error status of the routine (err = 0: no error; otherwise: err = 1).
EXAMPLE:
A = [0.5, 1.5, 1.6, 2.0, 2.3, 2.5, 2.7, 2.9, 3.2, 5.1, 5.6, 5.7, 6.0]
Result = bin_data(A, B_WIDTH = 2.0, B_MIN = 0.0, /PLOT)
- The histogram should be plotted
- HELP, result, /STR
** Structure <5a844c8>, 3 tags, length=36, refs=1:
BIN FLOAT Array[4]
FREQ LONG Array[4]
BIN_WIDTH FLOAT 2.00000
- PRINT, Result.bin :
0.000000 2.00000 4.00000 6.00000 - lower bound of bins
- PRINT, Result.freq :
3 6 3 1 - frequency of occurrence
MODIFICATION HISTORY:
Written by: F. Holland (ICG-3), 22.09.97.
Revised: F. Holland, 01.06.99.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\bin_data.pro)
NAME:
bin_stat
PURPOSE:
This function returns the statistics of a binned data set where the
partitition of the data set into the different bins is determined by the
reverse index vector of a preceding call to the IDL HISTOGRAM function.
CATEGORY:
MATH
CALLING SEQUENCE:
Result = BIN_STAT(Array, Riv, Nobs)
INPUTS:
Array: Data for which the statistical parameters should be calculated.
Riv: Reverse Index Vektor from the Functions BIN_DATA or HISTOGRAM
Nobs: Number of bins which correspond to the Riv.
OUTPUTS:
The return value of this funktion is a structure of arrays where the
array dimension n is equal to the number of bins in the density function.
For each bin the statistical parameters mean, stdev, sterr, n, and
median are returned (tag names: mean, stdev, sterr, n, median).
If a quantity is not defined (e.g. stdev for only one point in the bin),
the value !VALUES.F_NAN is returned.
EXAMPLE:
A = [0.5, 1.3, 1.5, 1.6, 2.0, 2.5, 2.9, 3.2, 5.1, 5.6, 5.7, 6.0]
B = [3.1, 2.0, 4.1, 8.2, 1.0, 0.0, 2.2, 5.3, 5.5, 0.7, 7.8, 5.1]
Result = bin_data(A, B_WIDTH = 2.0, B_MIN = 0.0, REV_INDEX = Riv)
nobs = N_ELEMENTS(Result.bin(*))
stat = bin_stat(B, Riv, Nobs)
HELP, stat, /STR
** Structure <1855a28>, 7 tags, length=112, refs=1:
MEAN FLOAT Array[4]
STDEV FLOAT Array[4]
STERR FLOAT Array[4]
N LONG Array[4]
MEDIAN FLOAT Array[4]
MIN FLOAT Array[4]
MAX FLOAT Array[4]
PRINT, stat.mean
4.35000 2.12500 4.66667 5.10000
PRINT, stat.stdev
2.70617 2.29982 3.62261 NAN
PRINT, stat.n
4 4 3 1
PRINT, stat.min
2.00000 0.000000 0.700000 5.10000
MODIFICATION HISTORY:
Written: F. Holland (ICG-3), 22.09.97.
Revised: F. Holland (ICG-3), 01.06.99.
14.06.1999: Function returns now also min and max of dataset.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\bin_stat.pro)
NAME:
BLEND
PURPOSE:
Sets up weighting array for blending arrays together.
CATEGORY:
CALLING SEQUENCE:
WT = BLEND(N,I1,I2)
INPUTS:
N = size of array to make. in
I1, I2 = indices of first and last values to blend. in
KEYWORD PARAMETERS:
OUTPUTS:
WT = weighting array. out
WT(0:I1) = 0
WT(I1:I2) = cosine shaped weighting from 0 to 1.
WT(I2:*) = 1
COMMON BLOCKS:
NOTES:
Notes: to blend arrays A and B: A*(1-WT) + B*WT
starts with pure A and ends with pure B.
MODIFICATION HISTORY:
Written by R. Sterner 6 Jan, 1986.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\blend.pro)
NAME:
bmp_definitions
PURPOSE:
This function returns the widget_button symbol array
CATEGORY:
PLOT
CALLING SEQUENCE:
Result=bmp_definitions(name)
EXAMPLE:
result=bmp_definitions('play')
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999, June 11
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\bmp_definitions.pro)
NAME:
bootstrap_mpfitfun
PURPOSE:
This function does a bootstrap simulation of a (non-linear) fit of
a given function to a set of data using the mpfitfun function
(MPFIT, MPFITFUN were provided by Craig Markwardt)
CATEGORY:
MATH
CALLING SEQUENCE:
Result = BOOTSTRAP_MPFITFUN(MYFUNCT, X, Y, ERR, start_params, ...)
INPUTS:
(text copied from from mpfitfun)
MYFUNCT - a string variable containing the name of an IDL function.
This function computes the "model" Y values given the
X values and model parameters. It should be declared in
the following way:
FUNCTION MYFUNCT, X, parms, dparms
; X are the independent variable values
; parms are the parameter values
; dparms - analytical derivative matrix - NOT REQUIRED
YMOD = ...
IF N_PARAMS() EQ 3 THEN $
DPARMS = ... ;; compute derivatives - NOT REQUIRED
RETURN, YMOD
END
The returned array YMOD should be of the same size and
dimensions as the "measured" Y values.
See the discussion of AUTODERIVATIVE and MYFUNCT in
MPFIT.PRO if you wish to compute your derivatives for
yourself. AUTODERIVATIVE is accepted by MPFITFUN and
passed directly to MPFIT.
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function MYFUNCT should map
X->Y.
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Y. ERR is ignored if the WEIGHTS
keyword is specified.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
OUTPUTS:
Returns a structure array containing the best-fit parameters of
each bootstrap replication.
KEYWORD PARAMETERS:
all input keyword parameters of MPFITFUN are parsed via _EXTRA
NBOOTSTRAP: number of bootstrap replications (def =10)
VERBOSE: if set a message is printed before any call of mpfit
KEEP_INITIAL: start every new call of mpfit with the same set
of starting values (def: use the result of the
last fit, which is normally faster)
DESCRIPTION:
The description of MPFITFUN is given in the header of these functions.
Basically BOOTSTRAP_MPFITFUN repeatatively calls MPFITFUN using a
bootstrap resanpled input data set and fit a user-supplied model to
easch set of the user-supplied data.
The idea of bootstrap is to evaluate errors of the estimated parameters
when the erros of y are not know precisely or when the model which
is fitted does not represent a full description of the dependence
of y on x. A discussion of bootstrap estimates is givern in the
references (see below)
EXAMPLE:
(text modified from from mpfitfun)
FUNCTION gauss2, x, p & RETURN, gauss1(x,p[0:2])+p[3] & END
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000. ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
p0 = [1.D, 1., 1000., 1234.] ; Initial guess
r = bootstrap_mpfitfun('GAUSS2', x, y, sy, p0, NBOOT = 50)
; Fit and replicate 50 times
HELP, /STR, r
; compare all
PLOT, x, y, PSYM=1
FOR i=1,50 DO OPLOT, x, GAUSS2(x,r[i].p), COLOR=2
OPLOT, x, GAUSS2(x,r[0].p), COLOR=3
FOR i=0,3 DO PRINT, r[0].perror[i], STDDEV(r[1:*].p[i])
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data (with different starting parameters) to see how close we can
get.
REFERENCES:
For details on bootstrap methods see:
A.C.Davison and D.V.Hinkley
Bootstrap methods and their applications
Cambridge series in statistical and probabilistical Mathematics
Cambridge, UK, 1997
and references therein
For details on MPFIT see:
http://cow.physics.wisc.edu/~craigm/idl/fitting.html
REVISION HISTORY:
Written Theo Brauers, Mar 2000
Corrected
Revised
Modified
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\bootstrap_mpfitfun.pro)
NAME: BOX VERSION: 4.0 PURPOSE: Creates an empty plot area, with boundaries defined by XLIMS and YLIMS. CATEGORY: General Graphics. CALLING SEQUENCE: BOX, XLIMS, YLIMS [, keywords] INPUTS: XLIMS, YLIMS 2 dimensional vectors, format: [xmin,xmax] and [ymin,ymax] respectively. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /BORDER Switch. Draws a border around the plot area. Default - no border. /OVER Switch. Creates the plot area over an existing plot. Default - new plot area. TRUASP Corrects the XLIMS or YLIMS values to yield a 1:1 aspect ratio. Accepts six possible character values (only first 2 characters matter): 'XLO' : Scale x, keeping lowest x-value constant. 'XCEN': Scale x, keeping center x-value constant. 'XHI' : Scale x, keeping highest x-value constant. 'YLO' : Scale y, keeping lowest y-value constant. 'YCEN': Scale y, keeping center y-value constant. 'YHI' : Scale y, keeping highest y-value constant. /UPDATE_LIMS Switch. If set, XLIMS and YLIMS are updated to the values used in plotting. _EXTRA A formal keyword used to pass all plotting keywords. Not to be used directly. See comment in RESTRICTIONS. OUTPUTS: None. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: If UPDATE_LIMS is set, the values of XLIMS, YLIMS may change. RESTRICTIONS: The keywords passed through _EXTRA are transferred to the PLOTS routine. No keyword verification is performed by BOX. PROCEDURE: Uses calls to CAST, and STRMATCH_MM from MIDL. The scaling is done using the sizes of the plotting area in device coordinates, provided by the system variables !d.x_vsize and !d.y_vsize. Therefore the scaling is always proper for the current output device. MODIFICATION HISTORY: Created 15-JUL-1991 by Mati Meron. Modified 15-DEC-1991 by Mati Meron. Added keyword COLOR. Modified 15-DEC-1993 by Mati Meron. Now BOX takes advantage of the keyword inheritance property and accepts all IDL plotting keywords. Modified 1-MAY-1995 by Mati Meron. Improved aspect ratio correction. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\box.pro)
NAME:
BOX1
PURPOSE:
Single mouse button interactive box on image display.
CATEGORY:
CALLING SEQUENCE:
box1, x, y, dx, dy
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/DEVICE Work in device coordinates (default).
/NORMAL Work in normalized coordinates.
/DATA Work in data coordinates.
COLOR=clr Box color. -2 for dotted box.
DXRANGE=dxr X size range [min, max].
DYRANGE=dyr Y size range [min, max].
SHAPE=shp If given box shape is locked: Shape=dy/dx.
/NOSTATUS Inhibits status display widget.
TEXT=txt Text array to display in status widget.
MENU=txtarr Text array with exit menu options.
Def=['OK','Abort','Continue']. 'Continue is added.'
/NOMENU Inhibits exit menu.
EXITCODE=code. 0=normal exit, 1=alternate exit.
If MENU is given then code is option index.
SETSTAT=st May use the same status display widget on
each call to box1 (stays in same position).
On first call: the status widget structure is returned.
Following calls: send st. Must use with /KEEP.
To delete status display widget after last box1 call:
widget_control,st.top,/dest (or drop /KEEP)
/KEEP Do not delete status widget on exit.
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1994 Jan 10
R. Sterner, 1995 Mar 22 --- Added /NOMENU option.
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\box1.pro)
NAME:
BOX2B
PURPOSE:
Simple two mouse button interactive box on image display.
CATEGORY:
CALLING SEQUENCE:
box2b, x1, x2, y1, y2
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/STATUS means display box size and position.
MENU=txtarr Text array with exit menu options.
Def=['OK','Abort','Continue']. 'Continue is added.'
/NOMENU Inhibits exit menu.
EXITCODE=code. 0=normal exit, 1=alternate exit.
If MENU is given then code is option index.
/YREVERSE makes y=0 be the top line.
OUTPUTS:
x1, x2 = min and max X. out
y1, y2 = min and max Y. out
COMMON BLOCKS:
NOTES:
Notes: Works in device coordinates.
Drag open a new box. Corners or sides may be dragged.
Box may be dragged by clicking inside.
Click any other button to exit.
A returned value of -1 means box undefined.
MODIFICATION HISTORY:
R. Sterner, 1997 Nov 10
R. Sterner, 1998 Feb 5 --- Fixed first erase box problem.
Better but not perfect.
R. Sterner, 1998 Jul 21 --- Added List Box Position.
R. Sterner, 1999 Mar 15 --- Added /YREVERSE keyword.
Copyright (C) 1997, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\box2b.pro)
NAME:
BOXAREA
PURPOSE:
Select an area with a box.
CATEGORY:
CALLING SEQUENCE:
boxarea, x1, y1, x2, y2
INPUTS:
KEYWORD PARAMETERS:
Keywords:
FLAG=flg Exit flag: 0=ok, 1=abort.
OUTPUTS:
x1,y1 = first box point. out
x2,y2 = second box point. out
COMMON BLOCKS:
NOTES:
Notes: Open a box by dragging with left mouse button.
Repeat to get desired box.
Accept box with middle button.
Reject box with right button.
All coordinates are device coordinates.
MODIFICATION HISTORY:
R. Sterner, 1995 Oct 31
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\boxarea.pro)
NAME:
boxarea2
PURPOSE:
Select an area with a box.
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
boxarea2, x_1, y_1, x_2, y_2 ,[/flag],[/js],[color=color]
KEYWORD PARAMETERS:
FLAG Exit flag: 0=ok, 1=abort.
JS Means X axis is time in Julian seconds. Example:
x=maken(-2e8,-1.9e8,200) & y=maken(20,30,200)
z=bytscl(makez(200,200))
izoom,x,y,z,/js
boxarea2,/js
OUTPUTS:
x_1,y_1 = first box point. out
x_2,y_2 = second box point. out
PROCEDURE:
Notes: Open a box by dragging with left mouse button.
Return by right button
All coordinates are device coordinates.
MODIFICATION HISTORY:
R. Sterner, 1995 Oct 31
R. Bauer, 1996, April 1 changed for data coordinates
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
1998-Mar-11 return variables changed
1999-Nov-06 help added
2000-Mar-13 color keyword added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\boxarea2.pro)
ROUTINE:
BOXONMAP, derived from IDL User Library Procedure BOX_CURSOR
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
BOXONMAP, wx0, wy0, wx1, wy1 [, INIT = init] [, FIXED_SIZE = fixed_size]
INPUTS:
No required input parameters.
OPTIONAL INPUT PARAMETERS:
wx0, wy0, wx1, and wy1 give the initial location of the lower left
(wx0, wy0) and upper right (wnx, wny) corners of the box if the
keyword INIT is set. Otherwise, the box is initially drawn in the
center of the screen. Both input and output parameters are in
Longitude (X) and Latitude (Y).
KEYWORD PARAMETERS:
INIT: If this keyword is set, wx0, wy0, wx1, and wy1 contain the
initial parameters for the box.
FIXED_SIZE: If this keyword is set, the initial parameters fix the
size of the box. This size may not be changed by the user.
MESSAGE: If this keyword is set, print a short message describing
operation of the cursor.
OUTPUTS:
wx0: X value (Lon) of lower left corner of box.
wy0: Y value (Lat) of lower left corner of box.
wx1: X value (Lon) of upper right corner of box.
wy1: Y value (Lat) of upper right corner of box.
The box is also constrained to lie entirely within the window.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
A window for display of numeric latitude and longitude is created.
It is destroyed on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: Move the box by dragging.
Middle mouse button: Resize the box by dragging. The corner
nearest the initial mouse position is moved.
Right mouse button: Exit this procedure, returning the
current box parameters.
MODIFICATION HISTORY:
DMS, April, 1990.
DMS, April, 1992. Made dragging more intutitive.
NFH, March, 1993, Warp box & use map coordinates,
display Lat & Lon in text box.
PJR/ESRG, March, 1994, display lat & lon in xmessage window
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\boxonmap.pro)
NAME:
BOXPLOT
PURPOSE:
This procedure produces a box and whisker plot of a data
vector and provides many options to customize the appearance
of the plots. The data can be supplied as one vector and the
statistics will be computed according to the group
index. Alternatively, the data can be supplied as
precalculated percentile values if the Is_Percentile flag is
set. Boxes may be plotted staggered along the x axis or the y
axis.
CATEGORY:
2D Graphics
CALLING SEQUENCE:
BOXPLOT, DATA [,GROUP=] [,MINGROUP=] $
[,MAXGROUP=] [,LABEL=] $
[,COLOR=] [,BOXCOLOR=] $
[,BOXWIDTH=] [,BOXPOSITION=] $
[,MEDIANCOLOR=] [,MEDIANTHICK=]$
[,MEANSYMBOL=] $
[,MEANCOLOR=] [,FILLCOLOR=] $
[,MISSING=] [,MIN_VALID=] $
[,MAX_VALID=] [,PRINTN=] $
[,CHARSIZE=] [,OVERPLOT=] $
[,VERTICAL=] $
[,ORIENTATION=] [,IS_PERCENTILE=] $
[,PERCVAL=] [,QUIET=]
INPUTS:
DATA --> The data vector. This can be an array of
any dimensions but is always treated as 1-dimensional
vector. If the Is_Percentiles keyword is set, data must be
an array of dimensions 5,N, where the first dimension
denotes the percentile values.
KEYWORD PARAMETERS:
GROUP --> array of the same dimension as DATA which
contains grouping information. One box is plotted for
each group. If MINGROUP or MAXGROUP are given, boxes and
whiskers are only plotted for group values within this
range. Group can also be a string array. In this case
MINGROUP and MAXGROUP make no sense of course.
If GROUP contains more than 28 values, the major tick
marks will no longer be aligned with the groups and a
warning message is printed.
MINGROUP --> the minimum group value for which a box
shall be plotted.
MAXGROUP --> the maximum group value for which a box
shall be plotted
LABEL --> Label values for different *groups*.
NOTE: The user must take care that one label is passed for
each group to be plotted. If label is not specified, the
group values will be used as axis labels. Note that
group itself can be a string array.
COLOR --> plotting color for axis (default: !P.Color).
BOXCOLOR --> color of the boxes (frames). Default
is the COLOR value, i.e. !P.COlor if not specified. This
color will also be used as default for MEDIANCOLOR and
MEANCOLOR. Set BoxColor to a negative value to suppress
the box outlines. In this case the default for MEDIANCOLOR
and MEANCOLOR will be the COLOR value.
BOXWIDTH --> Width of boxes relative to major tick
marks (default: 0.8).
BOXPOSITION --> Position of boxex relative to tick
marks on x axis (default: 0.). This parameter is useful
together with the OVERPLOT keyword in order to plot
multiple groups of boxes in one graph.
MEDIANCOLOR --> a color value for the median bar
(default: value of BOXCOLOR)
MEDIANTHICK -> thickness of the median line
MEANSYMBOL --> symbol to be used for mean values. If no
symbol is given, no mean values will be drawn.
MEANCOLOR --> color for mean symbols (default:
value of BOXCOLOR)
FILLCOLOR --> a value or an array containing the
colorindex for all boxes or each box, respectively. If a
single value is given, *all* boxes will be filled with
this color. If an array is passed that has less elements
than there are groups to plot, the remaining colors will
be filled with the default background color (!P.background).
If no FILLCOLOR is specified, the boxes will not be filled
at all.
MISSING --> a value that represents missing data. If
given, any data with a value of missing will be filtered
out before plotting.
MIN_VALID -> any data below this value will be ignored
from the analysis.
MAX_VALID -> any data above this value will be ignored
from the analysis.
PRINTN --> print number of elements on top of each
box/whisker.
CHARSIZE --> character size of the PRINTN labels
(default: 0.8)
OVERPLOT --> do not draw a new coordinate system but
overlay new data. For 2 sets of data it is recommended to
use BOXWIDTH=0.4 and BOXPOSITION=-0.25 and 0.25,
respectively.
ORIENTATION -> orientation for axis labels (see XYOUTS
procedure)
VERTICAL -> Set this keyword to have boxes staggered
along y axis (i.e. boxes are horizontal).
IS_PERCENTILE --> data are already processed
percentiles. In this case data must be an array with
dimensions 5,N. The GROUP keyword is ignored, and each set
of the N percentiles will be treated as one group.
PERCVAL --> percentile values (default: 0.05, 0.25,
0.5, 0.75, 0.95). See the percentiles function for
deatils. This keyword has only effect if Is_Percentile is
not set.
QUIET -> suppress printing of statistics for each
group.
_EXTRA keywords are passed to the PLOT routine and can be used
to determine the appearance of the plot (e.g. XTITLE,YTITLE,
YSTYLE,YRANGE,/YLOG,COLOR,THICK,FONT)
OUTPUTS:
SUBROUTINES:
xboxplot : produces plot with groups along x axis
yboxplot : produces plot with boxes along y axis
REQUIREMENTS:
function PERCENTILES is called and must either be compiled
or located in the IDL_PATH
NOTES:
EXAMPLE:
o3 = data(where(header eq 'O3'),*)
alt = data(where(header eq 'ALT'),*)
ialt=2.*fix(alt/2.)
boxplot,o3,group=ialt
produces a boxplot with ozone percentiles in altitude bins of
2 (km). Axis, box frames and labels will be plotted in the
default color, boxes are not filled.
boxplot,o3,group=ialt,fillc=15,meansym=sym(1),meancol=2, $
boxwidth=0.6,ytitle='O3',xtitle='alt. bin', $
missing=-999.99,/printn
produces boxes that are filled with color index 15 and have the
frame and median line in the default color. The mean values
are deonted by a circle filled with color index 2.
Titles are assigned to the x and y axis. The number of valid
observations is printed on top of each box. The boxes are
reduced in size.
co = data(where(header eq 'CO'),*)
boxplot,o3,group=ialt,missing=-999.99,boxcol=4, $
boxwidth=0.4,boxpos=-0.25
boxplot,co,group=ialt,missing=-999.99,boxcol=2, $
boxwidth=0.4,boxpos=+0.25,/overplot
produces a plot with different colored box frames for ozone
and CO data.
MODIFICATION HISTORY:
mgs, 30 Jul 1997: VERSION 1.00
mgs, 03 Aug 1997: added template
mgs, 27 Nov 1997: some revisions and suggested changes by T.Brauers:
- better color handling (NOTE: meaning of BOXCOLOR has changed)
- optional overlay of mean value
- box frames
- variable boxwidth
- error fixing lower upper boundaries in log plots
- bug fix with label keyword
- added OVERPLOT and BOXPOSITION keywords
mgs, 22 Jan 1998: added IS_PERCENTILE keyword to allow
plotting of data that has been processed already
mgs, 17 Apr 1998:
- x-axis handling improved (now uses axis command and xyouts)
- orientation and medianthick keywords added
mgs, 21 May 1998:
- added percval keyword
mgs, 24 Aug 2000:
- changed copyright to open source
- changed default colors to system values
- improved documentation and modernized code
- bug fix: n_elements instead of keyword_set
- added min_valid, max_valid, and quiet keywords
- added vertical keyword, thus yboxplot is obsolete
- [] array notation throughout
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\boxplot.pro)
ROUTINE: boxpos
USEAGE:
result=boxpos()
result=boxpos(aspect=aspect,rmarg=rmarg,xpos=xpos,ypos=ypos,$
get=get,curbox=curbox,print=print)
PURPOSE: returns the 4 element position of a properly shaped data window.
output is in normalized coordinates
INPUT:
none required
keyword input:
aspect x/y aspect ratio of map (default = 1)
rmarg the amount of margin to leave on the right side of the
box. The margin is specified in units of 10 character
widths, so merely setting the RMARG parameter provides
enough space for COLOR_KEY
get if set, retrieve the position information of the last
plot drawn.
xpos two element vector specifying x position of a multi frame
plot, the first element specifies the frame number, the
second element specifies the number of frames
ypos two element vector specifying y position of a multi frame
plot, the first element specifies the frame number, the
second element specifies the number of frames
print if set, print out the normal coordinates of the box
edges in format,
pos=[x0,y0,x1,y1]
where (x0,y0) and (x1,y1) are the normal coordiates
of the lower left and upper right corners of the box
The default value of PRINT is 1 if the CURSOR keyword
is set.
OUTPUT:
result=[x1,y1,x2,y2],
where (x1,y1) and (x2,y2) are the lower left hand
and upper right hand corner of the new data window
in normalized coordinates.
EXAMPLE: Draw a map over a TVIM image
tvim,dist(200)
map_set,0,0,/orth,/cont,/grid,pos=boxpos(/get),/noerase
Draw a map of the southern hemisphere with 2:1 aspect
ratio
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(aspect=2)
now try a 1:1 aspect ratio
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect)
now allow room for color key, and draw color key
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect,/rmarg)
color_key
Draw a multframe plot
x=findgen(100)
plot,x,x,pos=boxpos(aspect=1,ypos=[3,3])
plot,x,x^2,pos=boxpos(aspect=1,ypos=[2,3]),/noerase
plot,x,x^3,pos=boxpos(aspect=1,ypos=[1,3]),/noerase
; NOTE: the XMULTI and YMULTI proceedures (in this directory) can
; also be used to make multiframe plots and are more flexible
; than BOXPOS for positioning the individual frames.
author: Paul Ricchiazzi 25jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\boxpos.pro)
NAME:
BOX_SIZE
PURPOSE:
Used by MOVBOX to change box size using the cursor.
CATEGORY:
CALLING SEQUENCE:
BOX_SIZE, x, y, dx, dy, showflag
INPUTS:
x,y = lower left corner device coordinates. in
KEYWORD PARAMETERS:
Keywords:
/POSITION prints box position and size on exit.
XSIZE = factor. Mouse changes Y size, computes X size.
YSIZE = factor. Mouse changes X size, computes Y size.
/YREVERSE means y is 0 at screen top.
XFACTOR=xf convsersion factor from device coordinates
to scaled coordinates.
YFACTOR=yf convsersion factor from device coordinates
to scaled coordinates.
DXMIN=dxmn Minimum allowed box x size (def=1).
DYMIN=dymn Minimum allowed box y size (def=1).
COLOR=clr Box color (-2 for dotted box).
OUTPUTS:
dx, dy = box size. in, out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 25 July, 1989.
R. Sterner, 16 Mar, 1992 --- upgraded box list.
R. Sterner, 7 Dec, 1993 --- Added min box size.
R. Sterner, 1994 Nov 27 --- Switched !err to !mouse.button.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\box_size.pro)
NAME:
break_lines
PURPOSE:
This function breaks the linesin a string array into multiple records if the record is longer
than the reclength parameter. By default, the break is always located at
[' ','+','/','(',')','|'] charackters.
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
Result=break_lines(Str, Reclength, [LIST=list] )
INPUTS:
Str : array of (string) records
Reclength : maximum recordlength allowed
KEYWORD PARAMETERS:
LIST: a list of locations where a break might occur
default: [' ','+','/','(',')','|']
OUTPUTS:
Result: string array with string length of all elements less than revlength
EXAMPLE:
str_new=break_lines(['a=3+45+87/15;','b=3;'],10)
print,transpose(str_new)
gives :
a=3+45+87
/15;
b=3;
MODIFICATION HISTORY:
Written by: Franz Rohrer 1998-Jan-15
Modified: Theo Brauers, 1999-Jan-7
new keyword list
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\break_lines.pro)
NAME:
build_structure
PURPOSE:
This routine accumulates values into a structure or concatinates two structures
CATEGORY:
PROG_TOOLS
CALLING SEQUENCE:
build_structure,structure,declaration,value,[name=name],[/random_structure_name],[/counted_structure_name]
INPUTS:
structure : if it's present the structure which will be accumulated to
declaration: the tag which will be added to the structure
value : the value which will be added to the structure
KEYWORD PARAMETERS:
name: to set the Structure name
random_structure_name: if set the structure name is performed by random_hex_name()
counted_structure_name: if set the structure name is performed by count_name(name)
OUTPUTS:
structure: A structure holding value
EXAMPLE:
build_structure,def,'test',5
help,test,/str
** Structure <117e2f8>, 1 tags, length=2, refs=1:
TEST INT 5
build_structure,def,'AN',5
help,def,/str
** Structure <117ec88>, 2 tags, length=4, refs=1:
TEST INT 5
AN INT 5
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1998-Jun-27
1999-02-23 Problem if tag is alread defined in structure by is_tag resolved
1999-03-16 random_structure_name added
1999-03-20 counted_structure_name added
2000-Feb-18 help changed to call_help
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\build_structure.pro)
NAME: build_vector PURPOSE: This routine accumulates values into a vector CATEGORY: PROG_TOOLS CALLING SEQUENCE: build_vector,vector,value INPUTS: vector : if it's present the vector which will be accumulated to value : the value which will be added to the vector OUTPUTS: vector: A vector holding value EXAMPLE: build_vector,test,5 print,test 5 MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1998-Jun-27
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\build_vector.pro)
NAME:
BYT2STRARR
PURPOSE:
Unpack a string array from a byte array
CATEGORY:
CALLING SEQUENCE:
byt2strarr, barr, tarr
INPUTS:
barr = byte array with text. in
KEYWORD PARAMETERS:
OUTPUTS:
tarr = text string array. out
COMMON BLOCKS:
NOTES:
Notes: The format of barr is:
byte 0: NUM = Number of strings (255 max).
byte 1: MAX = Length of longest string (255 max).
byte 2: LEN1 = Length of 1st string.
byte 3: C1_0 = 1st char of 1st string.
byte 4: C1_1 = 2nd char of 1st string.
byte 5: C1_2 = 3rd char of 1st string.
. . .
byte x1 (2+LEN1): C1_last = last char of 1st string.
byte x1+1: LEN2 = Length of 2nd string.
. . .
To last char of last string in tarr.
NUM, MAX, LEN1, C1, C2, ..., Clast, LEN2, C1, C2, ...
Advantage: saves space, allows storing text arrays of
various lengths. See also strarr2byt, the inverse.
MODIFICATION HISTORY:
R. Sterner, 1996 May 29
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\byt2strarr.pro)
NAME:
BYTARR_GET
PURPOSE:
Extract a byte array from a byte buffer.
CATEGORY:
CALLING SEQUENCE:
bytarr_get, buf, out
INPUTS:
buf = byte buffer to extract output from. in
KEYWORD PARAMETERS:
Keywords:
INDEX=indx Index of byte array to extract:
0=1st, 1=2nd, ... Returned by bytarr_put
array was inserted. Out of range indices return
a single 0 byte (no error).
The inverse routine, bytarr_put, is used to insert
arrays into the buffer.
You must handle converting from byte to correct
data type when extracting.
OUTPUTS:
out = byte array extracted from buffer. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1996 May 30
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\bytarr_get.pro)
NAME:
BYTARR_PUT
PURPOSE:
Insert a byte array into a byte buffer.
CATEGORY:
CALLING SEQUENCE:
bytarr_put, buf, in
INPUTS:
in = byte array to add to buffer. in
KEYWORD PARAMETERS:
Keywords:
INDEX=indx Returned index of inserted byte array:
0=1st, 1=2nd, ... Can be used with bytarr_get to
retrieve a given array.
ADDRESS=a returned byte address into buffer for in.
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: To start set input buffer b to 1 element:
b = [0B] before using in bytarr_put.
Can use this routine to build up an array of
variable lengths arrays, or pack arrays of any data
type together in a compact form. Must convert input
to a byte array first using field extraction. Ex:
a=indgen(10) & b=byte(a,0,2*n_elements(a)) will create
an int array and convert it to a byte array.
The inverse routine, bytarr_get, allows extraction by
index number (1st input is 0, 2nd is 1, ...).
You must handle converting from byte when extracting.
MODIFICATION HISTORY:
R. Sterner, 1996 May 30
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\bytarr_put.pro)
NAME:
bytes2strarr
PURPOSE:
This function convertes a byte array to a string array
cut at the LF character (10B), all CR (13B) are removed
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
Result=BYTES2STRARR(Bytes)
INPUTS:
Bytes: bytearray
KEYWORD PARAMETERS:
REMOVE_10B: if set 10b is removed
OUTPUTS:
an string array containing the text converted from bytearrary
EXAMPLE:
b=GET_FILE('....', /BYTE)
s=BYTES2STRARR(b)
REVISION HISTORY:
Written Theo Brauers, June 1997
Modified by R.Bauer, F.Rohrer, 1998-Nov-10 added REMOVE_10B
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\bytes2strarr.pro)
NAME:
cache
PURPOSE:
This procedure is used to remember previously loaded data from file for the last plot;
CATEGORY:
PLOT/PLOT2D
CALLING SEQUENCE:
cache,plot,file,x,y,z,[i_xn=i_xn],[i_yn=i_yn]
INPUTS:
plot: The by pl_init defined structure plot
file: The filename of the netCDF file
x: The name of parameter x
y: The name of parameter y
z: The name of parameter z
OPTIONAL INPUTS:
i_xn: number of x page position
i_yn: number of y page position
OUTPUTS:
x: Structure
y: Structure
z: Structure
All structures of the same tag names:
.name : the name of the parameter
.file : the filename of the file
.param : the param field
.valid : the valid field
.time : the time field
.param_long_name : the long_name of the parameter
.param_units : the units of the parameter
.time_long_name : the long_name of the time
.time_units : the units of the time
COMMON BLOCKS:
plot_data
pl_data: A structure holding parameters, names, titles and the file name of a loaded dataset
EXAMPLE:
cache,plot,file,x,y,z,i_xn=i_xn,i_yn=i_yn
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 5. Oct 1997
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cache.pro)
NAME: cache_del PURPOSE: This procedure clears the common block plot_data variable pl_data CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: cache_del COMMON BLOCKS: plot_data: This is the common block where file and data information for plot2d and plotxy are saved EXAMPLE: cache_del MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 5. Oct 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cache_del.pro)
NAME:
cache_enz
PURPOSE:
Read-cache for enz-files
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
cache_enz,file,dvalue,ix,iy,fb,text,header,err
INPUTS:
file: name of enz-file
KEYWORD PARAMETERS:
js_time : time values in julian seconds, calculated with appropriate dvalue-columns
errmess : error message text
fill_value: fill value for non-existing data
nocache : to supress generation of *.sav-file
OUTPUTS:
dvalue: matrix of values, field[ix,iy]
ix : number of rows
iy : number of columns
fb : errorbar-flag for compatibility with zusammen-files, should be 0 for enz-files
text : array of headertext of columns
header: raw header information
err : file read error flag
SIDE EFFECTS:
stores and restores information in the file filename.enz.sav
EXAMPLE:
cache_enz,'test.enz',dvalue,ix,iy,fb,text,header,err,js_time=js_time,fillvalue=-12345
MODIFICATION HISTORY:
Written Franz Rohrer, May 1997
Modified: 25.9.1998 renamed fillvalue in fill_value
included nocache
10.11.1998 FR file_info used to determine time difference
16.03.1999 FR file=file_in included
06.06.1999 FR if result2[0] eq '' and result1[0] ne '' then dt=10 else begin
damit das sav-file auch eingelesen wird, wenn kein Original vorhanden ist
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\cache_enz.pro)
NAME:
cache_zus
PURPOSE:
Read-cache for zus-files
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
cache_zus,file,dvalue,ix,iy,fb,text,header,err
INPUTS:
file: name of zus-file
KEYWORD PARAMETERS:
js_time : time values in julian seconds, calculated with appropriate dvalue-columns
errmess : error message text
fillvalue: fill value for non existing data
high_err : upper end of errorbar
low_err : lower end of errorbar
OUTPUTS:
dvalue: matrix of values, field[ix,iy], errorbars are taken out and stored in high_err and low_err
ix : number of rows
iy : number of columns
fb : errorbar-flag, should be 0 for enz-files
text : array of the headertext of columns
header: raw header information
err : file read error flag
SIDE EFFECTS:
stores and restores information in file filename.zus.sav
EXAMPLE:
cache_zus,'test.zus',dvalue,ix,iy,fb,text,header,err,js_time=js_time,fillvalue=-12345,high_err=high_err,low_err=low_err
MODIFICATION HISTORY:
Written Franz Rohrer, May 1997
Corrected
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\cache_zus.pro)
NAME: CALCTYPE VERSION: 4.0 PURPOSE: Identifies maximal (and, optionally) minimal data type for calculation. CATEGORY: Programming. CALLING SEQUENCE: Result = CALCTYPE( V_0 [,V_1, ... V_7] [, VALUE = VAL]) INPUTS: V_0 through V_7 Numeric, otherwise arbitrary, at least one should be given. If the keyword /STRICT is set, unsigned integers of all lengths are not considered numerical. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /TYPES Switch. If set, the V_i parameters are taken to represent data types of inputs rather then the inputs themselves. /MAXTYP Switch. If set, the numerically *highest* of the data types is returned. This is the default, so there is really no need to set /MAXTYP, it is just provided for completeness. /MINTYP Switch. If set, the numerically *lowest* of the data types is returned. DEFAULT Accepts an integer value to be used as default type for those input variables which happen to be undefined. If not given, undefined inputs result in error. /EXACT Switch. Disables the resetting of lower value to 4 and higher to 9 when the inputs types are 5,6. Has no impact in other cases. /STRICT Switch. If set, unsigned integers are *NOT* considered numbers. /QUIET Switch. Determines error handling. See OUTPUTS below. OUTPUTS: If the data types of all inputs (or the inputs themself, when /TYPES is set) correspond to valid numeric types (excluding unsigned integers if /STRICT is set), CALCTYPE returns the numerically highest (or, if /MINTYP is set, numerically lowest) of the types present. Note that the numeric order of the types is (excluding unsigned types): 1, 2, 3, 14, 4, (5-6), 9 As neither of (5,6) is equivalent or higher to the other, in case the inputs are of types 5 and 6, the return value is 9 (for higher) or 4 (for lower) unless /EXACT is set. The types of unsigned integers (when accepted) are converted to these of signed ones of same length. The types of undefined inputs are converted to DEFAULT if given, else are left at 0 (which is *not* a valid numeric type). If some of the data types do not correspond to valid numeric types, the outcome depends on the /QUIET switch. If /QUIET is set, the routine returns 0, else it stops with an error message. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: All the V_i present have to be valid numeric inputs (or numeric data types) else an error results (unless /QUIET is set). PROCEDURE: Straightforward. Using ISNUM and ONE_OF from MIDL. MODIFICATION HISTORY: Created 15-FEB-2001 by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\calctype.pro)
NAME:
calc_av_residual
PURPOSE:
calculate geometric average of residuals
CATEGORY:
MATH
CALLING SEQUENCE:
calc_av_residual,x,y,a,b
INPUTS:
x,y : x/y data dublets
a,b : offset and slope of line
OUTPUTS:
returns geometric average of residuals =mean( sqrt(sum((y-a-b*x)^2)/n) )
EXAMPLE:
calc_av_residual,x,y,a,b
MODIFICATION HISTORY:
Written Franz Rohrer, May 1997
Corrected
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_av_residual.pro)
NAME:
calc_bin_averages
PURPOSE:
This function calculates averages of y-values for given x-intervals
CATEGORY:
MATH
CALLING SEQUENCE:
result=calc_bin_averages(x,y[,log=log][,number=number][,min=min][,max=max])
INPUTS:
x:vector of x-values
y:vector of y-values
OUTPUTS:
result.occurrence :number of occurrencies
.mean :mean of y-data inside bin-interval
.stddev :standard deviation of y-data inside bin-interval
.position :average x-position of bin-intervals
.left :left margins of bin-intervals
.right :right margins of bin-intervals
.binposition :average of left and right margins
KEYWORD PARAMETERS:
log : make equidistant bins on a logarithmic scale
number: number of bins, default=10
min : left margin, default=MIN(x)
max : right margin, default=MAX(x)
EXAMPLE:
x=findgen(1000) & y=randomn(seed,1000)
r=calc_bin_averages(x,y)
print,r.position,r.mean,format='(10f12.7)'
49.5000000 149.5000000 249.5000000 349.5000000 449.5000000 549.5000000 649.5000000 749.5000000 849.5000000 949.5000000
-0.0238803 0.0346891 -0.0060972 -0.0419993 0.1417571 -0.0071263 0.0606227 0.1793810 0.0087501 0.0297610
MODIFICATION HISTORY:
Written by: F. Rohrer (ICG-3), 1998-Nov-19
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_bin_averages.pro)
NAME:
calc_geometry
PURPOSE:
This function calculates the area and volume of a different geometrical
figures which are stacked into/onto another.
CATEGORY:
MATH
CALLING SEQUENCE:
Result = CALC_GEOMETRY(X)
INPUTS:
X: the thicknes of one layer of the figures, can be a single value, all
layer are of the same thickness, or an array. The length of this array
defines the size of the output structure array. If n_elements(x) ==1
then the num_box keyword is tested.
OPTIONAL INPUTS:
Y: see GEOMETRY keyword
Z: see GEOMETRY keyword
KEYWORD PARAMETERS:
KDIFF: set this keyword to a number or array with same elements as X the kd in
all layers will be set to the number or array (default=0.0)
GEOMETRY: possible options:
'SPHERE': concentric spheres
volume and area are calculated from the thickness input
only, Y and Z are disregarded
'TUBE': concentric cylinders, no length
volume and area are calculated from the thickness input
If Y is given it is taken as length of the tubes and
Z are disregarded
'BARREL': concentric barrels, length is total lenght if y is scalar
if Y is vector then these values are taken.
volume and area are calculated from the thickness and length
input, Z is disregarded
'CUBE': concentric cubes
volume and area are calculated from the thickness input
only, Y and Z are disregarded
'COLUMN': stacked boxes, if Y is area and volume, is calcualted
'UNKNOWN': Y and Z are area and volume, if not
provided they are set to 1.D0 in all boxes
NUM_BOX: number of boxes in a equal layer thickness model, if x is provided
as a scalar value
OUTPUTS:
This function returns an array of structure which contains the thickness , the
area, and the volume. Result.ar[k] is the area between layer k and k+1.
Result.vl[k] is the volume of layer[k]
EXAMPLES:
In order to calculate the volume and area of a 4m cube surrounded by a
4.2m cube one has to enter the following function call:
IDL> x=calc_geometry([2.,.1 ], g='cube') & print, x & help, x,/str
{ 2.0000000 64.000000 96.000000 0.0000 }
{ 0.10000000 10.088000 105.84000 0.0000 }
** Structure <1062420>, 3 tags, length=24, refs=1:
DH DOUBLE 2.0000000
VL DOUBLE 64.000000
AR DOUBLE 96.000000
A set of 10 concentric spheres of .05m layers is calculated
IDL> x=calc_geometry(.05D, g='sphere', n=10) & print, x[0:1], x[9]
{ 0.050000000 0.00052359879 0.031415927 0.010000 }
{ 0.050000000 0.0036651915 0.12566371 0.010000 }
{ 0.050000000 0.14189527 3.1415927 0.010000 }
note that the diameter of the last sphere is 1m corresponding to
a surface area of 3.1415..m
MODIFICATION HISTORY:
Written by: Theo Brauers, 1998-Feb-5
Modified: T.B. 1998-FEB-6
calc of cube/ tube / barrel corrected
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_geometry.pro)
NAME: calc_linear_interpol PURPOSE: This functions calls the linear interpolation for TIMES_SERIES_SYNC CATEGORY: MATH CALLING SEQUENCE: Result = CALC_LINEAR_INTERPOL(client_t, client_v, master_t) INPUTS: Client_t: client time array Client_v: client value array Master_t: master time array KEYWORD PARAMETERS: FILL_VALUE: value for missing entries in the output array ERROR: if set to a named variable an error status is returned (0: OK) OUTPUTS: This function returns an array of the interpolated values EXAMPLE: see TIME_SERIES_SYNC MODIFICATION HISTORY: Written by: Theo Brauers, 1999-FEB-15
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_linear_interpol.pro)
NAME: calc_linear_with_limit PURPOSE: This functions performs the linear interpolation with time limits for TIMES_SERIES_SYNC CATEGORY: MATH CALLING SEQUENCE: Result = CALC_LINEAR_WITH_LIMIT(client_t, client_v, master_t, master_w) INPUTS: Client_t: client time array Client_v: client value array Master_t: master time array KEYWORD PARAMETERS: FILL_VALUE: value for missing entries in the output array ERROR: if set to a named variable an error status is returned (0: OK) OUTPUTS: This function returns an array of the interpolated values EXAMPLE: see TIME_SERIES_SYNC MODIFICATION HISTORY: Written by: Theo Brauers, 1999-FEB-15
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_linear_with_limit.pro)
NAME:
calc_number_frequency
PURPOSE:
This function calculates the frequencies of the first digit of numbers
CATEGORY:
MATH
CALLING SEQUENCE:
result=calc_number_frequency(arr)
INPUTS:
arr: array of numbers
OUTPUTS:
result: frequency distribution of the first digits
EXAMPLE:
arr=[1.2,0.0122222,200]
print,calc_number_frequency(arr),format='(f45.2)'
0.00 0.67 0.33 0.00 0.00 0.00 0.00 0.00 0.00 0.00
MODIFICATION HISTORY:
Written by: F. Rohrer (ICG-3), 1998-Nov-17
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_number_frequency.pro)
NAME: calc_prop_interpol PURPOSE: This functions performs the proportional interpolation for TIMES_SERIES_SYNC CATEGORY: MATH CALLING SEQUENCE: Result = CALC_PROP_INTERPOL(client_t, client_v, master_t, master_v) INPUTS: Client_t: client time array Client_v: client value array Master_t: master time array Master_v: master value array KEYWORD PARAMETERS: FILL_VALUE: value for missing entries in the output array ERROR: if set to a named variable an error status is returned (0: OK) OUTPUTS: This function returns an array of the interpolated values EXAMPLE: see TIME_SERIES_SYNC MODIFICATION HISTORY: Written by: Theo Brauers, 1999-FEB-15
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_prop_interpol.pro)
NAME:
calc_solar_zenith_angle
PURPOSE:
This function calcutes the solar zenith
CATEGORY:
TIME
CALLING SEQUENCE:
Result = calc_solar_zenith_angle(time, longitude, latitude)
INPUTS:
Time: julian seconds or string [d.m.y h:m:s] or [yyyy-mm-dd hh:mm:ss]
(Julian Sec =0 : 2000-JAN-1 0:00:00 UTC)
Longitude: eastern longitude
Latitude: northern latitude
KEYWORD PARAMETERS
STRUCTURE: if set a structure with input and output params will be returned as structure
OUTPUT:
This functions returns an array of solar zenith angles or a structure
including the input parameters
PROCEDURE:
This set of routines is based on Yoshio Kubo, Rep. of Hydrographic Res. No. 15 1980
Sun position for 1970 - 2030 (see calc_sun_pos for details)
REVISION HISTORY:
Written Theo Brauers, Nov 1998
Modified Theo Brauers, June 1999
bugs removed !!!!
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_solar_zenith_angle.pro)
NAME: calc_spline_interpol PURPOSE: This functions call the spline interpolation for TIMES_SERIES_SYNC CATEGORY: MATH CALLING SEQUENCE: Result = CALC_SPLINE_INTERPOL(client_t, client_v, master_t) INPUTS: Client_t: client time array Client_v: client value array Master_t: master time array KEYWORD PARAMETERS: FILL_VALUE: value for missing entries in the output array ERROR: if set to a named variable an error status is returned (0: OK) OUTPUTS: This function returns an array of the interpolated values EXAMPLE: see TIME_SERIES_SYNC MODIFICATION HISTORY: Written by: Theo Brauers, 1999-FEB-15
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_spline_interpol.pro)
NAME: calc_sun_pos PURPOSE: This function calcutes the declination or right ascension of the sun CATEGORY: TIME CALLING SEQUENCE: Result = calc_sun_pos(jdf, [/RIGHT_ASCENSION] , [/DECLINATION]) INPUTS: Jdf: julian day with fractions of day KEYWORD PARAMETERS: RIGHT_ASCENSION: if set only right ascension will be returned DECLINATION: if set only declination be returned OUTPUTS: Result: sun positions given in degrees EXAMPLE: PROCEDURE: This set of routines is based on Yoshio Kubo, Rep. of Hydrographic Res. No. 15 1980 Sun position for 1970 - 2030 ( copied from MFC199m source code, GETMOON2.C, GETMOON.C, ..) typed by K. Pfeilsticker 13.9.1989) REVISION HISTORY: Written Theo Brauers, Nov 1998
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_sun_pos.pro)
NAME:
calc_unit
PURPOSE:
This function returns a structure with the result and other informations to calculate with units
CATEGORY:
MATH
CALLING SEQUENCE:
Result=calc_unit(value,inunit,outunit)
INPUTS:
value: one or an array of values that should be transformed
inunit: The input unit of the value
outunit: The output unit of the result
EXAMPLE:
result=calc_unit(5,'ppb','ppt')
help,result,/str
** Structure <302d43bc>, 5 tags, length=32, refs=1:
PARAM_UNITS_IN STRING 'ppb'
PARAM_UNITS_OUT STRING 'ppt'
PARAM INT 5
RESULT FLOAT 1000.00
FUNC STRING '*1.e-09/1.e-12'
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), August , 12 1997
1998-01-14 additional: seconds since 2000-01-01 00:00:00 UTC
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\calc_unit.pro)
NAME: calc_window_average PURPOSE: This functions performs the averaging over the provided tme windows for TIME_SERIES_SYNC CATEGORY: MATH CALLING SEQUENCE: Result = calc_window_average(client_t, client_v, master_t, master_w) INPUTS: Client_t: client time array Client_v: client value array Master_t: master time array Master_w: master window array KEYWORD PARAMETERS: FILL_VALUE: value for missing entries in the output array ERROR: if set to a named variable an error status is returned (0: OK) OUTPUTS: This function returns an array of the window averaged values EXAMPLE: see TIME_SERIES_SYNC MODIFICATION HISTORY: Written by: Theo Brauers, 1999-FEB-15
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\calc_window_average.pro)
NAME:
calc_zenith
PURPOSE:
This function calculates zenith and azimuth angle for a given location/time
CATEGORY:
MATH
CALLING SEQUENCE:
zenit=calc_zenith(js,long,lat,azimuth=azimuth)
INPUTS:
date: the speciefied day; scalar string
time: the time in UT ; scalar string
long: longitude of the geograhical position; scalar float
lat: latitude of the geograhical position; scalar float
OUTPUTS:
zenith : zenith angle
azimuth: azimuth angle
PROCEDURE:
This function is based on the publication by Sirri Aydinli,
Fortschrittberichte der VDI-Zeitschriften (Fortschr.Ber. VDI-Z.), 1981, Reihe 6, Nr.79, p5-12,
'Ueber die Berechnung der zur Verfuegung stehenden Solarenergie und des Tageslichtes'
EXAMPLE:
print,calc_zenith(str2js('12:00:00 08.11.1996'),6.35,50.92)
67.9200
print,calc_zenith(str2js('12:00:00 28.10.1997'),0.,0.)
13.1800
sollte 13.819 sein nach Ralf's astronomischen Tabellen
MODIFICATION HISTORY:
Written by: Franz Rohrer August 1998
Modified : 9.11.1998 FR, calc_zenit->calc_zenith,zenit->zenith,azimut->azimuth
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\calc_zenith.pro)
NAME: call_help PURPOSE: The result of this function is the text below CALLING SEQUENCE from a called routine CATEGORY: CASE_TOOLS CALLING SEQUENCE: result=call_help() EXAMPLE: message,call_help(),/info MODIFICATION HISTORY: Written by R.Bauer (ICG-1), 1999-Nov-06 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\call_help.pro)
ROUTINE: caption
PURPOSE: CAPTION can be used to print captions above or below a
figures. The character size is determined by the number
of characters per line.
USEAGE: caption,cap,xx,ybot=ybot,yt=ytop,nchar=nchar
INPUT:
cap string used for caption. Normally all text within CAP
is line wrapped to produce a multiline caption. All
white space within CAP is preserved in the caption.
Within CAP the character "\" can be used to force a line
break (i.e., to start a new line). Extra white space
following the "\" causes the text to be indented.
t='this is a test \ junk test test'+$
' \ junk test \ \ junk: this is a test'
caption,t
PRODUCES:
this is a test
junk test test
junk test
junk: this is a test
Note that the backslash character must be surrounded by
whitespace to be recognized
xx normal coordinates of left and right edge of caption
KEYWORD INPUT:
ytop normal coordinates of top of caption
(default=!y.window(0)-.15)
nchar number of characters per line
vspace vertical space factor, controls vertical space between
lines (default = 1)
bg_color background color
color foreground color
exdent number of character positions to indent all lines except
the first. (default=0)
nowrap if set do not line wrap the input text, instead use
embedded backslash characters to control line breaks.
KEYWORD OUTPUT:
ybot normal coordinates of bottom of caption. The value of
of ybot can be used append more text with another call
to CAPTION.
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
t1='CAPTION can be used to print captions above or below a '+$
'figures. The character size is determined by the number '+$
'of characters per line. here is a list of items: \ '+$
' 1. item 1 \ '+$
' 2. item 2 \ '+$
'END OF FIRST CAPTION
t2='BEGINNING OF SECOND CAPTION \ HERE is more text to add to '+$
'the previous text. Note how the '+$
'text starts immediately below the last line of the previous '+$
'written text. The use of ybot allows concatenation of text with '+$
'different right and left margins'
w8x11 & !p.multi=[0,1,2]
plot,dist(10)
caption,t1,nchar=80,ybot=yy
xwid=.5*(!x.window(1)-!x.window(0))
xmid=.5*(!x.window(0)+!x.window(1))
caption,t2,xwid+.5*[-xwid,xwid],nchar=40,ytop=yy
;; FILL option
t= 'HERE is more sample text to demonstrate the use of CAPTION''s, '+$
'"fill" option. Note how the text is stretched to fill the '+$
'entire width of the line. It is probably a good idea not '+$
'to force linebreaks using the backslash symbol while in this '+$
'mode. The "fill" option works best when NCHAR is large'
erase
caption,t,[.1,.9],ytop=.9,/fill,nchar=80
;; CAPTION used with READ_TEXT
caption,read_text('caption.txt','Figure 1.'),nchar=60
AUTHOR: Paul Ricchiazzi 12 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\caption.pro)
NAME: CAST VERSION: 4.0 PURPOSE: Generalized type casting. Converts variables whose type code is out of the range [LO,HI] into this range. CATEGORY: Programming (type conversion). CALLING SEQUENCE: Result = CAST( X, [LO [,HI]]) INPUTS: X Numerical, arbitrary (see /STRICT for possible limitations). LO Number representing a type code, range (1:15). If out of this range, an error results. If not given, it is set to 1. OPTIONAL INPUT PARAMETERS: HI Type code, same as LO. Default value is 9 (note that, though higher number codes exist, 9 corresponds to the "numerically highest" type). If HI is provided and corresponds to a "numerically lower" type than LO, it is set to LO. KEYWORD PARAMETERS: /STRICT Switch. If set, unsigned values are not accepted as numbers. /ROUND Switch. If set AND the casting is to any integer type, rounding is performed prior to type casting. /FIX Switch. If set, the output is filtered through FPU_FIX, eliminating floating underflow errors. OUTPUTS: If the type of X is < LO, CAST returns X converted to type LO. If the type of X is > HI, CAST returns X converted to type HI. Otherwise CAST returns X. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: And attempt to call CAST with non-numerical input or with type codes not corresponding to known numerical codes, will yield an error. PROCEDURE: Identifies the type of X, and if out of the range given by [LO,HI] calls the proper conversion routine using the system routine CALL_FUNCTION. The "range" follows the numerical order of types, i.e. 1, 2, 3, 14, 4, (5-6), 9 Unsigned types (Uint, Ulong, Ulong64) are either ignored (if /STRICT is set) or converted to the signed types of same length. CAST uses CALCTYPE, FPU_FIX and ISNUM from MIDL. MODIFICATION HISTORY: Created 25-DEC-1991 by Mati Meron. Modified 15-JUN-1995 by Mati Meron to accept the new DOUBLECOMPLEX type. Modified 25-SEP-1998 by Mati Meron. Underflow filtering added. Modified 25-DEC-2000 by Mati Meron. Added keyword ROUND. Checked for operation under Windows, 25-JAN-2001, by Mati Meron. Totally rewritten by Mati Meron, on 15-FEB-2001, to accomodate all new numeric types. Added keyword STRICT. Eliminated type conversion for CHARACTER type as it serves no useful purpose.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\cast.pro)
NAME: catalog PURPOSE: This procedure writes the html catalog files CATEGORY: CASE_TOOLS CALLING SEQUENCE: catalog,[path],[/no_examples],[/no_error],[/no_mail],[out_path=out_path],[/publish] EXAMPLE: catalog MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1997 new version: 2000-Jan-25 2000-Feb-08 get_template_one_value keywords added 2000-Apr-02 examples now without dbase and example icon
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\catalog.pro)
NAME: catalog_db PURPOSE: This procedure writes the html catalog database files and the tar and sav files of the routines CATEGORY: CASE_TOOLS CALLING SEQUENCE: catalog_db,[path],[out_path=out_path] INPUTS: path: the routine path to search routines PROCEDUE: idl_work and idl_model are the routine directories which will be scanned by resolve_dependencies. with the key /no_publish all our routine directories will be scanned MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1997 new version: 2000-Jan-25 2000-Feb-08 : get_template_one_value keywords added 2000-Jun-18 : link files sampled in a script and this will executed at the end of the routine catalog_db,['j:/links/idl_source/idl_work','j:/links/idl_source/idl_model'],out_path='j:\links\idl_source\' catalog_db,['/usr/local/icg/icg/idl_test/idl_source/idl_work','/usr/local/icg/icg/idl_test/idl_source/idl_model'],out_path='/usr/local/icg/icg/idl_test/idl_source'
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\catalog_db.pro)
NAME:
CBAR
PURPOSE:
Make a color bar.
CATEGORY:
CALLING SEQUENCE:
cbar
INPUTS:
KEYWORD PARAMETERS:
Keywords:
VMIN=vmn Minimum value of color bar parameter (def=0).
VMAX=vmx Maximum value of color bar parameter (def=top).
CMIN=cmn Color that represents vmn (def=0).
CMAX=cmx Color that represents vmx (def=top).
where top = !d.table_size-1.
CCLIP=cc Actual max color index allowed (def=!d.table_size-1)
/HORIZONTAL Colors vary horizontally (def).
/VERTICAL Colors vary vertical.
/BOTTOM Horizontal axis on bottom (def).
/TOP Horizontal axis on top.
/RIGHT Vertical axis on right (def).
/LEFT Vertical axis on left.
Plus all keywords accepted by PLOT.
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: Bar is positioned using the POSITION keyword.
To display a title use TITLE and so on.
MODIFICATION HISTORY:
R. Sterner, 13 Dec, 1993
R. Sterner, 1994 Jul 5 --- Added axis positioning.
R. Sterner, 1995 Dec 10 --- Allow position to be in device coords.
R. Sterner, 1995 Dec 18 --- Fixed to not clobber current xy scaling.
R. Sterner, 1996 Dec 9 --- Added CCLIP keyword.
R. Sterner, 1998 Jan 23 --- Added charthick keyword.
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cbar.pro)
NAME:
CED1
PURPOSE:
Simple widget to edit a single color table entry.
CATEGORY:
CALLING SEQUENCE:
ced1, index
INPUTS:
index = color table index to edit. in
KEYWORD PARAMETERS:
Keywords:
TITLE=txt Title text to display.
/HSV means work in Hue, Saturation, and Value
coordinates (def=Red, Green, Blue).
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 29 Oct, 1993
R. Sterner, 29 Oct, 1993
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ced1.pro)
NAME:
CENTERTLB
PURPOSE:
This is a utility routine to position a widget program
on the display at an arbitrary location. By default the
widget is centered on the display.
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:
Utilities
CALLING SEQUENCE:
CenterTLB, tlb, [x, y, /NOCENTER]
REQUIRED INPUTS:
tlb: The top-level base identifier of the widget program.
OPTIONAL INPUTS:
x: Set this equal to a normalized position for the center
of the widget as measured from the left-hand side of the screen.
The default value is 0.5 (the center) Setting this equal to 1.0
places the widget at the far right-hand side of the screen.
y: Set this equal to a normalized position for the center
of the widget as measured from the bottom of the screen.
The default value is 0.5 (the center) Setting this equal to 1.0
places the widget at the top of the screen.
KEYWORDS:
NOCENTER: By default, the center of the widget is positioned at the
location specified by the x and y parameters. If NOCENTER is set
to a non-zero value, then the upper left corner of the widget
is postioned at the specifed location.
PROCEDURE:
The program should be called after all the widgets have
been created, but just before the widget hierarchy is realized.
It uses the top-level base geometry along with the display size
to calculate offsets for the top-level base that will center the
top-level base on the display.
COMMENT:
Regardless of the values set for x, y and NOCENTER, the widget
is not permitted to run off the display.
MODIFICATION HISTORY:
Written by: Dick Jackson, 12 Dec 98.
Modified to use device-independent Get_Screen_Size
function. 31 Jan 2000. DWF.
Added x, y, NOCENTER and run-off protection. 26 Jan 2001. BT.
###########################################################################
LICENSE
This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.
Copyright Š 1998-2000 Fanning Software Consulting
This software is provided "as-is", without any express or
implied warranty. In no event will the authors be held liable
for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation
would be appreciated, but is not required.
2. Altered source versions must be plainly marked as such, and must
not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
For more information on Open Source Software, visit the Open Source
web site: http://www.opensource.org.
###########################################################################
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\centertlb.pro)
NAME:
CGM
PURPOSE:
Toggles graphics redirection to a *.cgm file on or off.
CATEGORY:
CALLING SEQUENCE:
cgm, [file]
INPUTS:
file = optional cgm file name. in
Default file name is seconds after midnight, like
31412.cgm.
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
cgm
NOTES:
Notes: Computer Graphics Metafile (CGM) format files are
useful because they may be imported into word processor
documents. An initial color table warning message appears
to be harmless.
MODIFICATION HISTORY:
R. Sterner 2 Dec, 1992
R. Sterner, 29 Jan, 1993 --- Revised.
Copyright (C) 1992, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cgm.pro)
NAME:
CHEBCOEF
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Estimate Chebyshev polynomial coefficients of a function on an interval
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
p = CHEBCOEF(FUNC, PRIVATE, FUNCTARGS=functargs, /DOUBLE, /EXPRESSION, $
PRECISION=prec, ERROR=err, NMAX=nmax, INTERVAL=interval, $
REDUCE_ALGORITHM=, STATUS=)
DESCRIPTION:
CHEBCOEF estimates the coefficients for a finite sum of Chebyshev
polynomials approximating the function FUNC(x) over an interval.
The user can choose the desired precision and maximum number of
chebyshev coefficients.
This routine is intended for functions which can be evaluated to
full machine precision at arbitrary abcissae, and which are smooth
enough to ensure that the coefficients are a decreasing sequence.
For already-tabulated or potentially noisy data, the routines
CHEBGRID or CHEBFIT should be used instead.
The function to be approximated may either be the name of an IDL
function (the default behavior), or an IDL expression (using the
/EXPRESSION keyword).
The procedure uses a modified form of the classic algorithm for
determining the coefficients, which relies the orthogonality
relation for Chebyshev polynomials. The interval [a,b] is
subdivided successively into sets of subintervals of length
2^(-k)*(b-a),(k = 0,1,2...). After each subdivision the
orthogonality properties of the Chebyshev polynomials with respect
to summation over equally-spaced points are used to compute two
sets of approximate values of the coefficients cj, one set
computed using the end-points of the subintervals, and one set
using the mid-points. Certain convergence requirements must be
met before terminating. If the routine fails to converge with 64
coefficents, then the current best-fitting coefficients are
returned, along with an error estimate in the ERROR keyword.
CHEBCOEF never returns more than 64 coefficients.
The coefficients may be further refined. If the keyword
REDUCE_ALGORITHM is set to a value of 1, then any high order
coefficients below a certain threshold are discarded. If
REDUCE_ALGORITHM is set to 2 (the default), then all coefficients
below the threshold are discarded rather than just the high order
ones. The threshold is determined by the PRECISION keyword.
INPUTS:
FUNC - a scalar string, the name of the function to be
approximated, or an IDL string containing an expression to
be approximated (if /EXPRESSION is set).
PRIVATE - any optional variable to be passed on to the function to
be integrated. For functions, PRIVATE is passed as the
second positional parameter; for expressions, PRIVATE can
be referenced by the variable 'P'. CHEBCOEF does not
examine or alter PRIVATE.
RETURNS:
An array of Chebyshev coefficients which can be passed to
CHEBEVAL. NOTE: the convention employed here is such that the
constant term in the expansion is P(0)*T0(x) (i.e., the convention
of Luke), and not P(0)/2 * T0(x).
KEYWORD PARAMETERS:
DOUBLE - if set, then computations are done in double precision
rather than single precision.
ERROR - upon return, this keyword contains an estimate of the
maximum absolute error in the approximation.
EXPRESSION - if set, then FUNC is an IDL expression to be
approximated, rather than the name of a function.
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by FUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks. By default, no extra parameters
are passed to the user-supplied function.
INTERVAL - a 2-element vector describing the interval over which
the polynomial is to be evaluated.
Default: [-1, 1]
NMAX - a scalar, the maximum number of coefficients to be
estimated. This number may not exceed 64.
Default: 64
PRECISION - a scalar, the requested precision in the
approximation. Any terms which do not contribute
significantly, as defined by this threshold, are
discarded. If the function to be estimated is not
well-behaved, then the precision is not guaranteed to
reach the desired level. Default: 1E-7
REDUCE_ALGORITHM - a scalar integer, describes how insignificant
terms are removed from the fit. If 0, then all terms
are kept, and none are dicarded. If 1, then only
trailing terms less than PRECISION are discarded. If
2, then both trailing and intermediate terms less than
PRECISION are discarded.
Default: 2
STATUS - upon return, this keyword contains information about the
status of the approximation. A value of -1 indicates bad
input values; a value of 0 indicates the required
accuracy was not obtained; a value of 1 indicates
success.
EXAMPLE:
x = dindgen(1000)/100 ; Range of 0 to 10
p = chebcoef('COS(x)', /expr, interval=[0d, 10d]) ;; Compute coefs
y = chebeval(x, p, interval=[0d,10d]) ;; Eval Cheby poly
plot, x, y - cos(x) ; Plot residuals
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
CERN, 1995, CERN Program Library, Function E406
Luke, Y. L., *The Special Functions and Their Approximations*,
1969, Academic Press, New York
MODIFICATION HISTORY:
Written and documented, CM, June 2001
Copyright license terms changed, CM, 30 Dec 2001
Added usage message, CM, 20 Mar 2002
Changed docs slightly, CM, 25 Mar 2002
$Id: chebcoef.pro,v 1.6 2002/05/03 18:40:27 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebcoef.pro)
NAME:
CHEBEVAL
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Evaluate a Chebyshev polynomial on an interval, given the coefficients
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
y = CHEBEVAL(X, P, INTERVAL=interval, DERIVATIVE=deriv)
DESCRIPTION:
CHEBEVAL computes the values of a Chebyshev polynomial function at
specified abcissae, over the interval [a,b]. The user must supply
the abcissae and the polynomial coefficients. The function is of
the form:
N
y(x) = Sum p_n T_n(x*) x in [a,b]
i=0
Where T_n(x*) are the orthogonal Chebyshev polynomials of the
first kind, defined on the interval [-1,1] and p_n are the
coefficients. The scaled variable x* is defined on the [-1,1]
interval such that (x*) = (2*x - a - b)/(b - a), and x is defined
on the [a,b] interval.
The derivative of the function may be computed simultaneously
using the DERIVATIVE keyword.
The is some ambiguity about the definition of the first
coefficient, p_0, namely, the use of p_0 vs. the use of p_0/2.
The p_0 definition of Luke is used in this function.
INPUTS:
X - a numerical scalar or vector, the abcissae at which to
evaluate the polynomial. If INTERVAL is specified, then all
values of X must lie within the interval.
P - a vector, the Chebyshev polynomial coefficients, as returned
by CHEBFIT or CHEBCOEF.
RETURNS:
An array of function values, evaluated at the abcissae. The
numeric precision is the greater of X or P.
KEYWORD PARAMETERS:
DERIVATIVE - upon return, a vector containing the derivative of
the function at each abcissa is returned in this
keyword.
INTERVAL - a 2-element vector describing the interval over which
the polynomial is to be evaluated.
Default: [-1, 1]
EXAMPLE:
x = dindgen(1000)/100 ; Range of 0 to 10
p = chebcoef('COS(x)', /expr, interval=[0d, 10d]) ;; Compute coefs
y = chebeval(x, p, interval=[0d,10d]) ;; Eval Cheby poly
plot, x, y - cos(x) ; Plot residuals
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
CERN, 1995, CERN Program Library, Function E407
Luke, Y. L., *The Special Functions and Their Approximations*,
1969, Academic Press, New York
MODIFICATION HISTORY:
Written and documented, CM, June 2001
Copyright license terms changed, CM, 30 Dec 2001
Added usage message, CM, 20 Mar 2002
$Id: chebeval.pro,v 1.5 2002/03/25 06:42:50 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebeval.pro)
NAME:
CHEBFIT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Fit Chebyshev polynomial coefficients to a tabulated function
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
p = CHEBFIT(X, Y, ERR, INTERVAL=interval, NMAX=nmax,
PRECISION=prec, /EVEN, /ODD, REDUCE_ALGORITHM=)
DESCRIPTION:
CHEBFIT fits a series of Chebyshev polynomials to a set of
tabulated and possibly noisy data points. The functions MPFIT and
CHEBEVAL, available from the above web page, must also be in your
IDL path for this function to work properly. The user can choose
the desired precision and maximum number of chebyshev
coefficients.
This function is intended for use on already-tabulated data which
are potentially noisy. The user should never expect more than
NPOINTS terms, where NPOINTS is the number of (x,y) pairs. For
functions which can be evaluated to full machine precision at
arbitrary abcissae, the routine CHEBCOEF should be used instead.
For exact data tabulated on a regular grid, the routine CHEBGRID
should be tried.
The user can also specify that the function is even or odd, using
the keywords EVEN or ODD. This saves computation time because
certain terms in the expansion can be ignored. For the purposes
of this function even and odd refer to the symmetry about the
center of the interval.
The algorithm is employed in three steps. In the first step, the
coefficients are estimated at a crude level. In the second step,
it is determined whether certain coefficients are deemed
"ignoreable", i.e., they do not contribute significantly to the
function and are discarded. The operation of this step is
determined by the REDUCE_ALGORITHM keyword. Finally, the
remaining "good" coefficients are re-fitted to achieve the best
fit.
INPUTS:
X, Y - the x- and y- tabulated values to be fitted.
ERR - (optional) the y-error bar associated with each (x,y) pair.
Default: 1
RETURNS:
An array of Chebyshev coefficients which can be passed to
CHEBEVAL. NOTE: the convention employed here is such that the
constant term in the expansion is P(0)*T0(x) (i.e., the convention
of Luke), and not P(0)/2 * T0(x).
KEYWORD PARAMETERS:
EVEN, ODD - if set, then the fitting routine assumes the function
is even or odd, about the center of the interval.
INTERVAL - a 2-element vector describing the interval over which
the polynomial is to be evaluated.
Default: [-1, 1]
NMAX - a scalar, the maximum number of polynomial terms to be
fitted at one time.
Default: 16
PRECISION - a scalar, the requested precision in the fit. Any
terms which do not contribute significantly, as
defined by this threshold, are discarded. If the
function to be fitted is not well-behaved, then the
precision is not guaranteed to reach the desired
level.
Default: 1E-7
REDUCE_ALGORITHM - a scalar integer, describes how insignificant
terms are removed from the fit. If 0, then all terms
are kept, and none are dicarded. If 1, then only
trailing terms less than PRECISION are discarded. If
2, then both trailing and intermediate terms less than
PRECISION are discarded.
Default: 2
EXAMPLE:
x = dindgen(1000)/100 ; Range of 0 to 10
y = cos(x) + randomn(seed,1000)*0.01 ; Function with some noise
p = chebfit(x, y, interval=[0d,10d])
plot, x, y - chebeval(x,p, interval=[0d,10d])
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
CERN, 1995, CERN Program Library, Function E407
Luke, Y. L., *The Special Functions and Their Approximations*,
1969, Academic Press, New York
MODIFICATION HISTORY:
Written and documented, CM, June 2001
Copyright license terms changed, CM, 30 Dec 2001
Added usage message, CM, 20 Mar 2002
Slight docs change, CM, 25 Mar 2002
$Id: chebfit.pro,v 1.6 2002/05/03 18:40:19 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebfit.pro)
NAME:
CHEBGRID
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Estimate Chebyshev polynomial coefficients of a function on a grid
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
p = CHEBGRID(T, X, [ DXDT, NPOINTS=, NPOLY=, NGRANULE= , $
RMS=, DRMS=, RESIDUALS=, DRESIDUALS= , $
XMATRIX=, DXMATRIX=, RESET=,
DERIV_WEIGHT= ] )
DESCRIPTION:
CHEBGRID estimates the coefficients for a finite sum of Chebyshev
polynomials approximating a continuous tabulated function over an
interval. The function (and optionally its derivative) must be
tabulated on a regularly sampled grid. The implementation of this
function is taken from a method described by X. X. Newhall, used
in estimating coefficients for ephemerides in the solar system.
The tabulated function is assumed to be continuous over the entire
interval. A Chebyshev series is fitted to the function over small
segments, called granules. The size of each granule, the number
of points in each granule, and the number of Chebyshev polynomials
are all configurable.
Users may specify either the function alone, or the function and
its first derivative. By also giving the tabulated derivative, a
more accurate Chebyshev polynomial can be developed. Aside from
the constraints mentioned in the next paragraph, the polynomial
that is returned is the best-fit polynomial in a least-squares
sense.
Here is a definition of terms:
GRANULE - a single continuous fitted segment. The length of the
granule, NGRANULE, is specified in units of the tabulated
grid size. Because of the continuity requirements developed
below, granules will always overlap at their endpoints.
Thus, then length of a granule should be a factor of
N_ELEMENTS(X)-1. For simple functions over short intervals,
the granule size can be equal to N_ELEMENTS(X)-1
NUMBER OF POINTS the number of points, NPOINTS, within a
granule to be fitted to the polynomial, not necessarily
equal to the granule size. The greater the number of
points, the more computation time and storage is required.
This number *must* be a factor of NGRANULE. Typically
NPOINTS is a number between 8 and 12. Because of the
single-point overlap between granules (see below), the
actual number of points per fit is NPOINTS+1.
NUMBER OF POLYNOMIALS the number of Chebyshev polynomial terms,
NPOLYNOMIAL, to be fitted per granule. The greater the
number of polynomial terms, the more computation time and
storage is required, but also the greater the approximating
precision of the fit.
The particular set of Chebyshev polynomial coefficients developed
by this function have some special properties. If both the
function and its derivative are specified, then the value and
derivative of the interpolating polynomial at the granule
endpoints will be exactly equal to the tabulated endpoint values.
This feature allows many approximations to be strung together
piecewise, and the function value and first derivative will be
continuous across granule boundaries.
If only the function value is specified, then only the function
value will be continuous at the granule endpoints, and not the
derivative.
An extensive set of statistics are computed to assess the quality
of the Chebyshev polynomial fit. The keywords RESIDUALS and
DRESIDUALS return the residuals of the fit after subtracting the
interpolation. The RMS and DRMS keywords return the root mean
squared deviations between data and model.
If the user does not know how many granules, points, or polynomial
coefficients to use, then he or she should try several
combinations and see which minimizes the r.m.s. value with the
fewest number of coefficients.
If the XMATRIX and DXMATRIX keywords are passed, then CHEBGRID
attempts to avoid recomputing several of the matrices it uses in
estimating the coefficients. If multiple calls to CHEBGRID are to
be made, some compution time savings can be made. In the first
call CHEBGRID the required matrices are computed and returned. In
subsequent calls, CHEBGRID detects the XMATRIX and DXMATRIX
keyword values and uses those values if it can.
The user can also estimate their own coefficients. The matrices
returned are (NPOINTS+1)x(NPOLYNOMIAL). The coefficients from a
NPOINTS+1 tabulation, X, are found by:
PCHEB = XMATRIX ## X + DXMATRIX ## DXDT
if derivative information is known, or
PCHEB = XMATRIX ## X
if no derivative information is known. [ Note: the matrices are
different, depending on whether derivative information is known or
not. ]
INPUTS:
T - array of regularly sampled *independent* variables. The number
of elements in T should be a multiple of NGRANULE, plus one.
X - array of regularly sampled *dependent* variables. The number
of elements in X should be equal to the number of elements in
T.
DXDT - optionally, a tabulated array of first derivatives of X
with respect to T, at the same grid points.
KEYWORD PARAMETERS:
NGRANULE - size of a "granule", in grid intervals. NGRANULE must
be at least 2, and a factor of N_ELEMENTS(T)-1.
Default: 8
NPOINTS - number of points per granule that are fitted. NPOINTS
must be at least 2, and a factor of NGRANULE.
Default: NGRANULE
NPOLYNOMIAL - number of Chebyshev polynomial terms per fit.
NPOLYNOMIAL must be at least 2 and less than
2*(NPOINTS+1), when derivative information is
specified; or less than NPOINTS+1, when no
derivative information is specified.
Default: 7
RESIDUALS - upon return, an array of size N_ELEMENTS(T), with
residuals of the tabulated function minus the
interpolated function.
DRESIDUALS - same as RESIDUALS, but for the function's first
derivative.
RMS - upon return, the root mean square of the function value
residuals.
DRMS - same as RMS, but for the function's first derivative.
XMATRIX - upon return, the matrix used to compute Chebyshev
polynomial coefficients from the function value.
Upon input, CHEBGRID determines if XMATRIX will apply to
the data, and if so, XMATRIX is reused rather than
computed. If XMATRIX cannot be reused, then it is
computed afresh, and the new value is returned in the
XMATRIX keyword.
The user should not modify the contents of the is array.
DXMATRIX - same as XMATRIX, but for the function's first
derivative.
RESET - if set, force a recomputation of XMATRIX and/or DXMATRIX.
DERIV_WEIGHT - amount of weight to give to function derivative,
relative to the function value.
Default: 0.16d
RETURNS:
An array of coefficient values. The dimensions of the array are
NPOLYNOMIALxNSEGS, where NSEGS is the number of granules in the
entire interval.
EXAMPLE:
;; Estimate Chebyshev coefficients for the function SIN(X), on the
;; interval [-1,+1].
xx = dindgen(9)/4d - 1d ;; Regular grid from -1 to 1 (9 points)
yy = sin(xx) ;; Function values, sin(x), ...
dy = cos(xx) ;; ... and derivatives
;; Estimate coefficients using CHEBGRID (single granule of 8 intervals)
p = chebgrid(xx, yy, dy, npoints=8, ngranule=8, npoly=10)
xxx = dindgen(1001)/500 - 1d ;; New grid for testing
res = sin(xxx) - chebeval(xxx, p)
plot, xxx, res
;; Same as example above, except extended range to [-1, +15],
using eight granules.
xx2 = dindgen(65)/4d - 1
yy2 = sin(xx2)
dy2 = cos(xx2)
p = chebgrid(xx2, yy2, dy2, ngranule=8, npoint=8, npoly=10)
help, p
P DOUBLE = Array[10, 8]
;; (i.e., 10 polynomial coefficients over 8 granules)
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
Newhall, X. X. 1989, Celestial Mechanics, 45, p. 305-310
MODIFICATION HISTORY:
Written, CM, Feb 2002
Documented, CM, 24 Mar 2002
Corrected documentation, CM, 28 Apr 2002
$Id: chebgrid.pro,v 1.3 2002/05/02 07:00:43 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\chebgrid.pro)
NAME: CHEBYSHEV_POL VERSION: 4.0 PURPOSE: Calculates Chebyshev polynomials Tn and associated functions. CATEGORY: Mathematical function. CALLING SEQUENCE: Result = CHEBYSHEV_POL( X, N, [ /ASSOCIATED]) INPUTS: X Numeric, absolute values must be <= 1, otherwise arbitrary. N Nonnegative scalar, rounded to integer on input. Defaults to 0. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /ASSOCIATED Switch. When set, an associated function, SIN(N*ARCCOS(X)) is returned. OUTPUTS: Returns the values of the Chebyshev polynomial T(n,x), defined as COS(N*ARCCOS(X)) or (when ASSOCIATED is set), the values of the associated Chebyshev function, SIN(N*ARCCOS(X)). OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None other then the restrictions on X, and N as mentioned above. PROCEDURE: Using the mathematical definition. Calling DEFAULT and FPU_FIX from MIDL. MODIFICATION HISTORY: Created 20-DEC-1994 by Mati Meron. Modified 15-SEP-1998 by Mati Meron. Underflow filtering added. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\chebyshev_pol.pro)
NAME:
CHECK5
PURPOSE:
Check if running IDL version 5 or greater.
CATEGORY:
CALLING SEQUENCE:
flag = check5()
INPUTS:
KEYWORD PARAMETERS:
OUTPUTS:
flag = 0 if false, 1 if true. out
COMMON BLOCKS:
NOTES:
Notes: Useful to check if the current IDL version
supports features from version 5 or greater.
MODIFICATION HISTORY:
R. Sterner, 1998 Jan 23
Copyright (C) 1998, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\check5.pro)
NAME:
CHECKER
PURPOSE:
Return a checker board pattern array of 0 and 1.
CATEGORY:
CALLING SEQUENCE:
checker, nx, ny, pat
INPUTS:
nx, ny = array size in x and y. in
KEYWORD PARAMETERS:
OUTPUTS:
pat = resulting array. out
COMMON BLOCKS:
NOTES:
Note: an example 4 x 4 array:
0 1 0 1
1 0 1 0
0 1 0 1
1 0 1 0
MODIFICATION HISTORY:
R. Sterner, 30 Dec, 1989
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\checker.pro)
NAME:
CHGCOLOR
PURPOSE:
The purpose of this routine is to allow the user to change
the color at a particular color index. The user is able to
mix their own color by manipulating red, green, and blue
sliders. This routine is ideal for changing axes or background
colors of a plot, for example. The routine works on 8-bit,
16-bit, and 24-bit displays.
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:
Widgets, Colors.
CALLING SEQUENCE:
CHGCOLOR, index
REQUIRED INPUTS:
INDEX: The color index to be changed. It must be a value
between 0 and 255.
KEYWORD PARAMETERS:
LABEL: Text that goes next to the color window. The default is
"Resulting Color".
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
NOTIFYID: A a 2 column by n row array that contains the IDs of widgets
that should be notified when CHGCOLOR changes a color. The first
column of the array contains widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarch in which the corresponding widgets in the first column
are located. (The purpose of the top widget IDs is to make it
possible for the widget in the first column to get the "info"
structure of the widget program.) An CHGCOLOR_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {CHGCOLOR_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
r:(!D.N_COLORS < 256), g:(!D.N_COLORS < 256), b:(!D.N_COLORS < 256)}
The ID field will be filled out with NOTIFYID(0, n) and the TOP
field will be filled out with NOTIFYID(1, n).
TITLE: This is the window title. It is "Modify Drawing Color" by
default. The program is registered with the name "chgcolor " plus
the TITLE string. The register name is checked before the widgets
are defined. This gives you the opportunity to have multiple copies
of CHGCOLOR operating simultaneously. (For example, one will change
the background color and one will change the plotting color.)
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color at the specified index is changed. Events are sent to widgets
if the NOTIFYID keyword is used.
RESTRICTIONS:
None.
EXAMPLE:
To change the background color of a plot, type:
CHGCOLOR, !P.Background
To see a more complete example, look at the program SLICE
in the Coyote Software Library:
ftp://ftp.frii.com/pub/dfanning/outgoing/idl_examples
MODIFICATION HISTORY:
Written by David Fanning, 23 April 97.
12 May 97, Fixed a bug in the way colors were loaded when
a tracking event occurred. DWF
13 May 97, Added a JUST_REGISTER keyword and set it up for
running in IDL 5.0 as a non-blocking widget.
27 Sept 98. Fixed problems caused by IDL 5.1 color changes.
27 Sept 98. Removed JUST_REGISTER keyword. Made widget non-blocking.
03 Nov 98. Modified layout and added slider ganging. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\chgcolor.pro)
NAME:
CHINIT
PURPOSE:
Initializes chart setup. Good for viewgraphs.
CATEGORY:
CALLING SEQUENCE:
chinit
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/HARD means plot on postscript printer (else screen).
/LAND means use landscape mode (else portrait mode).
UNITS=u Set plot units to 'inches' (def) or 'cm'.
BPOSITION=p scalar or array giving list of outline
offsets in UNITS from edge of page. Def=no outline.
BTHICKNESS=t scalar or array giving outline thicknesses
for each outline given in BPOS. Def=1.
XOFFSET=xoff Set chart X offset in UNITS (def=0).
YOFFSET=yoff Set chart Y offset in UNITS (def=0).
/MOVE means just move origin. The only other keywords
recognized with /MOVE are XOFFSET and YOFFSET.
/MOVE should be used on the second and later calls to
CHINIT to reposition the position of graphics.
WINSIZE=sz Multiply default screen window size by this factor.
Output keywords:
LAST=lst Highest available plot color, returned.
FONT=f "!17" for screen, null string for /HARD.
Put in front of first string printed to make
device independent.
FACTOR=f text size factor. 1 for /HARD, 0.68 for screen.
Multiply text size by this for device independence.
OUTPUTS:
COMMON BLOCKS:
chinit_com
NOTES:
Notes: Also erases to white and sets default plot
color to black. All plot commands may then be
given in units of inches or cm, whichever were set.
Plot size:
Portrait: 7.5 by 10 inches (360 by 480 on screen)
Landscape: 9.5 by 7 inches (640 by 472 on screen)
The screen view is not always close to the hard copy.
Spaces are handled differently, and strings that fit
for the hardcopy are sometimes too long on the screen.
MODIFICATION HISTORY:
R. Sterner, 17 Aug, 1991
R. Sterner, 9 Jan, 1992 --- added /MOVE, also common.
R. Sterner, 1 Sep, 1992 --- added WINSIZE
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\chinit.pro)
NAME:
CHISQR
PURPOSE:
Compute the Chi Square statistic of a function and a fit
to the function.
CALLING SEQUENCE:
Result=CHISQR(Y,SIGMA_Y,YFIT)
INPUTS:
Y - Input array.
SIGMA_Y - Uncertainty in Y.
YFIT - Fit to Y.
PROCEDURE:
CHISQR=TOTAL((Y-YFIT)^2/SIGMAY^2)
MODIFICATION HISTORY:
David L. Windt, Bell Labs, November 1989
windt@bell-labs.com
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\chisqr.pro)
NAME:
CHKSTRU (function)
PURPOSE:
Check validity of a structure and test if necessary
fields are contained. The result of this function will
be 0 if the argument is not a structure (this includes
undefined values) or if the argument does not contain
all the tags requested with the FIELDS argument.
CATEGORY:
General Programming
CALLING SEQUENCE:
res=CHKSTRU(STRUCTURE,FIELDS [,/VERBOSE])
INPUTS:
STRUCTURE --> the structure to be tested. If STRUCTURE is
not of type structure, the function will return 0
FIELDS --> a string or string array with field names to
be contained in STRUCTURE. CHKSTRU returns 1 (true)
only if all field names are contained in STRUCTURE.
The entries of FIELDS may be upper or lowercase.
KEYWORD PARAMETERS:
INDEX --> a named variable that will contain the indices of
the required field names in the structure. They can then
be assessed through structure.(index(i)) . Index will
contain -1 for all fields entries that are not in the
structure.
/VERBOSE --> set this keyword to return an error message
in case of an error.
OUTPUTS:
CHKSTRU returns 1 if successful, otherwise 0.
SUBROUTINES:
REQUIREMENTS:
NOTES:
This routine should still work with IDL 5.0 or even 4.0
EXAMPLE:
test = { a:1, b:2, c:3 }
required = ['a','c']
if CHKSTRU(test,required) then print,'found a and c.'
MODIFICATION HISTORY:
mgs, 02 Mar 1998: VERSION 1.00
mgs, 07 Apr 1998: - second parameter (FIELDS) now optional
mgs, 23 Aug 2000: - changed copyright to open source
- changed array indices to [] and "emacsified"
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\chkstru.pro)
NAME:
CHOICE
PURPOSE:
Allows user to choose interactively from several options
CATEGORY:
General Programming
CALLING SEQUENCE:
RESULT = CHOICE(VALUES [,options])
INPUTS:
VALUES -> a string array containing the selectable options
KEYWORD PARAMETERS:
TITLE -> title to be displayed on top of the selection menu
DEFAULT -> a default selection (to allow user to simply press enter)
BY_INDEX -> return selection index rather than value
/NOABORT -> prevents addition of 'ABORT' to selection
OUTPUTS:
CHOICE returns a string containing the selected value or
the index of the selection if keyword /BY_INDEX is set.
SUBROUTINES:
REQUIREMENTS:
NOTES:
CHOICE automatically adds 'ABORT' to the list of selections.
If keyword BY_INDEX is set then ABORT will return -1
(unless /NOABORT keyword is set)
EXAMPLE:
DIRNAMES = ['~my/dir/','~your/dir/','~any/dir']
DIR = CHOICE(DIRNAMES,TITLE='Select Directory')
IF (DIR ne 'ABORT') THEN BEGIN
OPENR, U1, DIR+FILE, /GET_LUN
READF, U1, DATA
CLOSE, U1
FREE_LUN,U1
ENDIF ELSE PRINT,'ABORTED !'
MODIFICATION HISTORY:
mgs, 26 Sep 1997: VERSION 1.00
mgs, 17 Nov 1998: - added DEFAULT and NOABORT keywords
mgs, 23 Aug 2000: - changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\choice.pro)
NAME:
CIndex
PURPOSE:
This is a program for viewing the current colors in the
colortable with their index numbers overlayed on each color.
On 24-bit systems you must click the cursor in the graphics window
to see the colors in the current color table.
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: CIndex
INPUTS: None.
Optional Inputs: None
OUTPUTS: None
OPTIONAL OUTPUTS: None
KEYWORD Parameters: None
COMMON BLOCKS: None
SIDE EFFECTS: None
RESTRICTIONS: Reqires XCOLORS and TVIMAGE from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
http://www.dfanning.com/programs/xtvimage.pro
PROCEDURE:
Draws a 31x25 set of small rectangles in 256 different colors.
Writes the color index number on top of each rectangle.
MODIFICATION HISTORY: Written by David Fanning, May 1995
Widgetized and made it work in 24-bit color. Colors are
updated by clicking in window. 22 Oct 98. DWF
Replace POLYFILL with TV command to avoid underflow error in
Z-buffer. 8 March 99. DWF
Fixed a problem with 24-bit devices with color decomposition ON. 15 Feb 2000. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\cindex.pro)
NAME:
CIRCLE
VERSION:
4.0
PURPOSE:
Draws a circle, around CENTER, with radius given by RADIUS, X_RADIUS,
or Y_RADIUS. The drawing is done in the currently defined plot area.
One and ONLY ONE of the three radius values MUST be provided. RADIUS
and X_RADIUS are equivalent. Alternatively, a *SHAPE* representation
(see SHAPE_VER for definition) of the circle may be returned through
the SHAPEOUT keyword. DATA coordinates are used unless one of the
keywords /DEVICE or /NORMAL is set. The circle is drawn so as to
appear visually as a circle, regardless of the coordinates used.
CATEGORY:
General Graphics.
CALLING SEQUENCE:
CIRCLE, CENTER = C, {RADIUS=R, X_RADIUS=XR, Y_RADIUS = YR} [, keywords]
INPUTS:
None.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
CENTER
Two dimensional vector, circle center location, mandatory.
RADIUS |
Scalar, value of radius (measured in the X direction). | One
X_RADIUS | and only one
Scalar, value of radius (measured in the X direction). | must be
Y_RADIUS | provided.
Scalar, value of radius (measured in the Y direction). |
/FILL
Switch. causes the circle to be filled with a solid pattern.
/DEVICE
Standard IDL plotting interpretation.
/NORMAL
Ditto.
/NO_SHOW
Switch. If set, no plotting is done, but the shape is generated and
may be returned through SHAPEOUT.
SHAPEOUT
Optional output, see below.
_EXTRA
A formal keyword used to pass all plotting keywords. Not to be used
directly. See comment in RESTRICTIONS.
OUTPUTS:
None.
OPTIONAL OUTPUT PARAMETERS:
SHAPEOUT
When provided with the name of a variable, on return the variable
contains the *SHAPE* representation of the circle.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
While nominally all graphics keywords can be passed (through _EXTRA),
care should be exercised to use only the applicable ones (ELLIPSE and
PLOTS keywords usually, POLYFILL keywords when /FILL is used.
PROCEDURE:
Uses calls to COO_CONV, ONE_OF and SHAPE_COCON from MIDL. Converts all
parameters to device coordinates and calls ELLIPSE (also from MIDL)
to do the actual plotting.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 15-DEC-1993 by Mati Meron. Now CIRCLE takes advantage of the
keyword inheritance property and accepts all IDL plotting keywords.
Modified 25-JUL-1999 by Mati Meron. Added keywords NO_SHOW and
SHAPEOUT.
Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\circle.pro)
ROUTINE: CLASSIFY
FUNCTION:
Display the physical locations of points selected on the
basis of image quantities, xa and ya. An interactive
cursor box is used to select clusters of points from the
2-d scatter plot of xa vs ya. These points are drawn on a
satellite image to indicate their actual physical
location.
CALLING SEQUENCE:
classify,xa,ya,class_out,image=image,class_in=class_in,select=select, $
n_samples=n_samples,blow_up=blow_up,title=title,ytitle=ytitle, $
xtitle=xtitle,ititle=ititle
CATEGORY:
Interactive graphics
REQUIRED INPUTS:
XA First channel parameter, x-axis of scatter plot
YA Second channel parameter, y-axis of scatter plot
OPTIONAL INPUTS (keyword parameters):
IMAGE Image of a particular satellite channel over which
points are ploted. If not supplied points are ploted
over blank plot
CLASS_IN (Byte array) Pixel color class initialization. Each
element corresponds to one pixel in the sample set
(see n_samples, below). An initial run of CLASSIFY
will generate the byte array, CLASS_OUT. This can be
used in a subsequent run of CLASSIFY with
CLASS_IN=CLASS_OUT to restart CLASSIFY in its former
state. When set, CLASS_IN overrides the effect of
SELECT and N_SAMPLES, below.
N_SAMPLES 2 element vector specifying the number of samples in the
x and y directions. E.g., if N_SAMPLES=[100,150],
then the scatter plot will consist of a 100x150
element subset of the original image. If N_SAMPLES
is not set, a default number of samples in the x and
y directions is used.
SELECT Vector of pre-selected indices (longword integers).
For example, SELECT=WHERE(XX LT 10) chooses only
those sample points for which parameter xx
is less than 10.
BLOW_UP Two element vector of specifying the image size blowup factor
TITLE Title of scatter plot
XTITLE Scatter plot x-axis label
YTITLE Scatter plot y-axis label
ITITLE Plot title of satellite image
NO_COLOR don't use color, show points with unique symbols
OUTPUTS
CLASS_OUT (Byte array) Color class of each sample point. Values
between 1 - 6 indicate different selected color
classes. Greater values indicate unselected points
which can be selected with the cursor. CLASS_OUT can
be used in another call to CLASSIFY, e.g.,
CLASSIFY,XA,YA,CLASS_OUT ; followed by,
CLASSIFY,XA,YA,CLASS_IN=CLASS_OUT
COMMON BLOCKS:
none
SIDE EFFECTS:
Two windows are created to contain the scatter plot (window 0) and
the physical image (window 2). Calls TVLCT to load a customized
color table with grey scale for byte values greater than 10 and
discreet colors for byte values between 1 and 10.
RESTRICTIONS:
Works only on window system drivers
PROCEDURE:
Points which enter into the cursor box are hi-lighted and stored
for plotting on the satellite image. The left mouse button increases
the size of the cursor box while the middle mouse button decreases it
The right mouse button stops the selection process and displays a
pop-up menu with 4 options:
(n) select a new selection class (assign a new color)
(r) reset the selection set
(d) display the selection set on the satellite image
(p) save current plot to postscript file "plot.ps"
(q) clean up displays and quit
author: Paul Ricchiazzi oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\classify.pro)
ROUTINE: classplt
USEAGE: classplt,xx
classplt,xx,yy,alat,alon,$
[title=title,xtitle=xtitle,ytitle=ytitle,sym=sym]
PURPOSE: Draws two seperate plots to the graphics device:
1. 2-d scatter plot of yy vs xx
2. physical position of selected classes with respect
to coastline features.
INPUT:
xx index array of selected points for a class
(class definition mode)
xx 2-D array, x quantity of scatter plot (ploting mode)
yy 2-D array, y quantity of scatter plot
alat latitude array
alon longitude array
title plot title (optional). One or two element string array
if two strings are specified the first string is used to
title the scatter plot while the second titles the mapped
plot
xtitle x title (optional)
ytitle y title (optional)
sym a vector of symbol index values. Classes are assigned symbols
in the sequence specified in SYM. (default=[1,4,7,5,6,2])
(1=+, 2=*, 3=., 4=diamond, 5=triangle, 6=square, 7=x)
PROCEDURE: At least two steps are required to make plots with CLASSPLT:
1. In class definition mode CLASSPLT is called with a single
argument one or more times to accumulate class definitions
to be used later in the ploting mode.
2. In plotting mode CLASSPLT is called with at least 4
arguments. In this mode CLASSPLT produces a scatter
plot and position plot of the previously defined classes.
EXAMPLE:
a4=congrid(avhrr4,40,30) ; reduce size of sample set
a3=congrid(avhrr3,40,30) ; could also use SUPERPIX
classplt,inside(a4,a3-a4,[3,6,5,3],[4,3,5,4]) ; define classes
classplt,where(a4 gt -6 and a3-a4 lt 8) ;
classplt,where(a4 gt -17 and a3-a4 gt 8) ;
classplt,a4,a3-a4,alat,alon ; make the plot
Here is a sequence of commands which uses the interactive graphics
procedure, INSIDE, to simplify class specifcation.
classplt,inside(a4,a3-a4)
classplt,inside(a4,a3-a4)
classplt,inside(a4,a3-a4)
classplt,a4,a3-a4,alat,alon
COMMON BLOCKS: classblk
author: Paul Ricchiazzi oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\classplt.pro)
NAME:
CLIPBOARD
PURPOSE:
The purpose of this program is to copy the contents of a
graphics window to the clipboard for subsequent pasting into
applications such as Photoshop or Powerpoint.
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:
CLIPBOARD, window_index
OPTIONAL INPUTS:
window_index: The window index number of the graphics window to
copy. If absent, the current graphics window is used
by default.
OUTPUTS:
None.
COMMON BLOCKS:
None.
DEPENDENCIES:
Uses the IDLgrClipboard object introduced in IDL 5.2(?).
PROCEDURE:
Copies the window contents to a clipboard object.
EXAMPLE:
IDL> Window
IDL> Plot, Findgen(11)
IDL> CLIPBOARD
RESTRICTIONS:
May not work for all applications. Applications tested successfully
include: Framemaker, Powerpoint, Photoshop, Excel, Microsoft Word.
Converts 24-bit images to 2D images with color tables.
MODIFICATION HISTORY:
Written by: David W. Fanning, 24 October 2001.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\clipboard.pro)
ROUTINE: cliprange
PURPOSE: compute greyscale range for images, allowing for a fixed
percentage of the pixels to be within the greyscale range.
USEAGE: result=cliprange(qval,clip_top,clip_bot)
INPUT:
qval image array
clip_top fraction of pixels to be clipped off top of range
clip_bot fraction of pixels to be clipped off bottom of range
OUTPUT: result=[range_bot,range_top], where range_bot and range_top
are the numerical range of the color scale
EXAMPLE: compute colorscale range such that 99% of the pixels are
within the range:
range=cliprange(image,.005,.005)
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cliprange.pro)
NAME: closedev PURPOSE: This procedure close teh open graphic device CATEGORY: PLOT/MPLOT CALLING SEQUENCE: CLOSEDEV MODIFICATION HISTORY: Written by: F. Holland, 19 Jun, 1997 Modified: T.B. 1997-Nov
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\closedev.pro)
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:
Printing
CALLING SEQUENCE:
CLOSE_DEVICE [,OLD_DEVICE] [,keywords]
INPUTS:
OLD_DEVICE (str) -> 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 (str) -> 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 -> 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,
/GERMAN.
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 (str) -> name of the PostScript file.
This keyword is now obsolete since the name of the postscript
file is determined automatically. It is kept as a surrogate
for LABEL to ensure compatibility with older implementations.
OUTPUTS:
If postscript device is active, a *.ps file will be closed and
optionally sent to the printer.
SUBROUTINES:
REQUIREMENTS:
Needs STRDATE for the TIMESTAMP option.
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.
23 Aug 2000:
I am about to change to Liam Gumley's method for opening
postscript files. This routine is merely kept for compatibility!
EXAMPLE:
CLOSE_DEVICE
closes a postscript file (if opened) and resets the current
plotting device to 'X', 'WIN', or 'MAC' depending on the
OS_FAMILY.
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.
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
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\close_device.pro)
NAME:
close_device
PURPOSE:
This procedure close the open graphic device
CATEGORY:
PLOT/MPLOT
CALLING SEQUENCE:
CLOSE_DEVICE
KEYWORD PARAMETERS:
If the following graphical keywords are provided they are multiplied by
the quoted factors if a non-screen device is closed.
CHARSIZE = charsize (factor 1./1.72)
SYMSIZE = symsize (factor 1./1.72)
THICK = thick (factor 1./2.0)
CHARTHICK = charthick (factor 1./2.0)
XTHICK = xthick (factor 1./2.0)
YTHICK = ythick (factor 1./2.0)
MODIFICATION HISTORY:
Written by: F. Holland, 19 Jun, 1997
Modified: T.B. 1997-DEC-16
15.02.2000: charsize and symsize are divided by 1.72 (size_factor),
thick, charthick, xthick, and ythick are divided by 2.0 (thick_factor)
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\close_device.pro)
ROUTINE: cloud_art
PURPOSE: draw an idealized cloud
USEAGE: cloud_art,pos,bumps=bumps
INPUT:
pos normal coordinates of cloud frame, [xll,yll,xur,yur]
where ll=lower left corner and ur=upper right corner
KEYWORD INPUT:
bumps number of bumps on upper side of cloud. (default=6)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
w8x11
cloud_art,[.1,.8,.9,.9],bumps=8
AUTHOR: Paul Ricchiazzi 15 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cloud_art.pro)
NAME:
CLR_SCALE
PURPOSE:
Clear image scaling values embedded by put_scale.
CATEGORY:
CALLING SEQUENCE:
clr_scale, [img]
INPUTS:
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: Pixel value 90 is used to overwrite pixels 0 to 89
if 1234567890 is found in the first 10 pixels.
MODIFICATION HISTORY:
R. Sterner, 1995 Feb 28
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\clr_scale.pro)
ROUTINE: clstrshd
USEAGE: result=clstrshd(a, binsz)
result=clstrshd(a, binsz, /align, /compare)
PURPOSE: compute super pixel cluster shade statistical test
of a scene. the cluster shade is a test of skewness
in the greylevel histogram of each superpixel.
INPUT:
a image array
binsz A scalar specifying the number of horizontal and
vertical sub-pixels in one super pixel.
BINSZ must be an odd integer.
align If set, output arrays are REBINed back up to the
original size and output array cell centers are aligned
with input array cell centers.
compare if set, compare A and ABIN with the FLICK procedure
OUTPUT:
cluster shade value at superpixel cell centers.
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\clstrshd.pro)
NAME:
CM2NORM
PURPOSE:
Convert from cm to normalized coordinates.
CATEGORY:
CALLING SEQUENCE:
cm2norm, xcm, ycm, xn, yn
INPUTS:
xcm, ycm = coordinates of a point in cm. in
poscm = plot page position in cm. in
KEYWORD PARAMETERS:
OUTPUTS:
xn, yn = same point in normalized system. out
or
cm2norm, poscm, posn
posn = page position in normalized system. out
the page position arrays have the format: [x1,y1,x2,y2]
where (x1,y1) = lower left corner,
and (x2,y2) = upper right corner of plot area.
COMMON BLOCKS:
NOTES:
Notes: Be sure plot device is set first.
For postscript plots call psinit first.
MODIFICATION HISTORY:
R. Sterner 13 Nov, 1989
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cm2norm.pro)
NAME:
CMAPPLY
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Applies a function to specified dimensions of an array
MAJOR TOPICS:
Arrays
CALLING SEQUENCE:
XX = CMAPPLY(OP, ARRAY, DIMS, [/DOUBLE], [TYPE=TYPE])
DESCRIPTION:
CMAPPLY will apply one of a few select functions to specified
dimensions of an array. Unlike some IDL functions, you *do* have
a choice of which dimensions that are to be "collapsed" by this
function. Iterative loops are avoided where possible, for
performance reasons.
The possible functions are: (and number of loop iterations:)
+ - Performs a sum (as in TOTAL) number of collapsed dimensions
AND - Finds LOGICAL "AND" (not bitwise) same
OR - Finds LOGICAL "OR" (not bitwise) same
* - Performs a product LOG_2[no. of collapsed elts.]
MIN - Finds the minimum value smaller of no. of collapsed
MAX - Finds the maximum value or output elements
USER - Applies user-defined function no. of output elements
It is possible to perform user-defined operations arrays using
CMAPPLY. The OP parameter is set to 'USER:FUNCTNAME', where
FUNCTNAME is the name of a user-defined function. The user
defined function should be defined such that it accepts a single
parameter, a vector, and returns a single scalar value. Here is a
prototype for the function definition:
FUNCTION FUNCTNAME, x, KEYWORD1=key1, ...
scalar = ... function of x or keywords ...
RETURN, scalar
END
The function may accept keywords. Keyword values are passed in to
CMAPPLY through the FUNCTARGS keywords parameter, and passed to
the user function via the _EXTRA mechanism. Thus, while the
definition of the user function is highly constrained in the
number of positional parameters, there is absolute freedom in
passing keyword parameters.
It's worth noting however, that the implementation of user-defined
functions is not particularly optimized for speed. Users are
encouraged to implement their own array if the number of output
elements is large.
INPUTS:
OP - The operation to perform, as a string. May be upper or lower
case.
If a user-defined operation is to be passed, then OP is of
the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
the user-defined function.
ARRAY - An array of values to be operated on. Must not be of type
STRING (7) or STRUCTURE (8).
OPTIONAL INPUTS:
DIMS - An array of dimensions that are to be "collapsed", where
the the first dimension starts with 1 (ie, same convention
as IDL function TOTAL). Whereas TOTAL only allows one
dimension to be added, you can specify multiple dimensions
to CMAPPLY. Order does not matter, since all operations
are associative and transitive. NOTE: the dimensions refer
to the *input* array, not the output array. IDL allows a
maximum of 8 dimensions.
DEFAULT: 1 (ie, first dimension)
KEYWORDS:
DOUBLE - Set this if you wish the internal computations to be done
in double precision if necessary. If ARRAY is double
precision (real or complex) then DOUBLE=1 is implied.
DEFAULT: not set
TYPE - Set this to the IDL code of the desired output type (refer
to documentation of SIZE()). Internal results will be
rounded to the nearest integer if the output type is an
integer type.
DEFAULT: same is input type
FUNCTARGS - If OP is 'USER:...', then the contents of this keyword
are passed to the user function using the _EXTRA
mechanism. This way you can pass additional data to
your user-supplied function, via keywords, without
using common blocks.
DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
RETURN VALUE:
An array of the required TYPE, whose elements are the result of
the requested operation. Depending on the operation and number of
elements in the input array, the result may be vulnerable to
overflow or underflow.
EXAMPLES:
Shows how CMAPPLY can be used to total the second dimension of the
array called IN. This is equivalent to OUT = TOTAL(IN, 2)
IDL> IN = INDGEN(5,5)
IDL> OUT = CMAPPLY('+', IN, [2])
IDL> HELP, OUT
OUT INT = Array[5]
Second example. Input is assumed to be an 5x100 array of 1's and
0's indicating the status of 5 detectors at 100 points in time.
The desired output is an array of 100 values, indicating whether
all 5 detectors are on (=1) at one time. Use the logical AND
operation.
IDL> IN = detector_status ; 5x100 array
IDL> OUT = CMAPPLY('AND', IN, [1]) ; collapses 1st dimension
IDL> HELP, OUT
OUT BYTE = Array[100]
(note that MIN could also have been used in this particular case,
although there would have been more loop iterations).
Third example. Shows sum over first and third dimensions in an
array with dimensions 4x4x4:
IDL> IN = INDGEN(4,4,4)
IDL> OUT = CMAPPLY('+', IN, [1,3])
IDL> PRINT, OUT
408 472 536 600
Fourth example. A user-function (MEDIAN) is used:
IDL> IN = RANDOMN(SEED,10,10,5)
IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
IDL> HELP, OUT
OUT FLOAT = Array[10, 10]
(OUT(i,j) is the median value of IN(i,j,*))
MODIFICATION HISTORY:
Mar 1998, Written, CM
Changed usage message to not bomb, 24 Mar 2000, CM
Signficant rewrite for *, MIN and MAX (inspired by Todd Clements
); FOR loop indices are now type
LONG; copying terms are liberalized, CM, 22, Aug 2000
More efficient MAX/MIN (inspired by Alex Schuster), CM, 25 Jan
2002
Make new MAX/MIN actually work with 3d arrays, CM, 08 Feb 2002
Add user-defined functions, ON_ERROR, CM, 09 Feb 2002
$Id: cmapply.pro,v 1.4 2002/02/09 16:32:23 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmapply.pro)
NAME:
CMCONGRID
PURPOSE:
Shrink or expand the size of an array by an arbitrary amount.
This IDL procedure simulates the action of the VAX/VMS
CONGRID/CONGRIDI function.
This function is similar to "REBIN" in that it can resize a
one, two, or three dimensional array. "REBIN", however,
requires that the new array size must be an integer multiple
of the original size. CONGRID will resize an array to any
arbitrary size (REBIN is somewhat faster, however).
REBIN averages multiple points when shrinking an array,
while CONGRID just resamples the array.
CATEGORY:
Array Manipulation.
CALLING SEQUENCE:
array = CONGRID(array, x, y, z)
INPUTS:
array: A 1, 2, or 3 dimensional array to resize.
Data Type : Any type except string or structure.
x: The new X dimension of the resized array.
Data Type : Int or Long (greater than or equal to 2).
OPTIONAL INPUTS:
y: The new Y dimension of the resized array. If the original
array has only 1 dimension then y is ignored. If the
original array has 2 or 3 dimensions then y MUST be present.
z: The new Z dimension of the resized array. If the original
array has only 1 or 2 dimensions then z is ignored. If the
original array has 3 dimensions then z MUST be present.
KEYWORD PARAMETERS:
INTERP: If set, causes linear interpolation to be used.
Otherwise, the nearest-neighbor method is used.
CUBIC: If set, uses "Cubic convolution" interpolation. A more
accurate, but more time-consuming, form of interpolation.
CUBIC has no effect when used with 3 dimensional arrays.
MINUS_ONE:
If set, will prevent CONGRID from extrapolating one row or
column beyond the bounds of the input array. For example,
If the input array has the dimensions (i, j) and the
output array has the dimensions (x, y), then by
default the array is resampled by a factor of (i/x)
in the X direction and (j/y) in the Y direction.
If MINUS_ONE is present (AND IS NON-ZERO) then the array
will be resampled by the factors (i-1)/(x-1) and
(j-1)/(y-1).
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.
OUTPUTS:
The returned array has the same number of dimensions as the original
array and is of the same data type. The returned array will have
the dimensions (x), (x, y), or (x, y, z) depending on how many
dimensions the input array had.
PROCEDURE:
IF the input array has three dimensions, or if INTERP is set,
then the IDL interpolate function is used to interpolate the
data values.
If the input array has two dimensions, and INTERP is NOT set,
then the IDL POLY_2D function is used for nearest neighbor sampling.
If the input array has one dimension, and INTERP is NOT set,
then nearest neighbor sampling is used.
EXAMPLE:
; vol is a 3-D array with the dimensions (80, 100, 57)
; Resize vol to be a (90, 90, 80) array
vol = CONGRID(vol, 90, 90, 80)
MODIFICATION HISTORY:
DMS, Sept. 1988.
DMS, Added the MINUS_ONE keyword, Sept. 1992.
Daniel Carr. Re-wrote to handle one and three dimensional arrays
using INTERPOLATE function.
DMS, RSI, Nov, 1993. Added CUBIC keyword.
Craig Markwardt, Dec, 1997. Added halfhalf keyword to
more evenly distribute "dead" pixel row
Use uniformly spaced grid points for half_half W. Landsman Feb. 2000
(and slightly modified by C. Markwardt 14 Feb 2000)
$Id: cmcongrid.pro,v 1.2 2001/03/25 18:10:47 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmcongrid.pro)
This routine retrieves the recall buffer and reverses its order to make useful in a text widget, skipping empty lines. @Hidden @Returns This function returns the recall buffer in reverse order. @Author JLP - RSI Global Services @History March 31, 2005 - Initial version
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)
This procedure updates the text widget with the
command buffer values, positioning the scrolling
text window so the most recent commands are visible.
@Hidden
@Param
Text {in}{required}{type=long}
Set this parameter to the ID of the text
widget to be populated.
@Param
Commands {in}{required}{type=string vector}
Set this parameter to the vector of strings
to populate the text widget.
@Author
JLP - RSI Global Services
@History
March 31, 2005 - Initial version
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)
This procedure manages events from the application.
@Param
Event {in}{required}{type=event structure}
Set this parameter to the event structure generated
by the GUI.
@Hidden
@Uses
CmdHistory_Get_Commands
@Author
JLP - RSI Global Services
@History
March 31, 2005 - Initial version
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)
This procedure continuously updates a text widget with the contents of the IDL command line recall buffer. This allows the user to copy, edit and paste useful sequences of commands back to the command line, or to an IDL procedure source file. @ExamplesIDL> CMDHISTORY@Uses CmdHistory_Event
CmdHistory_Get_Commands @Author JLP - RSI Global Services @History March 31, 2005 - Initial version @File_Comments This tool may be helpful to people who make extensive use of the IDL command line. It creates a continuously- updating editable text widget containing the command line history from which you can copy, edit and paste back to the IDL command line. It is built around the IDL 6.2 function RECALL_COMMANDS.
Learn more about the IDLdoc documentation style at http://www.rsinc.com/codebank/search.asp?FID=100
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\cmdhistory.pro)
ROUTINE: cmplxgen
USEAGE: result=cmplxgen(nx,ny[,/center])
INPUT:
nx,ny dimensions of output
KEYWORD INPUT:
center if set RESULT is shifted so that the (0,0) point
is the central element of the complex array
OUTPUT:
float(result) = array of column indecies
imaginary(result) = array of row indecies
EXAMPLE: r=cmplxgen(4,3)
0 1 2 3 0 0 0 0
float(r) = 0 1 2 3 imaginary(r) = 1 1 1 1
0 1 2 3 2 2 2 2
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cmplxgen.pro)
NAME:
CMPRODUCT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
CMPRODUCT() is the multiplicative equivalent of TOTAL().
CALLING SEQUENCE:
Result = CMPRODUCT(ARRAY)
DESCRIPTION:
Calculates the product of all the elements of an array. Vector
multiplication in groups of powers of two make this operation
faster than a simple FOR loop. The number of actual
multiplications is still N_ELEMENTS(ARRAY). Double precision
should be used for the highest accuracy when multiplying many
numbers.
INPUTS:
ARRAY - Array of elements to multiply together. For instance,
ARRAY could contain the dimensions of another array--then
CMPRODUCT(ARRAY) would be the total number of elements of
that other array.
RETURNS:
The result of the function is the total product of all the elements
of ARRAY.
EXAMPLE:
SEE ALSO:
TOTAL, PRODUCT (from Astronomy User's Library)
MODIFICATION HISTORY:
Written, CM, 28 Mar 2000
(based on outline of PRODUCT by William Thompson)
$Id: cmproduct.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmproduct.pro)
NAME:
CMPS_FORM
PURPOSE:
This function puts up a form the user can configure a PostScript
device driver. The function result (if the user selects either the
ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
procedure by means of its _Extra keyword. User's predefined
configurations may be retrieved from a common block.
AUTHOR:
*********** CM 01 Feb 2000 VERSION *************
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
$Id: cmps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $
Based almost entirely on, but a totally revamped version of, CMPS_FORM by
FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com
MAJOR TOPICS:
Device Drivers, Hardcopy Output, PostScript Output
PROCEDURE:
This is a pop-up form widget. It is a modal or blocking widget.
Keywords appropriate for the PostScript DEVICE command are returned.
Use your LEFT mouse button to move the "Plot Window" around the page.
Use your RIGHT mouse button to draw your own "Plot Window" on the page.
HELP:
formInfo = CMPS_FORM(/Help)
CALLING SEQUENCE:
formInfo = CMPS_FORM(xoffset, yoffset, Cancel=cancelButton)
OPTIONAL INPUTS:
XOFFSET -- Optional xoffset of the top-level base of cmps_form. Default is
to try to center the form on the display.
YOFFSET -- Optional yoffset of the top-level base of cmps_form. Default is
to try to center the form on the display.
INPUT KEYWORD PARAMETERS:
BITS_PER_PIXEL -- The initial configuration of the bits per pixel button.
BLOCKING -- Set this keyword to make this a blocking widget under IDL 5.0.
(All widget programs block under IDL 4.0.)
COLOR -- The initial configuration of the color switch.
DEFAULTS -- A stucture variable of the same type and structure as the
RETURN VALUE of cmps_form. It will set initial conditions. This makes
it possible to start cmps_form up again with the same values it had the
last time it was called. For example:
mysetup = cmps_form()
newsetup = cmps_form(Defaults=mysetup)
ENCAPSULATED -- The initial configuration of the encapsulated switch.
FILENAME -- The initial filename to be used on the form.
HELP -- Prints a helpful message in the output log.
INCHES -- The initial configuration of the inches/cm switch.
INITIALIZE -- If this keyword is set, the program immediately returns the
"localdefaults" structure. This gives you the means to configue the
PostScript device without interrupting the user.
SELECT -- used only when INITIALIZE is set. Set SELECT to a
string which identifies the predefined configuration to
be returned by cmps_form when INITIALIZE is set. This is
a convenient way to select a predefined config
non-interactively.
LANDSCAPE -- The initial configuration of the landscape/portrait switch.
LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
then it is added as a predefined configuration entry called "Local".
See below for a further discussion of predefined configurations.
PREDEFINED -- An alternate way to specify predefined
configurations. Pass an array of structures to
populate the "predefined" dropbox in the
dialog. This array, if specified, overrides the the
common block technique.
XOFFSET -- The initial XOffSet of the PostScript window.
YOFFSET -- The initial YOffSet of the PostScript window.
XSIZE -- The initial XSize of the PostScript window.
YSIZE -- The initial YSize of the PostScript window.
ASPECT -- The aspect ratio of the window (Y/X). This keyword can
substitute for one of XSIZE or YSIZE.
PRESERVE_ASPECT -- Set this keyword if you want to hold the
aspect ratio constant.
PAPERSIZE -- If set, allows user to specify the size of the paper
media to be printed on, as a scalar string. NOTE:
this specification cannot be passed to DEVICE, but
can be selected for completeness's sake. Default is
'Letter'.
MARGINSIZE -- Size of the margins on all sides. Default is 0.25 inches.
When MARGINSIZE is non-zero, a graphic cannot directly
abut the edge of the page. This is normally a good thing,
since there is often a non-printable region which borders
the page.
DEFAULTPAPER -- Default paper size to use, when it is unspecified
in a predefined, "local", or "default"
configuration. This value also overrides any
configuration from common blocks. European users
will probably set this to 'A4'.
PARENT -- if this widget is invoked by another widget program,
then this keyword parameter must be set to the top level
widget which is to serve as the group leader. Failure
to do so will result in unexpected behavior. IDL 4
programs do not need to pass this parameter. Default:
NONE.
OUTPUT KEYWORD PARAMETERS
CANCEL -- This is an OUTPUT keyword. It is used to check if the user
selected the "Cancel" button on the form. Check this variable rather
than the return value of the function, since the return value is designed
to be sent directly to the DEVICE procedure. The varible is set to 1 if
the user selected the "Cancel" button. Otherwise, it is set to 0.
CREATE -- This output keyword can be used to determine if the user
selected the 'Create File' button rather than the 'Accept' button.
The value is 1 if selected, and 0 otherwise.
PAPERSIZE -- If set to a named variable, any newly selected paper
size is returned in that variable.
XPAGESIZE -- Size of paper in "X" dimension, in units given by
the returned config structure.
YPAGESIZE -- Size of paper in "Y" dimension, in units given by
the returned config structure.
PAGEBOX -- specifies the page rectangle relative to the plot
window, in normalized units. A 4-vector of the form
[XLL, YLL, XUR, YUR] is returned, giving the positions
of the lower left (LL) and upper right (UR) corners of
the page with respect to the plot window. Thus, the
following command:
PLOT, x, y, position=PAGEBOX
will construct a graphic whose plot region exactly
fills the page (with no margin around the edges).
Naturally, the page is usually larger than the
graphics window, so the normalized coordinates will
usually fall outside the range [0,1].
However, the bounding box constructed by the
Postscript driver includes only the graphics window.
Anything drawn outside of it may be clipped or
discarded.
RETURN VALUE:
formInfo = { cmps_form_INFO, $
xsize:0.0, $ ; The x size of the plot
xoff:0.0, $ ; The x offset of the plot
ysize:0.0, $ ; The y size of the plot
yoff:0.0 $ ; The y offset of the plot
filename:'', $ ; The name of the output file
inches:0 $ ; Inches or centimeters?
color:0, $ ; Color on or off?
bits_per_pixel:0, $ ; How many bits per image pixel?
encapsulated:0,$ ; Encapsulated or regular PostScript?
isolatin1:0,$ ; Encoded with ISOLATIN1?
landscape:0 } ; Landscape or portrait mode?
USAGE:
The calling procedure for this function in a widget program will
look something like this:
info.ps_config = cmps_form(/Initialize)
formInfo = cmps_form(Cancel=canceled, Create=create, $
Defaults=info.ps_config)
IF NOT canceled THEN BEGIN
IF create THEN BEGIN
thisDevice = !D.Name
Set_Plot, "PS"
Device, _Extra=formInfo
Enter Your Graphics Commands Here!
Device, /Close
Set_Plot, thisDevice
info.ps_config = formInfo
ENDIF ELSE
info.ps_config = formInfo
ENDIF
MAJOR FUNCTIONS and PROCEDURES:
None. Designed to work originally in conjunction with XWindow, a
resizable graphics window. [ NOTE: this modified version of
cmps_form, by Craig Markwardt, is incompatible with the original
version of XWINDOW. ]
MODIFICATION HISTORY:
Based on cmps_form of : David Fanning, RSI, March 1995.
Major rewrite by: Craig Markwardt, October 1997.
- Drawing and updating of form and sample box are now modular
- Option of storing more than one predefined postscript configuration
- Selection of paper size by name
- Access to predfined configurations through (optional) common
block
Several additions, CM, April 1998 VERSION CM2.0
- better integration of paper sizes throughout program.
Predefined configurations now also know about paper.
- allow passing predefined configurations instead of using
common block
- addition of ISOLATIN selection, and streamlining of dialog
appearance
Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
Added SELECT keyword, CM, 09 Dec 1998
Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
Added "Choose" button for filename selection, 19 Sep 1999
Added ability to program different button names, 19 Sep 1999
Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
Oct 1999
Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
Added aspect to cmps_form_numevents (per Aaron Barth), 18 Oct 1999
Corrected small bug under Initialize keyword (inches), 18 Oct 1999
Made call to *_pscoord more consistent, 18 Oct 1999
Added XPAGESIZE, YPAGESIZE and PAGEBOX keywords, 19 Oct 1999
Small cosmetic cleanup, CM, 01 Feb 2000
Fix for IDL 5.5's handling of structures with arrays, CM, 11 Dec 2001
COMMON BLOCKS:
The user may store frequently used or helpful configurations in a
common block, and cmps_form() will attempt to access them. This
provides a way for the user to have persistent, named,
configurations.
NOTE: this format has changed since the last version. You may
have to quit your IDL session for the changes to take effect
properly. If you have place a predefined configuration in your
startup file, you should review the new format.
COMMON CMPS_FORM_CONFIGS, cmps_form_DEFAULT_PAPERSIZE, $
cmps_form_STDCONFIGS
cmps_form_DEFAULT_PAPERSIZE - a string designating the default
paper size, when none is given.
The predefined configurations
offerred by this program will
respect the default value. (See
also the DEFAULTPAPER keyword.)
cmps_form_STDCONFIGS - An array of cmps_form_CONFIG structures,
each containing information about one
predefined configuration, such as its
name and size of paper. Each "config"
element is a cmps_form_INFO structure,
which contains the actual postscript
configuration.
See the IDL source code cmps_form_LOAD_CONFIGS for an example of how
to make a list of configurations. One possibility would be to
declare and populate the common block from within the user's
start-up script, allowing the same configurations to appear in
every session.
cmps_form() takes its initial list of configurations from this
common block if it exists. A default list is provided ala the
procedure cmps_form_LOAD_CONFIGS. Any modifications that take place
during the cmps_form() widget session are not transferred back to
the common block upon return. It might be useful to be able to do
this, through some form of 'save' procedure.
Also, if the PREDEFINED keyword is used, then the common block is
not consulted.
$Id: cmps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmps_form.pro)
NAME:
CMREPLICATE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Replicates an array or scalar into a larger array, as REPLICATE does.
CALLING SEQUENCE:
ARRAY = CMREPLICATE(VALUE, DIMS)
DESCRIPTION:
The CMREPLICATE function constructs an array, which is filled with
the specified VALUE template. CMREPLICATE is very similar to the
built-in IDL function REPLICATE. However there are two
differences:
* the VALUE can be either scalar or an ARRAY.
* the dimensions are specified as a single vector rather than
individual function arguments.
For example, if VALUE is a 2x2 array, and DIMS is [3,4], then the
resulting array will be 2x2x3x4.
INPUTS:
VALUE - a scalar or array template of any type, to be replicated.
NOTE: These two calls do not produce the same result:
ARRAY = CMREPLICATE( 1, DIMS)
ARRAY = CMREPLICATE([1], DIMS)
In the first case the output dimensions will be DIMS and
in the second case the output dimensions will be 1xDIMS
(except for structures). That is, a vector of length 1 is
considered to be different from a scalar.
DIMS - Dimensions of output array (which are combined with the
dimensions of the input VALUE template). If DIMS is not
specified then VALUE is returned unchanged.
RETURNS:
The resulting replicated array.
EXAMPLE:
x = [0,1,2]
help, cmreplicate(x, [2,2])
INT = Array[3, 2, 2]
Explanation: The 3-vector x is replicated 2x2 times.
x = 5L
help, cmreplicate(x, [2,2])
LONG = Array[2, 2]
Explanation: The scalar x is replicated 2x2 times.
SEE ALSO:
REPLICATE
MODIFICATION HISTORY:
Written, CM, 11 Feb 2000
Fixed case when ARRAY is array of structs, CM, 23 Feb 2000
Apparently IDL 5.3 can't return from execute(). Fixed, CM, 24 Feb
2000
Corrected small typos in documentation, CM, 22 Jun 2000
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmreplicate.pro)
NAME:
CMRESTORE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Restore variables from an IDL SAVE file.
CALLING SEQUENCE: (various)
CMRESTORE, filename (implicit)
CMRESTORE, filename, var1, var2, ..., [, NAMES=names]
CMRESTORE, filename, DATA=pointers, NAMES=names, PASS_METHOD='POINTER'
CMRESTORE, filename, DATA=handles, NAMES=names, PASS_METHOD='HANDLE'
CMRESTORE, filename, DATA=structure, PASS_METHOD='STRUCT'
DESCRIPTION:
CMRESTORE is a replacement for the built-in IDL procedure RESTORE.
It restores variables and data from an existing IDL SAVE file,
written either by SAVE or CMSAVE. The CMSV utility library must
be installed in your IDL path to use CMSAVE and CMRESTORE.
The primary advantage to CMRESTORE is the ability to selectively
restore only certain variables from the input file (based on
name). CMRESTORE provides a number of ways to pass the data
between routines, typically using a pointer or structure, which
avoids the unsafe practice of restoring variables in the caller's
namespace. However, CMRESTORE can restore variables into the
caller's namespace, but users should be aware that this capacity
is somewhat limited in IDL versions 5.2 and below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
CMRESTORE should be able to read files written by SAVE and CMSAVE
from IDL version 4 to version 5.4.
CMRESTORE cannot restore objects, pointers, compressed files, or
data sets larger than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMRESTORE are available to
the user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly. Also, under IDL versions
5.2 and previous, it is not possible for CMRESTORE to restore
variables into the caller's name space if they are not yet
defined.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
FILENAME - the name of the SAVE file.
Default: none, this parameter must be specified.
VAR{i} - The values to be restored. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
If no variables are passed as positional parameters, they
can still be saved using the DATA keyword. By invoking
CMRESTORE without positional parameters or DATA,
CMRESTORE automatically will attempt to restore the
variables to the calling routine's name space (the
"implicit" technique).
NOTE: in IDL 5.2 and below, user routines are not
allowed to *CREATE* new variables in the caller's name
space. CMRESTORE may fail if the variable in
undefined in the caller. Therefore you must define it
before calling CMRESTORE. The safer practice is to
use the VAR{i} positional parameters, or the DATA
keyword.
KEYWORDS:
FILENAME - the name of the SAVE file. The positional FILENAME
parameter takes precedence over the keyword FILENAME
parameter.
PASS_METHOD - a scalar string, describing the method of passing
data between the caller and CMRESTORE. The keyword
can take the value 'ARGUMENT', 'POINTER', 'HANDLE'
or 'STRUCT'. A value of 'ARGUMENT' indicates that
data values will be passed by command line argument,
and is the default. Other values are described
below.
DATA - A list of data elements to be restored from the output
file. The data elements can be one of the following,
depending on the value of PASS_METHOD. The means of
extracting the data, and the method of naming each
variable, are also indicated.
* PASS_METHOD='POINTER': An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='HANDLE': An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='STRUCT': A structure containing data to be saved
Data: tag value Name: tag name
Data values are restored one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
CMRESTORE will allocate any pointer or handle resources.
The calling routine is responsible for deallocating any
pointer or handle resources.
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The values specified in the names keyword
override the tag names.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be restored; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the restore operation for each variable. A value of 1
at position i in the array indicates success for the
ith variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
EXAMPLE:
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
SEE ALSO:
CMSAVE, SAVE, RESTORE
MODIFICATION HISTORY:
Written, 14 May 2000
Documented, 22 Sep 2000
Restore into caller's name space now permitted, 11 Jan 2001
Documented "implicit" restore a little better, w/ errors, 01 Mar 2001
Make version checks with correct precision, 19 Jul 2001, CM
Restore with no args automatically does ALL, is this right?,
CM, 20 Aug 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmrestore.pro,v 1.18 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmrestore.pro)
NAME:
CMSAVE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Save IDL variables to a file. (IDL v5 and greater)
CALLING SEQUENCE: (various)
CMSAVE, var1, var2, ..., FILENAME=filename [, NAMES=names]
CMSAVE, DATA=pointers, NAMES=names, FILENAME=filename
CMSAVE, DATA=handles, NAMES=names, FILENAME=filename
CMSAVE, DATA=structure, FILENAME=filename
DESCRIPTION:
CMSAVE is a replacement for the built-in IDL procedure SAVE, with
more flexibility and increased capabilities.
CMSAVE produces output files that are compatible with the standard
save format of IDL versions 4 and 5 (and perhaps greater).
Variables may be restored by using either the built-in procedure
RESTORE, or CMRESTORE. The CMSV utility library must be installed
in your IDL path to use CMSAVE and CMRESTORE.
The primary advantages to CMSAVE are the ability to append
additional variables to an existing SAVE file, and several
flexible ways to pass the data and variable names to be saved.
CMSAVE also attempts to run on all IDL versions.
To append variables to an existing file, simply specify the APPEND
keyword, and the filename of an existing writable SAVE file.
Variables will be appended to the end of the file. It is possible
to append a variable with the same name as an existing variable in
a file. Both data values are stored in the file. However the
results upon restore are undefined. There is also a limitation
that only one series of heap values -- pointed-to data -- may be
saved in a file.
By the normal convention of the built-in SAVE command, both the
data and variable names to be saved are passed as parameters on
the command line. Each parameter must be a named variable; both
the name and value are saved.
This convention may be used in invoking CMSAVE as well. However,
in addition to passing the data by positional parameter, the user
can pass the data using the DATA keyword. If the DATA keyword is
used, then an array of pointers or handles may be passed, or a
structure of values may be passed. (see below) If both are
passed, then the positional parameters take precedence.
It is also possible to explicitly rename the saved variables: the
saved name does not need to be the name of the named variable.
Use the NAMES keyword to override the default name. By default
the name is drawn from any named variables, or from the structure
tag names if the DATA keyword is used with a structure. The NAMES
keyword takes precedence over these values. NOTE: Values passed
by pointer or handle are not named by default, and so will not be
saved unless the NAMES keyword is used.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
Files written by CMSAVE should be readable with all known versions
of IDL at the time of this writing (version 4 - version 5.4). It
is expected that this compatibility will persist.
CMSAVE cannot write objects, compressed files, or data sets larger
than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMSAVE are available to the
user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
VAR{i} - The variables to be saved. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
Variables can also be specified by passing an array of
handles or pointers in the DATA keyword.
If no variables are passed as positional parameters or
using DATA, then CMSAVE will assume that *all* variables
at the caller's level should be saved (this is similar
behavior to the built-in SAVE routine). Note that system
variables cannot be saved with CMSAVE.
KEYWORDS:
ALL - for compatibility with the built-in SAVE routine. Ignored.
Note that CMSAVE cannot save system variables.
FILENAME - the name of the output file.
Default: 'cmsave.sav'
DATA - A list of data elements to be saved to the output file.
The data elements can be one of the following. The means
of extracting the data, and the method of naming each
variable, are also indicated.
* An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* A 1-element structure containing data to be saved.
Data: tag value Name: tag name
Data values are saved one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
The calling routine is responsible for deallocating any
pointer or handle resources.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call. This can be especially useful to
rename local variables, and to give names to expressions.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The NAMES keyword values override the tag
names.
APPEND - if set, then the specified variables are appended to an
existing file.
Repeated variables will not cause an error, however they
may not be restored properly using the built-in RESTORE
procedure. It may also not be permitted to append
variables that contain heap pointers, to a save file
which already contains heap data.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be written; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the save operation for each variable. A value of 1 at
position i in the array indicates success for the ith
variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
XDR - for compatibility with the built-in SAVE routine. Ignored.
EXAMPLE:
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B. Data are passed by pointer.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B. Data are passed by structure.
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 14 May 2000
Documented, 22 Sep 2000
Made "more" compatible with SAVE; additional documentation, 11 Jan
2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsave.pro,v 1.14 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsave.pro)
NAME:
CMSAVEDIR
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Display a directory of the variables in an IDL SAVE file.
CALLING SEQUENCE:
CMSAVEDIR, filename [, /VERBOSE, /QUIET, ... ]
DESCRIPTION:
CMSAVEDIR will display a listing of the variables and other
objects stored in an IDL SAVE file.
For command-line users the primary function of CMSAVEDIR will be
to find out what data is stored in a file and when it was saved.
For that, they simply need to type: CMSAVEDIR, 'myfile.sav'
CMSAVEDIR also offers a number of features for programmers.
CMSAVEDIR essentially interrogates the save file and discovers the
numbers, names and types of each of the variables stored in the
file. Programmers can use that information to decide whether or
how to open a file using the other routines in the CMSVLIB.
Various keyword parameters are used return this information, as
documented below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
CMSAVEDIR cannot examine compressed save files, or files larger
than 2 gigabytes.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
FILENAME - a scalar string, the name of the file to be examined.
KEYWORDS:
VERBOSE - if set, print more detailed information about the input file.
QUIET - if set, then do not print any output. Programmers can use
this keyword to allow CMSAVEDIR to return information
about the file silently.
STATUS - upon output, 1 for success, otherwise to indicate
failure.
ERRMSG - upon output, if a failure occurs, a message describing
the error condition.
N_VARIABLES - upon output, the number of variables in the file.
VAR_NAMES - upon output, contains a string array of the names of
the variables stored in the file.
TYPES - upon output, an 11xN_VARIABLES array containing the SIZE
information of each variable in the file.
N_PRO - upon output, the number of procedures stored in the file.
PRO_NAMES - upon output, the names of the procedures stored in the
file, as a string array.
N_FUNCTION - upon output, the number of functions stored in the
file.
FUNC_NAMES - upon output, the names of the functions stored in the
file, as a string array.
NAMED_STRUCTS - upon output, a string array listing any named
structures which appear in the SAVE file.
NAMED_CLASSES - upon output, a string array listing any named
class structures which appear in the SAVE file.
TIMESTAMP - upon output, contains the timestamp record information
in a structure. The fields of the structure are:
SAVE_DATE - string - date saved
SAVE_USER - string - user who saved file
SAVE_HOST - string - host name on which file
saved
VERSION - upon output, contains the version record information in
a structure. The fields of the structure are:
FORMAT_VERSION - integer - major format version
ARCH - string - saving host's !VERSION.ARCH
OS - string - saving host's !VERSION.OS
RELEASE - string - saving host's !VERSION.RELEASE
FORCE - if set, will force CMSAVEDIR to open the file even if it
detects a potential incompatibility.
EXAMPLE:
IDL> cmsavedir, 'int_str_intarr.sav'
** int_str_intarr.sav
** Sun Apr 9 20:28:25 2000 (craigm@beach.gsfc.nasa.gov)
** IDL v5.2 (linux)
A INT = 0
B STRING = 'hello'
C INT = Array[3]
** 3 variable(s), 0 heap value(s) and 0 procedure(s) in 1376 bytes
SEE ALSO:
CMRESTORE, CMSAVE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Documented, 12 Jan 2001, CM
Added USAGE message, 09 Jun 2001, CM
Fixed bug in printing common variables, 17 Mar 2002, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsavedir.pro,v 1.16 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsavedir.pro)
NAME:
CMSET_OP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Performs an AND, OR, or XOR operation between two sets
CALLING SEQUENCE:
SET = CMSET_OP(A, OP, B)
DESCRIPTION:
SET_OP performs three common operations between two sets. The
three supported functions of OP are:
OP Meaning
'AND' - to find the intersection of A and B;
'OR' - to find the union of A and B;
'XOR' - to find the those elements who are members of A or B
but not both;
Sets as defined here are one dimensional arrays composed of
numeric or string types. Comparisons of equality between elements
are done using the IDL EQ operator.
The complements of either set can be taken as well, by using the
NOT1 and NOT2 keywords. For example, it may be desireable to find
the elements in A but not B, or B but not A (they are different!).
The following IDL expressions achieve each of those effects:
SET = CMSET_OP(A, 'AND', /NOT2, B) ; A but not B
SET = CMSET_OP(/NOT1, A, 'AND', B) ; B but not A
Note the distinction between NOT1 and NOT2. NOT1 refers to the
first set (A) and NOT2 refers to the second (B). Their ordered
placement in the calling sequence is entirely optional, but the
above ordering makes the logical meaning explicit.
NOT1 and NOT2 can only be set for the 'AND' operator, and never
simultaneously. This is because the results of an operation with
'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
both NOTs -- formally cannot produce a defined result.
The implementation depends on the type of operands. For integer
types, a fast technique using HISTOGRAM is used. However, this
algorithm becomes inefficient when the dynamic range in the data
is large. For those cases, and for other data types, a technique
based on SORT() is used. Thus the compute time should scale
roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
brute force approach. For large arrays this is a significant
benefit.
INPUTS:
A, B - the two sets to be operated on. A one dimensional array of
either numeric or string type. A and B must be of the same
type. Empty sets are permitted, and are either represented
as an undefined variable, or by setting EMPTY1 or EMPTY2.
OP - a string, the operation to be performed. Must be one of
'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
Other operations will cause an error message to be produced.
KEYWORDS:
NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
NOT1) or B (for NOT2) will be used in the operation.
NOT1 and NOT2 cannot be set simultaneously.
EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
assumed to be the empty set. The actual values
passed as A or B are then ignored.
INDEX - if set, then return a list of indices instead of the array
values themselves. The "slower" set operations are always
performed in this case.
The indices refer to the *combined* array [A,B]. To
clarify, in the following call: I = CMSET_OP(..., /INDEX);
returned values from 0 to NA-1 refer to A[I], and values
from NA to NA+NB-1 refer to B[I-NA].
COUNT - upon return, the number of elements in the result set.
This is only important when the result set is the empty
set, in which case COUNT is set to zero.
RETURNS:
The resulting set as a one-dimensional array. The set may be
represented by either an array of data values (default), or an
array of indices (if INDEX is set). Duplicate elements, if any,
are removed, and element order may not be preserved.
The empty set is represented as a return value of -1L, and COUNT
is set to zero. Note that the only way to recognize the empty set
is to examine COUNT.
SEE ALSO:
SET_UTILS.PRO by RSI
MODIFICATION HISTORY:
Written, CM, 23 Feb 2000
Added empty set capability, CM, 25 Feb 2000
Documentation clarification, CM 02 Mar 2000
Incompatible but more consistent reworking of EMPTY keywords, CM,
04 Mar 2000
Minor documentation clarifications, CM, 26 Mar 2000
Corrected bug in empty_arg special case, CM 06 Apr 2000
Add INDEX keyword, CM 31 Jul 2000
Clarify INDEX keyword documentation, CM 06 Sep 2000
Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
LAST_UNIQUE values, CM, 18 Sep 2000
Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
Sep 2000 (thanks to Ben Tupper)
Still trying to get documentation of INDEX and NOT right, CM, 28
Sep 2000 (no code changes)
$Id: cmset_op.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmset_op.pro)
NAME:
CMSVLIB
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Initialize the CMSVLIB save library
CALLING SEQUENCE:
VALUE = CMSVLIB(/QUERY)
DESCRIPTION:
This function initializes the CMSVLIB library to read, write and
interrogate IDL save files. Use the QUERY keyword to determine
whether the full CMSVLIB library is present.
The procedures in the library are:
High-level
CMSAVE - save variables to a save file
CMRESTORE - restore variables from a save file
CMSAVEDIR - list contents of a save file
CMSVLIB (function) - this file
Mid-level
CMSV_OPEN - open a save file for reading or writing
CMSVREAD - read non-pointer data from file
CMSVWRITE - write non-pointer data to file
Low-level
CMSV_RREC - read record from save file
CMSV_RVTYPE - read variable type information from file
CMSV_RDATA - read variable data from file
CMSV_WREC - write record to save file
CMSV_WVTYPE - write variable type information to file
CMSV_WDATA - write variable data to file
Utility
CMSV_RRAW (function) - read raw integer or string data from file
CMSV_WRAW - write raw integer or string data to file
CMSV_PTRSUM - create a heap data inventory
CMSV_TEST - test the library
TAGSIZE (function) - determine the types of all tags in a structure
HELPFORM (function) - create HELP-like string describing a variable
Users should consult
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
None
KEYWORDS:
QUERY - if set, determine whether the CMSVLIB library is
installed. Function returns 1 upon success, 0 upon
failure.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsvlib.pro,v 1.3 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsvlib.pro)
NAME:
CMSVREAD
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read a single variable from an open SAVE file
CALLING SEQUENCE:
CMSVREAD, UNIT, DATA [, NAME=NAME, /NO_DATA, VERSION=VERSION,
TIMESTAMP=TIMESTAMP ]
DESCRIPTION:
CMSVREAD reads a single IDL variable from an open IDL SAVE file.
The file should already have been opened as a normal file using
OPENR.
CMSVREAD is a simplified version of the CMSVLIB package, and as
such is not capable of reading heap data (pointers) or object
data. Strings, structures, and all array types are supported.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - the open file unit.
DATA - a named variable, into which the new data is to be read.
KEYWORDS:
NAME - upon output, the name of the saved variable is returned in
this keyword. If a failure or end of file condition
occurs, name will be undefined upon return.
STRUCTURE_NAME - if the data to be read is a structure, upon
output, this keyword will contain the name of the
structure. A value of '' indicates an anonymous
structure.
SIZE - upon output, the SIZE type of the data is returned in this
keyword.
NO_DATA - if set, no data is read from the file, only the variable
name and type.
TIMESTAMP - after the first call to CMSVREAD on a newly opened
file, this keyword will contain the file timestamp
structure.
VERSION - after the first call to CMSVREAD on a newly opened file,
this keyword will contain the file version information,
if available.
QUIET - if set, error messages are not printed.
Default: an error causes errors to be printed with MESSAGE
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
Read all variables from a file, and print help on them.
openr, 50, 'test.sav'
name = ''
while n_elements(name) GT 0 do begin ;; EOF signalled by NAME undefined
cmsvread, 50, data, name=name
help, name, data
end
close, 50
SEE ALSO:
CMSVWRITE, CMRESTORE, CMSAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written and documented, 11 Jan 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsvread.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsvread.pro)
NAME:
CMSVWRITE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write a single variable to an open SAVE file
CALLING SEQUENCE:
CMSVWRITE, UNIT, DATA [ , NAME=NAME, COMPATIBILITY=COMPAT ]
DESCRIPTION:
CMSVWRITE writes a single IDL variable to an open IDL SAVE file.
The file should already have been opened for writing as a normal
file using OPENW or OPENU.
CMSVWRITE is a simplified version of the CMSVLIB package, and as
such is not capable of writing heap data (pointers) or object
data, or structures that contain them. Strings, structures, and
all array types are supported.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - the open file unit.
DATA - the data to be written.
KEYWORDS:
NAME - the optional name of the variable to be written (must be a
valid variable name).
Default: CMSVWRITE automatically creates a valid name.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5'
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
NO_END - a save file must terminate with an "end" record. By
default, CMSVWRITE will append such a record after the
variable is written, and then rewind the file pointer.
The end record must be written after the last variable,
but is optional otherwise. Set this keyword to disable
writing the end record (for performance reasons).
QUIET - if set, error messages are not printed.
Default: an error causes errors to be printed with MESSAGE
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
Write variables A, B, C and D to a file.
openw, 50, 'test.sav' ;; Add /STREAM under VMS !
cmsvwrite, 50, a, name='a'
cmsvwrite, 50, b, name='b'
cmsvwrite, 50, c, name='c'
close, 50
SEE ALSO:
CMSVREAD, CMRESTORE, CMSAVE, SAVE, CMSVLIB
MODIFICATION HISTORY:
Written and documented, 11 Jan 2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsvwrite.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsvwrite.pro)
NAME:
CMSV_OPEN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Open IDL SAVE file for reading or writing
CALLING SEQUENCE:
CMSV_OPEN, UNIT, FILENAME, OFFSET, $
ACCESS=ACCESS, /FORCE, /GET_LUN, /REOPEN, $
COMPATIBILITY=COMPATIBILITY, $
STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_OPEN opens an IDL SAVE-formatted file for reading or writing.
The mode of operation is controlled by the ACCESS keyword, which
may be either 'R' for reading, 'W' for writing, or 'RW' for
read/write access.
'R': In the case of reading, the specified file is opened with
read-only access, and the first bytes are examined to verify that
it is indeed a valid IDL SAVE file.
'W': In the case of writing, the specified file is opened with
write access, and the initial file signature is written.
'RW': In the case of read-write access, the file must already
exist as a valid SAVE file. Users are advised that every time
they switch between reading and writing operations, they must use
POINT_LUN to flush the file buffers.
The CMSVLIB routines do not support file sizes greater than 2 GB,
nor SAVE files created with the COMPRESS option.
Upon return, the file pointer is positioned at the start of the
first valid SAVE record. The file offset is returned in OFFSET.
The user is responsible for reading or writing the remainder of
the file with other library routines.
The file unit is determined based on the following criteria. This
behavior is similar to the OPEN family of procedures, except for
the REOPEN keyword.
* If REOPEN is set then it is assumed that UNIT is an
already-open file, and FILENAME is ignored.
* If GET_LUN is set then a file unit is allocated with GET_LUN,
and upon success this unit is returned in UNIT.
* Otherwise it is asssumed that UNIT is a valid but unopened
file unit. Upon successful return, UNIT is opened.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - a logical unit number (a scalar). In the case of GET_LUN,
a file unit will be allocated and returned in UNIT. In the
default case, or REOPEN, UNIT must be a valid file unit
upon input. For REOPEN the corresponding file must be
seekable.
FILENAME - a scalar string specifying the filename path (ignored
for REOPEN).
OFFSET - upon return, the file offset of the next available SAVE
record.
KEYWORDS:
ACCESS - a scalar string, case insensitive:
'R' - read-only access
'W' - write access (new file)
'RW' - read-write access (existing file)
Default: 'R' - read-only
GET_LUN - if set, the file unit is allocated using GET_LUN
FORCE - if set, then the file is opened despite a detected file
format inconsistency.
REOPEN - if set, then an already-opened file is manipulated. The
valid file unit must be specified by UNIT, and FILENAME
is ignored.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Change BLOCK to STREAM to support VMS properly, 14 Feb 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_open.pro,v 1.12 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_open.pro)
NAME:
CMSV_PTRSUM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Construct an inventory of heap data accessible to a variable
CALLING SEQUENCE:
CMSV_PTRSUM, VAR, LIST
DESCRIPTION:
This procedure constructs an inventory of heap data that is
accessible to a single variable. It searches all array elements,
recursively through structure tags, and by dereferencing pointers.
Users can use this procedure to determine all heap variables that
need to be saved to disk.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
VAR - the variable to be examined
LIST - upon output, an array of pointers, each of which points to
a heap variable accessible to VAR. If there are no heap
data pointed to by VAR, then LIST returns a NULL value.
KEYWORDS:
NULL - if set, return the null value in LIST instead of the
pointer list. VAR is ignored.
HAS_OBJECTS - upon return, the value is 1 if VAR contains or
points to an object reference, and 0 if not.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_ptrsum.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_ptrsum.pro)
NAME:
CMSV_RDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read SAVE-formatted data variable record from input block or file unit
CALLING SEQUENCE:
CMSV_RDATA, BLOCK, POINTER, SIZE, DATA, UNIT=UNIT, $
TEMPLATE=TEMPLATE, /TEMPORARY, PTR_INDEX=PTR_INDEX, $
PTR_CALLBACK=PTR_CALLBACK, PTR_OFFSETS=PTR_OFFSETS, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_RDATA reads the data portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure reads the raw data and returns it to the user. The
initial type portion of the record must have already been read
using the CMSV_RVTYPE procedure.
CMSV_RDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
For scalars and arrays of numeric or string types, the caller must
only supply the SIZE parameter, which specifies the type and
dimensions of the variable to be read. This information can be
obtained from the CMSV_RVTYPE routine. The data is returned in the
output parameter DATA.
For structure data, in addition to specifying the SIZE array, the
user must also supply a "template" describing the structure into
which the data will be read. This template is simply a "blank"
form of the data structure, and is returned by CMSV_RVTYPE.
Thus, a simple way to read structure, numeric or string data is
the following code (with error checking removed)
CMSV_RVTYPE, block, pointer, name, size, template=template, unit=unit
CMSV_RDATA, block, pointer, size, data, template=template, unit=unit
[ This code assumes the record header has been read with
CMSV_RREC. ]
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
POINTER DATA
Pointer data stored in IDL SAVE files are particularly difficult
to manage, because the actual heap variables are stored in
separate records which *precede* the record of interest. Thus, if
your application requires the reading of pointer data, you must
perform special processing in your own code in order to support
it. In essence, you must maintain an inventory of heap variables
as they are encountered in the file.
If these procedures are not followed then pointer data will not be
read, and a LONG integer value appears in the pointers' places.
Under IDL 4, pointer data can never be read.
This is accomplished by placing some additional logic in your file
processing loop. There are four separate components to this: (1)
loop initialization; (2) reading a HEAP_INDEX record; (3) parsing
a HEAP_DATA record; and (4) passing extra arguments to CMSV_RDATA.
The additional state information is maintained in two variables
named PTR_INDEX, which keeps track of the heap variable numbers,
and PTR_OFFSETS, which stores the file location of each variable.
(1) Loop initialization: is quite simple, use the following code:
ptr_index = [0L]
ptr_offsets = [0L]
ptr_data = [ptr_new()]
(2) Reading HEAP_INDEX, which is an array of values indicating
the heap variable numbers of each heap variables. These
values are stored in PTR_INDEX:
CMSV_RHEAP, block, pointer, index, unit=unit
ptr_index = [ptr_index, index]
ptr_offsets = [ptr_offsets, lonarr(n_elements(index))]
ptr_data = [ptr_data, ptrarr(n_elements(index))]
(3) Parse the HEAP_DATA record. Here were are interested in the
heap variable number, and the file offset.
opointer = pointer
CMSV_RVTYPE, block, pointer, vindex, /heap, unit=unit
vindex = floor(vindex(0))
wh = where(ptr_index EQ vindex)
ptr_offsets(wh(0)) = offset + opointer
Keep in mind that the file offset is OFFSET+POINTER.
(4) Pass extra parameters to CMSV_RDATA. The user simply passes
these extra variables to the CMSV_RDATA procedure, which
automatically recognizes heap data and reads it from the
appropriate location.
CMSV_RVTYPE, block, pointer, name, size, unit=unit, template=tp
CMSV_RDATA, block, pointer, size, data, template=tp, $
unit=unit, ptr_offsets=ptr_offsets, $
ptr_index=ptr_index, ptr_data=ptr_data
If this technique is used properly, only those heap variables
which are needed are read. Thus, there are never any lost or
dangling pointers. Since each bit of heap data is stored in a
variable returned to the user, it is not necessary to
PTR_FREE(ptr_data); in fact, doing so would corrupt the input
data.
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
SIZE - an array of integers describing the type and dimensions of
the variable to be read, in the format returned by the
SIZE() routine. This parameter is required.
DATA - upon output, the data variable. If any heap data is read,
the user is ultimately responsible for freeing it.
KEYWORDS:
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
TEMPLATE - for structure data (data type 8), a "blank" structure
containing the fields and data values to be read in.
This structure is returned by CMSV_RVTYPE.
This keyword is mandatory for structure data.
TEMPORARY - if set, BLOCK becomes undefined upon return.
PTR_OFFSETS - array of file offsets, as described above. Default:
pointer data is converted to an integer.
PTR_INDEX - array of heap variable indices, as described above.
Default: pointer data is converted to an integer.
PTR_DATA - array of pointers, as described above.
Default: pointer data is converted to an integer.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added UNDEFINED data type for IDL >5.3, CM, 21 Apr 2001
Fixed bug for pointers within structures, CM, 21 Apr 2001
Add support for IDL 4 byte-compiled strings, CM, 22 Apr 2001
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rdata.pro,v 1.10 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rdata.pro)
NAME:
CMSV_RRAW
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read raw SAVE data from input block or file unit
CALLING SEQUENCE:
DATA = CMSV_RRAW( BLOCK, POINTER, NELT, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG )
DESCRIPTION:
This function reads raw integer or string data from an IDL SAVE
file. This is the lowest level reading function in the library,
intended for developers who are investigating new and existing
SAVE file formats.
The primary use of this function will be to read raw integer and
string data from the input. By default, a single value is read as
a scalar; however a vector of values can be read using the NELT
parameter. Special keywords are provided for the common data
types STRING, LONG and BYTE. Other integer types can be read
using the TYPE keyword. Users who want to read the data from an
IDL variable should use CMSV_RDATA, which can handle
multidimensional data, as well as floating point and structure
data.
A secondary use of this function is to buffer the data in BLOCK.
This will ensure that BLOCK contains enough data to convert NELT
integers without reading from disk. CMSV_RRAW itself does not
convert any values so the return value should be ignored.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
NELT - optional parameter specifying the number of values to read.
If unspecified, then a scalar value is read and returned.
If specified, then a vector of NELT values is read and
returned.
KEYWORDS:
BUFFER - if set, CMSV_RRAW will ensure that BLOCK contains at
least NELT values without converting them. The return
value should be ignored. This keyword is ignored for
strings.
LONG - if set, the values are converted as LONG integers.
BYTE - if set, the values are converted as BYTEs.
STRING - if set, the values are converted as STRINGs. Each string
may be of variable length.
TYPE - if none of the above keywords is set, then values of type
TYPE are read. TYPE should be a string, one of 'BYTE',
'FIX', 'LONG', 'ULONG', 'LONG64', or 'ULONG64'.
If no type is specified then BYTEs are read.
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rraw.pro,v 1.6 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rraw.pro)
NAME:
CMSV_RREC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read SAVE-formatted record header from input block or file unit
CALLING SEQUENCE:
CMSV_RREC, BLOCK, POINTER, DATA, UNIT=UNIT, $
BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME, NEXT_BLOCK=NEXT_BLOCK, $
INITIALIZE=INITIALIZE, FULL=FULL, PROMOTE64=PROMOTE64, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure reads the header of an IDL SAVE record. The header
consists of four bytes at the beginning of each record which
indentifies the type and size of the record. This procedure also
additionally reads many full records as noted below.
Users can determine the block type by examining the values
returned in the BLOCK_TYPE and BLOCK_NAME keywords. The following
values are supported. Some record types contain additional data.
CMSV_RREC reads some of these record types automatically (those
entries below marked with [this procedure]). Other records do not
contain any additional data at all (those entries marked with an
[empty]), and thus require no further processing.
BLOCK_TYPE BLOCK_TYPE READ RECORD DATA WITH...
0 = 'START_MARKER' [empty]
1 = 'COMMON_BLOCK' [this procedure]
2 = 'VARIABLE' CMSV_RVTYPE / CMSV_RDATA
3 = 'SYSTEM_VARIABLE' CMSV_RVTYPE / CMSV_RDATA
6 = 'END_MARKER' [empty]
10 = 'TIMESTAMP' [this procedure]
12 = 'COMPILED' no published procedure
13 = 'IDENTIFICATION' [this procedure]
14 = 'VERSION' [this procedure]
15 = 'HEAP_INDEX' [this procedure]
16 = 'HEAP_DATA' CMSV_RVTYPE
17 = 'PROMOTE64' [empty]
For records that contain variable data, the external procedures
CMSV_RVTYPE and CMSV_RDATA must be used, as noted above.
Otherwise CMSV_RREC will read and convert the appropriate data
automatically and return it in the DATA positional parameter.
The offset of the next record is returned in the NEXT_BLOCK
keyword. For file input, the command, "POINT_LUN, UNIT,
NEXT_BLOCK" will position the file pointer to the next block.
Users should be aware that the SAVE files produced by IDL version
5.4 appear to have a different header format. The new header size
is five bytes, and is incompatible with the older format. In
order to activate the longer header size, the PROMOTE64 keyword
must be set.
By default the entire record is not read from the file at once.
Users that wish to operate on the entire record immediately should
set the FULL keyword.
After issuing a POINT_LUN the block cache in BLOCK must be reset
using the /INITIALIZE keyword.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
SPECIFIC RECORD TYPES
CMSV_RREC reads certain specific record types automatically and
returns the data in the positional parameter data. Users should
pass a named variable in this parameter to retrieve the return
value.
When a record of type 'VERSION' (14) is encountered, it is read,
and returned as a structure. The returned data are of the form:
{ FORMAT_VERSION: 0L, $ ; Format version number of file
ARCH: '', $ ; !VERSION.ARCH of creating host
OS: '', $ ; !VERSION.OS of creating host
RELEASE: '' } ; !VERSION.RELEASE of creating host
When a record of type 'TIMESTAMP' (10) is encountered, it is read,
and returned as a structure. The returned data are of the form:
{ SAVE_DATE: '', $ ; Date the save file was created
SAVE_USER: '', $ ; User name who created file
SAVE_HOST: '' } ; Host name that created file
Save files created by IDL version 4 do not contain a timestamp
record.
When a record of type 'IDENTIFICATION' (13) is encountered, it is
read, and returned as a structure. The returned data are of the
form:
{ AUTHOR: '', $ ; Author of SAVE file
TITLE: '', $ ; Title of SAVE file
IDCODE: '' } ; Identifying code for SAVE file
It appears that this record is not used in IDL version 5 or later.
When a record of type 'COMMON_BLOCK' (1) is encountered, it is
read and returned. A common block descriptor consists of an array
of strings whose first element is the common block name, and whose
remaining elements are the common block variable names. No
variable data are stored with the common block definition.
When a record of type 'HEAP_INDEX' (15) is encountered, it is read
and returned in DATA. The heap index specifies a list of which
heap variables are stored in the current save file. These indices
are simply numbers which identify each heap variable (i.e.,
"" would have an index of 2). Users should note that
the heap index will not necessarily be sequentially increasing,
and may have gaps.
Users should consult CMSV_RDATA for instructions on how to read
heap data.
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
KEYWORDS:
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
BLOCK_TYPE - upon return, the numeric record type, as described
above.
BLOCK_NAME - upon return, a scalar string specifying the record
type, as specified above.
NEXT_BLOCK - upon return, file offset of the next record in the
file.
INITIALIZE - if set, then BLOCK and POINTER are initialized to a
pristine state. All data in these two variables is
lost before reading the next record.
FULL - if set, then the entire record will be read into BLOCK.
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Fix typo for RHEAP call, CM, 21 Apr 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rrec.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rrec.pro)
NAME:
CMSV_RVTYPE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read variable type information from input block or file unit
CALLING SEQUENCE:
CMSV_RVTYPE, BLOCK, POINTER, NAME, SIZE, UNIT=UNIT, $
TEMPLATE=TEMPLATE, SUFFIX=SUFFIX, $
/NO_CREATE, /NO_TYPE, /HEAP, /SYSTEM, $
STRUCTURE_NAME=STNAME, $
NAMED_STRUCTS=STRUCTS, NAMED_CLASSES=CLASSES, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_RVTYPE reads the type portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure reads the type descriptor returns it to the user.
This procedure can also determine the name of a variable; the heap
index number of a heap variable; and other important information.
Once the type of the data has been determined, the data portion
can be read using the CMSV_RDATA procedure.
CMSV_RVTYPE should recognize and correctly return type descriptor
information about all known IDL data types, as of this writing.
It should be noted that CMSV_RDATA will not necessarily be capable
of reading all of these data types, but the description of the
data should still be readable. Users can then use this
information to print a summary of the file contents for example.
The type information are normally returned in the SIZE parameter,
which gives the IDL variable type, and the dimensions of the
variable just as the IDL built-in function SIZE() would do.
However, in the case of structures, there is much more information
to convey. To assist the user a blank template structure is
returned in the keyword parameter TEMPLATE, which they can then
pass on to CMSV_RDATA.
Users should be aware of structure and class name clashes. The
problem arises because CMSV_RVTYPE must actually instantiate any
named structures or classes in the file. If these named
structures clash with the definitions of the structures on the
user's local computer, then an error will result. To prevent
this, the user can use the SUFFIX keyword. If the SUFFIX keyword
contains a string, then this string is appended to any structure
names discovered in the save file, before instantiation. Thus, as
long as the suffix is a unique string, there will be no clashes
with local structure definitions. Users are advised to pick a
different suffix for *each* save file that they open.
CMSV_RVTYPE also provides some diagnostic information about the
variable. Users can pass the NAMED_STRUCTS and NAMED_CLASSES
keywords in order to discover what named structures, classes and
superclasses are stored in the save file (this is especially
useful with the NO_TYPE keyword). Since the contents of
NAMED_STRUCTS and NAMED_CLASSES are not destroyed, but appended to
instead, users are advised to clear these variables when opening
each new file.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
NAME - upon return, the identifier of the variable. For named
variables, NAME is a string. For heap variables, NAME is
an integer heap index.
SIZE - upon return, an integers array describing the variable type
and size, in the same format as returned by the built-in
function SIZE.
KEYWORDS:
TEMPLATE - upon return, if the variable is a structure, TEMPLATE
will contain a single blank template structure, which
can be used in calls to CMSV_RDATA.
NO_CREATE - if set, then do not create any template structures
(saves execution time and structure name clashes).
NO_TYPE - if set, do not read type information. CMSV_RVTYPE
returns only the variable NAME or heap index.
HEAP - if set, then read the variable type assuming it is a heap
variable (a HEAP_DATA record).
SYSTEM - if set, then read the variable type assuming it is a
system variable (a SYSTEM_VARIABLE record).
SUFFIX - a scalar string, the suffix to be appended to any
structure names to force them to be unique.
STRUCTURE_NAME - upon return, if the variable is a named
structure, STRUCTURE_NAME will contain the name
of the structure as a string.
NAMED_CLASSES /
NAMED_STRUCTS - upon input, this keyword should contain an
undefined or a string array value.
If the variable contains any named structure/class
definitions, CMSV_RVTYPE will append those names
upon return, including any enclosed structures or
superclasses.
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is not used by this routine at this time)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rvtype.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_rvtype.pro)
NAME:
CMSV_TEST
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Test the CMSVLIB library
CALLING SEQUENCE:
CMSV_TEST, FILENAME, USER_VALUE=UVALUE
DESCRIPTION:
CMSV_TEST performs a standard test of the CMSVLIB library. It
reads and writes a save file using several different methods in an
attempt to test the different ways that the library can be used.
The test procedure can be used to verify that the library is
functioning properly.
By default, this procedure provides standard values to be written,
but the user can provide one of them with the USER_VALUE keyword.
If the user's data contains pointers, they must expect tests
listed under CMSVREAD and CMSVWRITE to fail.
By default the file is written in the current directory, but this
can be changed with the FILENAME parameter.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
FILENAME - a scalar string, the output path.
Default: 'CMSVTEST.SAV' in current directory
KEYWORDS:
USER_VALUE - any IDL variable to be saved, in place of variable
"C" in the test.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Resolve all routines at start, and add VMS keyword, 14 Feb 2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_test.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_test.pro)
NAME:
CMSV_WDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write SAVE-formatted data variable record to output block or file
CALLING SEQUENCE:
CMSV_WDATA, BLOCK, POINTER, DATA, UNIT=UNIT, TEMPORARY=TEMPORARY, $
PTR_INDEX=PTR_INDEX, PTR_DATA=PTR_DATA, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_WDATA writes the data portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure writes the raw data to the output. The initial
type descriptor portion of the record must have already been
writtenusing the CMSV_WVTYPE procedure.
Under normal circumstances a user will write variable or heap data
using the CMSV_WREC procedure.
CMSV_WDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
The caller must specify in the DATA parameter, the data to be
written to output. The variable passed as DATA must have the same
type and dimensions as passed to CMSV_WVTYPE.
Unlike most of the other output routines, this procedure is able
to send its output to a file rather than to the BLOCK buffer. If
the UNIT keyword is specified then output is sent to that file
UNIT, after any pending BLOCK data is first sent. Users should
note that after such operations, the BLOCK POINTER and OFFSET
parameters may be modified (ie reset to new values).
See CMSV_WREC for instructions on how to write heap data.
[ This code assumes the record header and type descriptor have
been written with CMSV_WREC and CMSV_WVTYPE. ]
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, the intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the data to be written, of any save-able data type.
KEYWORDS:
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wdata.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wdata.pro)
NAME:
CMSV_WRAW
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write raw SAVE data to output block
CALLING SEQUENCE:
CMSV_WRAW, BLOCK, POINTER, DATA, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure writes raw integer or string data to an IDL SAVE
block in memory. This is the lowest level writing function in the
library, intended for developers who are investigating new and
existing SAVE file formats.
The data to be written is specified by the DATA parameter. The
data must be of type BYTE, LONG or STRING, and the type is
determined automatically from the data itself. [ The mnemonic
STRING LONG and BYTE keywords are accepted for programming clarity
but ignored. ]
This procedure accepts but currently ignores the UNIT keyword. It
is the caller's responsibility to write the BLOCK data to disk
when appropriate.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be written is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written. Must of type STRING, BYTE or LONG.
KEYWORDS:
LONG - ignored (to be used for clarity)
BYTE - ignored (to be used for clarity)
STRING - ignored (to be used for clarity)
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wraw.pro,v 1.6 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wraw.pro)
NAME:
CMSV_WREC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write SAVE-formatted record header to output block or file
CALLING SEQUENCE:
CMSV_WDATA, BLOCK, POINTER, DATA, IDENT, UNIT=UNIT, $
INITIALIZE=INITIALIZE, NO_DATA=NO_DATA, $
NO_TYPE=NO_TYPE, COMPATIBILITY=COMPAT, $
BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME,
NEXT_BLOCK=NEXT_BLOCK, $
[ ... EXTRA KEYWORDS ... ]
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure writes most types of IDL SAVE record, including the
header and contents. The header consists of four bytes at the
beginning of each record which indentifies the type and size of
the record. This procedure also writes the contents of certain
records, as noted below.
Users can specify the block type by passing the BLOCK_TYPE or
BLOCK_NAME keywords. The values listed in the following table are
supported. CMSV_WREC writes the contents of essentially all
record types as well. Some records do not contain any contents at
all (those entries marked with an [empty]) and thus require no
further processing.
BLOCK_TYPE BLOCK_TYPE WRITE RECORD CONTENTS WITH...
0 = 'START_MARKER' [empty]
1 = 'COMMON_BLOCK' [this procedure]
2 = 'VARIABLE' [this procedure]
3 = 'SYSTEM_VARIABLE' [this procedure]
6 = 'END_MARKER' [empty]
10 = 'TIMESTAMP' [this procedure]
12 = 'COMPILED' no published procedure
13 = 'IDENTIFICATION' [this procedure]
14 = 'VERSION' [this procedure]
15 = 'HEAP_INDEX' [this procedure]
16 = 'HEAP_DATA' [this procedure]
17 = 'PROMOTE64' [empty]
For records that contain variable data, the external procedures
CMSV_WVTYPE and/or CMSV_WDATA may be used, however it is not
recommended, since the record header must finally be re-written by
the user. Users can write the entire record with this procedure.
After issuing a POINT_LUN, or after writing the BLOCK to disk, the
block cache in BLOCK must be reset using the /INITIALIZE keyword.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
SPECIFIC RECORD TYPES
CMSV_WREC reads certain specific record types automatically based
on data passed in the DATA parameter.
Records of type 'VARIABLE' (2), 'SYSTEM_VARIABLE' (3) and
'HEAP_DATA' (16) require both the DATA and IDENT parameters. For
the first two record types, the IDENT parameter is the name of the
variable, as a scalar string. Variable names should be valid IDL
variable names, uppercase, and have no embedded spaces. For the
'HEAP_DATA' record type, the IDENT parameter is the heap index
value, as described below. The DATA itself can be any supported
IDL variable type (as described in CMSV_WVTYPE).
For records that accept data in the form of a structure, as listed
below, the listed structure tag entries are optional. If the user
does not provide a value, then a suitable default will be computed
by this procedure (listed in parentheses).
A record of type 'VERSION' (14) has the following structure:
{ FORMAT_VERSION: 0L, $ ; Format version number of file (5)
ARCH: '', $ ; !VERSION.ARCH of creating host
OS: '', $ ; !VERSION.OS of creating host
RELEASE: '' } ; !VERSION.RELEASE of creating host
A record of type 'TIMESTAMP' (10) has the following structure:
{ SAVE_DATE: '', $ ; Date the save file was created (SYSTIME(0))
SAVE_USER: '', $ ; User name who created file ('UNKNOWN')
SAVE_HOST: '' } ; Host name that created file ('UNKNOWN')
Save files created by IDL version 4 do not contain a timestamp
record. Under Unix this procedure will attempt to discover the
user and host names automatically.
A record of type 'IDENTIFICATION' (13) has the following
structure:
{ AUTHOR: '', $ ; Author of SAVE file ('')
TITLE: '', $ ; Title of SAVE file ('')
IDCODE: '' } ; Identifying code for SAVE file ('')
It appears that this record is not used in IDL version 5 or later.
A record of type 'COMMON_BLOCK' (1) defines a named common block
and its variables. A common block descriptor consists of an array
of strings whose first element is the common block name, and whose
remaining elements are the common block variable names. Thus, a
common block descriptor must have at least two elements. No
variable data are stored with the common block definition.
A record of type 'HEAP_INDEX' (15) defines the heap index in a
SAVE file. The heap index specifies a list of which heap
variables are stored in the current save file. These indices are
simply numbers which identify each heap variable (i.e.,
"" would have an index of 2). The heap index can use
any numbers to identify the heap data; however it is required that
all index entries have corresponding heap data values.
WRITING HEAP DATA
If your data contains heap data and/or pointers, then users must
take special care in writing their data. Writing heap data is
actually more straightforward than reading it. There are several
steps involved which can be summarized as followed: (1) take
inventory of HEAP data; (2) write HEAP_INDEX record; (3) write one
HEAP_DATA record for each heap variable; and (4) write any other
variables using the heap index.
(1) Take inventory of heap data. Before writing any data to the
SAVE file, use the CMSV_PTRSUM procedure to discover all
pointer variables in the data set, like so:
cmsv_ptrsum, var, ptrlist
PTRLIST contains an array of any heap variables pointed to by
VAR (including structures or pointed-to variables). If
multiple variables are to be written, then the inventory must
contain the union of all heap variables.
(2) Write a HEAP_INDEX record. The heap index is an array of long
integers which identify the heap variables. In principle it
doesn't matter which integers are used, however there must be
a one-to-one correspondence between the entries in the heap
index and the heap identifiers used in the next step. In this
example a simple LINDGEN is used:
index = lindgen(n_elements(ptrlist))
cmsv_wrec, block, pointer, index, block_name='HEAP_INDEX', $
offset=offset
(3) Write one HEAP_DATA record for each heap variable. Issue one
CMSV_WREC call for each entry in PTRLIST, as follows for the
ith heap variable:
cmsv_wrec, block, pointer, ptrlist(i), block_name='HEAP_DATA', $
ptr_index=index, ptr_data=ptrlist, offset=offset
Note that the PTR_INDEX and PTR_DATA keywords are required
because heap data may itself contain pointers. The PTR_INDEX
and PTR_DATA keywords enable the CMSV_WREC procedure to write
appropriate descriptors when it encounters pointers.
(4) Write remaining data. For the ith variable, use:
cmsv_wrec, block, pointer, var(i), name(i), block_name='VARIABLE',$
ptr_index=index, ptr_data=ptrlist, offset=offset
As above, using the PTR_INDEX and PTR_DATA keywords will allow
the CMSV_WREC procedure to write the appropriate data.
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, the intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the record contents to be written, as describe above.
IDENT - for record types 'VARIABLE' (2) and 'SYSTEM_VARIABLE' (3),
the name of the variable as a scalar string. For record
type 'HEAP_DATA' (16), the heap index identifier as a
scalar long integer.
KEYWORDS:
BLOCK_NAME - a scalar string specifying the record type, as
described above. The BLOCK_TYPE keyword takes
precedence over BLOCK_NAME.
BLOCK_TYPE - a scalar integer specifying the record type, as
described above.
NEXT_BLOCK - if specified, the file offset of the next record
location.
Default: the offset will be computed automatically.
INITIALIZE - if the keyword is set, then the BLOCK is emptied and
the POINTER is reset before any new data is written.
NO_TYPE - if set, no type descriptor or data are written for
variable records.
NO_DATA - if set, no data are written for variable records.
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wrec.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wrec.pro)
NAME:
CMSV_WVTYPE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write variable type information to output block
CALLING SEQUENCE:
CMSV_WVTYPE, BLOCK, DATA, IDENT, $
HEAP=HEAP, SYSTEM=SYSTEM, UNIT=UNIT, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_WVTYPE writes the type portion of an IDL SAVE variable
record. An IDL variable is stored in two components: the type
descriptor which describes the name, type, and dimensions of the
variable; and the data record, which contains the raw data of the
variable. This procedure writes the type descriptor based on a
variable passed by the user. Once the type descriptor has been
written, the data portion can be written using the CMSV_WDATA
procedure.
CMSV_WVTYPE should recognize and correctly output type descriptors
for all currently known IDL data types, except for object
references. Type information is inferred from the DATA parameter
passed by the user.
Heap data is a special case, since the data itself are stored
separately from the pointer in the SAVE file. Three steps must be
satisfied: a HEAP_INDEX record must be written; a valid HEAP_DATA
record must be written containing a type descriptor (written with
this procedure) and the heap data; and the named pointer itself
must be written.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be written is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written, of any save-able data type.
IDENT - for variables, the name of the variable as a string; for
heap data, the heap index as an integer.
KEYWORDS:
HEAP - if set, the data is treated as heap data, and IDENT must be
an integer heap index.
SYSTEM - if set, the data is assumed to be a system variable.
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wvtype.pro,v 1.13 2002/05/13 06:41:10 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsv_wvtype.pro)
NAME:
CMSYSTIME
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute seconds since Jan 1, 1970 and (Modified) Julian Days
CALLING SEQUENCE:
TIMEVAL1 = CMSYSTIME(TIMEVAL0, ...)
DESCRIPTION:
CMSYSTIME serves two functions. It computes the current time in a
fashion similar to the built-in IDL system function SYSTIME(). It
also can convert between various time representations and systems,
including a textual format.
The current time can be obtained by invoking CMSYSTIME with the
/NOW keyword (which is entirely equivalent to SYSTIME(1)).
The most substantial part of CMSYSTIME, which distinguishes it
from SYSTIME, is its ability to convert between different time
formats. CMSYSTIME recognizes can recognize and convert between
time in seconds (seconds since Jan 1, 1970 [ = SEC ]) and days
(Julian days [ = JDAY ] or "Modified" Julian days [ = MJD = JDAY -
2400000.5 ]). It can also recognize and convert between local and
GM time.
CMSYSTIME takes maximum care to preserve the full numerical
precision of the time values. It converts all values to double
precision and may return days and seconds with fractional parts.
CMSYSTIME can also represent any time textually, not just the
current time. The following textual formats are supported:
DOW MMM DD hh:mm:ss YYYY - (Default - same as SYSTIME)
DOW MMM DD YYYY hh:mm:ss.uuuuuu TTTTT - (/EXTENDED)
where DOW and MMM are the abbreviated day of week and month in
English, DD is the day of the month, YYYY is the year, hh:mm:ss is
the time in 24 hr military time, uuuuuu are additional
microseconds, TTTTT is the timezone offset (in +hhmm
representation).
CMSYSTIME accepts one parameter, the input time to be converted.
Unlike SYSTIME, the *function* of CMSYSTIME is governed by various
keywords, as summarized in the following table:
Converting from Converting to
--------------- -------------
JDAY - /FROM_JULIAN JDAY - /JULIAN
MJD - /FROM_MJD MJD - /MJD
SEC - (Default) SEC - /SECONDS
Current time - /NOW TEXT - (Default or /EXTENDED)
Local time - /FROM_LOCAL Local time - /LOCAL
GM time - (Default) GM time - (Default)
If no argument is specified, the default is to report the current
time textually in the GM time zone. CMSYSTIME automatically
determines the local time zone.
INPUTS:
TIMEVAL0 - input time, in seconds or days, as described above.
This value is ignored if the NOW keyword is set. Array
values are allowed.
KEYWORDS:
NOW - If set, TIMEVAL0 is ignored and the current time is used as
input.
FROM_JULIAN - If set, TIMEVAL0 is in Julian days.
FROM_MJD - If set, TIMEVAL0 is in Modified Julian days (MJD).
FROM_LOCAL - If set, TIMEVAL0 is in the local time zone.
If no FROM_ keywords are set, the input is assumed
to be seconds from Jan 1, 1970.
JULIAN - If set, the input is converted to Julian days upon output.
MJD - If set, the input is converted to MJD upon output.
SECONDS - If set, the input is converted to seconds from Jan
1, 1970 upon output.
LOCAL - If set, the input is converted to the local time zone.
If no "destination" keywords are set, the output is
converted to textual representation.
EXTENDED - Convert to a textual representation with additional
information, as noted above.
TIMEZONE - Upon output, the timezone offset is returned in this
keyword. The offset is time difference in seconds
between GM time and the local time, such that LOCALTIME
= GMTIME + TIMEZONE
RETURNS:
The resulting converted time(s), either as a double precision
number or a string.
EXAMPLE:
The equivalent to SYSTIME(0)
IDL> print, systime(0) & print, cmsystime(/now, /local)
Wed Jul 5 12:10:46 2000
Wed Jul 5 12:10:46 2000
The equivalent to SYSTIME(1)
IDL> print, systime(1) & print, cmsystime(/now,/seconds)
9.6277750e+08
9.6277750e+08
Comparison between local and GM time zones (I live in the Eastern
US, daylight savings)
IDL> print, cmsystime(/now,/extended)
Wed Jul 5 2000 16:13:15.659000 -0400
IDL> print, cmsystime(/now,/local,/extended)
Wed Jul 5 2000 12:13:15.664000 -0400
What day of the week was it 200 days ago? (Note, there are 86400
seconds in one day)
IDL> today = cmsystime(/now,/seconds)
IDL> print, cmsystime(today-86400L*200, /local)
Sat Dec 18 12:17:52 1999
SEE ALSO:
SYSTIME, JULDAY, CALDAT
MODIFICATION HISTORY:
Written, CM, 05 Jul 2000
Printed time zone is zero when LOCAL=0, CM, 21 Aug 2000
$Id: cmsystime.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\cmsystime.pro)
NAME: cnes PURPOSE: This procedure is an example how to translate a cnes file CATEGORY: EXAMPLES CALLING SEQUENCE: cnes MODIFICATION HISTORY: Written by: R. Bauer , May, 4, 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\examples\cnes.pro)
NAME: cnes2ncdf PURPOSE: This procedure will translate a cnes Data File and translate it into a netCDF File. CATEGORY: DATAFILES/FILTER CALLING SEQUENCE: cnes2ncdf,file=file,inpath=inpath,outpath=outpath,[campaign=campaign],[/xp] ,[gps_aus=gps_aus] INPUTS: file: the filename of the cnes file inpath: the path where the cnesfile is outpath: the path where the result should be stored OPTIONAL INPUTS: campaign: the campaign name belonging to the cnes file KEYWORD PARAMETERS: xp: will use pickfile for opening a cnes file OPTIONAL OUTPUTS: gps_aus: the GPS data array from the cnesfile EXAMPLE: inpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/asc/' outpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/bin/' file = 'kir05110297.krn' campaign = 'ADEOS1997' cnes2ncdf,file=file,inpath=inpath,outpath=outpath,campaign=campaign MODIFICATION HISTORY: Written by: R.Bauer March, 3, 1997 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cnes2ncdf.pro)
NAME: cnes_kir2ncdf PURPOSE: This procedure will translate a cnes KIR Data File and translate it into a netCDF File. CATEGORY: DATAFILES/FILTER CALLING SEQUENCE: cnes_kir2ncdf,file=file,inpath=inpath,outpath=outpath,[campaign=campaign],[/xp] ,[gps_aus=gps_aus] INPUTS: file: the filename of the cnes file inpath: the path where the cnesfile is outpath: the path where the result should be stored OPTIONAL INPUTS: campaign: the campaign name belonging to the cnes file KEYWORD PARAMETERS: xp: will use pickfile for opening a cnes file OPTIONAL OUTPUTS: gps_aus: the GPS data array from the cnesfile EXAMPLE: inpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/asc/' outpath = '/usr/local/icg/icg1/daten/experiments/adeos/cnes/bin/' file = 'kir05110297.krn' campaign = 'ADEOS1997' cnes_kir2ncdf,file=file,inpath=inpath,outpath=outpath,campaign=campaign MODIFICATION HISTORY: Written by: R.Bauer March, 3, 1997 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cnes_kir2ncdf.pro)
NAME:
COLOR
PURPOSE:
Set a color in the color table by specifying color name.
CATEGORY:
CALLING SEQUENCE:
color, name, [index, r, g, b]
INPUTS:
name = color name (like red, green, ...). in
Name may be modified by the words dark, pale,
very dark, very pale.
(Only one very is handled). Default color=white.
index = color table index for new color (def=last). in
r, g, b = components of color table to modify. in,out
If r,g,b sent then table is not loaded.
KEYWORD PARAMETERS:
Keywords:
FILE=f color file to use instead of the default.
Text file, each line has r g b color_name.
/LEARN prompts for r,g,b values of an unknown color.
/LIST lists all available colors.
MAXNUMBER=mx return number of colors known.
NUMBER=n Select color by color number (0 to MAXNUMBER-1).
Index # 255 is set by default. To set a different index
a dummy color name must also be given. It is ignored.
Ex: color,'dum',50,number=7 sets index 50 to color 7.
If no args are given default color and index used.
NAME = nam return name of selected color.
Useful with NUMBER keyword.
TEXT=txt returns 0 or 255, whichever best with color.
RED=r. Return red value for specified color.
GREEN=g. Return green value for specified color.
BLUE=b. Return blue value for specified color.
/EXIT exit without modifying screen color table.
OUTPUTS:
COMMON BLOCKS:
color_com
NOTES:
MODIFICATION HISTORY:
R. Sterner, 26 Dec 1989
R. Sterner, 7 Jun, 1990 --- polished for vms.
R. Sterner, 4 Feb, 1991 ---- made system independent.
R. Sterner, 1997 Dec 30 --- Converted colors file to text file
and dropped need for Env. Var.
R. Sterner, 1998 Jan 14 --- Switched to !d.table_size instead
of !d.n_colors.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\color.pro)
NAME:
COLOR24
PURPOSE:
The purpose of this function is to convert a RGB color triple
into the equivalent 24-bit long integer. The 24-bit integer
can be decomposed into the appropriate color by interpreting
the lowest 8 bits as red, the middle 8 bits as green, and the
highest 8 bits as blue.
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, Color Specification.
CALLING SEQUENCE:
color = COLOR24(rgb_triple)
INPUTS:
RGB_TRIPLE: A three-element column or row array representing
a color triple. Or an N-by-three element array of color triples.
The values of the elements must be between 0 and 255.
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To convert the color triple for the color YELLOW,
(255, 255, 0), to the hexadecimal value '00FFFF'x
or the decimal number 65535, type:
color = COLOR24([255, 255, 0])
This routine was written to be used with device-independent
color programs like GETCOLOR.
MODIFICATION HISTORY:
Written by: David Fanning, 3 February 96.
Completely revised the algorithm to accept color arrays. 19 October 2000. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\color24.pro)
NAME:
COLORBAR
PURPOSE:
The purpose of this routine is to add a color bar to the current
graphics window.
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, Widgets.
CALLING SEQUENCE:
COLORBAR
INPUTS:
None.
KEYWORD PARAMETERS:
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARSIZE: The character size of the color bar annotations. Default is 1.0.
COLOR: The color index of the bar outline and characters. Default
is !P.Color..
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(I5)'.
INVERTCOLORS: Setting this keyword inverts the colors in the color bar.
MAXRANGE: The maximum data value for the bar annotation. Default is
NCOLORS.
MINRANGE: The minimum data value for the bar annotation. Default is 0.
MINOR: The number of minor tick divisions. Default is 2.
NCOLORS: This is the number of colors in the color bar.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.15, 0.95, 0.95] for a vertical bar and
[0.15, 0.88, 0.95, 0.95] for a horizontal bar.
;
RANGE: A two-element vector of the form [min, max]. Provides an
alternative way of setting the MINRANGE and MAXRANGE keywords.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
TITLE: This is title for the color bar. The default is to have
no title.
TOP: This puts the labels on top of the bar rather than under it.
The keyword only applies if a horizontal color bar is rendered.
VERTICAL: Setting this keyword give a vertical color bar. The default
is a horizontal color bar.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
EXAMPLE:
To display a horizontal color bar above a contour plot, type:
LOADCT, 5, NCOLORS=100
CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
C_COLORS=INDGEN(25)*4, NLEVELS=25
COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]
MODIFICATION HISTORY:
Written by: David Fanning, 10 JUNE 96.
10/27/96: Added the ability to send output to PostScript. DWF
11/4/96: Substantially rewritten to go to screen or PostScript
file without having to know much about the PostScript device
or even what the current graphics device is. DWF
1/27/97: Added the RIGHT and TOP keywords. Also modified the
way the TITLE keyword works. DWF
7/15/97: Fixed a problem some machines have with plots that have
no valid data range in them. DWF
12/5/98: Fixed a problem in how the colorbar image is created that
seemed to tickle a bug in some versions of IDL. DWF.
1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
3/30/99: Modified a few of the defaults. DWF.
3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
3/30/99: Added the RANGE keyword. DWF.
3/30/99: Added FONT keyword. DWF
5/6/99: Many modifications to defaults. DWF.
5/6/99: Removed PSCOLOR keyword. DWF.
5/6/99: Improved error handling on position coordinates. DWF.
5/6/99. Added MINOR keyword. DWF.
5/6/99: Set Device, Decomposed=0 if necessary. DWF.
2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
10/10/99. Modified the program so that current plot and map coordinates are
saved and restored after the colorbar is drawn. DWF.
3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
4/28/00. Made !P.Font default value for FONT keyword. DWF.
9/26/00. Made the code more general for scalable pixel devices. DWF.
1/16/01. Added INVERTCOLORS keyword. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\colorbar.pro)
NAME:
COLORBAR
PURPOSE:
Draw a colorbar (legend) with labels
CATEGORY:
Colors
CALLING SEQUENCE:
COLORBAR [,options]
INPUTS:
KEYWORD PARAMETERS:
COLOR -> the drawing color for boxes and labels
(default: !P.COLOR)
BOTTOM -> first color index to use (default: 1)
NCOLORS -> number of colors to use (default:
!D.N_Colors-bottom)
MIN, MAX -> range of the data (default bottom and
bottom+ncolors-1
LABEL -> array with label values (must be numeric).
Normally, it is easier to generate labels with the
DIVISIONS options, but this allows tighter control
(e.g. 1,2,5,10,20 labels on logarithmic scales).
Default (if no DIVISIONS are given): min and max
DIVISIONS -> number of labels to put on the colorbar.
Note that this keyword is overwritten by LABEL.
The labels will be equally spaced and the /LOG option
will be honored.
FORMAT -> output format of the labels. Default is determined
according to the range given in min and max. Label strings
will be trimmed, so you can safely specify f14.2 for example.
SCIENTIFIC -> If set, will call STRSCI to put the colorbar
labels in scientific notation format (e.g. in the form
A x 10^B). STRSCI will use the format string specified
in the FORMAT keyword.
/LOG -> logarithmic spacing of labels (colors are *always*
linearily distributed)
C_COLORS -> array of color indices for "discrete" color bars
e.g. in filled contour plots. You must also use the
C_LEVELS keyword, otherwise there will most likely be
a mismatch between your plot colors and your colorbar
colors. COLORBAR normally limits the number of labels
it prints to 10. Use the SKIP keyword to force a different
behaviour. If C_COLORS is not undefined it overrides the
settings from NCOLORS, and BOTTOM.
C_LEVELS -> array with label values for discrete colorbars.
Use the LABEL keyword for continuous colors. C_LEVELS
must have the same number of elements as C_COLORS and
assigns one label to each color change (LABEL distributes
the labels evenly). Use the SKIP keyword to skip labels.
As default, COLORBAR limits the number of labels printed
to 10.
NB: In order to be consistent with the behaviour of the
CONTOUR procedure, colorbar disregards the first entry of
C_LEVELS.
SKIP -> print only every nth discrete label. Default is computed
so that COLORBAR will print no more than 10 labels.
STARTLABEL -> for discrete colorbars: the first left box side to be
labeled. Default is 1, i.e. between the first two boxes.
/VERTICAL -> set this keyword to produce a vertical colorbar
(default is horizontal). Note that out-of-range boxes are
only implemented for horizontal color bars.
POSITION -> a position value or 4-element vector. If POSITION
contains only one element, it will be centered at the
bottom or right side of the page and extend over 60% of
the total plotting area.
CHARSIZE -> character size (default !p.charsize)
TITLE -> a title string (similar to XTITLE or YTITLE for PLOT)
UNIT -> a unit string that will be added to the right (top) of
the labels
BotOutOfRange, TopOutOfRange -> a colorindex value for data
that falls below or above the normal plot range. If given,
an extra box will be drawn to the left or right of the color-
bar, and the colorbar will shrink in size. A default label
'<' ('>') will be placed below. Note that these options are
only available for horizontal colorbars.
BOR_Label, TOR_Label -> label values for BOTOutOfRange and
TopOutOfRange that replace the defaults.
OUTPUTS:
SUBROUTINES:
REQUIREMENTS:
The user should have some knowledge about colortables and the
use of parts of a colortable.
This program uses STRSCI for labels in scientific notation.
NOTES:
This routine was designed after David Fanning's colorbar
routine and enhanced. Some of the postscript
handling of DF was removed, positioning is a little easier but
maybe a little less flexible; out-of-range boxes have been
added.
EXAMPLE:
; draw a colorbar with all available colors on top of index 20
; will be placed at the bottom of the page
colorbar,bottom=20,min=min(data),max=max(data)
; draw another colorbar above the first one, use logarithmic scale
colorbar,bottom=20,min=0.1,max=10.,labels=[0.1,0.5,1.,5.10.],/log, $
position=0.3,unit='ppt'
; (simply add keyword /vertical and you'll get it flipped)
; colorbar with out-of-range information on right side only
; Here we used 20 colors for the plot, the 21st is for
; out-of-range data
colorbar,bottom=20,ncolors=20,min=0,max=100,divisions=5, $
TopOutOfRange=40
MODIFICATION HISTORY:
mgs, 02 Jun 1998: VERSION 1.00
mgs, 14 Nov 1998: - changed default format to f14.2 from f6.2
mgs, 19 Nov 1998: - added cbdefaultformat function to better handle
default labeling format.
mgs, 28 Nov 1998: - default labelling format now exponential for
values gt 1.e6
mgs, 19 May 1999: - unit string placed a little further right
in horizontal colorbars.
mgs, 27 May 1999: - added functionality for discrete colorbars
(C_COLORS, C_LEVELS, and SKIP keywords)
bmy, 02 Jun 1999: - added /SCIENTIFIC keyword
- updated comments
mgs, 14 Sep 1999: - charsize bug fix. Needed to check for 0.
mgs, 23 Sep 1999: - now uses !P.COLOR as default color (as it was originally)
- BOTTOM default now 1 (because 0 is the standard beackground
value)
mgs, 17 Dec 1999: - fixed zero division for SKIP=0
- added StartLabel keyword for discrete colorbars
mgs, 20 Dec 1999: - disregard first entry of C_LEVELS
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\colorbar.pro)
NAME:
COLORBAR__DEFINE
PURPOSE:
The purpose of this routine is to implement a COLORBAR object
class. The ColorBar is rendered in the direct graphics system.
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:
colorbar = Obj_New("COLORBAR")
INPUTS:
All inputs to the program are via keyword parameters.
KEYWORD PARAMETERS:
Background: Background color. This is the color with which the colorbar is
erased. The default color is !P.Background.
Bottom: Bottom color index of colors allocated to colorbar.
Charsize: Character size of annotation. Default is 1.0.
Color: Color of annotation and outline. Default is !P.Color.
Font: Font to use for annotation. Default is -1, Hershey fonts.
Format: Format of annotation. Default is "(F8.2)".
Major: The number of major tick intervals. Default is 5.
Minor: The number of minor tick intervals. Default is 2.
MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command
that resizes the colorbar into the window.
NColors: The number of colors allocated to colorbar. Default is (256 <
!D.N_Colors).
Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is
0 (Bilinear).
Position: The position of colorbar in normalized coordinates. Default for a
horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a
vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are
designed for a 400 by 400 window.
Range: The data range on colorbar. Default is [0, 255].
TickLen: The length of tick marks. Default is -0.1
TickV: Locations for the tick marks in data units. This is the same as
the [XY]TickV keyword. Default is to do what IDL would do
normally.
Vertical: Set this keyword if you want a vertical colorbar. Default is
horizontal.
XEraseBox: A five-element vector of X points (normalized) for erasing the
colorbar plot. Normally this keyword will not have to be used.
The program uses the plot REGION for erasing. But larger
character sizes can result in annotation going outside the
region enclosed by the plot. If that is the case, then use this
keyword along with YEraseBox to specify a larger-than-normal
erasure area. The points are sent to the POLYFILL command for
erasing.
POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background
YEraseBox: A five-element vector of Y points (normalized) for erasing the
colorbar plot.
OBJECT METHODS:
Clamp: This procedure method allows the color bar range to be "clamped"
to a particular data range.
Draw: This procedure method draws the colorbar in the display window. The
ERASE keyword to this method will erase the current colorbar (by
calling the ERASE method) before drawing the colorbar in the display
window.
colorbar->Draw
Erase: This procedure method erases the colorbar object in the window. It
accomplishes this by performing a POLYFILL in the background color.
This method is primarily useful for interactive graphics display
devices.
colorbar->Erase
GetProperty: This procedure method allows one to obtain the current state
of the object via the keyword parameters listed above.
colorbar->GetProperty, Range=currentRange, Title=currentTitle
Print, currentRange, currentTitle
SetProperty: This procedure method allows one to set the properties of the
colorbar object via the keywords described above. In addition,
a DRAW and ERASE keyword are provided so that the colorbar can
be immediately drawn when the new property is set.
colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw
COMMON BLOCKS:
None.
SIDE EFFECTS:
The display window is not erased first.
RESTRICTIONS:
None.
EXAMPLE:
To create a colorbar, use it, then destroy it, type:
colorbar = Obj_New("COLORBAR", Title='Colorbar Values', Range=[0,1000],$
Format='(I4)')
Window
LoadCT, 5
colorbar->Draw
colorbar->SetProperty, Range=[0,500], /Erase, /Draw
Obj_Destroy, colorbar
MODIFICATION HISTORY:
Written by: David Fanning, Fanning Software Consulting,
26 November 1998.
Added Horizontal keyword to SetProperty method and fixed problem in
going from Vertical to Horizontal color bars. 29 Nov 1998. DWF.
Added LoadCT method and current color table index to object.
6 December 1998.
Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF.
Fixed a bug with how NCOLORS and BOTTOM keywords interacted.
29 Aug 1999. DWF.
10 Oct 99. Modified the program so that current plot and map coordinates
are saved and restored after the colorbar is drawn. DWF.
26 May 2000 Added {XY}TICKV capability to the draw method. This
required adding TickV to the object data structure, and to the
INIT, GetProperty and SetProperty methods.
Changed default tick length to -0.1. DWF (and Jack Saba)
18 Nov 2001. Added Clamp method. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\colorbar__define.pro)
NAME:
colorchart
PURPOSE:
produce a chart with many colors to test printers and find colors
suitable for plotting.
EXPERIMENTAL STATUS - NOT PERFECT
CATEGORY:
Colors
MODIFICATION HISTORY:
mgs, some time in 1999.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\colorchart.pro)
NAME:
COLORIZE
PURPOSE:
Colorize an image.
CATEGORY:
CALLING SEQUENCE:
colorize
INPUTS:
KEYWORD PARAMETERS:
Keywords:
IMAGE=img Name of GIF image to colorize.
COLORS=clr Name of GIF image with color areas to overlay.
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: Result is displayed on screen.
MODIFICATION HISTORY:
R. Sterner, 1999 Aug 17
Copyright (C) 1999, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\colorize.pro)
NAME:
COLORS8BIT
PURPOSE:
Show array of 256 colors in a window.
CATEGORY:
CALLING SEQUENCE:
colors8bit
INPUTS:
KEYWORD PARAMETERS:
Keywords:
BLACK=blk Specify black or dark color (def=0).
WHITE=wht Specify white or bright color (def=1).
These are used for the index numbers.
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: useful to pick colors from the window systems
colors in case IDL cannot control the colors. For
example, when using 256 colors on a workstation and
a widget, the IDL colors will not show up while using
the widget. This may make it impossible to use the
widget. One work around is to use good window colors
for the IDL graphics. For example, window color 23
may be white and 32 blue. If XOR mode graphics is used
then XOR 55 with 23 to get 32 (32 = 23 xor 55). If the
background color is bck and you want plot color clr then
just plot (bck XOR clr), where the plot crosses the
background it will be that color.
MODIFICATION HISTORY:
R. Sterner, 1998 May 12
Copyright (C) 1998, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\colors8bit.pro)
NAME:
COLORWARN
PURPOSE:
Warn if available IDL colors too few.
CATEGORY:
CALLING SEQUENCE:
colorwarn
INPUTS:
KEYWORD PARAMETERS:
Keywords:
MINIMUM=n Alert if below this value.
/QUIET Suppress information message.
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1996 Feb 23
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\colorwarn.pro)
ROUTINE: color_bar
PURPOSE: draw a horizontal color bar
USEAGE: color_bar
INPUT:
levels
a vector of physical values (required)
colors
a vector of color values. If colors is not specified a
continuous spectrum of colors between colors values 1 and
!d.n_colors-2 are used.
KEYWORD INPUT:
pos
position of color bar in normal or subnormal coordinates
[xmin,ymin,xmax,ymax], if pos is not specified, CURBOX is
called to set the color bar position interactively.
digits
number of significant digits used in number scale label
digits=0 causes an integer format to be used. any positive value
causes a floating point format.
stride
if set, label only those intervals which have n mod stride eq 0,
where n is the number of intervals counting left to right.
subnorm
use subnormal coordinates to specify pos. subnormal coordinates
vary from 0 to 1 across the range of the last plotting window.
If not set, normalized coordinates are used.
labels a string array of labels for color values.
if nlabels eq nlevels ==> center labels under tick marks
if nlabels eq nlevels-1 ==> center labels between tick marks
otherwise ==> execution stops, error message issued
where nlabels=n_elements(labels) and nlevels=n_elements(levels)
title overall title for color bar, appears below labels
OUTPUT:
none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
loadct,5
!y.omargin=[10,0]
!p.multi=[0,2,2]
r=randata(50,50,s=4) & r=(r-3)
levels=-9+indgen(10)
colors=findrng(20,!d.n_colors,9)
confill,r,/noscale,levels=levels,colors=colors
confill,rotate(r,1),/noscale,levels=levels,colors=colors
confill,rotate(r,2),/noscale,levels=levels,colors=colors
confill,rotate(r,3),/noscale,levels=levels,colors=colors
!y.omargin=0
labels='10!a-'+strcompress(string(8-indgen(9)),/rem)
title='ozone mass density (ug/m3)'
color_bar,levels,colors,labels=labels,title=title
; use a continuous spectrum of colors
!y.omargin=[10,0]
!p.multi=[0,2,2]
r=randata(50,50,s=4) & r=(r-3)
levels=-9+indgen(10)
colors=findrng(20,!d.n_colors,9)
tvim,r & tvim,rotate(r,1) & tvim,rotate(r,2) & tvim,rotate(r,3)
!y.omargin=0
color_bar,indgen(10),labels=labels,title=title
AUTHOR: Paul Ricchiazzi 09 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_bar.pro)
ROUTINE: color_frame
PURPOSE: draw a color background on which to overlay plots
USEAGE: result=color_frame(color,pos=pos,xmargin=xmargin,ymargin=ymargin)
INPUT:
color
the background color of the plot frame
KEYWORD INPUT:
pos
4 element vector specifying the lower left and upper right
normalized coordinates of the plot frame [xll,yll,xur,yur]
xmargin
2 element vector specifying the left and right margins in character
width units
ymargin
2 element vector specifying the lower and upper margins in character
height units
bg_color
back ground color used outside of plot frame
;
OUTPUT:
result
4 element vector specifying the lower left and upper right
normalized coordinates of the plot frame [xll,yll,xur,yur]
DISCUSSION:
COLOR_FRAME can be used to produce color backgrounds within plot
frames. Since COLOR_FRAME itself calls PLOT to obtain the
default frame position, it is necessary to include the NOERASE
keyword in the PLOT call that actually draws the plot. See examples.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
!p.multi=[0,1,2]
loadct,5
xx=findrng(-2.5,2.5,200)
yy=exp(-xx^2)
yc=cos(xx*10)
plot,xx,yy,pos=color_frame(50),/noerase
plot,xx,yc*yy,pos=color_frame(70),/noerase
plot,xx,yc^2*yy,pos=color_frame(90),/noerase
plot,xx,yc^3*yy,pos=color_frame(110),/noerase
;; multi-frame plot
loadct,5
!p.multi=[0,1,2]
plot,xx,yy,pos=color_frame(100,ymargin=ymulti(p,np=2)),/noerase
plot,xx,yc*yy,pos=color_frame(60,ymargin=ymulti(p)),/noerase
;; plot within a plot
loadct,5
!p.multi=0
plot,xx,yy*yc,pos=color_frame(50,bg=10),/noerase
plot,xx,yy,pos=color_frame(100,pos=boxpos(/cur)),/noerase
;; color in frame over a different background color
loadct,5
plot,xx,yy,pos=color_frame(100,bg=50),/noerase,color=255
AUTHOR: Paul Ricchiazzi 23 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_frame.pro)
ROUTINE: COLOR_KEY
PURPOSE: draws a numbered color scale.
NOTE: COLOR_KEY is intended to replace PUT_COLOR_SCALE
USEAGE:
COLOR_KEY,pos=pos,ysize=ysize,range=range,inc=inc,$
charsize=charsize,barwidth=barwidth,step=step,$
labels=labels,title=title,colors=colors,nbotclr=nbotclr
PURPOSE: Draws a numbered color scale
INPUT: no required input
OPTIONAL KEYWORD INPUT:
pos 2 element vector, x and y device coordinates of lower
left hand corner of color bar. If POS is not set the
color bar will be placed one character width to the
right of the lower right corner of the last defined
data window
xoff x offset of color bar from right edge of plot frame in
units of default character with. (default=1) xoff is
disabled when pos is set.
range array which contains full range of physical values,
The number scale limits are computed fron min(range) and
max(range). (default=0-255)
inc increment step of the number scale in physical units
If INC is not set the number scale increment is set
automatically
step if set to one, the color table is modified with STEP_CT.
The color scale is stepped at the number scale intervals.
colors a vector of discreet colors selected from the original
color table. In this case the original color table is
not modified and the number of elements of COLORS
is used to find the number scale increments. This
option should be used with devices that do not accept
user specified color tables (such as the Apple Laser
Writers). BEWARE: when the COLORS option is used with
TVIM's SCALE option care must be taken to ensure that
COLOR_KEY's number scale matches the quantity values.
Unlike the STEP option, this is not automatic (see
example below)
nbotclr number of reserved colors at the bottom of the color
table. these colors will not appear in the color key.
charsize character size on number scale
ysize vertical size of color bar in device units.
if ysize is negative, the abs of ysize is interpreted
as the normalized z coordinate of the top of the bar.
barwidth width of color bar (default=1)
labels a vector of strings used to label the color key levels
if not set the default color key number labels are
used. If the number of elements in LABELS is the same
as the number of elements in COLORS then the labels
will appear in the middle of a given color band
instead of at the boundary between colors.
title color scale title drawn to the right of the color key
slevels selected levels at which to mark vertical scale. If LABELS
is also set, the number of elements in LABELS should be
equal to either nsl, or nsl-1 where nsl is the number of
elements in SLEVELS. The SLEVELS input does not work when
COLORS is also specified.
rct if set, reverse direction of grey scale increase. This
keyword can be used on black & white printers to allow
large field values to be represented by dark colors.
KEYWORD OUTPUT
clevels physical values at the color key tic marks
SIDE EFFECTS:
if STEP is set COLOR_KEY calls STEP_CT to discreetize
the color scale. To return to original color table
enter STEP_CT,/OFF
EXAMPLE:
; on devices which allow user defined color tables:
loadct,0
TVIM,dist(200),/scale
COLOR_KEY,range=dist(200),inc=20,/step ; change the color scale
COLOR_KEY,range=dist(200),inc=40,/step ; change it again
; on devices with a single hard-wired color table:
d=dist(200)+20.
inc=step_size(d) ; finds good step size
dmin=fix(min(d)/inc)*inc
dmax=fix(max(d)/inc)*inc
nclrs=(dmax-dmin)/inc
colors=!p.color*indgen(nclrs)/(nclrs-1)
TVIM,colors((d-dmin)/inc),/scale,/c_map
color_key,range=[dmin,dmax],colors=colors
; draw one big color key which applies to all tvim images on frame
!p.multi=[0,2,2]
loadct,5
im1=randata(128,128,s=3)
im2=rotate(im1,5)
im3=rotate(im1,7)
im4=rotate(im1,2)
range=[min(im1,max=mx),mx]
!x.omargin=[0,20]
tvim,im1,range=range
tvim,im2,range=range
tvim,im3,range=range
tvim,im4,range=range
color_key,range=range,xoff=10,ysize=-.97
; logarithmic scales
im=randata(128,128)
im=abs(im) & im=3*(im/max(im) > .001)
tvim,im,/rmarg ; here we assume im is the log10 of some plot quantity.
ndec=3 ; number of decades
slevels=[1.] ; starting value
for i=0,ndec-1 do slevels=[slevels,(findgen(9)+2)*10.^i]
slevels=alog10(slevels)
labels=strarr(n_elements(slevels))
labels(indgen(ndec+1)*9)=string(f='("10!a",i1,"!b")',indgen(ndec+1))
color_key,range=im,slevels=slevels,labels=labels
AUTHOR: Paul Ricchiazzi jan93
Earth Space Research Group, UCSB
REVISIONS:
20sep93: put in LABELS option
21sep93: use pure white blankout color for postscript
22sep93: put in COLORS option
09sep96: put in SLEVELS option
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_key.pro)
ROUTINE: color_pal AUTHOR: Terry Figel, ESRG, UCSB 10-21-92 CALLING SEQUENCE: color_pal PURPOSE: Displays Color palette in a seperate window
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\color_pal.pro)
NAME:
COLOR_QUANJ
PURPOSE:
Combines Red, Green, Blue components into a color image.
CATEGORY:
CALLING SEQUENCE:
c = color_quanj(red, grn, blu, r, g, b)
INPUTS:
red, grn, blu = Red, green, and blue images. in
KEYWORD PARAMETERS:
Keywords:
COLORS=n Number of colors to have in final image
(def=number of available colors).
/DITHER Combined using dithering.
/DISPLAY Display resulting image.
/ORDER Display image with first line at top.
OUTPUTS:
r,g,b = Color table for combined color image. out
c = Resulting color image. out
COMMON BLOCKS:
NOTES:
Notes: This routine uses another color combining method
then color_quan, it writes the image to a JPEG file and
then reads it back. This gives better results than
color_quan in some cases.
MODIFICATION HISTORY:
R. Sterner, 1995 Nov 24
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\color_quanj.pro)
NAME:
color_scheme
PURPOSE:
This procedure is used to load one or more predefined dynamical color scheme (ct_*.pro')
CATEGORY:
PLOT/PLOT2D
CALLING SEQUENCE:
color_scheme,plot,[scheme_code=scheme_code]
INPUTS:
plot: This is the defined plot scructure look at pl_init
If it is not given defaults will be loaded from pl_init
KEYWORD PARAMETERS:
scheme_code: the integer code or "character string" of the color scheme
1: a dyamical color code from yellow - red - blue - green - black that's the default
2: a dyamical color code from blue - red - yellow
3: a dyamical color code from blue - green - yellow - red
12: a dyamical color code from yellow - red - blue
20: a dynamical gray scaled color code
'ct_yellow_red_blue'
EXAMPLE:
color_scheme,plot,scheme_code=1
or for setting up of two colorsystems:
color_scheme,plot,scheme_code=[20,2]
or
color_scheme,plot,scheme_code=['ct_yellow_red_blue_green_black','ct_yellow_red_blue']
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1997-Oct-5
R.Bauer 1997-Nov-12 additional colortable
1998-Jul-8 multiple color tables added
1999-Feb-05 because of idl5.2 interpretation of !d.n_colors this constant is replaced by def_n_colors()
1999-Feb-28 color names changed
1999-Dec-08 some more colortables added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\color_scheme.pro)
NAME:
COLOR_WHEEL
PURPOSE:
Pick a color using a color wheel.
CATEGORY:
CALLING SEQUENCE:
color_wheel, clr
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/VARYWHEEL means vary wheel brightness using bar.
XPOS=xpos, YPOS=ypos Window position.
SIZE=sz Size of color wheel (def=200).
OUTPUTS:
clr = Returned color. out
-1 means ignore new color.
COMMON BLOCKS:
NOTES:
Notes: color is selected by clicking on a color
wheel and brightness bar.
MODIFICATION HISTORY:
R. Sterner, 2000 Aug 22
R. Sterner, 2001 Feb 15 --- Added HSV and RGB listing.
Copyright (C) 2000, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\color_wheel.pro)
USERLEVEL:
TOPLEVEL
NAME:
combine_path_file
PURPOSE:
This function will combine path and file, change '\' to '/' and add '/' to the path if necessaray
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
result=combine_path_file(path,file)
INPUTS:
path,file : scalar strings
OUTPUTS:
result: correct combination of path and file
SIDE EFFECTS
will resolve multiple // into /
EXAMPLE:
result=combine_path_file('d:\/temp','test.xxx')
will return result:'d:/temp/test.xxx'
result=combine_path_file('d:\/temp','')
will return result:'d:/temp/'
MODIFICATION HISTORY:
Written by Franz Rohrer Aug 1998
Modified
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\combine_path_file.pro)
NAME:
COMMALIST
PURPOSE:
Return a given array as a comma delimited text list.
CATEGORY:
CALLING SEQUENCE:
list = commalist(array, [form])
INPUTS:
array = Input array of numbers. in
form = Optional format (like I3). in
KEYWORD PARAMETERS:
Keywords:
/NOCOMMAS do not add commas to returned list.
DELIMITER=del Delimiter instead of comma.
OUTPUTS:
list = Returned text string with list. out
COMMON BLOCKS:
NOTES:
Note: see wordarray as a near inverse.
MODIFICATION HISTORY:
R. Sterner, 1995 Nov 28
R. Sterner, 1998 Jul 31 --- Added DELIMITER=d, also fixed for alpha.
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\commalist.pro)
ROUTINE: compass
USEAGE compass, lat0,lon0,alat,alon,rng,az
compass, lat0,lon0,rng,az,alat,alon,/to_latlon
PURPOSE: Given the geographical coordinates of an array of points
on the on the earth's surface, compute the great-circle
distance and compass heading from the central point.
Distances and azimuth angles about the central point are
provided in KM and Degrees.
If TO_LATLON is set, convert the specified range and
azimuth values to lat, lon coordinates
INPUT:
lat0 geographic latitude (degrees) of central point
lon0 geographic longitude (degrees) of central point
INPUT/OUTPUT
alat geographic latitudes
alon geographic longitudes
rng great circle distances (km) from (lat0,lon0) to (alat,alon)
az azimuth angles (degrees), azimuth is measured clockwise
from due north (compass heading)
KEYWORD INPUT:
to_latlon if set, rng, az input converted to lat, lon
EXAMPLE:
;; plot family of great circles passing though lat,lon=(0,0)
rng=findrng(0,2*!pi*6371.2,400)
map_set,/cyl,/cont,/grid
for az=0,90,15 do begin &$
compass,0,0,rng,az,alat,alon,/to_latlon & oplot,alon,alat & endfor
;; find the range and az of Janus Island from Palmer Station
lat0=-64.767 & lon0=-64.067 & alat=-64.78 & alon=-64.11
compass,lat0,lon0,alat,alon,rng,az
compass,lat0,lon0,rng,az,nlat,nlon,/to_latlon
print,f='(6a13)','alat','alon','rng','az','nlat','nlon' &$
print,alat,alon,rng,az,nlat,nlon
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\compass.pro)
NAME: compile_plot PURPOSE: This routine writes a precompiled idl sav file CATEGORY: PRECOMPILE CALLING SEQUENCE: compile_plot MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1998-Jul-05 1999-02-28 independent_path removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\compile_plot.pro)
NAME: compose_structure PURPOSE: This is the reverse function to decompose_structure. For details see that procedure. CATEGORY: PROG_TOOLS CALLING SEQUENCE: result = compose_structure(pstruc [, index]) INPUTS: pstruc: Array of structures as it is obtained from the procedure decompose_structure KEYWORD PARAMETERS: /NO_FREE: If set no PTR_FREE command will be issued to destroys the heap variables. OPTIONAL INPUTS: index: Index vector to subscribe single elements of pstruc OUTPUTS: This function returns a 'normal' structure. EXAMPLE: see decompose_structure MODIFICATION HISTORY: Written by: Frank Holland, 09.12.1999 04.01.2000: Added PTR_FREE command 05.01.2000: Got rid of LINK tag 12.01.2000: Added keyword parameter /NO_FREE
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\compose_structure.pro)
pro compound,compound_string,density,z_array
Type in a chemical formula and the density. The routine
then figures out the atomic weight in g/mole of "molecules"
and how many of what Z atoms you have. The
density isn't really needed here; it's just that if
what you type is defined in
(your directory) compound.dat
(a system directory; see below) compound.dat
then you can type
compound,'protein',density,atwt,z_array
and get both the density and z_array set for you.
Note that you can do "zshow,z_array" to check out the
composition.
CJJ Feb 93
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\HENKE\compound.pro)
NAME: comp_bits PURPOSE: This function performs a bitwise AND operation on two operands. CATEGORY: MATH CALLING SEQUENCE: result = comp_bits(var, value) INPUTS: var, value: the two operands KEYWORD PARAMETERS: /BIT - operandis treated as bit number. the following AND operation is performed: var AND 2^value OUTPUTS: This function either returns 0 if the bitwise AND operation returns 0 or 1 in any other case. EXAMPLE: print, comp_bits(9, 1) --> 1 print, comp_bits(9, 3, /BIT) --> 1 MODIFICATION HISTORY: Written by: Frank Holland, 08. Jun 98. 30.04.1999: Removed debug statement
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\comp_bits.pro)
NAME: comp_k_oh_no2 PURPOSE: This procedure compares different literature values for the reaction constant OH+NO2 CATEGORY: PHYSCHEM CALLING SEQUENCE: comp_k_oh_no2 INPUTS: OUTPUTS: EXAMPLE: comp_k_oh_no2 MODIFICATION HISTORY: Written by: Franz Rohrer March 1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\comp_k_oh_no2.pro)
NAME: concatenate_ncdf_inhalt PURPOSE: This function will concatenate two structures read from a ncdf-file into one. CATEGORY: PROG_TOOLS/STRUCTURES CALLING SEQUENCE: result=concatenate_ncdf_inhalt(master,client) INPUTS: master: master structure client: OUTPUTS: result: concatenated structure Tags 'time', 'param' and the tags flagged in 'flags' are concatenated from master and client. All other tags will be taken from master only. Tag 'valid' will be updated correctly. EXAMPLE: MODIFICATION HISTORY: Written by Franz Rohrer Jan 1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\concatenate_ncdf_inhalt.pro)
NAME: concatinate_two_structure_tags PURPOSE: The result of this function is an structure where the elements of two structure tags are concatinated CATEGORY: PROG_TOOLS/STRUCTURES CALLING SEQUENCE: Result=concatinate_two_structure_tags(master,client) INPUTS: master: The master structure client: the client structure both structure have to have the same tag names defined OUTPUTS: This function returns a structure EXAMPLE: MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1998-Sep-29 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\concatinate_two_structure_tags.pro)
NAME:
concat_str
PURPOSE:
This function concatenates two structures
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
result = concat_str(master, client [,/OVERWRITE] [,/PARSE] [,ERR = err])
INPUTS:
master, client: Two structures
KEYWORD PARAMETERS:
/OVERWRITE: If set, a tag of client will overwrite a tag with the same name in master.
The default is that all tags from master are part of the returned stucture.
ERR: If set to a named variable the error status of the routine will be returned:
0: no error, 1: error ocurred (see log window)
/PARSE: If set, a tag in client will be removed if its name starts with the same
string as the name of a master tag (e.g. master = {tag: 4}, client = {tag_name: 9.2})
If not set (default), a tag in client will only be removed if a tag with exactly
the same name appears in master.
OUTPUTS:
This function returns the structure which results from the concatenation of the two
structures master and client
EXAMPLE:
master = {a: 1, b: 'ASD'}
client = {b: 7L, c: 6.78}
HELP, concat_str(master, client), /STR
** Structure <1362ec4>, 3 tags, length=16, refs=1:
A INT 1
B STRING 'ASD'
C FLOAT 6.78000
master={col: 3, thick: 2, ycharsize: 2}
client={color: 5, thick: 1, charsize: 3}
HELP, concat_str(master, client, /PARSE), /STR
** Structure <1353bf8>, 4 tags, length=8, refs=1:
COL INT 3
THICK INT 2
YCHARSIZE INT 2
CHARSIZE INT 3
MODIFICATION HISTORY:
Written by: Frank Holland, 02. May 1998.
15.11.1998: Header added
17.11.1998: Implemented new procedure to build concatenated structure
17.02.1999: Changed entry under PURPOSE
28.04.1999: Added KEYWORD parameter PARSE
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\concat_str.pro)
NAME:
CONCOORD
PURPOSE:
Convert between two linear coordinate systems.
CATEGORY:
CALLING SEQUENCE:
concoord, x1, y1, x2, y2
INPUTS:
x1,y1 = input coordinates. in
KEYWORD PARAMETERS:
Keywords:
/ROUND means round output to nearest integers.
Intended for pixel coordinates.
/TO_1 the input point(s), x1,y1, are in system 2 and are
to be converted to system 1. /TO_1 is the default.
/TO_2 the input point(s), x1,y1, are in system 1 and are
to be converted to system 2.
/INIT means initialize coordinate transformations.
In this case x1,y1 are the known reference point
coordinates in system 1, and x2,y2 are the known
reference point coordinates in system 2.
At least 3 non-colinear reference points are needed
to define the coordinate transformations, more are
ok. So for /INIT all 4 parameters are inputs and
arrays of at least 3 elements.
NAME1=nm1, NAME2=nm2 Optional coordinate system names,
def=system 1 and system 2. Only on /INIT.
Use /SYSTEMS to display system names at a later time.
Very useful to make the correct calls clear.
OUTPUTS:
x2,y2 = output coordinates. out
COMMON BLOCKS:
concoord_com
NOTES:
Notes: Example for pixel coordinates and lat/long:
concoord,ix,iy,lng,lat,/init,name1='Pixels',name2='Long/lat'
ix,iy are arrays of ref pt pixel coord, lng,lat are
arrays of ref pt long, lat.
concoord,lng,lat,ix,iy,/to_1,/round
From long,lat find pixel coordinates.
MODIFICATION HISTORY:
R. Sterner, 1996 Oct 2
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\concoord.pro)
ROUTINE: confill
PURPOSE: display a contour plot with filled contours
USEAGE: confill,z,x,y,xrange=xrange,yrange=yrange,charsize=charsize,$
title=title,stitle=stitle,xtitle=xtitle,ytitle=ytitle,$
aspect=aspect,colors=colors,range=range,nlevels=nlevels,$
rmarg=rmarg,pcharsize=pcharsize,lcharsize=lcharsize,$
c_thick=c_thick,c_label=c_label,c_charsize=c_charsize,$
c_orientation=c_orientation,c_spacing=c_spacing,$
downhill=downhill,xtype=xtype,ytype=ytype,$
c_color=c_color,labels=labels,position=position,$
levels=levels,rgb_data=rgb_data,noscale=noscale
INPUT:
z
array of field values
x
one or two dimensional array of x axis points
y
one or two dimensional array of y axis points
IF z,x, and y are all one dimensional vectors and all the same
size, it is assumed that irregularly grided data is being
supplied. In this case the routine TRIANGULATE is called to get
the Delaunay triangulation of the data. The triangulation info
is then passed on to CONTOUR
KEYWORD INPUT:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
noscale
if set, no color key will be drawn
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
x axis range. (default = [0,x_dimension-1])
yrange
y axis range. (default = [0,y_dimension-1])
range
two element vector indicating physical range over which
to distribute contour levels.
nlevels
maximum number of contour levels. If LEVELS is not set the
actual number of contour levels is determined automatically by
AUTORANGE. NLEVELS sets the maximum allowed number of levels,
the actual number of levels may be less.
levels
contour level values (vector). The default contour levels are
set by AUTORANGE. The automatically selected levels chosen by
AUTORANGE can be retrieved by setting LEVELS to a named variable
which is initially undefined or set to zero.
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set, the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies used to fill contours. The number of
color values should be one less than the number of levels. The
default colors are chosen to be uniformally distributed over the
full color table. The automatically selected colors chosen by
CONFILL are: colors=fix((!d.n_colors-2)*(1+findgen(nclr))/nclr),
where nclr=n_elements(levels)-1. If COLORS is set to a negative
number these automatically chosen colors are reversed so that dark
colors are used to represent high intensity areas.
NOTE: The default color indicies generated by CONFILL never
include color index 0 or !d.n_colors-1. These indicies are
reserved for the overall plot background and foreground colors.
For best results, color index 0 and !d.n_colors-1 should
correspond to pure black and white respectively, which is
usually the case in the predefined color tables supplied by RSI.
A predefined color table that doesn't follow this rule can be
redefined using TVLCT to put black and white in these slots,
without affecting any of the filled contours used in the CONFILL
plot: tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
c_label
integer array indicating which contour lines to label. For
example, c_label=[0,0,0,1,0,1] indicates that the contour lines
which correspond to levels(3) and levels(5) are to be labeled.
The number of C_LABELs should be the same as the number of
LEVELS. By default no contour lines are labeled.
c_thick
thickness of contour lines (may be a vector of values),
Default is 1.
c_color
color of contour lines (may be a scalor or vector of values).
If c_color is negative then the color of contour lines is chosen
to maximize contrast with adjacent fill colors. The default is
not to drawn contour lines. This keyword must be set to get
contour lines.
NOTE: The number of contour levels is determined automatically
if LEVELS is not set. Hence, it may not be possible to guess
how many values of LABELS, COLORS, C_LABEL, C_THICK or C_COLOR
should be specified. It is probably safer not to include these
parameters unless LEVELS is also specified.
c_orientation
If the FILL keyword is set, this keyword can be set to the angle,
in degrees counterclockwise from the horizontal, of the lines
used to fill contours. If neither C_ORIENTATION or C_SPACING are
specified, the contours are solid filled.
c_spacing
If the FILL keyword is set, this keyword can be used to control
the distance, in centimeters, between the lines used to fill the
contours.
xtype
Set this keyword to specify a logarithmic X axis.
ytype
Set this keyword to specify a logarithmic Y axis.
downhill
Set this keyword to label each contour with short, perpendicular
tick marks that point in the "downhill" direction, making the
direction of the grade readily apparent. If this keyword is set,
the contour following method is used in drawing the contours.
NOTE: Due to a bug in IDL_3.6, the concurrent use of C_LABEL and
DOWNHILL causes an IDL session crash. For this reason the
DOWNHILL option is disabled on IDL_3.6.
aspect
the x over y aspect ratio of the output image. If not set, the
aspect ratio is adjusted to fill the available plotting area.
position
specifies the lower left and upper right CONFILL frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling CONFILL.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to CONFILL.
lcharsize
character size of color key number or labels (default is
pcharsize if set, otherwise !p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of contour plot (default=1).
rgb_nodata
if set, regions with field values less then the minimum of LEVELS
or RANGE will be colored with the RGB values specified in
RGB_NODATA (a scalor or three element vector). Color index 1 is
used for the nodata color. When RGB_NODATA is set don't use
color index 1 in the COLORS input vector.
NOTE: RGB_NODATA has no effect unless either RANGE or LEVELS is
set. This is because the default contour levels are set so that
the minimum level is less than the minimum field value.
overplot if set, current field is super imposed over a previous
confill plot this option only works when z,x, and y are all one
dimensional vectors and all the same size, in which case it is
assumed that irregularly grided data is being supplied. In this
case the routine TRIANGULATE is called to get the Delaunay
triangulation of the data. The triangulation info is then passed
on to CONTOUR.
DEPENDENCIES: COLOR_KEY, AUTORANGE
SIDE EFFECTS: if RGB_NODATA is set the rgb value of color index 1
is modified
EXAMPLES:
loadct,5
n=128
zz=randata(n,n,s=4)
xx=findrng([-120,-100],n)
yy=findrng([20,50],n)
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='contour levels',c_color=-1
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='contour levels',c_color=-1,rgb_nodata=!p.color/2
; labeled regions
levels=-3+findgen(6)*2
labels=[' ocean',' rain!c forrest',' sand',$
' old!c snow',' real!c new!c snow']
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='surface types',labels=labels,levels=levels,barwidth=.5
; contour irregularly grided data
loadct,5
w8x11
n=128
z=randata(n,n,s=4)
x=findgen(n)
y=findgen(n)
!p.multi=[0,1,2]
confill,z,x,y,title='Regularly Grided',c_color=-1
ii=randomu(iseed,200)*(n*n-1) ; random sample points
zz=z(ii) ; random samples
xx=ii mod n ; (zz,xx,yy are vectors)
yy=ii / n
confill,zz,xx,yy,title='Randomly Sampled',c_color=-1
oplot,xx,yy,psym=4,color=1,symsize=.4 ; show locations of sample points
; overlay three irregular regions in one confill plot
loadct,5
w8x11
n=128
z=randata(n,n,s=4)
ii=randomu(iseed,200)*(n*n-1) ; random sample points
zz=z(ii) ; random samples
xx=ii mod n ; (zz,xx,yy are vectors)
yy=ii / n
confill,zz,xx,yy,xrange=[0,300]
confill,zz^2,xx+150,yy/2,/overplot
confill,sqrt(zz>0),xx+150,70+yy/2,/over
AUTHOR: Paul Ricchiazzi 24 May 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\confill.pro)
NAME: CONFRAC VERSION: 4.0 PURPOSE: Performs continued fraction evaluation. CATEGORY: Mathematical function (general). CALLING SEQUENCE: Result = CONFRAC( A, B [,X [, keywords]]) INPUTS: A A numeric scalar, vector or a 2-D array. A(i,*) contains the i-th A coefficient(s) of the continued fraction. B Same as A for the B coefficient(s). A and B must agree in their first dimension, i.e. if A is an (N,M) array (including the possibility of M = 1) then B must be an (N,M') array, with an arbitrary M'. OPTIONAL INPUT PARAMETERS: X Numeric, otherwise arbitrary. When provided, X is used together with A and B to determine the continued fraction coefficients. KEYWORD PARAMETERS: AFUNCTION Name of a function to be used (with the CALL_FUNCTION routine) to determine the A coefficients. Optional. BFUNCTION Same as AFUNCTION for the B coefficients. Optional. EPSILON Smallness parameter, determining the allowed evaluation error. Optional. Default values are machine dependent, established through TOLER which calls MACHAR(). /RELATIVE Switch. If set, EPS represent the allowed relative evaluation error. ERROR Optional output, see below. STATUS Optional output, see below. OUTPUTS: Returns the value(s) of the continued fraction. The result is of the same format as X (a scalar if X is not given). The type of the result is the highest of the types of A, B, and X, but no lower than 4 (float). OPTIONAL OUTPUT PARAMETERS: ERROR The name of the variable to receive the estimated evaluation error. Given in the same format as X (scalar if X isn't provided). If RELATIVE is set the error returned is relative. STATUS The name of the variable to receive evaluation status information. Same format as ERROR. Possible values are: 0 - evaluation didn't converge. 1 - OK. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None other then the restrictions on A, B, as mentioned above. PROCEDURE: CONFRAC evaluates continued fractions of the form res = a(0)/(b(0) + a(1)/(b(1) + a(2)/(b(2) + ...... Using the recurrence relation from Numerical Recipies, Sec 5.2. The designation of the coefficients a(i), b(i) depends on the data provided, as follows: 1) If X isn't provided then a(i) = A(i) (or A(i,0) if A is a 2-dim array) and same is true for b(i) (using B) 2) If X is provided then a(i) = Sum_j(A(i,j)*X^j) and the same for b(i) using B. In other words the fraction coefficients are polynomials in X, using columns of A, B, as polynomial coefficients. Note that if A and/or B are one dimensional arrays then only X^0 is used i.e. we are back to case 1. 3) If AFUN and/or BFUN are provided then a(i) = afun(x,A(i,*),i) and same for b(i) with BFUN and B. The functions can be arbitrary but they must accept at least three parameters. CONFRAC uses CALCTYPE, CAST, DEFAULT, FPU_FIX, POLEVAL, TOLER and TYPE from MIDL. MODIFICATION HISTORY: Created 20-DEC-1994 by Mati Meron. Modified 10-SEP-1998 by Mati Meron. Underflow filtering added. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\confrac.pro)
NAME:
CONGRID2
PURPOSE:
Alternate (and limited) congrid using interpolate.
CATEGORY:
CALLING SEQUENCE:
z2 = congrid2(z,mx,my)
INPUTS:
z = input 2-d array. in
mx, my = requested output array size. in
KEYWORD PARAMETERS:
Keywords:
/INTERPOLATE means do bilinear interpolation.
Default is nearest neighbor.
/CENTERED means assume pixels centered. This means
the pixel at (0,0) is clipped to 1/4 size.
Default is that pixel start (not center) is at index.
OUTPUTS:
z2 = resulting array. out
COMMON BLOCKS:
NOTES:
Notes: tries to correct problems in congrid. Result may
look odd due to extrapolation. For example, using
/CENT and /INTERP gives results with magnified pixels
not all the same size.
MODIFICATION HISTORY:
R. Sterner, 1996 Dec 2
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\congrid2.pro)
NAME:
CONGRID8C
PURPOSE:
Do 24 bit congrid interpolation on 8 bit color image.
CATEGORY:
CALLING SEQUENCE:
out = congrid8c(in, nx, ny)
INPUTS:
in = input 8 bit color image. in
nx,ny = New output image dimensions. in
KEYWORD PARAMETERS:
Keywords:
INRED=r1 Input image red color table.
INGREEN=g1 Input image green color table.
INBLUE=b1 Input image blue color table.
If these are not given the current color table is used.
RED=r1 Output image red color table.
GREEN=g1 Output image green color table.
BLUE=b1 Output image blue color table.
/INTERP, /CUBIC, and /MINUS_ONE work as for congrid.
OUTPUTS:
out = interpolated output image. out
COMMON BLOCKS:
NOTES:
Notes: Intended for 8 bit color images such as GIF or TIFF.
MODIFICATION HISTORY:
R. Sterner, 1994 May 4
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\congrid8c.pro)
NAME: CONJ_MM VERSION: 4.0 PURPOSE: Returns complex conjugate values. CATEGORY: Mathematical, general. CALLING SEQUENCE: Result = CONJ_MM (X) INPUTS: X Numerical, otherwise arbitrary. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: None. OUTPUTS: Returns the complex conjugate of the input, if the input is complex, else returns the input. The only difference from the RSI function CONJ is that the output of CONJ_MM is always of the same numerical type as the input. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Straightforward. Calling CAST and ISNUM from MIDL. MODIFICATION HISTORY: Created 15-JUL-2000 by Mati Meron. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\conj_mm.pro)
routine: connected
useage: connected,image,nstring,view=view
purpose: The bi-level image is searched for all pixels which are
are part a continous set of adjacent pixels. Those pixel
groupings which contain fewer than NSTRING "on" pixels are
set to zero.
input:
image a bi-level image array (2d)
nstring the number of "on" pixels required for a given cluster of
adjacent pixels to survive.
output:
image a bi-level image with islands composed of fewer than nstring
pixels removed.
EXAMPLE:
r=randata(128,128,s=2) gt 7
connected,r,3,/view
WARNING: this procedure can take a lot of time for large images.
for images larger than 64 x 64 computation times goes
something like
time=c * (NX x NY)^2
for a DecStation 5000/240, c=7.4e-8, and
a 256x256 image takes about 5 minutes.
author: Paul Ricchiazzi Nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\connected.pro)
NAME: CONSTANTS VERSION: 4.0 PURPOSE: Creates or updates a system variable named !PCON. !PCON is a structure the fields of which contain values of physical constants as follows: !PCON USYS - Unit System. Either 'MKS' or CGS'. C - Speed of light. E - Electron charge. H - Planck constant. ME - Electron mass. K - Boltzman constant. NA - Avogadro constant. ECONV - Used internally for unit conversion. HBAR - Planck constant divided by 2*pi. ALPHA - Fine structure constant. AMU - Atomic mass unit. SIGMA - Stefan-Boltzman radiation constant. All the values are given in a double precision format. Of course, the actual accuracy depends on how precisely they can be measured. CATEGORY: Utility. CALLING SEQUENCE: CONSTANTS [,/MKS or /CGS] INPUTS: None. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /MKS Switch. Sets the units system to MKS. This is also the default. /CGS Switch. Sets the units system to CGS. Default is MKS. OUTPUTS: None. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: M_CONS. Contains a single parameter, EXISTS. SIDE EFFECTS: None. RESTRICTIONS: Can't use both MKS and CGS at the same time. PROCEDURE: Either creates or, if EXISTS is defined, updates the system variable !PCONS. Uses ONE_OF from MIDL. MODIFICATION HISTORY: Created 30-MAR-1994 by Mati Meron. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\constants.pro)
ROUTINE: contlev
PURPOSE: find a good set of contour levels
USEAGE: result=contlev(a)
INPUT:
a an array
KEYWORD INPUT:
maxlev maximum number of levels on the plot. Setting this keyword to,
say, 5 does not mean you will get 5 levels. It just means no
more than 5 levels will be generated.
OUTPUT:
result a vector of contour levels
EXAMPLE: contour,dist(20),levels=contlev(dist(20),maxlev=8)
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\contlev.pro)
NAME:
CONTRASTZOOM
PURPOSE:
The purpose of this program is to demonstrate how to
zoom an image "in place" and how to window and level
(set "contrast and brightness") an image using object
graphics functionality. The exercise involves using
multiple views in an object graphics scene, and being
able to interact with different views in different ways.
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:
Widgets, Object Graphics.
CALLING SEQUENCE:
ContrastZoom, image
REQUIRED INPUTS:
None. The image "mr_knee.dcm" from the examples/data directory
is used if no data is supplied in call.
OPTIONAL INPUTS
image: A 2D image array of any data type.
OPTIONAL KEYWORD PARAMETERS:
COLORTABLE: The number of a color table to use as the image palette.
Color table 0 (grayscale) is used as a default.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None. The Coyote Library program VCOLORBAR is included.
EXAMPLE:
To use this program with your 8-bit image data and a red-temperature
color scale, type:
IDL> ContrastZoom, image, Colortable=3
NOTES:
The left image is used to "zoom" into a portion of the image.
The aspect ratio of the sub-image is always preserved. To see
the entire image, click and release the mouse button in this
window.
The center image is used to adjust the contrast and brightness
(sometimes called the "window" and "level" of the image. Click and
drag the mouse vertically to set contrast. Click and drag the mouse
horizontally to set brightness. To return to original values (25%
contrast and 75% brightness), click and release in the center image.
The color bars shows the image values of the image.
MODIFICATION HISTORY:
Written by David Fanning, 18 November 2001.
Added second colorbar to show the relationship of the clamped
colors to the overall image values. 19 November 2001. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\contrastzoom.pro)
NAME:
cont_error_19990804
PURPOSE:
This example shows the error by contour and triangulation
CATEGORY:
EXAMPLES/PLOT/PLOT2D
CALLING SEQUENCE:
cont_error_19990804
EXAMPLE:
cont_error_19990804
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Aug-04
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\examples\plot\plot2d\cont_error_19990804.pro)
NAME: conv13b_10b PURPOSE: this procedure will remove all ^M in unix from pc created idlscripts CATEGORY: PROG_TOOLS CALLING SEQUENCE: conv13b_10b,file_name INPUTS: file_name: the name of the file RESTRICTIONS: will only work on unix EXAMPLE: conv13b_10b MODIFICATION HISTORY: Written by: R.Bauer (ICG-1),August 1997 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\conv13b_10b.pro)
NAME:
convert_icgs_name
PURPOSE:
If an ICG structure and a short name (tag name) is provided this function returns
one of the following: [short name, tag name, long name, unit].
CATEGORY:
ICG_STRUCT/PROG_TOOLS
CALLING SEQUENCE:
result = convert_icgs_name(icgs, name)
INPUTS:
icgs: ICG structure
name: short name of parameter in ICG structure (scalar or array).
KEYWORD PARAMETERS:
/TAG_NAME: If set name is interpreted as tag name.
/TO_SHORT_NAME: If set conversion is to short name.
/TO_TAG_NAME: If set conversion is to tag name.
/TO_LONG_NAME: If set conversion is to long name ('NONE' if not defined).
/TO_UNITS: If set conversion is to unit ('NONE' if not defined).
OUTPUTS:
This function returns the [short name, tag name, long name, unit] for
parameters in an ICG structure which are characterized by their short
or tag name.
EXAMPLE:
hox_data = read_ncdf('hox.nc')
PRINT, convert_icgs_name(hox_data, 'OH', /TO_LONG_NAME) ---> 'OH radical concentration'
MODIFICATION HISTORY:
Written by: Frank Holland, 18.02.2000
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\convert_icgs_name.pro)
NAME:
CONVERT_IND
PURPOSE:
Convert a text description of runs of indices to numbers.
CATEGORY:
CALLING SEQUENCE:
ind = convert_ind(txt)
INPUTS:
txt = text string or array. in
KEYWORD PARAMETERS:
OUTPUTS:
ind = long array of indices. out
COMMON BLOCKS:
NOTES:
Notes: txt contains a list of integers. A range may
be indicated by the syntax b:e where b = beginning,
and e = end of the range. A step, s, may also be
given: b:e:s. An example list might be:
txt=['2,3,4,10:20:2,25:30','34,35,38:40','50:100:10,111']
print,convert_ind(txt) gives:
2 3 4 10 12 14 16 18 20 25 26 27 28 29 30
34 35 38 39 40 50 60 70 80 90 100 111
Inverse of LISTRUNS.PRO.
MODIFICATION HISTORY:
R. Sterner, 24 Jul, 1991
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\convert_ind.pro)
NAME:
CONVERT_INDEX
PURPOSE:
Converts a 1-D array index (such as is returned from
WHERE, UNIQ, etc) to the appropriate 1-D, 2-D, or 3-D
array indices
CATEGORY:
Array Tools
CALLING SEQUENCE:
Result = CONVERT_INDEX( Index, Dim )
INPUTS:
INDEX -> The 1-D array index to be converted to
multi-dimensional indices. INDEX is returned
to the calling program unchanged.
DIM -> A vector containing the dimensions of the array
for which multi-dimensional indices are required.
KEYWORD PARAMETERS:
FORTRAN -> Interpret array indices as FORTRAN indices, i.e.
starting from 1 instead of 0. This applies to INPUT
and OUTPUT indices!
OUTPUTS:
Returns either a vector index or a vector of multi-dimensional
array indices as the value of the function. If INDEX is a
1-dimensional parameter, the result will have n_elements(dim)
dimensions, if Index is a multidimensional parameter, the result
will be a scalar.
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
Right now only works for 3-D arrays and smaller. Will
eventually do the general case...
EXAMPLE:
IDL> print,convert_index([1,1],[2,2])
3
IDL> print,convert_index([2,2],[2,2])
% CONVERT_INDEX: Index[0] greater than Dim[0]
% CONVERT_INDEX: Index[1] greater than Dim[1]
6
IDL> print,convert_index([2,2],[2,2],/FORTRAN)
4 ; <<<-- shifted by 1 !
IDL> print,convert_index(72,[72,46,20])
0 1 0
IDL> print,convert_index(72,[72,46,20],/FORTRAN)
72 1 1
MODIFICATION HISTORY:
bmy, 07 Oct 1998: VERSION 1.00
mgs, 07 Oct 1998: VERSION 1.20
- made result etc LONG arrays
- allow sany dimensions now
- added reverse operation if index is multidimensional
- added FORTRAN keyword
mgs, 23 Aug 2000: - changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\convert_index.pro)
NAME:
CONVERT_LON
PURPOSE:
Convert longitudes from -180..180 to 0..360 or vice
versa.
CATEGORY:
Geography
CALLING SEQUENCE:
CONVERT_LON,data,names,Pacific=Pacific,Atlantic=Atlantic, $
minval=minval
INPUTS:
DATA -> A data array (lines,vars) or vector containing
longitude data. If DATA is a 2D array, the NAMES
parameter must be given to identify the LONgitude variable.
NAMES -> A string list of variable names. The longitude data
must be labeled 'LON', unless specified with the LONNAME
keyword. The NAMES parameter is not needed, if a data
vector is passed.
KEYWORD PARAMETERS:
PACIFIC -> Convert longitudes from -180..180 to 0..360
ATLANTIC -> Convert from 0..360 to -180..180
LONNAME -> Name of the longitude variable if a name other
than 'LON' is used.
OUTPUTS:
The longitude column in the data array will be changed.
SUBROUTINES:
REQUIREMENTS:
NOTES:
EXAMPLE:
londat = [ -180.,-179.,-0.1,0.1,179.,180.,270.,359.]
CONVERT_LON,londat,/Pacific
print,londat
CONVERT_LON,londat,/Atlantic
print,londat
MODIFICATION HISTORY:
mgs, 25 Aug 1998: VERSION 1.00
mgs, 19 May 1999: - now makes sure that longitude range does
not exceed -180..180 or 0..360
mgs, 24 Jun 1999: - bug fix: choked at missing values
mgs, 23 Aug 2000: - changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\convert_lon.pro)
NAME:
CONVERT_UNIT
PURPOSE:
Convert data to a different unit. You can either
replace a unit by the corresponding standard SI unit or
replace a specific unit with another one.
CATEGORY:
General Science
CALLING SEQUENCE:
CONVERT_UNIT,DATA,UNIT,TOPARAM [,keywords]
INPUTS:
DATA -> A data vector, array, or a single value that shall
be converted to a new unit.
UNIT -> A string variable containing the (current) unit of
DATA. This will be replaced by the new unit afterwards.
If omitted, you must give the FROM_UNIT keyword to indicate
the current unit of DATA.
TOPARAM -> The unit to convert DATA to. This is equivalent to
the keyword TO_UNIT and overwrites it.
KEYWORD PARAMETERS:
FROM_UNIT -> An individual unit to search and replace. If not
given, any unit will be converted to TO_UNIT, as long as
the current unit belongs to the same physicalcategory.
TO_UNIT -> An individual unit to convert to. If not given, all
unit that are converted (see FROM_UNIT) will be replaced
by the standard SI unit of their physicalcategory.
For the individual unit and categories see FIND_UNIT
RESULT -> returns 1 if conversion was successful, 0 otherwise
This keyword is mostly for consistency witholder routines.
It is more convenient to test !ERROR_STATE.CODE for being
0.
MINVAL -> minimum valid data value. Only data above this
value will be converted (default: -1.E30)
QUIET -> In case of an error, an error message is displayed,
and the !ERROR_STATUS system variable is set to reflect the
error condition (program execution continues). Set the
QUIET keyword to suppress the error message.
OUTPUTS:
DATA will be converted and unit will contain new names.
SUBROUTINES:
REQUIREMENTS:
Uses FIND_UNIT
NOTES:
CONVERT_UNIT wil return the value and unit unchanged if
the unit was not found in the standard list (see FIND_UNIT)
or the physicalcategory of the target unit does not match the
physicalcategory of the source unit. In these cases,
!ERROR_STATE.CODE will be set to signal an error condition.
Should try the udunits implementation by ?????
EXAMPLE:
; create some data
data = findgen(100)
unit = 'cm'
; convert all data to SI unit of same category (m)
convert_unit,data,unit
; test success
if (!ERROR_STATE.CODE ne 0) then stop
; convert temperature in Fahrenheit to 'deg C'
; (multiple calls to capture all different spellings)
; Data will only be changed if unit is indeed Fahrenheit
convert_unit,data,unit,from='F',to='deg C'
convert_unit,data,unit,from='degF',to='deg C'
convert_unit,data,unit,from='deg F',to='deg C'
; (easier way) convert any temperature to 'C'
; This will also convert 'K' !
; Don't display error message
convert_unit,data,unit,to='C',/QUIET
; convert 'mph' data to SI ('m/s')
convert_unit,data,unit,from='mph'
; explicitely convert 'cm' to 'm'
convert_unit,data,'cm','m'
; equivalent to
convert_unit,data,from='cm',to='m'
MODIFICATION HISTORY:
mgs, 26 Aug 1998: VERSION 1.00
mgs, 27 Aug 1998:
- added RESULT and QUIET keywords
- improved error handling
mgs, 23 Aug 2000:
- changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\convert_unit.pro)
NAME: CONVOL_MM VERSION: 4.0 PURPOSE: Calculates the convolution of two functions represented by arrays. CATEGORY: Mathematical, array function. CALLING SEQUENCE: Result = CONVOL_MM (FAR, GAR [, keywords]) INPUTS: FAR Array, numeric, otherwise arbitrary. GAR Ditto. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /NOCENTER Switch. Prevents centering one array over the other (corresponds to the CENTER = 0 setting in IDL CONVOL. The default is CENTERED. /REVERSE Switch. Reverses the direction, i.e instead of f(x-x')g(x') the integrand becomes f(x+x')g(x'). /CLIP Switch. If set, the edges of the result (which cannot be fully convolved) are set to zero, same as the default behavior of IDL CONVOL. The default behaviour of CONVOL_MM corresponds to the IDL CONVOL EDGE_WRAP SETTING. EDGE_VAL Accepts a value to be used for all the "beyond the edge " elements. if EDGE_VAL is provided, /CLIP is ignored. EDGE_VAL and EDGE_TRUNCATE are mutually exclusive. /EDGE_TRUNCATE Switch. If set, the "beyond the edge" elements are obtained by a propagation of the edge elements of FAR. EDGE_TRUNCATE and EDGE_VAL are mutually exclusive. /NOROUND Switch. Normally, if both input arrays are of one of the integer types, the result is rounded before type casting to the output type. Setting NOROUND prevents the rounding. OUTPUTS: Returns the result of the convolution with dimensions corresponding to the bigger of the two arrays. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Uses FFT. Faster then the IDL CONVOL, and differs from it in few significant aspects, as follows: 1) The two arrays are treated symmetrically, i.e. the result stays the same if they are exchanged (with the exception that when /REVERSE is set, it is always the second array that's reversed. 2) The problem with IDL CONVOL, where the centered convolution is calculated in a reversed direction (versus standard mathematical practice) has been corrected. 3) The arrays don't have to be of the same dimensionality. If they're not they are imbedded in an array big enough to contained both and padded with zeroes (default), a constant value (if EDGE_VAL is used) or the edge elements of FAR (if EDGE_TRUNCATE is used). Calls CALCTYPE, CAST, EXTEND_ARRAY, FPU_FIX and TYPE from MIDL. MODIFICATION HISTORY: Created 15-NOV-1996 by Mati Meron as M_CONVOL. Modified 20-JAN-1997 by Mati Meron. Streamlined (through the use of EXTEND_ARRAY and added keyword EDGE_TRUNCATE. Modified 15-SEP-1998 by Mati Meron. Underflow filtering added. Renamed 25-SEP-1999 by Mati Meron, to CONVOL_MM. Modified 25-DEC-2000 by Mati Meron. Added rounding for integer types and the keyword NOROUND. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\convol_mm.pro)
NAME:
CONV_UNIX_VAX
PURPOSE:
To convert Unix IDL data types to Vax IDL data types.
EXPLANATION:
CONV_UNIX_VAX assumes the Unix IDL data type is IEEE standard in either
big-endian or little-endian format.
CALLING SEQUENCE:
CONV_UNIX_VAX, variable, [ SOURCE_ARCH = ]
PARAMETERS:
variable - The data variable to be converted. This may be a scalar
or an array. Valid datatypes are integer, longword,
floating point, and double precision. The result of the
conversion is passed back in the original variable.
OPTIONAL INPUT KEYWORD:
SOURCE_ARCH = name (string) of source architecture
if using this function on a VAX, otherwise
!VERSION.ARCH is used to determine the conversion.
**If run on a VAX, the default is to assume the source to be
a little-endian machine with IEEE floating point
(e.g. MIPSEL or Alpha***).
RESTRICTIONS:
Requires that data be from IEEE standard Unix machines
(e.g. SUN, MIPSEL, or Alpha).
EXAMPLE:
Read a 100 by 100 matrix of floating point numbers from a data
file created on a Sun. Then convert the matrix values into
VAX format.
IDL> openr,1,'vax_float.dat
IDL> data = fltarr(100,100)
IDL> forrd,1,data
IDL> CONV_UNIX_VAX,data,SOURCE_ARCH='sparc'
MODIFICATION HISTORY:
Version 1 By John Hoegy 13-Jun-88
04-May-90 - WTT: Created CONV_UNIX_VAX from VAX2SUN,
reversing floating point procedure.
Modified P. Keegstra September 1994
Implemented MIPSEL and ALPHA architecture,
distinguishing VMS and OSF
Modified P. Keegstra February 1995
Added 386 PC based architectures
If since V5.1 then VMS is always little endian June 1998
Convert to IDL V5.0 W. Landsman June 1998
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\conv_unix_vax.pro)
NAME:
COO_CONV
VERSION:
4.0
PURPOSE:
Transforms values between the coordinate systems supported by IDL.
Allowed coord systems are DATA, DEVICE (only for X, Y axes) and NORMAL.
Functionally similar to the IDL function CONVERT_COORD, COO_CONV is
maintained for historical reasons.
CATEGORY:
Plotting /General Graphics.
CALLING SEQUENCE:
Result = COO_CONV( R, AXIS = AX [, keywords])
INPUTS:
R
numeric, otherwise arbitrary, assumed to be a coordinate(s) in the
direction specified by AXIS.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
AXIS
Sets the transformation axis. Accepts either a numeric value, one of
(0, 1, 2) or a character value (only first character matters), one of
('X', 'Y', 'Z'). Mandatory.
FROM
Character value (only first 3 characters matter), specifies input
coord. system. One of ('DATA','DEVICE','NORMAL'). Defaults to 'DATA'.
TO
Same as FROM. Specifies output coord. system.
OUTPUTS:
'' (0 length string) in case of failure (bad keyword value), otherwise
returns the transformed value as floating (or double if the input is
of type double).
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Uses calls to CAST, DEFAULT, FPU_FIX, ISNUM, STREQ, STRMATCH_MM and
TYPE from MIDL. Converts coordinates using values provided by relevant
system variables.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 10-SEP-1998 by Mati Meron. Underflow filtering added.
Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\coo_conv.pro)
NAME:
correlate_all_columns
PURPOSE:
This function calculates the correlation coefficients (Pearson, Spearman, or Kendall)
for a 2 dim data matrix
CATEGORY:
MATH
CALLING SEQUENCE:
Result = CORRELATE_ALL_COLUMNS(Value, [Text], [/SPEARMAN], [/KENDALL])
INPUTS:
Value: 2d data array
OPTIONAL INPUTS:
Text: column header(title) for input array
KEYWORD PARAMETERS:
SPEARMAN: if set Spearman rank correlation will be used (default: Pearson)
KENDAL: if set Kendal tau rank correlation will be used (default: Pearson)
MISSING_VALUE: if set to a single number these values will be excluded from calculation
SIGNIFICANCE: upper limit for significance to be plotted (def 1.0), see R_CORRELATE
R_MINIMUM: lower limit for correlation coeff. to be plotted (def 0.0)
PLOT_ROWS, PLOT_COLS number of rows and columns in plot
N_MINIMUM: minimum of data points to be considered for correaltion and plot
SORT_BY_R if set output array will be sorted after correlation coeff.
SORT_BY_SIGNIF if set output array will be sorted after significance
REVERSE_ORDER if set reverse order sorting, highest correlation first
FIXED_COLUMN if set to column number or an array of column numbers this column/these columns
will be correlated against all other columns
EXCLUDE_COLUMNS if set to a cloumns number these columns will be excluded
NO_PLOT: suppress plotting
PSFILE: postscript filename for plotting (def: idl.ps)
MESSAGE: if set messages will be printed
ERR: if set to a named variable an error is indicated (OK:0, error:1)
_EXTRA: additional keywords can be provided for plot, init_dev, init_mplot
OUTPUTS:
This function returns a structure r containing the indeces to the columns r.i and r.j
and the respective correlation coefficient r.r and a significance level r.s
EXAMPLE:
nr=100 & nc=3
v = FINDGEN(nr,nc)+nr*RANDOMU(s,nr,nc)
PRINT, correlate_all_columns(v, /MESSAGE)
% CORRELATE_ALL_COLUMNS: no column headers given
% CORRELATE_ALL_COLUMNS: Pearson's linear correlation
% CORRELATE_ALL_COLUMNS: plotting COLUMN1 vs. COLUMN0 (0,1)
% CORRELATE_ALL_COLUMNS: plotting COLUMN2 vs. COLUMN0 (0,2)
% CORRELATE_ALL_COLUMNS: plotting COLUMN2 vs. COLUMN1 (1,2)
{ 1 0 0.59619999 0.00000000}
{ 2 0 0.57707387 0.00000000}
{ 2 1 0.48136258 0.00000000}
MODIFICATION HISTORY:
Written by: Theo Brauers, 1998-DEC-1
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\correlate_all_columns.pro)
NAME: COSANGLE VERSION: 4.0 PURPOSE: Finds the Cosine of the angle between two vectors. CATEGORY: Geometry, General. CALLING SEQUENCE: Result = COSANGLE ( U, V) INPUTS: U, V Vectors, numeric, same length, otherwise arbitrary. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: None. OUTPUTS: Returns the Cosine of the angle between the two vectors. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: Vectors must be non-zero. PROCEDURE: Uses the functions FPU_FIX, VINP and VNORM from MIDL. MODIFICATION HISTORY: Created 30-JUNE-1992 by Mati Meron. Added to MIDL 10-NOV-1997 by Mati Meron. Modified 10-SEP-1998 by Mati Meron. Underflow filtering added. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\cosangle.pro)
NAME:
COSD
PURPOSE:
Return the cosine of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = cosd(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Cosine of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cosd.pro_)
NAME:
COSFILT
PURPOSE:
Cosine tapered weighting array to use for FFT filtering.
CATEGORY:
CALLING SEQUENCE:
W = COSFILT(DATA, F1, F2, [F3, F4])
INPUTS:
DATA = 1-d data array (only used to find array size). in
F1 = filter start of rolloff (fraction of sample freq). in
F2 = end of rolloff (fraction of sample freq). in
or
F1 = filter start of rollup (fraction of sample freq). in
F2 = end of rollup (fraction of sample freq). in
F3 = filter start of rolloff (fraction of sample freq). in
F4 = end of rolloff (fraction of sample freq). in
F1 < F2 < F3 < F4 <= .5
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner., B. Gotwols 7 Apr, 1987.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1987, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cosfilt.pro)
NAME:
COSSCATANG
PURPOSE:
Return the scattering angle of the incident and emerging rays.
NOTE: the scattering angle is defined as 180 degrees when
sza = vza = 0 and phi = 180.
CALLING SEQUENCE:
cos_omega = cosscatang(cossza, cosvza, phi)
INPUTS:
cossza cosine of solar (or incident) zenith angle
cosvza cosine of viewing (or emergin or satellite) zenith angle
phi relative azimuth angle; this is defined as the difference
between the solar azimuth angle and the viewing azimuth
angle; when sat, sun are in the same position in
the sky, phi = 0
OPTIONAL INPUTS:
OUTPUTS:
The scattering angle is returned.
EXAMPLE:
IDL> print,acosd(cosscatang(cosd(60),cosd(60),0))
0.00000
IDL> print,acosd(cosscatang(cosd(60),cosd(60),180))
120.000
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cosscatang.pro)
NAME:
COSTAP
PURPOSE:
Cosine taper weighting from 1 at center to 0 at ends.
CATEGORY:
CALLING SEQUENCE:
w = costap(n,[f])
INPUTS:
n = # of pts in weighting array. in
f = fraction of pts in flat region (def=0). in
KEYWORD PARAMETERS:
OUTPUTS:
w = weight with values from 0 to 1. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Written by R. Sterner, 6 Dec, 1984.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1984, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\costap.pro)
NAME:
count_name
PURPOSE:
This function increments a given name with a number. The old number is stored in an heap variable named: 'count_name_'+name
CATEGORY:
PROG_TOOLS
CALLING SEQUENCE:
Result=count_name(name,[/reset])
INPUTS:
name: the name which should be used as base for the counting
KEYWORD_PARAMETERS:
reset: if set counter is set zero
EXAMPLE:
PRINT,count_name('test')
test_1
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Mar-20
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\count_name.pro)
NAME:
COYOTE_FIELD
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. What has
always annoyed me about CW_FIELD is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
would be helpful. For example, you can now assign an event handler
to the compound widget.
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:
General programming.
CALLING SEQUENCE:
fieldID = COYOTE_Field(parent, Title='X Size: ", Value=256, /IntegerValue)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Column -- Set this keyword to have the Label Widget above the Text Widget.
CR_Only -- Set this keyword if you only want Carriage Return events. If
this keyword is not set, all events are returned. No events
are returned unless the EVENT_PRO or EVENT_FUNC keywords are used.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- Set this keyword to the name of an Event Function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
Event_Pro -- Set this keyword to the name of an Event Procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
FieldFont -- The font name for the text in the Text Widget.
FloatValue -- Set this keyword for FLOAT values.
Frame -- Set this keyword to put a frame around the compound widget.
IntegerValue -- Set this keyword for INTEGER values.
LabelFont -- The font name for the text in the Label Widget.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
Scr_XSize -- The X screen size of the compound widget.
Scr_YSize -- The Y screen size of the compound widget.
StringValue -- Set this keyword for STRING values. (The default.)
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
EVENT STRUCTURE:
All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. By
default all events generated by the text widget are passed to the assigned
event handler. If you wish to receive only Carriage Return events, set the
CR_Only keyword.
event = { COYOTE_FIELD, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
Value: Ptr_New(), $ ; A pointer to the widget value.
Type:"" ; A string indicating the type of data in the VALUE field.
} ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".
EXAMPLE:
An example program is provided at the end of the COYOTE_FIELD code. To run it,
type these commands:
IDL> .Compile COYOTE_Field
IDL> Example
MODIFICATION HISTORY:
Written by: David Fanning, 17 NOV 1999.
Added check to make float and double values finite. 18 NOV 1999. DWF.
Fixed a bug when selecting and deleting all numerical text. 19 NOV 1999. DWF.
Added DECIMAL and DIGITS keywords. 2 Jan 2000. DWF.
Added the POSITIVE keyword. 12 Jan 2000. DWF.
Fixed a few minor bugs with delete and digits. 12 Jan 2000. DWF.
Made GET_VALUE function return pointer to data, instead of data. 12 Jan 2000. DWF.
Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
Fixed a small problem with the Example program. 7 Oct 2000. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\coyote_field.pro)
NAME: cplot_all_columns PURPOSE: This function plots all columns of a matrix versus 1 vector CATEGORY: MATH CALLING SEQUENCE: CPLOT_ALL_COLUMNS, X, Value, Text INPUTS: Xvalue: vector of N elements Yvalue: array of [N, M] elements OPTIONAL INPUTS: Text: column header(title) for input array KEYWORD PARAMETERS: MISSING_VALUE: if set to a single number these values will be excluded from calculation PLOT_ROWS, PLOT_COLS number of rows and columns in plot PSFILE: postscript filename for plotting (def: idl.ps) MESSAGE: if set messages will beprinted ERR: if set to a named variable an error is indicated (OK:0, error:1) _EXTRA: additional keywords can be provided for plot, init_dev, init_mplot EXAMPLE: nr=100 & nc=3 v = FINDGEN(nr,nc)+nr*RANDOMU(s,nr,nc) plot_all_columns(v[*,0], v, /MESSAGE) MODIFICATION HISTORY: Written by: Theo Brauers, 1998-DEC-1
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\cplot_all_columns.pro)
NAME:
CPOSPRINT
PURPOSE:
Print a string showing character positions.
CATEGORY:
CALLING SEQUENCE:
cposprint, s
INPUTS:
s = input string to print. in
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
NOTES:
Note: prints character positions above string.
MODIFICATION HISTORY:
R. Sterner, 2000 May 31
Copyright (C) 2000, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cposprint.pro)
NAME:
CREATED
PURPOSE:
Return file creation host, user, and time stamp or tag.
CATEGORY:
CALLING SEQUENCE:
txt = created()
INPUTS:
KEYWORD PARAMETERS:
Keywords:
VERB=verb First word to use (def=Created).
OUTPUTS:
txt = returned text. out
Ex: Created on tesla by Sterner on Tue Jul 1 14:22:15 1997
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1997 Jul 1
Copyright (C) 1997, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\created.pro)
NAME:
Create_GridFile
PURPOSE:
This procedure generates a netcdf file with grid information for
regular grids or gaussian grids corresponding to a spectral
truncation of T21, T30, T42, T63, T85, T106, T126, T170, T213, or
TL319. The netcdf file contains the three variable lon, lat, and
lat_weight. Lat_weight is the area weighting factor for latitudes
(integral = 1).
CATEGORY:
Geography
AUTHOR:
Martin Schultz
Max-Planck-Institute for Meteorology
Bundesstr. 55, 20146 Hamburg, Germany
martin.schultz@dkrz.de
MODIFICATION HISTORY:
mgs, 24 Aug 2000: VERSION 1.00
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\create_gridfile.pro)
NAME: create_history PURPOSE: This function returns the following - history - string: '[ at ]' CATEGORY: PROG_TOOLS/STRUCTURES CALLING SEQUENCE: Result = create_history([text]) OPTIONAL INPUTS: text: A text string (scalar) which will appear in the history string. OUTPUTS: This function returns the following - history - string: ' [ at ]' MODIFICATION HISTORY: Written by: Frank Holland, 24.09.1999 18.11.1999: Added optional input parameter: text 19.11.1999: Minor change on default setting for text.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\create_history.pro)
NAME:
create_href
PURPOSE:
This function creates an HTML href from a file name
CATEGORY:
PROG_TOOLS/HTML
CALLING SEQUENCE:
Result=CREATE_HREF(Location, Name)
INPUTS:
Location: filename with path
example: 'a.txt', 'http://ich313.ich.kfa-juelich.de/test.html'
OPTIONAL INPUTS:
Name: Name to appear in the browser, if not given location will be
taken instead
KEYWORD PARAMETERS:
FULLNAME: if this keyword is set the name wil not be stripped for
directory etc.
OUTPUTS:
This function returns the hrefs for the input files
EXAMPLE:
a=['a.txt', 'b.txt']
print, transpose(create_href(a))
a.txt
b.txt
MODIFICATION HISTORY:
Written by: Theo Brauers 1998 July 26
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\create_href.pro)
NAME:
CREATE_INFO_STRUCT
PURPOSE:
This function defines a structure for informations about files (ENZ,ZUS,NC )
and for informations to write a html-file
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
s= CREATE_INFO_STRUCT(n_sets,n_header, n_flags $
,FILE_NAME=FILE_NAME,FILETYPE=FILETYPE, FILEDATE=FILEDATE, EXPERIMENT=experiment )
INPUTS:
n_sets : number of rows of structure s.data (tags: text,nvalid,mean,median,stdev,minimum,maximum)
output of zus_fb_info or nc_info or enz_info
n_header: number of rows of header
KEYWORD PARAMETERS:
FILENAME, FILETYPE, FILEDATE, EXPERIMENT
OUTPUTS:
a structure for example s
.file_infoname : name of file
.file_info.filetype : 'zus' or 'enz' or 'nc'
.file_info.filedate : date of file
.record_info.jstime : DBLARR(2) start-time and end-time in julian seconds
.record_info.ntime : STRARR(2) start-time and end-time in normal date and time
.record_info.n_records: number of rows of time- and parameter vectors
.record_info.n_sets : number of columns
.pi.pi_name:
.pi.email :
.pi.phone_number :
.pi.organisation :
.hsrefs.ps :'ps' (reference to ps-file:filename+.ps)
.hsrefs.data :'data' (reference to
.hsrefs.html :'html' (reference to html-file: filename+.savinfo.html)
.data.text :description of a data column (string-array )
.data.nvalid :array containing the number of valid values of a column
.data.mean :array containing the avarage values of a data column
.data.median :array containing the median values of a data column
.data.stdev :array containing the standard deviation of a column
.data.minimum:array containing the lowest values of a data column
.data.maximum:array containing the greatest values of a data column
.experiment.text: containing the experiment text of the file if it exists
.header.text :string array containing the header of the file
EXAMPLE:
s= CREATE_INFO_STRUCT(n_sets,n_header , FILENAME=FILENAME)
REVISION HISTORY:
Written Theo Brauers, Marsy Lisken, July 1998
Corrected
Revised
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\create_info_struct.pro)
NAME:
create_widget_button_symbol
PURPOSE:
This function translates a given symbol to it's bitmap buttom equivalent
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
create_widget_button_symbol,symbol
INPUTS:
symbol: The by icgsym_n defined icg symbolnumber
OPTIONAL INPUTS:
buttom_size=buttom_size: the size of the buttom (multiples from 8)
see restrictions
OUTPUTS:
This function returns an array as input for widget_buttom
RESTRICTIONS:
At the moment while an error on the aix occurs this routine is not in a state to use
really the buttom_size key
EXAMPLE:
result=create_widget_button_symbol(208)
print,result
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 240 7 0
0 248 15 0
0 252 31 0
0 254 63 0
0 254 63 0
0 254 63 0
0 254 127 0
0 254 63 0
0 254 63 0
0 254 63 0
0 254 63 0
0 248 15 0
0 248 15 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1998-Apr-04
2000-Feb-18 help changed to call_help
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\create_widget_button_symbol.pro)
NAME:
CROSSI
PURPOSE:
Interactive cross-hair cursor on screen or plot.
CATEGORY:
CALLING SEQUENCE:
crossi, [x, y, z]
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/DATA Causes data coordinates to be used (default).
/DEVICE Causes window device coordinates to be used.
/NORMAL Causes normalized coordinates to be used.
/ORDER Reverse device y coordinate (0 at window top).
/PIXEL Show pixel value.
COLOR=c Set color of line (ignored for /XOR).
Use -2 for dotted line.
LINESTYLE=s Line style.
MAG=m Magnification for an optional magnified window.
Setting MAG turns window on. /MAG gives magnification 10.
SIZE=sz Mag window approx. size in pixels (def=200).
XFORMAT=xfn These keywords are given names of functions
YFORMAT=yfn that accept the numeric value of x or y
and return a corresponding string which is displayed
in place of the actual value. For example, Julian
days could be displayed as a date with jd2date.
XSIZE=xs, YSIZE=ys Coordinate display widths.
/JS Means X axis is time in Julian seconds. Example:
x=maken(-2e8,-1.9e8,200) & y=maken(20,30,200)
z=bytscl(makez(200,200))
izoom,x,y,z,/js
crossi,/js
/NOSTATUS Inhibits status display widget.
SETSTAT=st May use the same status display widget on
each call to crossi (stays in same position).
On first call: the status widget structure is returned.
Following calls: send st. Must use with /KEEP.
To delete status display widget after last box1 call:
widget_control,st.top,/dest (or drop /KEEP)
/KEEP Do not delete status widget or mag window on exit.
/XMODE Means use XOR plot mode instead of tvrd mode.
INSTRUCTIONS=t String array with exit instructions.
Default: Press any button to exit.
/DIALOG Means give an exit dialog box.
MENU=m A string array with exit dialog box options.
An option labeled Continue is always added. Def=Continue.
DEFAULT=def Set exit menu default.
EXITCODE=x Returns exit code. Always 0 unless a dialog
box is requested, then is selected exit option number.
BUTTON=b Returned button code: 1=left, 2=middle, 4=right.
OUTPUTS:
x = X coordinate of line. in, out
y = Y coordinate of line. in, out
z = optionally returned pixel value. out
Only if /PIXEL is specified.
COMMON BLOCKS:
js_com
NOTES:
Note: data coordinates are default.
X and Y may be set to starting position in entry.
MODIFICATION HISTORY:
R. Sterner, 1994 May 16
R. Sterner, 1994 May 19 --- Added mag window.
R. Sterner, 1995 May 12 --- Added exit menu default.
R. Sterner, 1995 Jun 30 --- Added /ORDER.
R. Sterner, 1995 Oct 17 --- Added /PIXEL and RGB display.
R. Sterner, 1995 Nov 30 --- Added color=-2 option.
R. Sterner, 1998 Jan 15 --- Dropped the use of !d.n_colors.
R. Sterner, 1999 Oct 05 --- Upgraded for true color.
R. Sterner, 1999 Dec 07 --- Fixed /PIXEL for 24-bit color & mag bug.
R. Sterner, 2001 Jan 12 --- Fixed for maps.
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\crossi.pro)
NAME:
CROSSI2
PURPOSE:
Interactive cross-hair cursor on screen or plot.
CATEGORY:
CALLING SEQUENCE:
crossi, [x, y]
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/DATA Causes data coordinates to be used (default).
/DEVICE Causes window device coordinates to be used.
/NORMAL Causes normalized coordinates to be used.
/ORDER Reverse device y coordinate (0 at window top).
STATUS_PRO=pro Name of optional status update procedure.
/DETAILS for more info on using STATUS_PRO.
COLOR=c Set color of line (ignored for /XOR).
Use -2 for dotted line.
LINESTYLE=s Line style.
MAG=m Magnification for an optional magnified window.
Setting MAG turns window on. /MAG gives magnification 10.
SIZE=sz Mag window approx. size in pixels (def=200).
/XMODE Means use XOR plot mode instead of tvrd mode.
/DIALOG Means give an exit dialog box.
MENU=m A string array with exit dialog box options.
An option labeled Continue is always added. Def=Continue.
DEFAULT=def Set exit menu default.
EXITCODE=x Returns exit code. Always 0 unless a dialog
box is requested, then is selected exit option number.
BUTTON=b Returned button code: 1=left, 2=middle, 4=right.
OUTPUTS:
x = X coordinate of line. in, out
y = Y coordinate of line. in, out
COMMON BLOCKS:
NOTES:
Note: data coordinates are default.
X and Y may be set to starting position in entry.
MODIFICATION HISTORY:
R. Sterner, 1996 Oct 6.
R. Sterner, 1998 Jan 15 --- Dropped the use of !d.n_colors.
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\crossi2.pro)
NAME:
CROSSI_FR
PURPOSE:
Interactive cross-hair cursor on screen or plot.
CATEGORY:
CALLING SEQUENCE:
crossi_fr, [x, y, z]
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/DATA Causes data coordinates to be used (default).
/DEVICE Causes window device coordinates to be used.
/NORMAL Causes normalized coordinates to be used.
/ORDER Reverse device y coordinate (0 at window top).
/PIXEL Show pixel value.
COLOR=c Set color of line (ignored for /XOR).
Use -2 for dotted line.
LINESTYLE=s Line style.
MAG=m Magnification for an optional magnified window.
Setting MAG turns window on. /MAG gives magnification 10.
SIZE=sz Mag window approx. size in pixels (def=200).
XFORMAT=xfn These keywords are given names of functions
YFORMAT=yfn that accept the numeric value of x or y
and return a corresponding string which is displayed
in place of the actual value. For example, Julian
days could be displayed as a date with jd2date.
XSIZE=xs, YSIZE=ys Coordinate display widths.
/JS Means X axis is time in Julian seconds. Example:
x=maken(-2e8,-1.9e8,200) & y=maken(20,30,200)
z=bytscl(makez(200,200))
izoom,x,y,z,/js
crossi,/js
/NOSTATUS Inhibits status display widget.
SETSTAT=st May use the same status display widget on
each call to crossi (stays in same position).
On first call: the status widget structure is returned.
Following calls: send st. Must use with /KEEP.
To delete status display widget after last box1 call:
widget_control,st.top,/dest (or drop /KEEP)
/KEEP Do not delete status widget or mag window on exit.
/XMODE Means use XOR plot mode instead of tvrd mode.
INSTRUCTIONS=t String array with exit instructions.
Default: Press any button to exit.
/DIALOG Means give an exit dialog box.
MENU=m A string array with exit dialog box options.
An option labeled Continue is always added. Def=Continue.
DEFAULT=def Set exit menu default.
EXITCODE=x Returns exit code. Always 0 unless a dialog
box is requested, then is selected exit option number.
BUTTON=b Returned button code: 1=left, 2=middle, 4=right.
OUTPUTS:
x = X coordinate of line. in, out
y = Y coordinate of line. in, out
z = optionally returned pixel value. out
Only if /PIXEL is specified.
COMMON BLOCKS:
js_com
NOTES:
Note: data coordinates are default.
X and Y may be set to starting position in entry.
MODIFICATION HISTORY:
R. Sterner, 1994 May 16
R. Sterner, 1994 May 19 --- Added mag window.
R. Sterner, 1995 May 12 --- Added exit menu default.
R. Sterner, 1995 Jun 30 --- Added /ORDER.
R. Sterner, 1995 Oct 17 --- Added /PIXEL and RGB display.
R. Sterner, 1995 Nov 30 --- Added color=-2 option.
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\crossi_fr.pro)
NAME:
CROSSPN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
A version of CROSSP for efficient vector cross products
CALLING SEQUENCE:
C = CROSSPN(A, B)
DESCRIPTION:
The function CROSSPN computes the vector cross product (outer
product). The difference between CROSSPN and the IDL library
function CROSSP, is that CROSSPN allows more than one cross
product to be computed at one time (i.e., it is vectorized).
Thus, in the expression "C = CROSSPN(A, B)" the vector cross
product is computed as C = A x B. Because CROSSPN is vectorized,
any of the following combinations are valid:
* A is a 3-vector, B is a 3-vector
==> C is the vector cross product C = A x B
* A is a 3xN array, B is a 3-vector
==> C(*,I) = A(*,I) x B (each A is crossed with B)
* A is a 3-vector, B is a 3xN array
==> C(*,I) = A x B(*,I) (A is crossed with each B)
* A is a 3xN array, B is a 3xN array
==> C(*,I) = A(*,I) x B(*,I) (component-by-component)
If both A and B are arrays then they must have the same
dimensions.
INPUTS:
A - a 3-vector or 3xN array.
B - a 3-vector or 3xN array.
RETURNS:
The vector cross product A x B, either a 3-vector or a 3xN array
depending on A and B.
SEE ALSO:
CROSSP
MODIFICATION HISTORY:
Written, CM, 10 Mar 2002
Documented, CM, 22 Mar 2002
$Id: crosspn.pro,v 1.2 2002/03/22 22:02:02 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\crosspn.pro)
NAME:
CRS_EDIT
PURPOSE:
Edit a bitmap to use for a cursor image.
CATEGORY:
CALLING SEQUENCE:
crs_edit, img, msk
INPUTS:
KEYWORD PARAMETERS:
Keywords:
HOT=[ix,iy] x and y offsets to cursor hot spot (def=[8,8]).
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: Displays current array values as a large version
of the cursor. Click on pixels to change state among
black, white, and gray. Transparent part of cursor is
gray. Left and middle mouse buttons change state,
right button exits.
MODIFICATION HISTORY:
R. Sterner, 1999 Nov 24
Copyright (C) 1999, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\crs_edit.pro)
ROUTINE: crystal
PURPOSE: compute the radius of an mie-sphere with scattering
properties equivalent to a irregular crystal shape.
USEAGE: crystal,type,rsph,nsph,area,volume, $
d=d,t=t,bb=bb,bt=bt,l1=l1,l2=l2,l3=l3,a1=a1,a2=a2,a3=a3
INPUT:
type crystal type description Geom input parameters
------------ ----------- ---------------------
1 hollow column L1,a1,d
2 bullet rosette L1,a1,t
3 dendrite on plate L1,a1,bb,bt
4 capped column L1,L2,L3,a1,a2,a3
KEYWORD INPUT:
;
type 1: hollow column
L1 column length (um)
a1 hexagonal face width (um)
d cavity depth at each end of column (um)
type 2: bullet rosette
L1 column length (um)
a1 hexagonal face width (um)
t conical pyramid height on bullet rosettes (um)
type 3: dendrite on plate
L1 disk thickness (um)
a1 hexagonal face width (um)
bb base width of dendrite (um)
bt length of dendrite (um)
type 4: capped column
L1 cap thickness (um)
L2 column length (um)
L3 other cap thickness (um)
a1 cap hexagonal face width (um)
a2 hexagonal face width of column (um)
a3 other cap hexagonal face width (um)
These geometric parameters are difined in Takano and Liou, 1995:
"Radiative Transfer in Cirrus Clouds. Part III: Light
Scattering by Irregular Ice Crystals" JAS 152, No 7, April 1995
OUTPUT:
rsph radius of equivalent Mie spheres (um)
nsph number of equivalent Mie spheres
(factors into particle distribution function in mie
calculation if a distribution of crystal sizes are
computed, see example)
area area in um^2
volume volume in um^3
DISCUSSION:
According to Warren and Grenfeld, the scattering
parameters of an irregular crystal can be approximated
by those of the set of equivalent Mie spheres, such
that the both the area and volume of the set of
spheres match those of the original crystal.
Say the density of a given crystal type is N per unit volume
the extinction coefficient, kappa, (per unit distance) is
given by,
kappa = N * Q * A / 4
where Q is the unknown extinction efficiency and the factor
of 4 is to turn area into average cross-sectional area.
According to W&G, kappa is approximately given by,
kappa = N * Q_mie(rsph) * (nsph * pi rsph^2)
= N * Q_mie(rsph) * A/4
The single scattering albedo and asymmetry factor are given by,
omega = omega_mie(rsph)
g = g_mie(rsph)
EXAMPLE:
; Plot equivalent mie radius versus crystal length
l1=findrng(50,200,100)
crystal,1,rsph,nsph,l1=l1,a1=50,d=10
plot,l1,rsph
; Determine PDF of equivalent radius mie spheres given distribution
; of crystal shapes. Suppose dendrite width is fixed and the number
; of particles of a given length is given by a lognormal pdf with
; cutoffs at 10 and 500um:
;
l1=findrng(10,500,100) & sig=.3
w=exp(-alog10(l1/50.)^2/(2.*sig^2))
crystal,1,rsph,nsph,l1=l1,a1=10.,d=0
wmie=w*nsph ; pdf of equivalent mie sphere
; radius distribution
!p.multi=[0,1,2]
plot,l1,w,title='dendrite length pdf',xtitle='length'
plot,rsph,wmie,title='equivalent mie radius pdf',xtitle='radius'
REVISIONS:
AUTHOR: Paul Ricchiazzi 27 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\crystal.pro)
NAME: cr_struct_name PURPOSE: This function returns a unique structure name based on current date and time information and an additional random number. CATEGORY: PROG_TOOLS/STRUCTURES CALLING SEQUENCE: structure_name = cr_struct_name() COMMON BLOCKS: STORE_SEED: A Long Array[36] which stores the state of the random number generator EXAMPLE: PRINT, cr_struct_name() 'Mon Mar 16 20:55:13 1998 425995' MODIFICATION HISTORY: Written by: Frank Holland, 17. Mar. 98. 16.03.1999 Removed debug statement, Header edited
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\cr_struct_name.pro)
NAME:
CSPEC
PURPOSE:
Compute ensemble averaged frequency spectrum of complex data.
CATEGORY:
CALLING SEQUENCE:
s = cspec(z,n,sr,[freq])
INPUTS:
z = input signal: Z = X + iY. in
If z has too few points, -1 is returned.
n = number of points to use in each transform in
May be arbitrary.
sr = sample rate in Hz in
Needed to get actual units
KEYWORD PARAMETERS:
Keywords:
OVERLAP=novr number of points to overlap spectra (Def=0).
ZEROPAD=zlen length to zero pad out to (def=no 0 pad).
N_ENSEMBLE=n returned # spectra ensemble averaged.
/NOTES lists some additional comments.
OUTPUTS:
freq = optionally output frequency array. out
If freq is requested then s is shifted for plots.
s = spectral density in units of z**2/Hz. out
First value is DC, unless freq is requested.
COMMON BLOCKS:
cspec_com
NOTES:
Notes: For example, if Z=I+iQ, and I and Q are in volts,
s will be volts**2/Hz
Restrictions: one dimensional data only.
MODIFICATION HISTORY:
B. L. Gotwols Oct. 13, 1990.
R. E. Sterner Sep. 13, 1991 --- added freq and cleaned up.
R. E. Sterner Mar. 1, 1993 --- Tested for ntimes eq 0 sooner.
R. Sterner, 1994 Oct 31 --- added overlap
R. Sterner, 1994 Nov, 10 --- Added ZEROPAD keyword.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cspec.pro)
NAME:
CTINT
PURPOSE:
Interpolate between two color table entries.
CATEGORY:
CALLING SEQUENCE:
ctint, r, g, b, i1, i2, [mode]
INPUTS:
i1, i2 = start and end index for interpolation. in
mode = interpolation mode (def=1). in
Color interpolation mode
0 = Copy. Copy color i1 to i1:i2 range.
1 = R,G,B. Interp each color independently.
2 = H,S,V straight. Through less sat. hues (grays).
3 = H,S,V curved. Through sat. in-between hues.
4 = Reverse. Reverse colors in i1:i2 range.
5 = Ramp value from i1 down to 0 at i2.
KEYWORD PARAMETERS:
OUTPUTS:
r,g,b = color table, red, green, blue. in out
COMMON BLOCKS:
NOTES:
Note: Modifies the color table.
MODIFICATION HISTORY:
R. Sterner, 6 Sep, 1990
R. Sterner, 18 Oct, 1993 --- Added Copy and Reverse.
R. Sterner, 21 Oct, 1993 --- Added Ramp mode.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ctint.pro)
NAME:
CTOOL
PURPOSE:
Modify a color table using widgets.
CATEGORY:
CALLING SEQUENCE:
ctool
INPUTS:
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 13 Oct, 1993
R. Sterner, 1998 Jan 15 --- Dropped the use of !d.n_colors.
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ctool.pro)
NAME:
CTRIM
PURPOSE:
Do a circular trim on an array.
CATEGORY:
CALLING SEQUENCE:
b = ctrim(a)
INPUTS:
a = input array. in
KEYWORD PARAMETERS:
OUTPUTS:
b = output trimmed array. out
COMMON BLOCKS:
NOTES:
Note: if input array is not square then
trimmed array is elliptical.
MODIFICATION HISTORY:
R. Sterner. 24 May, 1987.
Johns Hopkins University Applied Physics Laboratory.
R. Sterner, 25 Jan 1990 --- converted to SUN.
Copyright (C) 1987, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ctrim.pro)
NAME: ct_blue PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
| |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_blue.pro)
NAME: ct_blue_green PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_green.pro)
NAME: ct_blue_green_yellow_red PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_green_yellow_red.pro)
NAME: ct_blue_red PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_red.pro)
NAME: ct_blue_red_yellow PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_blue_red_yellow.pro)
NAME: ct_cyan_green_yellow_red PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_cyan_green_yellow_red.pro)
NAME: ct_grey_191_32 PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_grey_191_32.pro)
NAME: ct_grey_220_70 PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_grey_220_70.pro)
NAME: ct_ncdf PURPOSE:
| This procedure defines a colorindices of 20 possible colors for plotxy |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_ncdf.pro)
NAME: ct_pastel PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_pastel.pro)
NAME: ct_yellow_red_blue PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\ct_yellow_red_blue.pro)
NAME: ct_yellow_red_blue_green_black PURPOSE:
| This procedure defines a linear interpolated color table added to the previously defined first 20 colors |
 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\ct_yellow_red_blue_green_black.pro)
NAME:
CUMULATE
PURPOSE:
Array with the cumulative sum of an array. Integrate.
CATEGORY:
CALLING SEQUENCE:
out = cumulate(in)
INPUTS:
in = input array. in
KEYWORD PARAMETERS:
OUTPUTS:
out = cumulative sum of in. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Ray Sterner, 20 June, 1985.
R. Sterner, 26 June, 1991 --- fixed long overflow bug.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cumulate.pro)
NAME:
CURBOX
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector). CURBOX can be used to select a sub-region
from a TVIM image (see example).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
CURBOX, x1,x2,y1,y2
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,init=init,$
message=message,inc=inc, index=index,label=label, $
color=color,charsize=charsize
+
INPUTS:
x1,x2,y1,y2
coordinates of box edges. If XWIN,YWIN,XRNG,YRNG are set, then
input is in data coordinates, otherwise in normalized coordinates.
KEYWORD PARAMETERS:
init
If this keyword is set, the initial position of the cursor
is given by X1,X2,Y1,Y2
message
If this keyword is set, print a short message describing
operation of the cursor.
xwin,ywin
two element vectors giving normalized x and y coordinates of window
subregion, for example that given by !x.window or !y.window
xrng,yrng
two elements vectors giving data range of window subregion, for
example, as given by !x.crange or !y.crange. When CURBOX is used
with TVIM (and XRANGE and YRANGE are not used with TVIM), XRNG
and YRNG represent the total index range of the displayed
image. X1,X2,Y1,Y2 will then be the array subrange of the
selected region.
index
if set, the XRNG,YRNG,XWIN,YWIN parameters are set to the values of
the last data window, i.e., !x.crange,!y.crange, !x.window, and
!y.window respectively. Setting INDEX causes X1,X2,Y1,Y2 to be
interpreted as index range coordinates.
inc
increment by which to change cursor box size when right or left
mouse button is pressed. Specified in data index coordinates (i.e.,
array index coordinate) when XWIN,YWIN,XRNG,YRNG are set, otherwise
in normalized coordinates. The x and y increments may be specified
separately by providing INC as a two element array.
label
a string which is used to label the selected region. The string is
centered within the region and is sized to ensure that it fits within
the box. If LABEL is set the box is not erased after CURBOX returns
color
color used to label regions
charsize
character size used for region labels
fill
color used to fill box region, only effective when LABEL is set
OUTPUTS:
x1,x2,y1,y2
normalized coordinates coordinates of box edges. Howvever, if
xwin, ywin, xrng, and yrng are set, output is in data index
coordinates, i.e., x1,x2,y1,y2 provide the index range of the
boxed region of the image.
If xwin,ywin,xrng,yrng are set, the output range is clipped to be
within the limits of xrng and yrng.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: reduce box size
Middle mouse button: increase box size
Right mouse button: Exit this procedure, returning the
current box parameters.
NOTE: CURBOX is designed for applications in which the aspect
ratio of the cursor box is fixed. However, if the
aspect ratio must be adjusted do the following: jam the
box against one of the window borders. If you force
the box against the left or right borders (while
keeping the cursor pointer within the window) box size
is constrained to change only in the height. Similarly
the box can be made fatter or thiner by pushing the box
against the top or bottom. As usual the LMB decreases
size and the MMB increases size.
; EXAMPLE
;
; use curbox to interactively select subregions from a TVIM image
w8x11
!p.multi=[0,1,2]
f=randata(128,128,s=3)
tvim,f,/interp
xw=!x.window & xr=!x.crange
yw=!y.window & yr=!y.crange
x1=60 & x2=80 & y1=60 & y2=80
!p.charsize=2
!p.multi=[4,2,4]
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 1'
confill,f(x1:x2,y1:y2),title='region 1'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 2'
confill,f(x1:x2,y1:y2),title='region 2'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 3'
confill,f(x1:x2,y1:y2),title='region 3'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 4'
confill,f(x1:x2,y1:y2),title='region 4'
; use CURBOX to find the normalized coordinates of a window region
; of given aspect ratio
x1=.4 & x2=x1+.3 & y1=.4 & y2=y1+.1
curbox,x1,x2,y1,y2,/init,/mess
print,x1,x2,y1,y2
author Paul Ricchiazzi April, 1993
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\curbox.pro)
ROUTINE: cursim
USEAGE: cursim,a,yy,xx,range=range
PURPOSE: Use the graphics cursor to interrogate a TVIM image for
pixel values and positions.
INPUT:
a image array, same size as used in TVIM image
yy, xx 2-D arrays of "vertical" and "horizontal" position
in the geographical case these would be lat and lon arrays
If these arrays are not supplied the x and y data
coordinates are used instead.
OPTIONAL INPUT:
point if set, CURSIM will print the range and azimuth
of the cursor from this point. (Palmer = [-64.767,-64.067] )
When this option is used the lat,lon coordinates must
be available either in the data coordinates of the plot
(i.e., as specified by the XRANGE and YRANGE parameter
in the TVIM call) or explicitly as the YY and XX parameters
in CURSIM
EXAMPLE:
tvim,hanning(200,200),xrange=[-180,180],yrange=[-90,90]
map_set,0,0,/cont,/grid,pos=boxpos(/get),/noerase
cursim,hanning(200,200),point=[35,-120]
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cursim.pro)
ROUTINE: cursx
USEAGE: cursx,xx,yy,verbose=verbose
PROCEDURE: Use the graphics cursor to find xy point on plot.
xy point is written to pop-up widget.
If a single argument is supplied (XX) it is interpreted
as an image or z value which will be evaluated when
the LMB is pressed. This option works with TVIM images
or plots drawn with CONTOUR.
if two arguments are supplied (XX and YY) they are
interpreted as the x and y values of a curve in the xy
plane. The y value of the function is evaluated when
the LMB is pressed. This option works with plots drawn
with PLOT
Hit and drag LMB to retrieve coordinates and values
Hit MMB to quit and retain pop-up display
Hit RMB to quit and destroy pop-up
INPUT:
xx x coordinate or image array
yy if present this parameter indicates CURSX should be run
in curve follow mode (CFM). In this mode the y value at a
x coordiate point is indicated with a drawn symbol. The
symbol position follows the shape of the drawn curve as
the cursor is dragged across the plot.
Keyword input
psym symbol used to mark xy point in plot follow mode.
symsize symbol size
color color of symbol
silent if set, pop up window will not contain operating instructions
interpolate if set and non-zero, interpolate between defined x and y
points in plot follow mode
EXAMPLE:
plot,dist(20)
cursx
; display value at a point
f=randata(100,100,s=3)
tvim,f,xra=[100,120],yra=[30,50],xtitle='longitude',ytitle='latitude',/scale
cursx,f
; pick values off a plot using curve follow mode
x=findgen(200)
y=randf(200,1.5)
plot,x,y
loadct,5
thick,2
cursx,x,y,psym=1,symsize=2,color=100
thick,1
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\cursx.pro)
NAME:
CURVE_LABEL
PURPOSE:
Draw labels close to one or more (up to 30) curves that have
been previously plotted.
CALLING SEQUENCE:
CURVE_LABEL,X,Y1,[Y2,Y3,Y4,Y5],LABELS=LABELS, $
[COLOR=COLOR,XPOSITION=XPOSITION,YOFFSET=YOFFSET]
INPUTS:
X - xaxis vector (1D array)
Y1 - 1st y axis vector to be labelled.
OPTIONAL INPUTS:
Y2 - 2nd y axis vector to be labelled.
Y3 - 3rd y axis vector to be labelled.
....etc....
KEYWORD PARAMETERS:
LABELS - String array of labels. The size of the LABELS array
must match the number of y variables passed. This
keyword is required.
XPOSITION - A scalar variable specifying where along the x
axis the labels are to be drawn, in normal
coordinates. Default = 0.25. Unless the
NO_REPOSITION keyword is set, this might get
changed if the procedure determines that the
labels are too close together when drawing
multiple labels.
YOFFSET - A scalar specifying the distance in Y between the
labels and the curves, in normal
coordinates. Default = 0.01
NO_REPOSITION - Set this to inhibit moving the label positions
if the labels are too close together when
drawing multiple labels.
COLOR - Integer array of color indices for the labels.
_EXTRA - The idl _EXTRA keyword, for additional graphics
keywords to the XYOUTS procedure.
PROCEDURE:
All labels are lined up at one point along the xaxis. The
procedure will try to find a position along the xaxis for
which the labels are not too close to each other. If it fails
at this, it will just stick the labels at x=0.25 (normal).
EXAMPLE:
To label a plot containing three curves, try something like
this:
plot,x,y1,/nodata
oplot,x,y1,color=2
oplot,x,y2,color=3
oplot,x,y3,color=4
curve_label,x,y1,y2,y3,labels=['Y1','Y2','Y3'],color=[2,3,4]
MODIFICATION HISTORY:
David L. Windt, Bell Labs, March, 1997.
windt@bell-labs.com
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\curve_label.pro)
NAME: CutOff_first_chars PURPOSE: This function cuts off the first n characters from a string CATEGORY: PROG_TOOLS/STRINGS CALLING SEQUENCE: fc = CutOff_first_chars(charstr [,n] [,CUTOFF = co]) INPUTS: charstr: string of which the first n characters should be cut off. n: number of characters to cut off (default: 1). KEYWORD PARAMETERS: CUTOFF = co: Named variable which will contain the truncated characters of charstr. This variable has to be initialised as a string before calling the routine. OUTPUTS: fc: truncated string. EXAMPLE: a = 'Hello' fc = CutOff_First_Chars(a, 3, CUTOFF = co) PRINT, fc + '+' + co -> lo+Hel MODIFICATION HISTORY: Written by: Frank Holland, 04. Sep. 1998
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\cutoff_first_chars.pro)
NAME: CutOff_last_chars PURPOSE: This function cuts off the last n characters from a string CATEGORY: PROG_TOOLS/STRINGS CALLING SEQUENCE: fc = CutOff_last_chars(charstr [,n] [,CUTOFF = co]) INPUTS: charstr: string of which the last n characters should be cut off. n: number of characters to cut off (default: 1). KEYWORD PARAMETERS: CUTOFF = co: Named variable which will contain the cut-off characters of charstr. This variable has to be initialised as a string before calling the routine. OUTPUTS: fc: truncated string. EXAMPLE: a = 'Hello' fc = CutOff_last_chars(a, 3, CUTOFF = co) PRINT, fc + '+' + co -> He+llo MODIFICATION HISTORY: Written by: Frank Holland, 04. Sep. 1998
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\cutoff_last_chars.pro)
NAME:
CW_BTGROUP
PURPOSE:
CW_BTGROUP is a compound widget that simplifies creating
a base of buttons. It handles the details of creating the
proper base (standard, exclusive, or non-exclusive) and filling
in the desired buttons. Events for the individual buttons are
handled transparently, and a CW_BTGROUP event returned. This
event can return any one of the following:
- The Index of the button within the base.
- The widget ID of the button.
- The name of the button.
- An arbitrary value taken from an array of User values.
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
Widget = CW_BTGROUP(Parent, Names)
PROCEDURE:
To get or set the value of a CW_BTGROUP, use the GET_VALUE and
SET_VALUE keywords to WIDGET_CONTROL. The value of a CW_BTGROUP
is:
-----------------------------------------------
Type Value
-----------------------------------------------
normal None
exclusive Index of currently set button
non-exclusive Vector indicating the position
of each button (1-set, 0-unset)
-----------------------------------------------
INPUTS:
Parent: The ID of the parent widget.
Names: A string array, containing one string per button,
giving the name of each button.
KEYWORD PARAMETERS:
BUTTON_UVALUE: An array of user values to be associated with
each button and returned in the event structure.
COLUMN: Buttons will be arranged in the number of columns
specified by this keyword.
EVENT_FUNCT: The name of an optional user-supplied event function
for buttons. This function is called with the return
value structure whenever a button is pressed, and
follows the conventions for user-written event
functions.
EXCLUSIVE: Buttons will be placed in an exclusive base, with
only one button allowed to be selected at a time.
FONT: The name of the font to be used for the button
titles. If this keyword is not specified, the default
font is used.
FRAME: Specifies the width of the frame to be drawn around
the base.
IDS: A named variable into which the button IDs will be
stored, as a longword vector.
LABEL_LEFT: Creates a text label to the left of the buttons.
LABEL_TOP: Creates a text label above the buttons.
MAP: If set, the base will be mapped when the widget
is realized (the default).
NONEXCLUSIVE: Buttons will be placed in an non-exclusive base.
The buttons will be independent.
NO_RELEASE: If set, button release events will not be returned.
RETURN_ID: If set, the VALUE field of returned events will be
the widget ID of the button.
RETURN_INDEX: If set, the VALUE field of returned events will be
the zero-based index of the button within the base.
THIS IS THE DEFAULT.
RETURN_NAME: If set, the VALUE field of returned events will be
the name of the button within the base.
ROW: Buttons will be arranged in the number of rows
specified by this keyword.
SCROLL: If set, the base will include scroll bars to allow
viewing a large base through a smaller viewport.
SET_VALUE: The initial value of the buttons. This is equivalent
to the later statement:
WIDGET_CONTROL, widget, set_value=value
SPACE: The space, in pixels, to be left around the edges
of a row or column major base. This keyword is
ignored if EXCLUSIVE or NONEXCLUSIVE are specified.
UVALUE: The user value to be associated with the widget.
XOFFSET: The X offset of the widget relative to its parent.
XPAD: The horizontal space, in pixels, between children
of a row or column major base. Ignored if EXCLUSIVE
or NONEXCLUSIVE are specified.
XSIZE: The width of the base.
X_SCROLL_SIZE: The width of the viewport if SCROLL is specified.
YOFFSET: The Y offset of the widget relative to its parent.
YPAD: The vertical space, in pixels, between children of
a row or column major base. Ignored if EXCLUSIVE
or NONEXCLUSIVE are specified.
YSIZE: The height of the base.
Y_SCROLL_SIZE: The height of the viewport if SCROLL is specified.
TRACKING_EVENTS:Return tracking events.
OUTPUTS:
The ID of the created widget is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, SELECT:0, VALUE:0 }
The SELECT field is passed through from the button event. VALUE is
either the INDEX, ID, NAME, or BUTTON_UVALUE of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
MODIFICATION HISTORY:
15 June 1992, AB
7 April 1993, AB, Removed state caching.
6 Oct. 1994, KDB, Font keyword is not applied to the label.
10 FEB 1995, DJC fixed bad bug in event procedure, getting
id of stash widget.
11 April 1995, AB Removed Motif special cases.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_btgroup.pro)
NAME:
cw_buttons
PURPOSE:
This compound widget function is used to set a group of buttons
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
result=cw_buttons(base,value,uvalue=uvalue,_extra=extra)
INPUTS:
base: the base where the widget should be placed in
value: a structure of value and set
.value: a vector of the text labels of the buttons
.set : a vector of 0 or 1 to set the buttons on
KEYWORD PARAMETERS:
uvalue: the users uvalue of the widget
_extra: all keywords for widget_base
and all keywords for buttons as buttons_ e.g. buttons_xsize
OUTPUTS:
This function returns widget id
EXAMPLE:
PRO test_event,ev
WIDGET_CONTROL,ev.id,get_uval=cmd
WIDGET_CONTROL,ev.top,get_uvalue=b
CASE cmd OF
'done':WIDGET_CONTROL,ev.top,/dest
'FF': BEGIN
WIDGET_CONTROL,ev.id,get_value=v
print,v.set
idx=(WHERE(v.set EQ 1,count))[0]
IF count GT 0 THEN BEGIN
value={value:[strtrim(SINDGEN(idx+1),2)],set:MAKE_ARRAY(idx+1,/LONG,value=1)}
WIDGET_CONTROL,b,set_value=value
ENDIF
END
ELSE:
ENDCASE
END
PRO test
a=WIDGET_BASE(row=2)
value={value:['MIN','SPEC','DEFAULT','MAX'],set:[1,0,0,0]}
b=cw_buttons(a,value=value,uvalue='FF',row=1,button_xsize=60,frame=2,xoffset=0,yoffset=0,button_frame=1)
value={value:['0'],set:[1]}
b=cw_buttons(a,value=value,uvalue='EF',col=2,/nonexclusive,frame=2,xoffset=20,yoffset=0,button_frame=1)
d=WIDGET_BUTTON(a,val='done',uval='done')
WIDGET_CONTROL,/realize,a,set_uvalue=b
XMANAGER,'test',a
END
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Oct-11
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_buttons.pro)
NAME:
CW_CURVE_LABEL
PURPOSE:
A compound widget used to select the position for a curve
label; this widget is intended to be used in conjunction with
the CURVE_LABEL procedure in this directory, in that this
widget lets the user select a value from a slider from 0 to
one, corresponding to the XPOSITION keyword in CURVE_LABEL.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
Result = CW_CURVE_LABEL(PARENT)
INPUTS:
PARENT - The ID of the parent widget.
KEYWORD PARAMETERS:
UVALUE - Supplies the user value for the widget.
VALUE - Initial value for the widget: a floating point between
0 and 1, corresponding to the XPOSITION keyword in
CURVE_LABEL.
TITLE - A title for the widget.
FRAME - Set to draw a frame around the widget; ignored if
PARENT is present.
FORMAT - Format string for CW_FSLIDER (default is F5.3)
FONT - Fonts to use for labels and buttons.
DONE - Set this to add a Done button, in addition to the
standard Apply button.
OUTPUTS:
The ID of the created widget is returned.
PROCEDURE/EXAMPLE:
A slider widget is created in which the user can select a
position value. By pressing the "Apply" button, an event is
returned, allowing the calling procedure to redraw the
curve label if desired.
This widget generates an event when the user presses the
Apply button or the Done button, if present. The EVENT.TAG
keyword will return either "APPLY" or "DONE" accordingly.
MODIFICATION HISTORY:
David L. Windt, Bell Labs, April 1997
windt@bell-labs.com
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_curve_label.pro)
NAME:
CW_DRAWCOLOR
PURPOSE:
This compound widget is used to place a label or color name next
to a color patch. Clicking on the color patch allows the user
to select another color
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:
colorpatchID = CW_DrawColor(parent)
REQUIRED INPUTS:
parent - The identifier of a parent base widget.
OUTPUTS:
colorpatchID - The widget identifier of the top-level base of this compound widget
INPUT KEYWORDS:
COLOR - The name of the color to be displayed. Color names come from PickColorName.
COLUMN - Set this keyword to stack widgets in a column. Default is in a row.
EVENT_FUNC - The name of an event handler function for this compound widget.
EVENT_PRO -The name of an event handler procedure for this compound widget.
INDEX - An index number where the color should be loaded. !D.Table_Size-2, by default.
LABEL_LEFT - Set this keyword to have the label text aligned on the left of the label. Default is to center.
LABEL_RIGHT - Set this keyword to have the label text aligned on the right of the label. Default is to center.
LABELSIZE - This is the X size of the label widget (containing the label) in device coordinates. Default is natural size.
LABELTEXT - This is the text on the label. Example, "Background Color", etc.
TITLE - This is the title on the PickColorName program that allows the user to select another color.
UVALUE - A user value for the widget.
XSIZE - The xsize (in pixel units) of the color patch. By default, 20.
YSIZE - The xsize (in pixel units) of the color patch. By default, 20.
OUTPUT KEYWORDS:
OBJECT - The object reference. Use this to call methods, etc.
DEPENDENCIES:
Reqires FSC_COLOR and PICKCOLORNAME from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.pro
http://www.dfanning.com/programs/pickcolorname.pro
MODIFICATION HISTORY:
Written by David Fanning, March 2001.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\cw_drawcolor.pro)
NAME:
CW_DRAWSIZE
PURPOSE:
A compound widget used to change the size of an existing
draw widget. The widget contains fields for the X and Y
draw size (in pixels), an Apply button, and optionally a
Done button.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
Result = CW_DRAWSIZE(PARENT,DRAW_WIDGET)
INPUTS:
PARENT - The ID of the parent widget.
DRAW_WIDGET - The id of the draw widget being resized.
KEYWORD PARAMETERS:
UVALUE - Supplies the user value for the widget.
FRAME - set to draw a frame around the widget; ignored if
PARENT is present.
ROW - set to place the two window size fields (x,y) in a row.
COLUMN - set to place the two window size fields (x,y) in a column.
FONT - fonts to use for labels and buttons.
DONE - set this to add a Done button, in addition to the standard
Apply button.
NO_RETURN - The default behavior is that the user must press
after entering new values. Set this
keyword so that an event is returned even if the
user just changes a value and then moves the
cursor outside of the text entry area.
OUTPUTS:
The ID of the created widget is returned.
PROCEDURE/EXAMPLE:
A widget is created in which the user can specify the X and Y
draw widget size in pixels. By pressing the "Apply" button,
the draw widget is resized, and an event is returned, allowing
the calling procedure to repaint the window if desired.
This widget generates an event when the user presses the
Apply button or the Done button, if present. The EVENT.TAG
keyword will return either "APPLY" or "DONE" accordingly.
MODIFICATION HISTORY:
David L. Windt, Bell Labs, March 1997
windt@bell-labs.com
DLW, June 1997, Added NO_RETURN keyword.
DLW, Sep 1997, Fixed bug that caused initial values of X and Y
pixel sizes to be displayed as floating point values rather
than integers.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_drawsize.pro)
NAME: CW_FIELD PURPOSE: This widget cluster function manages a data entry field widget. The field consists of a label and a text widget. CW_FIELD's can be string fields, integer fields or floating-point fields. The default is an editable string field. CATEGORY: Widget Clusters. CALLING SEQUENCE: Result = CW_FIELD(Parent) INPUTS: Parent: The widget ID of the widget to be the field's parent. KEYWORD PARAMETERS: TITLE: A string containing the text to be used as the label for the field. The default is "Input Field:". VALUE: The initial value in the text widget. This value is automatically converted to the type set by the STRING, INTEGER, and FLOATING keywords described below. UVALUE: A user value to assign to the field cluster. This value can be of any type. FRAME: The width, in pixels, of a frame to be drawn around the entire field cluster. The default is no frame. RETURN_EVENTS: Set this keyword to make cluster return an event when ais pressed in a text field. The default is not to return events. Note that the value of the text field is always returned when the WIDGET_CONTROL, field, GET_VALUE=X command is used. ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the contents of a text field have changed. COLUMN: Set this keyword to center the label above the text field. The default is to position the label to the left of the text field. ROW: Set this keyword to position the label to the left of the text field. This is the default. XSIZE: An explicit horizontal size (in characters) for the text input area. The default is to let the window manager size the widget. Using the XSIZE keyword is not recommended. YSIZE: An explicit vertical size (in lines) for the text input area. The default is 1. STRING: Set this keyword to have the field accept only string values. Numbers entered in the field are converted to their string equivalents. This is the default. FLOATING: Set this keyword to have the field accept only floating-point values. Any number or string entered is converted to its floating-point equivalent. INTEGER: Set this keyword to have the field accept only integer values. Any number or string entered is converted to its integer equivalent (using FIX). For example, if 12.5 is entered in this type of field, it is converted to 12. LONG: Set this keyword to have the field accept only long integer values. Any number or string entered is converted to its long integer equivalent (using LONG). FONT: A string containing the name of the X Windows font to use for the TITLE of the field. FIELDFONT: A string containing the name of the X Windows font to use for the TEXT part of the field. NOEDIT: Normally, the value in the text field can be edited. Set this keyword to make the field non-editable. NO_RETURN: The default behavior is that the user must press after entering new values. Set this keyword so that an event is returned even if the user just changes a value and then moves the cursor outside of the text entry area. TEXT_ID: The widget id of the text widget. OUTPUTS: This function returns the widget ID of the newly-created cluster. COMMON BLOCKS: None. PROCEDURE: Create the widgets, set up the appropriate event handlers, and return the widget ID of the newly-created cluster. EXAMPLE: The code below creates a main base with a field cluster attached to it. The cluster accepts string input, has the title "Name:", and has a frame around it: base = WIDGET_BASE() field = CW_FIELD(base, TITLE="Name:", /FRAME) WIDGET_CONTROL, base, /REALIZE MODIFICATION HISTORY: Written by: Keith R. Crosley June 1992 KRC, January 1993 -- Added support for LONG integers. AB, 7 April 1993, Removed state caching. JWG, August 1993, Completely rewritten to make use of improved TEXT widget functionality ACY, 25 March, 1994, fix usage of FRAME keyword KDB, May 1994, Initial value =0 would result in a null text field. Fixed keyword check. David L. Windt, Bell Labs, June 1997, Added NO_RETURN keyword. David L. Windt, Bell Labs, March 1998, Added TEXT_ID keyword. windt@bell-labs.com
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_field.pro)
NAME:
cw_fields
PURPOSE:
This compound widget function is used to set a group of lables and input data fields
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
result=cw_fields(base,value=value,uvalue=uvalue,_extra=extra)
INPUTS:
base: the base where the widget should be placed in
KEYWORD PARAMETERS:
value: a structure of description and values
.label : a vector of the text labels of the values
.value : a vector of the values, type of value musn't be string
.description : the label of the whole frame (if it's not defined no label is printed)
uvalue: the users uvalue of the widget
_extra: all keywords for widget_base
and all keywords for widget_text or widget_label as text_ or label_ e.g. text_xsize or label_xsize
OUTPUTS:
This function returns widget id
EXAMPLE:
PRO test2_event,ev
WIDGET_CONTROL,ev.id,get_uval=cmd
WIDGET_CONTROL,ev.top,get_uvalue=b
CASE cmd OF
'done':WIDGET_CONTROL,ev.top,/dest
'FF': BEGIN
WIDGET_CONTROL,ev.id,get_value=v
print,v.value
idx=(WHERE(v.value EQ 1,count))[0]
IF count GT 0 THEN BEGIN
value={label:['AHA','ABA'],value:[10.1,10.3]}
WIDGET_CONTROL,b,set_value=value
ENDIF
END
ELSE:
ENDCASE
END
PRO test2
a=WIDGET_BASE(row=2)
value={label:['MIN','SPEC','DEFAULT','MAX'],value:[1,0,0,0]}
b=cw_fields(a,value=value,uvalue='FF',row=1,text_xsize=10,text_editable=1,frame=2,xoffset=0,yoffset=0,button_frame=1)
d=WIDGET_BUTTON(a,val='done',uval='done')
WIDGET_CONTROL,/realize,a,set_uvalue=b
XMANAGER,'test2',a
END
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Oct-24
2000-Feb-07 possible variable size of text fields added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_fields.pro)
NAME:
cw_list
PURPOSE:
This compound widget function is used to set up a input list
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
result=cw_list(base,value=value,uvalue=uvalue,_extra=extra)
INPUTS:
base: the base where the widget should be placed in
KEYWORD PARAMETERS:
value={label:fn.name+fn.ext,list:list,text:'',button:'FILE',list_selected:-1,button_pressed:0}
value: a structure of description and values
.label : a label right to the button
.list : a vector of strings to set as value to the list
.list_selected : a vector of indices to set which list values are selected
The following tags are optional:
.button : a string to set as value to the button
.button_pressed : 1 if button is pressed 0 if not
.description : the label of the whole frame (if it's not defined no description is printed)
uvalue: the users uvalue of the widget
_extra: all keywords for widget_base
and all keywords for widget_text or widget_label or widget_button or widget_list as text_ or label_ e.g. text_xsize or label_xsize
OUTPUTS:
This function returns widget id
EXAMPLE:
PRO test_event,ev
WIDGET_CONTROL,ev.id,get_uval=cmd
WIDGET_CONTROL,ev.top,get_uvalue=b
CASE cmd OF
'done':BEGIN
WIDGET_CONTROL,b,get_value=v
IF v.list_selected[0] NE -1 THEN PRINT,v.list[v.list_selected]
WIDGET_CONTROL,ev.top,/dest
END
'FF':BEGIN
WIDGET_CONTROL,ev.id,get_value=v
IF v.button_pressed EQ 1 THEN BEGIN
file_name=DIALOG_PICKFILE(filter='*.nc')
fn=file_path_name_ext(file_name)
list=f_names(file_name,/time)
value={label:fn.name+fn.ext,list:list,text:'',button:'FILE',list_selected:-1,button_pressed:0}
WIDGET_CONTROL,ev.id,set_value=value
ENDIF
END
ELSE:
ENDCASE
END
PRO test
a=WIDGET_BASE(row=2,/frame)
value={label:'testdatei',list:STRTRIM(SINDGEN(40),2),text:'',button:'FILE',$
list_selected:-1,button_pressed:0,description:'TEST'}
b=cw_list(a,value=value,uvalue='FF',frame=2, XOFFSET=9,$
YOFFSET=15 ,SCR_XSIZE=140 ,SCR_YSIZE=200,$
/text_all_events, text_xsize=19,/text_editable, $
/list_multiple,list_ysize=10,list_xsize=20,$
label_xsize=100,$
button_ysize=20 )
d=WIDGET_BUTTON(a,val='done',uval='done')
WIDGET_CONTROL,/realize,a,set_uvalue=b
XMANAGER,'test',a
END
2nd example
PRO test2_event,ev
WIDGET_CONTROL,ev.id,get_uval=cmd
WIDGET_CONTROL,ev.top,get_uvalue=b
CASE cmd OF
'done':BEGIN
WIDGET_CONTROL,b,get_value=v
IF v.list_selected[0] NE -1 THEN PRINT,v.list[v.list_selected]
WIDGET_CONTROL,ev.top,/dest
END
'FF':BEGIN
WIDGET_CONTROL,ev.id,get_value=v
IF v.button_pressed EQ 1 THEN BEGIN
replace_tag,v,'list_selected','list_selected',INDGEN(2)
WIDGET_CONTROL,ev.id,set_value=v
ENDIF
END
ELSE:
ENDCASE
END
PRO test2
a=WIDGET_BASE(row=2,/frame)
value={label:'[0,1]',list:STRTRIM(SINDGEN(40),2),text:'',button:'PRESELECTION',$
list_selected:-1,button_pressed:0,description:'TEST'}
b=cw_list(a,value=value,uvalue='FF',frame=2, XOFFSET=9,$
YOFFSET=15 ,SCR_XSIZE=140 ,SCR_YSIZE=200,$
/text_all_events, text_xsize=19,/text_editable, $
/list_multiple,list_ysize=10,list_xsize=20,$
label_xsize=100,$
button_ysize=20 )
d=WIDGET_BUTTON(a,val='done',uval='done')
WIDGET_CONTROL,/realize,a,set_uvalue=b
XMANAGER,'test2',a
END
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Nov-07
2000-Jan-07 : button definition changed
2000-Jan-11 : pointer removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_list.pro)
NAME:
cw_pdrb
PURPOSE:
cw_pdrb is a compound widget that simplifies creating
pulldown menus. It has a simpler interface than the XPDMENU
procedure, which it is intended to replace. Events for the
individual buttons are handled transparently, and a cw_pdrb
event returned. This event can return any one of the following:
The Index of the button within the base.
The widget ID of the button.
The name of the button.
The fully qualified name of the button. This allows
different sub-menus to contain buttons with the same
name in an unambiguous way.
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
widget = cw_pdrb(Parent, Desc)
INPUTS:
Parent: The ID of the parent widget.
Desc: An array of strings or structures. Each element contains
a menu description with two fields, a flag field, and
the name of the item. If a structure, each element
is defined as follows:
{ cw_pdrb_S, flags:0, name:'' }
The name tag gives the name of button. The flags
field is a two-bit bitmask that controls how the button is
interpreted:
Value Meaning
-------------------------------------------
0 This button is neither the beginning
nor the end of a pulldown level.
1 This button is the root of a
sub-pulldown menu. The sub-buttons
start with the next button.
2 This button is the last button at the
current pulldown level. The next button
belongs to the same level as the current
parent button.
3 This button is the root of a sub-pulldown
menu, but it is also the last entry of
the current level.
If Desc is a string, each element contains the flag field
followed by a backslash character, followed by the menu item's
contents. See the example below.
event procedures: An event procedure may be specified for an
element and all its children, by including a third field
in Desc, if Desc is a string array. Events for buttons without
an event procedure, are dispatched normally.
See the example below.
KEYWORD PARAMETERS:
delimeter: The character used to separate the parts of a
fully qualified name in returned events. The
default is to use the '.' character.
font: The name of the font to be used for the button
titles. If this keyword is not specified, the
default font is used.
help: If MBAR is specified and one of the buttons on the
menubar has the label "help" (case insensitive) then
that button is created with the /HELP keyword to
give it any special appearance it is supposed to
have on a menubar. For example, Motif expects
help buttons to be on the right.
ids: A named variable into which the button IDs will
be stored as a longword vector.
mbar: if constructing a menu-bar pulldown, set this
keyword. In this case, the parent must be the
widget id of the menu bar of a top-level base,
returned by WIDGET_BASE(..., MBAR=mbar).
return_id: If present and non-zero, the VALUE field of returned
events will be the widget ID of the button.
return_index: If present and non-zero, the VALUE field of returned
events will be the zero-based index of the button
within the base. THIS IS THE DEFAULT.
return_name: If present and non-zero, the VALUE field of returned
events will be the name of the selected button.
return_full_name: If present and non-zero, the VALUE field of returned
events will be the fully qualified name of the
selected button. This means that the names of all
the buttons from the topmost button of the pulldown
menu to the selected one are concatenated with the
delimiter specified by the DELIMITER keyword. For
example, if the top button was named COLORS, the
second level button was named BLUE, and the selected
button was named LIGHT, the returned value would be
COLORS.BLUE.LIGHT
This allows different submenus to have buttons with
the same name (e.g. COLORS.RED.LIGHT).
uvalue: The user value to be associated with the widget.
xoffset: The X offset of the widget relative to its parent.
yoffset: The Y offset of the widget relative to its parent.
OUTPUTS:
The ID of the top level button is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }
VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
EXAMPLE:
The following is the description of a menu bar with two buttons,
"Colors" and "Quit". Colors is a pulldown containing the colors
"Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown
containing "Light", "Medium", "Dark", "Navy", and "Royal":
; Make sure cw_pdrb_S is defined
junk = { cw_pdrb_S, flags:0, name:'' }
; The description
desc = [ { cw_pdrb_S, 1, 'Colors' }, $
{ cw_pdrb_S, 0, 'Red' }, $
{ cw_pdrb_S, 0, 'Green' }, $
{ cw_pdrb_S, 1, 'Blue' }, $
{ cw_pdrb_S, 0, 'Light' }, $
{ cw_pdrb_S, 0, 'Medium' }, $
{ cw_pdrb_S, 0, 'Dark' }, $
{ cw_pdrb_S, 0, 'Navy' }, $
{ cw_pdrb_S, 2, 'Royal' }, $
{ cw_pdrb_S, 0, 'Cyan' }, $
{ cw_pdrb_S, 2, 'Magenta' }, $
{ cw_pdrb_S, 2, 'Quit' } ]
The same menu may be defined as a string by equating the Desc parameter
to the following string array:
desc =[ '1\Colors' , $
'0\Red' , $
'0\Green' , $
'1\Blue\BLUE_EVENT_PROC' , $
'0\Light' , $
'0\Medium' , $
'0\Dark' , $
'0\Navy' , $
'2\Royal' , $
'0\Cyan' , $
'2\Magenta\MAGENTA_EVENT_PROC' , $
'2\Quit' ]
The following small program can be used with the above description
to create the specified menu:
base = widget_base()
menu = cw_pdrb(base, desc, /RETURN_FULL_NAME)
WIDGET_CONTROL, /REALIZE, base
repeat begin
ev = WIDGET_EVENT(base)
print, ev.value
end until ev.value eq 'Quit'
WIDGET_CONTROL, /DESTROY, base
end
Note that independent event procedures were specified for
the multiple Blue buttons (blue_event_proc), and the Magenta button
(magenta_event_proc).
MODIFICATION HISTORY:
18 June 1992, AB
16 Jan 1995, DMS, Added MBAR keyword, event procedures,
and menu descriptor strings.
2 July 1995, AB, Added HELP keyword.
21 Mar 1998, learned now that's an opposite problem will occur
if variables named same as functions
in the past functions would not be found if they have same names as variables
now variables won't be found if they have same names as functions whithout using []
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_pdrb.pro)
NAME:
CW_PDTMENU
PURPOSE:
CW_PDTMENU is a compound widget that simplifies creating
pulldown menus. It has a simpler interface than the XPDTMENU
procedure, which it is intended to replace. Events for the
individual buttons are handled transparently, and a CW_PDTMENU
event returned. This event can return any one of the following:
- The Index of the button within the base.
- The widget ID of the button.
- The name of the button.
- The fully qualified name of the button. This allows
different sub-menus to contain buttons with the same
name in an unambiguous way.
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
widget = CW_PDTMENU(Parent, Desc)
INPUTS:
Parent: The ID of the parent widget.
Desc: An array of strings or structures. Each element contains
a menu description with two fields, a flag field, and
the name of the item. If a structure, each element
is defined as follows:
{ CW_PDTMENU_S, flags:0, name:'' }
The name tag gives the name of button. The flags
field is a two-bit bitmask that controls how the button is
interpreted:
Value Meaning
-------------------------------------------
0 This button is neither the beginning
nor the end of a pulldown level.
1 This button is the root of a
sub-pulldown menu. The sub-buttons
start with the next button.
2 This button is the last button at the
current pulldown level. The next button
belongs to the same level as the current
parent button.
3 This button is the root of a sub-pulldown
menu, but it is also the last entry of
the current level.
If Desc is a string, each element contains the flag field
followed by a backslash character, followed by the menu item's
contents. See the example below.
EVENT PROCEDURES: An event procedure may be specified for an
element and all its children, by including a third field
in Desc, if Desc is a string array. Events for buttons without
an event procedure, are dispatched normally.
See the example below.
KEYWORD PARAMETERS:
DELIMITER: The character used to separate the parts of a
fully qualified name in returned events. The
default is to use the '.' character.
FONT: The name of the font to be used for the button
titles. If this keyword is not specified, the
default font is used.
HELP: If MBAR is specified and one of the buttons on the
menubar has the label "help" (case insensitive) then
that button is created with the /HELP keyword to
give it any special appearance it is supposed to
have on a menubar. For example, Motif expects
help buttons to be on the right.
IDS: A named variable into which the button IDs will
be stored as a longword vector.
MBAR: if constructing a menu-bar pulldown, set this
keyword. In this case, the parent must be the
widget id of the menu bar of a top-level base,
returned by WIDGET_BASE(..., MBAR=mbar).
RETURN_ID: If present and non-zero, the VALUE field of returned
events will be the widget ID of the button.
RETURN_INDEX: If present and non-zero, the VALUE field of returned
events will be the zero-based index of the button
within the base. THIS IS THE DEFAULT.
RETURN_NAME: If present and non-zero, the VALUE field of returned
events will be the name of the selected button.
RETURN_FULL_NAME: If present and non-zero, the VALUE field of returned
events will be the fully qualified name of the
selected button. This means that the names of all
the buttons from the topmost button of the pulldown
menu to the selected one are concatenated with the
delimiter specified by the DELIMITER keyword. For
example, if the top button was named COLORS, the
second level button was named BLUE, and the selected
button was named LIGHT, the returned value would be
COLORS.BLUE.LIGHT
This allows different submenus to have buttons with
the same name (e.g. COLORS.RED.LIGHT).
UVALUE: The user value to be associated with the widget.
XOFFSET: The X offset of the widget relative to its parent.
YOFFSET: The Y offset of the widget relative to its parent.
TRACKING_EVENTS: Enable widget tracking events.
OUTPUTS:
The ID of the top level button is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }
VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
EXAMPLE:
The following is the description of a menu bar with two buttons,
"Colors" and "Quit". Colors is a pulldown containing the colors
"Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown
containing "Light", "Medium", "Dark", "Navy", and "Royal":
; Make sure CW_PDTMENU_S is defined
junk = { CW_PDTMENU_S, flags:0, name:'' }
; The description
desc = [ { CW_PDTMENU_S, 1, 'Colors' }, $
{ CW_PDTMENU_S, 0, 'Red' }, $
{ CW_PDTMENU_S, 0, 'Green' }, $
{ CW_PDTMENU_S, 1, 'Blue' }, $
{ CW_PDTMENU_S, 0, 'Light' }, $
{ CW_PDTMENU_S, 0, 'Medium' }, $
{ CW_PDTMENU_S, 0, 'Dark' }, $
{ CW_PDTMENU_S, 0, 'Navy' }, $
{ CW_PDTMENU_S, 2, 'Royal' }, $
{ CW_PDTMENU_S, 0, 'Cyan' }, $
{ CW_PDTMENU_S, 2, 'Magenta' }, $
{ CW_PDTMENU_S, 2, 'Quit' } ]
The same menu may be defined as a string by equating the Desc parameter
to the following string array:
desc =[ '1\Colors' , $
'0\Red' , $
'0\Green' , $
'1\Blue\BLUE_EVENT_PROC' , $
'0\Light' , $
'0\Medium' , $
'0\Dark' , $
'0\Navy' , $
'2\Royal' , $
'0\Cyan' , $
'2\Magenta\MAGENTA_EVENT_PROC' , $
'2\Quit' ]
The following small program can be used with the above description
to create the specified menu:
base = widget_base()
menu = cw_pdtmenu(base, desc, /RETURN_FULL_NAME)
WIDGET_CONTROL, /REALIZE, base
repeat begin
ev = WIDGET_EVENT(base)
print, ev.value
end until ev.value eq 'Quit'
WIDGET_CONTROL, /DESTROY, base
end
Note that independent event procedures were specified for
the multiple Blue buttons (blue_event_proc), and the Magenta button
(magenta_event_proc).
MODIFICATION HISTORY:
18 June 1992, AB
16 Jan 1995, DMS, Added MBAR keyword, event procedures,
and menu descriptor strings.
2 July 1995, AB, Added HELP keyword.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_pdtmenu.pro)
NAME:
CW_PLOTAXES
PURPOSE:
A compound widget used to change the type, range and style
(bit 0) values of one or more plot axis structure variable. A
CW_PLOTAXIS (single axis) widget is created for each element
of the LABELS input parameter. The widget also includes an
Apply button, and (optionally) a Done button.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
Result = CW_PLOTAXES(PARENT,LABELS)
INPUTS:
PARENT - The ID of the parent widget.
LABELS - A string array of labels to be drawn to the left (or
top) of each of the CW_PLOTAXIS widgets.
OPTIONAL KEYWORD PARAMETERS:
UVALUE - Supplies the user value for the widget.
FRAME - Set to draw a frame around the widget.
VALUE - An (n,4) array of initial values, where
n = n_elements(LABELS), and each row has
the form VALUE(i,*)=[type,min,max,style]
FONT - Font keyword for labels etc.
ROW - Set to create a row of column-oriented CW_PLOTAXIS widgets.
COLUMN - Set to create a column of row-oriented CW_PLOTAXIS
widgets. (default)
DONE - Set this to add a Done button, in addition to the standard
Apply button.
AXIS_IDS - An array of widget id's for the individual
CW_PLOTAXIS widgets.
X_SCROLL_SIZE, Y_SCROLL_SIZE - if these values are non-zero,
then the base widget which
holds the CW_PLOTAXIS widgets
will include scroll bars.
NO_RETURN - The default behavior is that the user must press
after entering new values. Set this
keyword so that new values are accepted even if
the user just changes a value and then moves the
cursor outside of the text entry area.
OUTPUTS:
The ID of the created widget is returned.
PROCEDURE/EXAMPLE:
The idea is that this cw would be used in a widget intended
to allow the user to interactively adjust the settings for a
plot. For instance, you might have a menu item such as Plot
Options->Scaling, which would create a popup widget
containing a CW_PLOTAXES subwidget for the X and Y plot
variables. When the user makes changes to the Type, Range,
and Style values, and then presses the Apply button, the
popup widget event handler would re-draw the plot
accordingly.
This widget generates an event when the user presses the
Apply button or the Done button, if present. The EVENT.TAG
keyword will return either "APPLY" or "DONE" accordingly.
Example:
axes=CW_PLOTAXES(BASE,['X','Y'],/DONE, $
VALUE=TRANSPOSE([[FLTARR(4)],[FLTARR(4)]]))
MODIFICATION HISTORY:
David L. Windt, Bell Labs, March 1997
windt@bell-labs.com
DLW, June 1997, Added NO_RETURN keyword.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\cw_plotaxes.pro)
NAME:
cw_rbfslider
PURPOSE:
The standard slider provided by the WIDGET_SLIDER() function is
integer only. This compound widget provides a floating point
slider.
CATEGORY:
PROG_TOOLS/WIDGETS
CALLING SEQUENCE:
widget = CW_RBFSLIDER(Parent)
INPUTS:
Parent: The ID of the parent widget.
KEYWORD PARAMETERS:
DRAG: Set this keyword to zero if events should only
be generated when the mouse is released. If it is
non-zero, events will be generated continuously
when the slider is adjusted. Note: On slow systems,
/DRAG performance can be inadequate. The default
is DRAG=0.
EDIT: Set this keyword to make the slider label be
editable. The default is EDIT=0.
FORMAT: Provides the format in which the slider value is
displayed. This should be a format as accepted by
the STRING procedure. The default is FORMAT='(G13.6)'
FRAME: Set this keyword to have a frame drawn around the
widget. The default is FRAME=0.
MAXIMUM: The maximum value of the slider. The default is
MAXIMUM=100.
MINIMUM: The minimum value of the slider. The default is
MINIMUM=0.
SCROLL Sets the SCROLL keyword to the WIDGET_SLIDER underlying
this compound widget. Unlike WIDGET_SLIDER, the
value given to SCROLL is taken in the floating units
established by MAXIMUM and MINIMUM, and not in pixels.
SUPPRESS_VALUE: If true, the current slider value is not displayed.
The default is SUPPRESS_VALUE=0.
TITLE: The title of slider. (The default is no title.)
UVALUE: The user value for the widget.
VALUE: The initial value of the slider
VERTICAL: If set, the slider will be oriented vertically.
The default is horizontal.
XSIZE: For horizontal sliders, sets the length.
YSIZE: For vertical sliders, sets the height.
XOFFSET: The offset in x direction, if it's used then xsize=xsize-yoffset ;new March 98
YOFFSET: The offset in y direction, if it's used then ysize=ysize-yoffset ;new March 98
OUTPUTS:
The ID of the created widget is returned.
SIDE EFFECTS:
This widget generates event structures containing a field
named value when its selection thumb is moved. This is a
floating point value.
PROCEDURE:
WIDGET_CONTROL, id, SET_VALUE=value can be used to change the
current value displayed by the widget.
WIDGET_CONTROL, id, GET_VALUE=var can be used to obtain the current
value displayed by the widget.
MODIFICATION HISTORY:
April 2, 1992, SMR and AB
Based on the RGB code from XPALETTE.PRO, but extended to
support color systems other than RGB.
5 January 1993, Mark Rivers, Brookhaven National Labs
Added EDIT keyword.
7 April 1993, AB, Removed state caching.
28 July 1993, ACY, set_value: check labelid before setting text.
3 October 1995, AB, Added SCROLL keyword.
30 March 1998 RB added xoffset and yoffset
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\cw_rbfslider.pro)
NAME:
CYPH
PURPOSE:
Construct a cycle/phase array from time series data.
CATEGORY:
CALLING SEQUENCE:
cyph, data, time
INPUTS:
data = time series data. in
time = time tag of each data point. in
KEYWORD PARAMETERS:
Keywords:
CPOUT=z Returned reformatted data image.
TOUT=t Returned time for bottom line image.
OFFSET=frac Given starting offset into data as fraction
of time slice size (def=0).
SLICE=dx Given slice size in samples (may be fractional).
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: See also xcyph, a widget based interactive version.
MODIFICATION HISTORY:
R. Sterner, 1994 Mar 2.
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\cyph.pro)
NAME:
D2DMS
PURPOSE:
Function to convert from degrees to deg, min, sec.
CATEGORY:
CALLING SEQUENCE:
s = d2dms( deg)
INPUTS:
deg = input in degrees. in
KEYWORD PARAMETERS:
Keywords:
DIGITS=n Force degrees to have n digits.
OUTPUTS:
s = output string. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1997 Jan 17
Copyright (C) 1997, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\d2dms.pro)
NAME:
DATATYPE
PURPOSE:
Datatype of variable as a string (3 char or spelled out).
CATEGORY:
CALLING SEQUENCE:
typ = datatype(var, [flag])
INPUTS:
var = variable to examine. in
flag = output format flag (def=0). in
KEYWORD PARAMETERS:
Keywords:
NUMERIC=num returns a code indicating numeric type:
0=non-numeric, 1=integer, 2=float, 3=complex.
INTEGER_BITS=bits returns number of bits if integer:
0=Not Integer, 8=Byte, 16=Int, 32=Long, 64=Long 64.
/DESCRIPTOR returns a descriptor for the given variable.
If the variable is a scalar the value is returned as
a string. If it is an array a description is return
just like the HELP command gives. Ex:
datatype(fltarr(2,3,5),/desc) gives
FLTARR(2,3,5) (flag always defaults to 3 for /DESC).
OUTPUTS:
typ = datatype string or number. out
flag=0 flag=1 flag=2 flag=3
UND Undefined 0 UND
BYT Byte 1 BYT
INT Integer 2 INT
LON Long 3 LON
FLO Float 4 FLT
DOU Double 5 DBL
COM Complex 6 COMPLEX
STR String 7 STR
STC Structure 8 STC
DCO DComplex 9 DCOMPLEX
PTR Pointer 10 PTR
OBJ Object 11 OBJ
UIN U_Integer 12 UINT
ULO U_Long 13 ULON
LLO Long_64 14 LON64
ULL U_Long_64 15 ULON64
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Written by R. Sterner, 24 Oct, 1985.
RES 29 June, 1988 --- added spelled out TYPE.
R. Sterner, 13 Dec 1990 --- Added strings and structures.
R. Sterner, 19 Jun, 1991 --- Added format 3.
R. Sterner, 18 Mar, 1993 --- Added /DESCRIPTOR.
R. Sterner, 1995 Jul 24 --- Added DCOMPLEX for data type 9.
R. Sterner, 1999 Jun 4 --- Added types 10 on, also numeric and bits.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\datatype.pro)
NAME:
DATA_BLOCK
PURPOSE:
Read the block of data following data_block call.
CATEGORY:
CALLING SEQUENCE:
data_block, out
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/CHECK means just list data block lines without
interpreting them.
ERROR=err Error flag: 0=ok, 1=error.
OUTPUTS:
out = returned array of data. out
COMMON BLOCKS:
NOTES:
Notes: Block of data must directly follow call to data_block.
Examples:
data_block, x
; 11,23,26.5, 34.7 42 EOD
data_block, t
; 1, 2, 3 ; Line 1.
; 11,22,33 ; Line 2.
; eod
<> Values may be separated by commas, spaces, and/or tabs.
<> The string EOD indicates the End Of Data and may be at
the end of a line or on a separate line (but only once).
<> Multiple data lines are allowed.
<> Data always comes back as a floating 1-d array.
<> Data lines must be commented out so IDL will ignore them.
<> Anything following a second comment char is ignored.
MODIFICATION HISTORY:
R. Sterner, 1995 May 23
R. Sterner, 2000 Aug 01 --- Fixed chnage in returned calling line #.
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\data_block.pro)
NAME: data_separator PURPOSE: This function searches possible separators between data entries in a string. CATEGORY: PROG_TOOLS/STRINGS CALLING SEQUENCE: Result=DATA_SEPARATOR(string) INPUTS: string: a string containing data seperated by ';' ',' tab or space OUTPUTS: This function returns the separator. If different separators or no separator is present, the string '0' is returned EXAMPLE: string = '12345, 234, 123' r=data_separator(string) print, r the output should be: , MODIFICATION HISTORY: Written by: Theo Brauers, 1997-Sep-19
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\data_separator.pro)
NAME:
data_subset
PURPOSE:
This function makes a subset of data from the structure INHALT
depending on a time range
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
Result=data_subset(structure,time_range)
INPUTS:
structure: The structure INHALT
time_range: An Array of start and end time
OUTPUTS:
The Result is a new Structure type INHALT whith the subset of called
time_range
EXAMPLE:
Result=data_subset(INHALT,time_range)
result=data_subset(inhalt,[dtime2js('1997-03-01 00:00:00 000'),$"
dtime2js('1997-03-05 00:00:00 000')])"
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), Date. August 14 1997
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\data_subset.pro)
NAME:
DATE2DN
PURPOSE:
Find day of year number from date.
CATEGORY:
CALLING SEQUENCE:
dn = date2dn(date)
INPUTS:
date = date string (like 6 Jul, 1995). in
KEYWORD PARAMETERS:
OUTPUTS:
dn = day number in year (like 187). out
COMMON BLOCKS:
NOTES:
Notes: The format of the date is flexible except that the
month must be month name.
Dashes, commas, periods, or slashes are allowed.
Some examples: 23 sep, 1985 sep 23 1985 1985 Sep 23
23/SEP/85 23-SEP-1985 85-SEP-23 23 September, 1985.
Doesn't check if month day is valid. Doesn't
change year number (like 86 does not change to 1986).
Dates may have only 2 numeric values, year and day. If
both year & day values are < 31 then day is assumed first.
systime() can be handled: dn=date2dn(systime()).
Day number is returned as a string.
For invalid dates dn is set to a null string.
Times are allowed.
MODIFICATION HISTORY:
R. Sterner, 1995 Jul 6
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2dn.pro)
NAME:
DATE2DOY
PURPOSE:
Date to Day of Year conversion.
CATEGORY:
CALLING SEQUENCE:
date2doy
INPUTS:
KEYWORD PARAMETERS:
Keywords:
FIRST=date1 Starting date for list of dates.
LAST=date2 Ending date for list of dates.
Date must be entered using month name, 3 letters
or more. Year, month, and day may be any order
but must be separated by spaces, commas, tabs,slashes,
or dashes (like 1998-Nov-25, NOT 1998nov25).
FILE=file Optional output file (else screen).
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1998 Nov 25
Copyright (C) 1998, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2doy.pro)
NAME:
DATE2JD
PURPOSE:
Convert a date string to Julian Day number.
CATEGORY:
CALLING SEQUENCE:
jd = date2jd(date)
INPUTS:
date = date string. in
KEYWORD PARAMETERS:
OUTPUTS:
jd = Returned Julian Day number. out
COMMON BLOCKS:
NOTES:
Note: date must contain month as a name of 3 or more leeters.
MODIFICATION HISTORY:
R. Sterner, 1996 Sep 15
R. Sterner, 1999 Aug 4 --- Improved 2 digit year case.
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2jd.pro)
NAME:
DATE2YMD
PURPOSE:
Date text string to the numbers year, month, day.
CATEGORY:
CALLING SEQUENCE:
date2ymd,date,y,m,d
INPUTS:
date = date string. in
KEYWORD PARAMETERS:
OUTPUTS:
y = year number. out
m = month number. out
d = day number. out
COMMON BLOCKS:
NOTES:
Notes: The format of the date is flexible except that the
month must be month name.
Dashes, commas, periods, or slashes are allowed.
Some examples: 23 sep, 1985 sep 23 1985 1985 Sep 23
23/SEP/85 23-SEP-1985 85-SEP-23 23 September, 1985.
Doesn't check if month day is valid. Doesn't
change year number (like 86 does not change to 1986).
Dates may have only 2 numeric values, year and day. If
both year & day values are < 31 then day is assumed first.
systime() can be handled: date2ymd,systime(),y,m,d
For invalid dates y, m and d are all set to -1.
MODIFICATION HISTORY:
Written by R. Sterner, 29 Oct, 1985.
Johns Hopkins University Applied Physics Laboratory.
25-Nov-1986 --- changed to REPCHR.
RES 18 Sep, 1989 --- converted to SUN.
R. Sterner, 1994 Mar 29 --- Modified to handle arrays.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\date2ymd.pro)
purpose: return date string given year and day of year
useage: result=date_string(year,day)
EXAMPLE: print,date_string(1991,283)
October 10, 1991
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\date_string.pro)
ROUTINE: daverage
USEAGE: daverage,lat,sza,yy
PURPOSE:
finds the daylight hour average of yy at each latitude
point. Average values are for spring or fall equinox
INPUT:
lat array of latitude points
sza solar zenith angle array
yy function of solar zenith angle
OUTPUT:
result average of yy over 12 hours (daylight)
EXAMPLE:
lat=indgen(10)*10
sza=acos((indgen(11))*.1)/!dtor
yy=90-sza
!p.multi=[0,1,2]
plot,sza,yy
plot,lat,daverage(lat,sza,yy)
procedure: At the spring or fall equinox the solar zenith angle at
a given latitude is given by,
cos(sza)=cos(lat)*cos(phi)
where phi is the phase angle of the earth's rotation
[= 2 pi*(time-12)/24)]
thus for each value of lat we have
yave=integral(phi,yv)/!pi
where,
yv=interpol(yy,mu,cos(lat*!dtor)*cos(phi*!dtor))
mu=cos(sza*!dtor)
AUTHOR: Paul Ricchiazzi 24 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\daverage.pro)
ROUTINE: dayave
PURPOSE: convert quantities which depend on sza to daily averages for
given values of day_of_year and latitude
USEAGE: result=dayave(doy,lat,sza,xx)
INPUT:
doy the day of year (vector)
lat latitude (vector)
sza a vector of solar zenith angles (degrees) monitonic increasing
xx a vector of a quantity which varies with SZA. If
max(sza) lt 90 then it is assumed that xx=0 when
(cos(sza) le 0). If this is not the case, then data
values for the full SZA angle range [-90,90] must be
supplied.
KEYWORD INPUT
dt averaging interval in hours (default=0.25 hours)
zenith zenith angles at each time, doy and lat (24/dt,nday,nlat)
(returned by first call of DAYAVE, see below)
if zero or absent, DAYAVE recomputes the zenith angle at
each point in the (DOY # LAT) input grid. This can be
fairly time consuming when there are lots of grid points.
By supplying a zero filled named variable to DAYAVE you
can retrieve the ZENITH grid for the next call to DAYAVE.
night if set, the interpolated value of xx is not set to zero
when sza is greater than 90. This should be used for
physical quantities which maintain non-zero values even
after sunset
OUTPUT:
result the integral of xx(t) dt for the given days and latitudes
EXAMPLE:
!p.multi=[0,1,2]
doy=findgen(365/30+1)*30
lat=findgen(90/10+1)*10
sza=findgen(90/10)*10
xx=cos(sza*!dtor)
zenith=0. ; zero filled named variable to
; retrieve zenith angle grid
yy=dayave(doy,lat,sza,xx,zenith=zenith)
tvim,yy,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
title='daily integral of sup(cos(sza),0)',/scale,/interp
xx2=xx^2
yy2=dayave(doy,lat,sza,xx2,zenith=zenith)
tvim,yy2,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
title='daily average of sup(cos(sza)!a2!n,0)',/scale,/interp
author: Paul Ricchiazzi aug94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dayave.pro)
NAME:
DAYGLOBE
PURPOSE:
Show the area of daylight/night on a globe.
CATEGORY:
CALLING SEQUENCE:
dayglobe, lat0, lng0, ang0
INPUTS:
lat0 = Latitude at center of globe. in
lng0 = Longitude at center of globe. in
ang0 = Rotation angle of image (deg CCW). in
KEYWORD PARAMETERS:
Keywords:
TIME=time Time string (def=current).
ZONE=hrs Hours ahead of GMT (def=0). Ex: zone=-4 for EDT.
/DEEPER means use deeper colors.
/QUANTIZED means 10 degree banded day colors.
/BLACK means use black background (else white).
/COUNTRIES means plot countries.
POINT='lng lat' Point to mark.
COLOR=clr Color of point as R G B like '0 255 0').
/GRID display a grid.
CGRID=gclr Color for Grid as R G B like '0 255 0').
CHARSIZE=csz Relative character size (def=1).
/STEREO means use Stereographic projection instead of
Orthographic.
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1999 Oct 14
R. Sterner, 2000 Sep 19 --- Added quantized day colors.
Copyright (C) 1999, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dayglobe.pro)
NAME:
day_average
PURPOSE:
This function calculates a small statistical survey for each day of a given data set of a given array
CATEGORY:
MATH
CALLING SEQUENCE:
Result = DAY_AVERAGE(time, array)
INPUTS:
time: julian seconds
array: data field
OPTIONAL INPUTS:
Keyword PARAMETERS:
MISSING: missing value to be ignored
FORMAT: format for numbers
OUTPUTS:
String array containing the statistics
EXAMPLE:
printtab, day_average(DINDGEN(144)*3600., DINDGEN(144))
REVISION HISTORY:
Written Theo Brauers, Apr 1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\day_average.pro)
NAME:
dbd_dirtree
PURPOSE:
this procedure write a html directory structure and creates the depending dir2html.html files.
CATEGORY:
DATAFILES/DBD
CALLING SEQUENCE:
dbd_dirtree,path,_extra=e
INPUTS:
path: the path to make the html tree
KEYWORD PARAMETERS:
_extra: to submit keywords to get_dir_tree or/and dir2htmlfile
PROCEDURE:
The tree html information file is stored one path segment before the submitted path.
At the moment it is not possible to create a tree of the root path.
EXAMPLE:
dbd_dirtree,'C:\temp',level=5
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 2000-May-25
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dbd_dirtree.pro)
ROUTINE dcolors
USEAGE dcolors
dcolors,r=r,g=g,b=b,pickc=pickc,squeeze=squeeze,view=view
INPUT: none
Keyword input:
pickc if set, call pickc to adjust discreet colors
squeeze if set, original color table is resampled to fit
in remaining color table index space.
view if set, draw palette of discreet colors to separate window
r,g,b red, green and blue values of discreet color table.
default colors:
r = [0, 255, 0, 150, 255, 194, 125, 0, 255, 19, 0]
g = [0, 0, 255, 150, 248, 196, 255, 175, 10, 215, 0]
b = [0, 0, 0, 255, 6, 196, 185, 0, 246, 224, 255]
OUTPUT: none
PURPOSE: loads custom colors in lower part of current color
scale. If SQUEEZE is set pre-existing color scale
is squeezed to fit between color index n_elements(r)
and !d.n_colors.
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dcolors.pro)
NAME:
DDEABM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Integrate Ordinary Differential Equation with Adams-Bashford-Moulton
MAJOR TOPICS:
Numerical Analysis.
CALLING SEQUENCE:
DDEABM, FUNCT, T0, F0, TOUT, [ PRIVATE, FUNCTARGS=, STATE= , ]
[ /INIT, /INTERMEDIATE, TSTOP=, EPSREL=, EPSABS=, ]
[ TGRID=, YGRID=, YPGRID=, NGRID=, NFEV=, ]
[ STATUS=, ERRMSG= ]
DESCRIPTION:
DDEABM performs integration of a system of one or more ordinary
differential equations using a Predictor-Corrector technique. An
adaptive Adams-Bashford-Moulton method of variable order between
one and twelve, adaptive stepsize, and error control, is used to
integrate equations of the form:
DF_DT = FUNCT(T, F)
T is the independent variable, F is the (possibly vector) function
value at T, and DF_DT is the derivative of F with respect to T,
evaluated at T. FUNCT is a user function which returns the
derivative of one or more equations.
DDEABM is based on the public domain procedure DDEABM.F written by
L. F. Shampine and M. K. Gordon, and available in the DEPAC package
of solvers within SLATEC library.
DDEABM is used primarily to solve non-stiff and mildly stiff
ordinary differential equations, where evaluation of the user
function is expensive, or high precision is demanded (close to the
machine precision). A Runge-Kutta technique may be more
appropriate if lower precision is acceptable. For stiff problems
neither Adams-Bashford-Moulton nor Runge-Kutta techniques are
appropriate. DDEABM has code which detects the stiffness of the
problem and reports it.
The user can operate DDEABM in three different modes:
* the user requests one output at a time (the default), and
maintains the integrator state using the STATE keyword;
* the user requests a grid of times (by passing an array to
TOUT), and optionally maintains the integrator state for
subsequent integrations using the STATE keyword;
* the user requests output at the natural adaptive stepsizes
using the /INTERMEDIATE keyword.
When the user requests explicit output points using TOUT, it is
likely that the output will be interpolated between two natural
stepsize points.
If the user requests a grid of outputs, and the integration fails
before reaching the requested endpoint, then control returns
immediately to the user with the appropriate STATUS code.
The initial conditions are given by F0, when T = T0. The number of
equations is determined by the number of elements in F0.
Integration stops when the independent variable T reaches the final
value of TOUT. If the user wants to continue the integration, it
can be restarted with a new call to DDEABM, and a new value of
TOUT.
USER FUNCTION
The user function FUNCT must be of the following form:
FUNCTION FUNCT, T, F, PRIVATE, ...
; ... compute derivatives ...
RETURN, DF_DT
END
The function must accept at least two, but optionally three,
parameters. The first, 'T', is the scalar independent variable
where the derivatives are to be evaluated. The second, 'F', is the
vector of function values. The function must return an array of
same size as 'F'. The third positional parameter, 'PRIVATE', is a
purely optional PRIVATE parameter. FUNCT may accept more
positional parameters, but DDEABM will not use them. Any number of
keyword parameters can be passed using the FUNCTARGS keyword.
The user function FUNCT must not modify either the independent
variable 'T' or the function values 'F'.
RESTARTING THE INTEGRATOR
When restarting the integrator, the STATE keyword can be used to
save some computation time. Upon return from DDEABM the STATE
keyword will contain a structure which describes the state of the
integrator at the output point. The user need merely pass this
variable back into the next call to continue integration. The
value of T, and the function value F, must not be adjusted between
calls to DDEABM.
If T or F0 are to be adjusted, then the integrator must be
restarted afresh *without* the previous state. This can be
achieved either by reseting STATE to undefined, or by setting the
/INIT keyword to DDEABM.
ERROR CONTROL
Local error control is governed by two keywords, EPSABS and EPSREL.
The former governs the absolute error, while the latter governs the
relative or fractional error. The error test at each iteration is:
ABS(ERROR) LE EPSREL*ABS(F) + EPSABS
A scalar value indicates the same constraint should be applied to
every equation; a vector array indicates constraints should be
applied individually to each component.
Setting EPSABS=0.D0 results in a pure relative error test on that
component. Setting EPSREL=0. results in a pure absolute error test
on that component. A mixed test with non-zero EPSREL and EPSABS
corresponds roughly to a relative error test when the solution
component is much bigger than EPSABS and to an absolute error test
when the solution component is smaller than the threshold EPSABS.
Proper selection of the absolute error control parameters EPSABS
requires you to have some idea of the scale of the solution
components. To acquire this information may mean that you will
have to solve the problem more than once. In the absence of scale
information, you should ask for some relative accuracy in all the
components (by setting EPSREL values non-zero) and perhaps impose
extremely small absolute error tolerances to protect against the
danger of a solution component becoming zero.
The code will not attempt to compute a solution at an accuracy
unreasonable for the machine being used. It will advise you if you
ask for too much accuracy and inform you as to the maximum accuracy
it believes possible.
HARD LIMIT ON T
If for some reason there is a hard limit on the independent
variable T, then the user should specify TSTOP. For efficiency
DDEABM may try to integrate *beyond* the requested point of
termination, TOUT, and then interpolate backwards to obtain the
function value at the requested point. If this is not possible
because the function because the equation changes, or if there is a
discontinuity, then users should specify a value for TSTOP; the
integrator will not go past this point.
INPUTS:
FUNCT - by default, a scalar string containing the name of an IDL
function to be integrated. See above for the formal
definition of FUNCT. (No default).
T0 - scalar number, upon input the starting value of the
independent variable T. Upon output, the final value of T.
Y - vector. Upon input the starting values of the function for T =
T0. Upon output, the final (vector) value of the function.
TOUT - must be at least a scalar, but optionally a vector,
specifies the desired points of output.
If TOUT is a scalar and INTERMEDIATE is not set, then DDEABM
integrates up to TOUT. A scalar value of the function at
TOUT is returned in F.
If TOUT is a scalar and /INTERMEDIATE is set, then DDEABM
computes a grid of function values at the optimal step
points of the solution. The grid of values is returned in
TGRID, YGRID, and YPGRID. The final function value,
evaluated at the last point in TOUT, is returned in F.
If TOUT is a vector, then DDEABM computes a grid of function
values at the requested points. The grid of values is
returned in TGRID, YGRID and YPGRID. The final function
value, evaluated at the last point in TOUT, is returned in
F.
It is possible for TOUT to be less than T0, i.e., to
integrate backwards.
PRIVATE - any optional variable to be passed on to the function to
be integrated. For functions, PRIVATE is passed as the
second positional parameter. DDEABM does not examine or
alter PRIVATE.
KEYWORD PARAMETERS:
EPSABS - a scalar number, the absolute error tolerance requested
in the integral computation. If less than or equal to
zero, then the value is ignored.
Default: 0
EPSREL - a scalar number, the relative (i.e., fractional) error
tolerance in the integral computation. If less than or
equal to zero, then the value is ignored.
Default: 1e-4 for float, 1d-6 for double
ERRMSG - upon return, a descriptive error message.
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by FUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks. By default, no extra parameters
are passed to the user-supplied function.
INIT - if set, indicates that the integrator is to be restarted
afresh.
INTERMEDIATE - if set, indicates that the integrator is to compute
at the natural step points.
NFEV - upon output, the scalar number of function evaluations.
NGRID - if /INTERMEDIATE is set, the number of points to compute
before returning.
Default: 1
STATE - upon input and return, the integrator state. Users should
not modify this structure. If the integrator is to be
restarted afresh, then the /INIT keyword should be set, in
order to clear out the old state information.
STATUS - upon output, the integer status of the integration.
1 - A step was successfully taken in the
intermediate-output mode. The code has not yet
reached TOUT.
2 - The integration to TOUT was successfully completed
(T=TOUT) by stepping exactly to TOUT.
3 - The integration to TOUT was successfully completed
(T=TOUT) by stepping past TOUT. Y(*) is obtained by
interpolation.
*** Task Interrupted ***
Reported by negative values of STATUS
-1 - A large amount of work has been expended. (500 steps
attempted)
-2 - The error tolerances are too stringent.
-3 - The local error test cannot be satisfied because you
specified a zero component in EPSABS and the
corresponding computed solution component is zero.
Thus, a pure relative error test is impossible for
this component.
-4 - The problem appears to be stiff.
*** Task Terminated ***
Reported by the value of STATUS=-33
-33 - The code has encountered trouble from which it
cannot recover. A error message is printed
explaining the trouble and control is returned to
the calling program. For example, this occurs when
invalid input is detected.
TGRID - upon output, the grid of values of T for which the
integration is provided.
TSTOP - a scalar, specifies a hard limit for T, beyond which the
integration must not proceed.
Default: none, i.e., integration is allowed to
"overshoot"
YGRID - upon output, the grid of function values for which the
integration is provided.
YPGRID - upon ouptut, the grid of function derivative values at
the points where the integration is provided.
EXAMPLES:
REFERENCES:
SAND79-2374 , DEPAC - Design of a User Oriented Package of ODE
Solvers.
"Solving Ordinary Differential Equations with ODE, STEP, and INTRP",
by L. F. Shampine and M. K. Gordon, SLA-73-1060.
SLATEC Common Mathematical Library, Version 4.1, July 1993
a comprehensive software library containing over
1400 general purpose mathematical and statistical routines
written in Fortran 77. (http://www.netlib.org/slatec/)
MODIFICATION HISTORY:
Fix bug in TSTOP keyword, 09 May 2002, CM
$Id: ddeabm.pro,v 1.13 2002/05/09 23:04:47 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\ddeabm.pro)
NAME:
debug
PURPOSE:
debugging of IDL routines
CATEGORY:
PROG_TOOLS
CALLING SEQUENCE:
DEBUG, version_string, file=filename
INPUTS:
version_string: string containing info
about the version an author of a routine
OPTIONAL INPUTS:
filename: output file for debug info
(only on the first call of debug during an IDL session)
OUTPUTS:
SIDE EFFECTS:
if called first time it creates the sysvar !debug with 2 tags:
!debug.flag and !debug.file
on next calls it controlls the output of the version
string to screen and/or file:
!debug.flag = 00000(0x00) : no output
= 00001(0x01) : screen
= 00010(0x02) : + systime
= 00100(0x04) : + calling routine
= 01000(0x08) : + file
any combination possible
EXAMPLE:
debug, file='test.txt'
!debug.flag=4
........
debug, '1.11 T.B. 1997-JAN-1'
REVISION HISTORY:
Written Franz Rohrer, June 1997
Corrected
Revised Theo Brauers, Sep 1997
Theo Brauers, Oct 1997
!debug is struct
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\debug.pro)
NAME:
decompose_structure
PURPOSE:
This function decomposes a structure into its single elements.
CATEGORY:
PROG_TOOLS
CALLING SEQUENCE:
result = decompose_structure(struc)
INPUTS:
struc: Any structure
OPTIONAL INPUTS:
pointer: This argument is for internal use only.
OUTPUTS:
This function returns a decomposed structure with the following tags:
NUM LONG --> running number
TN STRING --> tag name
VAL POINTER --> pointer to tag value
ROOT STRING --> root of tag
EXAMPLE:
s = {a: 0, b: {b1: FINDGEN(10), b2: 'LOP'}}
p = decompose_structure(s)
HELP, p
P STRUCT = -> Array[4]
HELP, p, /STR
** Structure <1350828>, 6 tags, length=32, refs=1:
LEV LONG 0 --> level of tag
TN STRING 'A' --> tag name
VAL POINTER --> pointer to tag value
ROOT STRING '' --> root of tag
PRINT, p.lev --> 0 0 1 1
PRINT, p.tn --> A B B1 B2
HELP, *p[0].val --> INT = 0
HELP, *p[1].val --> STRUCT = -> Array[1]
HELP, *p[2].val --> FLOAT = Array[10]
HELP, *p[3].val --> STRING = 'LOP'
MODIFICATION HISTORY:
Written by: Frank Holland, 09.12.1999
04.01.2000: Header was edited
05.01.2000: Removed tags NUM and LINK
12.01.2000: A named structure is returned
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\decompose_structure.pro)
NAME: DEFAULT VERSION: 4.0 PURPOSE: Provides an automatic default value for nondefined parameters. CATEGORY: Programming. CALLING SEQUENCE: Result = DEFAULT( X, Y [, keywords]) INPUTS: X, Y Arbitrary, at least one needs to be defined. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /STRICT Switch. If set, X is considered defined only if it is of the same type as Y. /DTYPE Switch. If set, the result will be typecast into the type of Y. Explicit settings for LOW and/or HIGH (see below) override DTYPE. LOW Numeric value representing a valid numeric type. If given, the result is of type >= LOW. HIGH Numeric value representing a valid numeric type. If given, the result is of type <= HIGH. OUTPUTS: X if it is defined, otherwise Y. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: All type casting is bypassed if the result is not of numeric type. PROCEDURE: Uses the functions CAST, ISNUM and TYPE from MIDL. MODIFICATION HISTORY: Created 15-JUL-1991 by Mati Meron. Modified 15-NOV-1993 by Mati Meron. The keyword TYPE has been replaced by STRICT. Added keywords DTYPE, LOW and HIGH. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\default.pro)
NAME:
default_cache_path
PURPOSE:
The result of this function is the platform independent path for the cache files
CATEGORY:
PROG_TOOLS
CALLING SEQUENCE:
result=default_cache_path([/alternative_path])
KEYWORD PARAMETERS:
alternative_path: to use the alternative cache path. It is defined as if is_write_access to /private/tmp or $HOME for WS or TEMP for PC
OUTPUTS
result: a string with the pathname
MODIFICATION HISTORY:
R. Bauer, 1998-Jun-09
1998-Jul-02 /scratch/cache now idl_source/idl_cache
2000-Apr-06 environment variables are handled as strupcase and strlowcase
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\default_cache_path.pro)
NAME:
DEFAULT_RANGE (function)
PURPOSE:
Make sure a RANGE argument or keyword is a valid
vector with at least two elements. Can also be used
to limit RANGE to two elements. The argument may be a string
containing one or more numeric values delimited by almost
any character combination (including '..' and '-'). A '-'
will be treated as seperator if it is preceeded by a
digit or not followed by a digit.
The resulting range will be sorted and spans the minimum and
maximum of the "data" given in the argument.
CATEGORY:
General programming
CALLING SEQUENCE:
range = DEFAULT_RANGE( ARG, DEFAULT [,/LIMIT2] )
INPUTS:
ARG -> The range argument or keyword as passed into
a procedure or function. This can be an undefined
variable or a variable with 1 or more elements.
If ARG contains 1 element, it will be repeated
to range from and to the same number.
DEFAULT -> A 2-element vector containing the default range
if ARG is undefined. This argument is mandatory
although it is not used if ARG contains at least
1 element.
KEYWORD PARAMETERS:
/LIMIT2 -> Limit the resulting RANGE vector to 2 elements.
Default is to return *at least* 2 elements.
RANGE -> Limit the RANGE vector to minimum and maximum value
given by this keyword.
/NOSORT -> Do not sort the output. This can be useful for
longitude vectors spanning the Pacific ;-)
OUTPUTS:
A two (or more) element vector that can be used in statements
like WHERE(x ge RANGE[0] AND x lt RANGE[1]).
SUBROUTINES:
none.
REQUIREMENTS:
none.
NOTES:
This function is meant for argument checking in procedures
or functions, hence it will generally not be called from the
command line.
EXAMPLE:
; Suppose a procedure has a keyword parameter named LATRANGE.
; Before we use LATRANGE in any form, we should test it:
LATRANGE = DEFAULT_RANGE(LATRANGE,[-90.,90.])
; This ensures that we have at least 2 elements in LATRANGE
; and it defaults LATRANGE to the whole globe if nothing was
; passed in the LATRANGE keyword.
MODIFICATION HISTORY:
mgs, 29 Sep 1998: VERSION 1.00
mgs, 17 Nov 1998: - added string handling
- added RANGE and NOSORT keywords
mgs, 23 Aug 2000: - changed copyright to open source
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\default_range.pro)
NAME: defp2d PURPOSE: This procedure is used to replace tag arrays in the defined plot structure CATEGORY: PLOT/PLOT2D CALLING SEQUENCE: defp2d,struct,name,attvalue INPUTS: struct: The structure which should be modified name: The tagname which should be replaced attvalue: The new values which should be added to the structure OUTPUTS: struct: The modified structure EXAMPLE: defp2d,plot,'levels',indgen(10) MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 5. Oct 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\defp2d.pro)
NAME:
DEFSUBCELL
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Returns a default subcell suitable for plotting in.
CALLING SEQUENCE:
sub = defsubcell( [default] )
DESCRIPTION:
DEFSUBCELL returns a "nice" subcell, useful for plotting in. It
gives 8% margins on the left and bottom, and 5% margins on the
right and top.
A set of user-defined default values can be passed in. Any that
are negative are replaced by this function's.
INPUTS:
DEFAULT - a "default" subcell. Any elements that are negative are
replaced by DEFSUBCELL's notion of the proper margins.
This feature is used, for example, by SUBCELLARRAY to
make subcells that have special margins on certain sides
and default ones on other sides.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
NONE
RETURNS:
The new subcell.
PROCEDURE:
EXAMPLE:
SEE ALSO:
DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
MODIFICATION HISTORY:
Written, CM, 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\defsubcell.pro)
NAME:
deftype
PURPOSE:
This function is able to translate a variable to the same type of another variable
CATEGORY:
MATH
CALLING SEQUENCE:
Result=deftype(data_with_type,value_without_type,[/value],[/type],[/char])
INPUTS:
data_with_type: A variable e.g. 10.5
value_without_type: A variable e.g. 4
KEYWORD PARAMETERS:
value: if the key value is used the result is
value_without_type with the same type as data_with_type
type: if the key type is used result is the integer code of type of data_with_type
char: same as type diffeternt is thats the result is the name of the type
OUTPUTS:
see KEYWORD PARAMETERS:
EXAMPLE:
Result=deftype(10.5,4)
Result is 4.00000
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), Jan. 2 1997
1997-Nov-01 nicer programcode
1998-Mar-04 limittest for integer included
1998-Mar-04 default is now new_value
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\deftype.pro)
NAME:
def_colorsystem
PURPOSE:
This procedure defines the colors for the colorsystem
CATEGORY:
PLOT/PLOT2D
CALLING SEQUENCE:
def_colorsystem,[colors=colors],[start_color=start_color],[max_colors=max_colors]
KEYWORD PARAMETERS:
colors=colors: the RGB color code which describe the colors
default comes from ct_fr2
start_color=start_color: the beginning index of the colorsystem
default is 20
max_colors=max_colors: the number of indices belonging to the colorsystem
default is def_n_colors()-1
EXAMPLE:
def_colorsystem,start=100,max_colors=50
erase
cbar
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1998-Jul-09
1999-Feb-05 because of idl5.2 interpretation of !d.n_colors this constant is replaced by def_n_colors()
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_colorsystem.pro)
NAME:
def_color_sysv
PURPOSE:
This procedure defines the new system variable with color indices
CATEGORY:
PLOT
CALLING SEQUENCE:
def_color_sysv
KEYWORD PARAMETERS:
NAME: Name of new system variable (STRING) - default: !F
OUTPUTS:
the new system variable which is of type structure with the tags
.black :0
.red :1
.blue :2
.geen :3
.pink :4
.violett :5
.orange :6
.dark_red :7
.cyan :8
.yellow :9
.blue_green :10
.white :11
EXAMPLE:
def_color_sysv
HELP, !F, /STR
** Structure <88963dcc>, 12 tags, length=24, refs=2:
BLACK INT 0
RED INT 1
BLUE INT 2
GREEN INT 3
PINK INT 4
VIOLETT INT 5
ORANGE INT 6
DARK_RED INT 7
CYAN INT 8
YELLOW INT 9
BLUE_GREEN INT 10
WHITE INT 11
SIDE EFFECTS:
A new system variable is defined
REVISION HISTORY:
Definition of colors written by Franz Rohrer
Wrapper written by Frank Holland, 28. Jan. 1998
History:
04.11.98: Changed color structure from anonymous into a named structure
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\def_color_sysv.pro)
NAME:
def_inhalt_def
PURPOSE:
This procedure write the definition procedure inhalt_def.pro for the structure inhalt
CATEGORY:
DATAFILES/NETCDF
CALLING SEQUENCE:
def_inhalt_def
OUTPUTS:
This procedure write the idl Source inhalt_def.pro
OPTIONAL OUTPUTS:
inhalt_def: could used for debugging
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_inhalt_def.pro)
NAME:
def_mplotstr
PURPOSE:
This function defines a structure with default settings for plot keywords
CATEGORY:
PLOT/MPLOT
CALLING SEQUENCE:
mplot_str = def_mplotstr()
OUTPUTS:
This function returns a structure with the tags
.screen
.ps
.printer
each of which is a structure with tags which define values for different plot keywords
EXAMPLE:
ms = def_mplotstr()
HELP, ms, /STR
** Structure <13554f8>, 3 tags, length=84, refs=1:
SCREEN STRUCT -> SCREEN Array[1]
PS STRUCT -> PS Array[1]
PRINTER STRUCT -> PRINTER Array[1]
REVISION HISTORY:
Written by Frank Holland, 05.11.1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\def_mplotstr.pro)
NAME:
def_ncdf_dimensions_for_parameters
PURPOSE:
write_ncdf
This procedure sets the diension ids for the parameters and the flags
CATEGORY:
DATAFILES/NETCDF
CALLING SEQUENCE:
def_ncdf_dimensions_for_parameters,dimensions
INPUTS:
file_id: the id of the netcdf File
dimensions: A Structure holding parameter and flag informations
n_parameters: n_elements of parameter tags
e.g.:
DIMENSIONS STRUCT
TIME: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [-1]
TYPE LONG 5
N2O: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [-1]
TYPE LONG 4
FLAG STRUCT
STDEV STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [-1]
TYPE LONG 5
TAG_NAME: STRING ['TIME', 'N2O']
SHORT_NAME: STRING ['time', 'N2O']
FLAG: STRUCT
N2O STRUCT
SHORT_NAME STRING 'N2O@STDEV'
TAG_NAME STRING 'STDEV'
OUTPUTS:
input structure is output structure
dimensions for flags: dimensions.(i).flag.(ii).d_ids is altered to dimensions.(i).d_ids
DIMENSIONS STRUCT
TIME: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [-1]
TYPE LONG 5
N2O: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [-1]
TYPE LONG 4
FLAG STRUCT
STDEV STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [-1]
TYPE LONG 5
TAG_NAME: STRING ['TIME', 'N2O']
SHORT_NAME: STRING ['time', 'N2O']
FLAG: STRUCT
N2O STRUCT
SHORT_NAME STRING 'N2O@STDEV'
TAG_NAME STRING 'STDEV'
EXAMPLE:
def_ncdf_dimensions_for_parameters,dimensions
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Mar-02
name wird spaeter geändert
2000-Feb-09 added MESSAGE,'Problem with dimensions of parameter: '+dimensions.short_name[i],/info
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_ncdf_dimensions_for_parameters.pro)
NAME:
def_ncdf_variable
PURPOSE:
This routine defines all netCDF parameters and flags described in the dimensions structure.
CATEGORY:
DATAFILES/NETCDF
CALLING SEQUENCE:
def_ncdf_variable,file_id,dimensions
INPUTS:
file_id: the ncdf_open file_id of a netCDF File
dimensions: a structure holding informations about type size and name of a parameter
e.g.:
DIMENSIONS STRUCT
TIME: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [0]
TYPE LONG 5
N2O: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [0]
TYPE LONG 4
FLAG STRUCT
STDEV STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG -1
D_IDS LONG [0]
TYPE LONG 5
TAG_NAME: STRING ['TIME', 'N2O']
SHORT_NAME: STRING ['time', 'N2O']
FLAG: STRUCT
N2O STRUCT
SHORT_NAME STRING 'N2O@STDEV'
TAG_NAME STRING 'STDEV'
OUTPUTS:
dimensions: a structure holding informations about type size and name of a parameter
the tag P_id is altered by the real parameter ID of the netCDF File
e.g.
DIMENSIONS STRUCT
TIME: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG 0
D_IDS LONG [0]
TYPE LONG 5
N2O: STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG 1
D_IDS LONG [0]
TYPE LONG 4
FLAG STRUCT
STDEV STRUCT
NAME STRING ['time']
SIZE LONG [100]
P_ID LONG 2
D_IDS LONG [0]
TYPE LONG 5
TAG_NAME: STRING ['TIME', 'N2O']
SHORT_NAME: STRING ['time', 'N2O']
FLAG: STRUCT
N2O STRUCT
SHORT_NAME STRING 'N2O@STDEV'
TAG_NAME STRING 'STDEV'
EXAMPLE:
| TIME | N2O | TAG_NAME | SHORT_NAME |
| str[1] | str[1] | TIME | time |
| N2O | N2O |
| TIME | ||||
| NAME | SIZE | P_ID | D_IDS | TYPE |
| time | 100 | -1 | 0 | 5 |
| N2O | ||||
| NAME | SIZE | P_ID | D_IDS | TYPE |
| time | 100 | -1 | 0 | 4 |
| TIME | N2O | TAG_NAME | SHORT_NAME |
| str[1] | str[1] | TIME | time |
| N2O | N2O |
| TIME | ||||
| NAME | SIZE | P_ID | D_IDS | TYPE |
| time | 100 | 0 | 0 | 5 |
| N2O | ||||
| NAME | SIZE | P_ID | D_IDS | TYPE |
| time | 100 | 1 | 0 | 4 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_ncdf_variable.pro)
NAME: def_n_colors PURPOSE: This function returns 256 if !d.n_colors is gt 256 else !d.n_colors CATEGORY: PLOT CALLING SEQUENCE: Result=def_n_colors() EXAMPLE: print,def_n_colors() 256 MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1999, Feb. 05
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_n_colors.pro)
NAME:
def_plotstr_sysv
PURPOSE:
This procedure defines the new system variable with default settings for plot keywords
CATEGORY:
PLOT/MPLOT
CALLING SEQUENCE:
def_plotstr_sysv
KEYWORD PARAMETERS:
NAME: Name of new system variable (STRING) - default: !FH_PLOTSTR
OUTPUTS:
a new system variable which is of type structure with the tags
.screen
.printer
each of which has subtags which define values for different plot keywords
EXAMPLE:
def_plotstr_sysv
HELP, !FH_PLOTSTR, /STR
** Structure <88963dcc>, 12 tags, length=24, refs=2:
SIDE EFFECTS:
A new system variable is defined
REVISION HISTORY:
Written by Frank Holland, 12.06.98
History:
04.11.98: Changed plot structure from anonymous into a named structure
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\def_plotstr_sysv.pro)
NAME:
def_plxy
PURPOSE:
This procedure defines the internal communication structure for plotxy-like procedures
CATEGORY:
PLOT/PLOTXY
CALLING SEQUENCE:
def_plxy,pl_xy
OUTPUTS:
pl_xy. : The predefined structure whith the following tags:
.i_xn: 0
.i_yn: 0
.n_xn: 1
.n_yn: 1
.charsize: 0.
.title_charsize :0.
.c_charsize: 0.
.framethick: 0.
.thick: 0.
.factor: 0.
.xticklen: 0.
.yticklen: 0.
.zticklen: 0.
EXAMPLE:
def_plxy, pl_xy
MODIFICATION HISTORY:
Written by: Franz Rohrer September 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\def_plxy.pro)
NAME:
def_sizes
PURPOSE:
definition of charsize and thick for plotxy-type procedures
CATEGORY:
PLOT/PLOTXY
CALLING SEQUENCE:
def_sizes,plot,pl_xy
INPUTS:
plot : structure with plot-options (see pl_init.pro for details)
OUTPUTS:
pl_xy : structure with parameters for plotxy as defined by def_plxy
EXAMPLE:
def_sizes,plot,pl_xy
MODIFICATION HISTORY:
Written Franz Rohrer, September 1997
Corrected
9.10.1997 added that ticklength would not be reduced if it's set to make gridlines
29.10.1997 "IF strupcase(!version.os) EQ 'AIX' THEN corr = 0.75"
11.01.1998 plot.charsize_norm_factor zur Normierung der Textbreite eingeführt, wird in plotinit berechnet
03.06.00 : plot.spalten+plot.zeilen nach plot.columns+plot.rows umbenannt
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\def_sizes.pro)
NAME:
def_valid_for_param
PURPOSE:
This function returns the valid information arrays for the ICG data_structure
CATEGORY:
DATAFILES
CALLING SEQUENCE:
Result=def_valid_for_param(param,quality, [valid_min=valid_min], [valid_max=valid_max], [fill_value=fill_value_intern], [missing_value=missing_value_intern], [struct_name=struct_name])
INPUTS:
param: the data of a parameter
quality: the quality flag vector describing quality of param
KEYWORD PARAMETERS:
valid_min: if also valid_max is set the valid data range is from valid_min to valid_max
valid_max: if also valid_min is set the valid data range is from valid_min to valid_max
if no data fits in this range a message is given and valid from 0:*
fill_value: if set indicator value for setting fill valuess
missing_value: if set indicator value for setting missing values
struct_name: name of the resulting structure by count_name(struct_name)
PROCEDURE:
if valid eq -1 then plot_min and plot_max = !values.f_nan
EXAMPLE:
fill_value=-999.9
missing_value=-999.8
param=findgen(10)
param[1:2]=fill_value
param[6:9]=missing_value
result=def_valid_for_param(param,fill_value=fill_value, missing_value=missing_value)
help,result,/str
** Structure <1357cf8>, 5 tags, length=48, refs=1:
PLOT_MIN FLOAT 0.000000
PLOT_MAX FLOAT 5.00000
VALID LONG Array[4]
FILLED LONG Array[2]
MISSED LONG Array[4]
| PLOT_MIN | PLOT_MAX | VALID | FILLED | MISSED |
| 0.000000 | 5.00000 | 0 | 1 | 6 |
| 3 | 2 | 7 | ||
| 4 | 8 | |||
| 5 | 9 |
| PLOT_MIN | PLOT_MAX | VALID | FILLED | MISSED |
| 0.000000 | 5.00000 | 0 | 1 | 6 |
| 5 | 2 | 7 | ||
| 8 | ||||
| 9 |
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_valid_for_param.pro)
NAME:
def_valid_tagname
PURPOSE:
This function translates short_names to tag_names
CATEGORY:
DATAFILES
CALLING SEQUENCE:
Result=def_valid_tagname(short_name,[consideration=consideration])
INPUTS:
short_name: the short name of a parameter
KEYWORD PARAMETERS::
consideration: beware of duplicate definitions
EXAMPLE:
print,def_valid_tag_name('test 1')
TEST_1
print,def_valid_tagname('test 1',consideration='test_1')
TEST_1A
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Mar-02
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\def_valid_tagname.pro)
NAME: DEGLITCH VERSION: 4.0 PURPOSE: Replaces exceptional array elements by the average of their neighbors. CATEGORY: Array Function. CALLING SEQUENCE: Result = DEGLITCH( ARR, THRESH [, keywords]) INPUTS: ARR Array, numeric, otherwise arbitrary. THRESH Threshold value for element replacement. Must be > 1. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /DOWN Switch. If set the correction is downward, i.e. elements which are too big (in absolute value) are replaced. This is the default. /UP Switch. If set the correction is upward, i.e. elements which are too small (in absolute value) are replaced. COUNT Optional output, see below. OUTPUTS: Returns the corrected array, i.e. an array of the same format as ARR, in which all the exceptional element have been replaced by the average of their neighbors. OPTIONAL OUTPUT PARAMETERS: COUNT The name of the variable to receive the number of exceptional elements. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Compares the absolute values of the original array and the one obtained by neighborhood averaging. Locates exceptions and replaces them by neighborhood average. Uses FPU_FIX, NEIGHBORS and ONE_OF from MIDL. MODIFICATION HISTORY: Created 30-MARCH-1994 by Mati Meron. Modified 10-SEP-1998 by Mati Meron. Underflow filtering added. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\deglitch.pro)
FUNCTION degrade
PURPOSE: degrade image resolution by a factor of two
USEAGE: result=degrade(array)
INPUT:
array an image array of dimension NX x NY, where both nx
ny are divisible by 2. If nx or ny are not divisible by
2 a subimage is extracted that leaves off the last row
or column and is divisible by 2 in both directions.
KEYWORD INPUT:
min if set the returned value for each superpixel is the min
of each of the four subpixels
max if set the returned value for each superpixel is the max
of each of the four subpixels
output:
result image array of dimension NX/2 x NY/2 composed of 2 x 2
superpixel averages of u (except if MIN or MAX keyword is
set, see above)
AUTHOR: Paul Ricchiazzi 26 May 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\degrade.pro)
NAME:
DELCHR
PURPOSE:
Delete all occurrences of a character from a text string.
CATEGORY:
CALLING SEQUENCE:
new = delchr(old, char)
INPUTS:
old = original text string. in
char = character to delete. in
KEYWORD PARAMETERS:
OUTPUTS:
new = resulting string. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 5 Jul, 1988.
Johns Hopkins Applied Physics Lab.
RES 11 Sep, 1989 --- converted to SUN.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\delchr.pro)
NAME: delete_from_path PURPOSE: This function deletes entries from the !path setting of IDL CATEGORY: PROG_TOOLS CALLING SEQUENCE: DELETE_FROM_PATH, str INPUTS: Str: Input string, name of path entry to be deleted EXAMPLE: PRINT, !path DELETE_FORM_PATH, 'examples' PRINT, !path MODIFICATION HISTORY: Written by: Theo Brauers, 1999-JAN
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\delete_from_path.pro)
USERLEVEL:
TOPLEVEL
NAME:
delete_tag
PURPOSE:
This functions deletes a tag in a structure, even within substructures.
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
result = delete_tag(struct, tagname, [sub_structure = sub_structure])
INPUTS:
struct: the structure in which to delete the tag
tagname: the name of the tag to be deleted (scalar or array),
wildcards '*' are possible (see examples).
KEYWORD PARAMETERS:
sub_structure: to define a sub structure within struct where to delete the tag
/ALL: If set all tags which agree to tagname will be deleted starting from the
main level or the level 'sub_structure' downwards.
OUTPUTS:
This function returns a structure with some tags deleted.
EXAMPLE:
d = {A: 1, B: {B1: 0, B2: 1}, C: {B1: 0, B2: 1}}
result = delete_tag(d, 'B')
help, result, /str
** Structure <1342678>, 2 tags, length=8, refs=1:
A INT 1
C STRUCT -> Array[1]
result = delete_tag(d, ['B*'], SUB = 'C')
help, result, /str
** Structure <13694a8>, 2 tags, length=6, refs=1:
A INT 1
B STRUCT -> Array[1]
result = delete_tag(d, '*B1', SUB = ['B', 'C'])
help, result.b, /str
** Structure <1331be8>, 1 tags, length=2, refs=1:
B2 INT 1
result = delete_tag(d, ['B1', 'B2'], /ALL)
help, result, /str
** Structure <170fac8>, 1 tags, length=2, refs=1:
A INT 1
help,(delete_tag(d,'b1',sub_structure='B')).b,/str
B2 INT 1
help,(delete_tag(d,'b1',sub_structure='B')).c,/str
** Structure <1333618>, 2 tags, length=4, refs=1:
B1 INT 0
B2 INT 1
help,(delete_tag(d,'*',sub_structure='B')),/str
** Structure <133b2d8>, 2 tags, length=6, refs=1:
A INT 1
C STRUCT -> Array[1]
help,(delete_tag(d,'*',sub_structure='B',/sort)),/str
** Structure , 2 tags, length=6, refs=1:
A INT 1
C STRUCT -> Array[1]
help,(delete_tag(d,sub_structure=['B','A'])),/str
** Structure <132fe78>, 2 tags, length=6, refs=1:
A INT 1
C STRUCT -> Array[1]
help,(delete_tag(d,sub_structure=['B','C'])),/str
** Structure <1333288>, 1 tags, length=2, refs=1:
A INT 1
help,(delete_tag(d,['B1','B2'],sub_structure=['B','C'])),/str
** Structure <46a9498>, 1 tags, length=2, refs=1:
A INT 1
d = {ABRA: {B1: 0, B2: 1}, ABRA2B: {B1: 0, B2: 1}, ABRA3B: {B1: 0, B2: 1}}
result=delete_tag(d,'abra')
help,result,/str
** Structure <1365a48>, 2 tags, length=8, refs=1:
ABRA2B STRUCT -> Array[1]
ABRA3B STRUCT -> Array[1]
result=delete_tag(d,'abra*')
help,result,/str
RESULT INT = -1
result=delete_tag(d,'abra?B')
help,result,/str
** Structure <1364358>, 1 tags, length=4, refs=1:
ABRA STRUCT -> Array[1]
d = {ABRA: {B1: 0, B2: {A:1}}, ABRA2B: {B1: 0, B2: {A:1}}, ABRA3B: {B1: 0, B2: {A:1}}}
result=delete_tag(d,'A',sub_structure='abra.b2')
help,result.abra,/str
** Structure <1365c68>, 1 tags, length=2, refs=2:
B1 INT 0
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 2000-Jan-05
14.03.2000: Header edited
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\delete_tag.pro)
NAME:
delete_tag_fh
PURPOSE:
This function can be used to delete tags within a substructure of a given structure
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
result = delete_tag(struct, tag_name)
INPUTS:
struct: Input structure.
tag_name: Name of tag or array of tag names to be deleted from struct (STRING).
KEYWORD PARAMETERS:
SUB_STR = sub_str: Name of the substructure under which the tags are deletetd.
OUTPUTS:
This function returns a structure were the tags 'tag_name' have been removed.
EXAMPLE:
s0 = {H2O: {param: 4, units: 'mbar'}, O3: {param: 17, units: 'ppb'}}
s1 = delete_tag(s0, 'H2O')
HELP, s1, /STR
** Structure , 1 tags, length=12, refs=1:
O3 STRUCT -> Array[1]
HELP, s1.o3, /STR
** Structure , 2 tags, length=12, refs=2:
PARAM INT 17
UNITS STRING 'ppb'
s1 = delete_tag(s0, 'units')
HELP, s1, /STR
** Structure , 2 tags, length=4, refs=1:
H2O STRUCT -> Array[1]
O3 STRUCT -> Array[1]
HELP, s1.o3, /STR
** Structure , 1 tags, length=2, refs=2:
PARAM INT 17
s1 = delete_tag(s0, 'units', SUB_STR = 'O3')
HELP, s1.o3, /STR
** Structure , 1 tags, length=2, refs=2:
PARAM INT 17
HELP, s1.h2o, /STR
** Structure , 2 tags, length=12, refs=2:
PARAM INT 4
UNITS STRING 'mbar'
MODIFICATION HISTORY:
Written by: Frank Holland, 05.01.2000
13.03.2000: Header edited
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\delete_tag_fh.pro)
NAME:
dellog
PURPOSE:
dummy procedure for the one defined by VMS idl
CATEGORY:
CASE_TOOLS
CALLING SEQUENCE:
dellog,a
MODIFICATION HISTORY:
R.Bauer 1998-Jul-24
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dellog.pro)
NAME: del_file PURPOSE: This procedure deletes a file or files CATEGORY: PROG_TOOLS CALLING SEQUENCE: del_file,file INPUTS: file: the file(s) which should be deleted EXAMPLE: del_file,'test.dat' MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1998-Jun-07 1998-12-16 message added if file does not exist 1999-09-13 get_ownership added 2000-2-17 keyword verbose added T.B.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\del_file.pro)
NAME:
del_tag
PURPOSE:
This function deletes a tag from a given structure.
It also handels an array of tags.
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
x = del_tag(str, tag)
INPUTS:
str: variable name of structure
tag: name of tag or array of tag names to be deleted (STRING)
KEYWORD PARAMETERS:
RETURN_ON_LAST_TAG_DELETED: Defines a variable which will be returned if the only tag
in str is deleted.
NAME: New name for a named structure (must not exist already)
EXAMPLE:
as = {Bsp1, a:0, b:'asd'}
bs = del_tag(as, 'b', NAME = 'Bsp3')
HELP, bs, /STR :
** Structure BSP3, 1 tags, length=2:
A INT 0
MODIFICATION HISTORY:
Written by: Frank Holland, 28. Jan. 98.
29.09.98: Debug statement deleted.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\del_tag.pro)
NAME:
del_tag2
PURPOSE:
This function deletes a tag from a given structure.
It also handels an array of tags and/or 1-dim array of structures.
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
x = del_tag2(str, tag)
INPUTS:
str: variable name of structure
tag: name of tag or array of tag names to be deleted (STRING)
KEYWORD PARAMETERS:
RETURN_ON_LAST_TAG_DELETED: Defines a variable which will be returned if the only tag
in str is deleted.
NAME: New name for a named structure (must not exist already)
OPTIONAL OUTPUTS:
status: Status information =0: every thing worked fine;
=1: something went wrong (see messages on screen)
EXAMPLE:
as = {Bsp1, a:0, b:'asd'}
bs = del_tag2(as, 'b', NAME = 'Bsp3')
HELP, bs, /STR :
** Structure BSP3, 1 tags, length=2:
A INT 0
MODIFICATION HISTORY:
Written by: Frank Holland, 11. Apr. 98.
This program is based on the procedure del_tag.pro but provides additional features
15.11.98: call to debug deleted
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\del_tag2.pro)
NAME:
demo_xyouts_auto
PURPOSE:
This routine shows the capabilities of xyouts_auto
CATEGORY:
EXAMPLES
CALLING SEQUENCE:
demo_xyouts_auto
MODIFICATION HISTORY:
Written by: Frank Holland, 29.10.1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\examples\demo_xyouts_auto.pro)
ROUTINE dens2d,x,y,g,nbins=nbins,xrange=xrange,yrange=yrange,$
title=title,xtitle=xtitle,ytitle=ytitle,psym=psym,$
grid=grid,tvim=tvim,scale=scale,contur=contur
PURPOSE Compute and/or display the density function of a 2-d scatter
of points with coordinate x and y
INPUTS:
x array of values
y array of values (same size as x)
OUTPUTS:
g 2-d histogram array of size nbins(0) x nbins(1)
OPTIONAL INPUTS (keyword parameters):
nbins 1 or 2 element vector, number of bins in x and y direction
default is (20,20)
xrange 2 element vector, binning range in x direction
yrange 2 element vector, binning range in y direction
charsize character size
title plot title
xtitle x axis label
ytitle y axis label
psym symbol used for scatter plot, if negative don't plot points
grid if set, show binning grid
contur if set, draw in density contours (default)
confill if set, use CONFILL is used to draw contours
tvim if set, use TVIM to display the point density function
if tvim is set to 1 image is smoothed
if tvim is set to 2 image is not smoothed
scale if set, draw in a color scale
0=> no color scale
1=> regular color scale (default)
2=> stepped color scale
EXAMPLE
x=randomn(is,2000)
y=4*randomn(is,2000) + x^3
dens2d,x,y,g,/tvim,/grid
dens2d,x,y,/tvim,/contur
dens2d,x,y,psym=-1,/contur
AUTHOR: Paul Ricchiazzi, Earth Space Research Group, sep92
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dens2d.pro)
NAME:
dependences_of_family
PURPOSE:
This function returns a structure of keys depending on !version.os_family
CATEGORY:
PROG_TOOLS
CALLING SEQUENCE:
Result=dependences_of_family( )
OUTPUTS:
This function returns a structure:
slash: The platform depended slash or back slash
path_separator: The platform depended : od ;
two_path_backwards: The platform depended '../../' od ...
EXAMPLE:
result=dependences_of_family()
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1998-Jun-27
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dependences_of_family.pro)
NAME: DEPENDENCY VERSION: 4.2 PURPOSE: Locating routines dependent on a given routine. CATEGORY: Programming utility. CALLING SEQUENCE: Result = DEPENDENCY( RNAME [, keywords]) INPUTS: RNAME Character value resolving to a routine name (no extension). OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /GLOBAL Switch. If set, the search is global, default is search in current directory. DIRPATH Directory path, for internal use only (recursive calls). NFOUND Optional output, see below. OUTPUTS: Returns a list of addresses for all the routines which are calling RNAME. If none are found, returns null string. OPTIONAL OUTPUT PARAMETERS: NFOUND Returns the number of files satisfying the search criterion. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Straightforward. Calls itself recursively. Also calls DEFAULT, SDEP, STREQ, STRPARSE_MM and STRVALID_MM, from MIDL. MODIFICATION HISTORY: Created 10-AUG-2001 by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\dependency.pro)
NAME:
des_inh
PURPOSE:
The include of des_inh will transform the tagnames of the structure inhalt
to variables.
CATEGORY:
DATAFILES/NETCDF
CALLING SEQUENCE:
@des_inh
OUTPUTS:
all in Structure INHALT defined tagnames as variables
EXAMPLE:
ncdf_gr,file='test.nc',name='sin2',inhalr=inhalt
@des_inh
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1996
R.Bauer Feb., 26, 1997 areal in type umbenannt
R.Bauer March, 17, 1997 valid_last_index eingefuegt
R.Bauer March, 19, 1997 param_stdev, param_accuracy,param_detection_limit,param_high_err,param_low_err
R.Bauer / F.Rohrer June, 6, 1997 downgrade to idl 3.6.1
1998-Jun-30 strmid removed
R.Bauer 1998-11-16 alt_inhalt_def instead of inhalt_def
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\des_inh.pro)
NAME:
DETAB
PURPOSE:
Replace tab characters by spaces.
CATEGORY:
CALLING SEQUENCE:
out = detab(in)
INPUTS:
in = input text string. in
KEYWORD PARAMETERS:
Keywords:
TAB=tb number of spaces per tab (def=8).
OUTPUTS:
out = processed output text string. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1995 Nov 3
Copyright (C) 1995, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\detab.pro)
NAME: DIAGOARR VERSION 4.0 PURPOSE: Creates a diagonal square matrix with the elements of a given vector on the diagonal. CATEGORY: Array Manipulation. CALLING SEQUENCE: Result = DIAGOARR(VEC) INPUTS: VEC Vector. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: None. OUTPUTS: Return a square N*N (N is the vector's dimension) matrix, with the elements of VEC on the diagonal and zeroes elsewhere. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Straightforward. Calls TYPE from MIDL. MODIFICATION HISTORY: Created 20-MAY-1993 by Mati Meron. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\diagoarr.pro)
NAME: DIAGOVEC VERSION: 4.0 PURPOSE: Extracts the diagonal of a square matrix as a vector. CATEGORY: Array Manipulation. CALLING SEQUENCE: Result = DIAGOVEC(ARR) INPUTS: ARR Array, 2-dimensional, square (a scalar is considered a 1*1 matrix). OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: None. OUTPUTS: If ARR is a square matrix, returns the diagonal as a vector, else generates an error message. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. PROCEDURE: Straightforward. MODIFICATION HISTORY: Created 20-DEC-1991 by Mati Meron. Checked for operation under Windows, 25-JAN-2001, by Mati Meron. Modified 25-NOV-2001 by Mati Meron. Added scalar handling capability.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\diagovec.pro)
USERLEVEL: TOPLEVEL NAME: dialog_changedir PURPOSE: This function provides a widget directory change CATEGORY: PROG_TOOLS/FILES CALLING SEQUENCE: new = DIALOG_CHANGEDIR( [OLDDIR=old] [, /VERBOSE]) KEYWORD PARAMETERS: VERBOSE: print messages OLDDIR: if set to named variable the previous dir is returned OUTPUTS: This function returns the selected directory EXAMPLE: MODIFICATION HISTORY: Written by: Theo Brauers, 1999-FEB-25
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dialog_changedir.pro)
NAME:
Dialog_PSSetup
PURPOSE:
This function displays a widget to interactively choose the setting for the ps device.
(Wrapper around the ps_form routine by Craig B. Markwardt)
CATEGORY:
PLOT
CALLING SEQUENCE:
Result = Dialog_PSSetup(ps_config [,LOCALDEFAULT = local_config] [,CANCEL = canceled] [,/QUIET] )
OPTIONAL INPUTS:
ps_config: structure with a default configuration for the PS device.
For information about this structure run the routine and set
ps_config to a named variable.
KEYWORD PARAMETERS:
LOCALDEFAULT = local_config: structure with a 2nd default configuration ('local') for the PS device.
CANCEL = canceled : Set to 1 if dialog was closed with CANCEL button.
/QUIET: Don't show the widget; rather return the default ps configuration
PSFILE = psfile: Name of the ps file.
OUTPUTS:
ps_config: structure with the configuration of the PS device. This structure
can be passed into the DEVICE procedure via the _EXTRA keyword.
EXAMPLE:
create = Dialog_PSSetup(ps_config, CANCEL = canceled)
IF NOT canceled THEN HELP, ps_config, /STR
MODIFICATION HISTORY:
This routine is a wrapper around the ps_form routine by Craig B. Markwardt and David Fanning
Written by: Frank Holland, 13.11.98
17.11.98: QUIET keyword enabled (bug in PS_FORM was fixed by CM)
Keyword handling improved
17.02.99: Changed the header
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\dialog_pssetup.pro)
NAME: DIF VERSION: 4.1 PURPOSE: Calculates finite differences for 1D vectors. CATEGORY: Mathematical, general. CALLING SEQUENCE: Result = DIF( VEC [, ORD] [, keywords]) INPUTS: VEC 1-D numeric array (a scalar may be used and ti is treated as a vector with length of 1. OPTIONAL INPUT PARAMETERS: ORD The order of the difference. Default value is 1. KEYWORD PARAMETERS: /BACKWARD Switch. If set, backward difference is performed, i.e. Result[n] = VEC[n] - VEC[n-1]. This is also the default. /FORWARD Switch. If set, forward difference is performed, i.e. Result[n] = VEC[n+1] - VEC[n]. /CENTERED Switch. If set, centered difference is performed, i.e. Result[n] = (VEC[n+1] - VEC[n-1])/2. Note: Only one of BACKWARD, FORWARD and CENTERED may be set at any given call. /EDGE_EXTEND Switch. If set, the "beyond the edge" elements which are needed for the differences are set equal to the appropriate edge elements. The default operation is to set them to 0. /CLIP Switch. If set, the elements (within ORD from either edge) for which there is not enough information to determine the result, are set to 0. OUTPUTS: Returns the difference vector for VEC, of a type determined by the keywords. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: As mentioned above, Only one of BACKWARD/FORWARD/CENTERED may be used. PROCEDURE: Straightforward. Calls DEFAULT, ISNUM and ONE_OF from MIDL. MODIFICATION HISTORY: Created 15-APR-2001 by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\dif.pro)
ROUTINE: digitize
PURPOSE: digitize hardcopy graphical information.
USEAGE: digitize,x,y
INPUT: none
KEYWORD INPUT:
xr x axis range of hardcopy plot, prompted for if not supplied
yr y axis range of hardcopy plot, prompted for if not supplied
OUTPUT:
x vector of x coordinate values
y vector of y coordinate values
PROCEDURE: 1. make a photo copy of the graph on tranparency film.
2. IDL> DIGITIZE,x,y,xr=xr,yr=yr
where xr and yr are the x and y axis range.
3. align the hard copy graph onto the axis drawn by DIGITIZE
and use scotch tape to stick the film onto your screen
4. click with LMB on the axis end points (will prompt)
5. trace over the plot with cursor, LMB adds points, MMB
erases points and RMB exits the program
NOTE: Because the outer glass surface of the screen is not
on the same plane as the displayed image their is a
slight parallax effect between the tranparency and the
DIGITIZE grid. The parallax error is minimized by
keeping your line of sight normal to the screen.
EXAMPLE:
digitize,x,y ; try it
plot,x,y
REVISIONS:
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\digitize.pro)
NAME:
dig_les
PURPOSE:
reads ascii-files with 3 columns of data (as made by digitise.exe)
CATEGORY:
DATAFILES/FILE
CALLING SEQUENCE:
dig_les,file,x,y,z
INPUTS:
file: name of ascii inputfile
OUTPUTS:
x,y,z : data vectors
KEYWORD PARAMETERS:
skip: skip lines 1 to value(skip)
EXAMPLE:
dig_les,'test.txt',x,y,z,skip=1
REVISION HISTORY:
Written Franz Rohrer, May 1997
Corrected FR 12.08.1998
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\dig_les.pro)
NAME:
DIR
PURPOSE:
Simple procedure that can be executed within an interactive session of IDL to print
the filesystem contents of the current working directory to the output log.
CATEGORY:
Utilities
CALLING SEQUENCE:
dir
INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
None.
COMMON BLOCKS:
None.
MODIFICATION HISTORY:
Written by: AEB, 4/03.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\CODEBANK\dir.pro)
USERLEVEL:
TOPLEVEL
NAME:
dir2htmlfile
PURPOSE:
writes the informations about a directory to a html file
CATEGORY:
PROG_TOOLS/HTML
CALLING SEQUENCE:
Result=DIR2HTMLFILE(Dirname)
INPUTS:
dirname : directory name or string array of dir-names to be searched for
KEYWORD PARAMETERS:
HTMLFILE: a name for the html file ( default: 'dir2html.html' )
OUTPUTS:
This function returns the names of the htmlfiles with path.
EXAMPLE:
x = dir2htmlfile( ['/home3/ich388','/home3/ich388/IDL'] $
, CAPTION='test', HTMLFILE='a.html', INFO='info' $
, /FIXED, /SMALL, ALIGN=0.5 )
MODIFICATION HISTORY:
Written by: Theo Brauers, Marsy Lisken july 1998
R.Bauer bug with no write access removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dir2htmlfile.pro)
NAME:
dir2htmltable
PURPOSE:
writes the informations about the current directory to a html table
CATEGORY:
PROG_TOOLS/HTML
CALLING SEQUENCE:
Result = DIR2HTMLTABLE( )
OPTIONAL INPUTS:
Search: Search pattern for findfile, if not given *.* is assumed
KEYWORD PARAMETERS:
EXCLUDE: string array of file search patterns to be excluded
(in lowercase characters)
INCLUDE: string array of file search patterns to be included
(only these files will be considered for search)
HTMLFILE: a name for the html file ( default: 'dir2html.html' )
(written later in dir2htmlfile)
REVERSE: if keyword set the order of files will be reversed
MIXEDCASE: if keyword set no forcing to lower case is done
LAST_EXTENSION: if keyword set only last extendion is separated
OUTPUTS:
This routines returns the html code for a directory table
EXAMPLE:
x = dir2htmltable('a*.*', EXCLUDE='*.bak', /FIXED, /SMALL)
MODIFICATION HISTORY:
Written by: Theo Brauers / Marsy Lisken july 1998
modified by Franz Rohrer, Sep98, reverse keyword included
Revised: Theo Brauers Sep 1998
2000-05-23 : last_extension added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dir2htmltable.pro)
NAME:
DIRMEM
PURPOSE:
Update a directory list for easy access.
CATEGORY:
CALLING SEQUENCE:
out_list = dirmem( entry)
INPUTS:
entry = potential new list entry. in
Directory followed by an optional alias:
/users/images/lunar/gif Moon GIFS
KEYWORD PARAMETERS:
Keywords:
READ=rf Initialization text file: one directory/alias
pair per line. Comments allowed (start with * or ;).
Over-rides any given list.
WRITE=wf File to save updated list in.
LIST=lst Text array with dir/alias pairs. In/out.
/ALIAS Means use aliases for out_list (display list).
Default is use directories. ALIAS=2 means use both.
MAX_ENTRIES=m Max size of list. Def=size of init file
or 5 if that is not available.
OUTPUTS:
out_list = Display list. out
Directories, aliases, or both.
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1994 Feb 14
Copyright (C) 1994, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dirmem.pro)
NAME:
dirtree2htmlfile
PURPOSE:
This procedure writes a directory tree to a html tree
CATEGORY:
PROG_TOOLS/STRUCTURES
CALLING SEQUENCE:
dirtree2htmlfile,file_name,path,[level=level]
INPUTS:
file_name: the name of the file to write to
path: the start directory for get_dir_tree
KEYWORD PARAMETERS:
_extra: to add keywords to get_dir_tree
EXAMPLE:
dirtree2htmlfile,'S:\links\daten\experiments\stream1998.html','S:\links\daten\experiments\stream1998',level=10
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 2000-MAR-05
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dirtree2htmlfile.pro)
NAME:
dirtreearray2html
PURPOSE:
makes the html-table of a directory tree
CATEGORY:
PROG_TOOLS/HTML
CALLING SEQUENCE:
array=DIRTREEARRAY2HTML(dirarray,nfiles)
INPUTS:
dirpath : path specification of directory
dirarray : array of directory names output of GET_DIR_TREE (without path)
nfiles : integer array with number of files for each directory output of GET_NFILES
KEYWORD PARAMETERS:
DIR2HTMLFILE: name of the html-file, which contains the table of informations
about the directories (default=dir2html.html)
_EXTRA : BORDER=border (default), CAPTION=dirpath (default) see array2htmltable for details
OUTPUTS:
This function returns a string array which contains the html-table: array(cx,lev+1)
cx :number of directories (output of GET_DIR_TREE)
lev:number of directory levels
EXAMPLE:
dirpath='/home3/ich388/IDL'
dirarray=get_dir_tree(dirpath,LEVEL=-1,count=cdx)
dirarrayplus=dirpath+dirarray
nfiles =get_nfiles(dirarrayplus)
array =DIRARRAY2HTML(dirpath,dirarray,nfiles)
MODIFICATION HISTORY:
Written by: Marsy Lisken august 1998
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dirtreearray2html.pro)
NAME:
DISKCENTER
PURPOSE:
Find center and radius of a disk in an image.
CATEGORY:
CALLING SEQUENCE:
diskcenter, img, xc, yc, rd
INPUTS:
img = input image containing the disk. in
KEYWORD PARAMETERS:
Keywords:
/GRID plots fit to disk.
OUTPUTS:
xc, yc = array indices of disk center. out
rd = estimated radius of disk in pixels. out
COMMON BLOCKS:
NOTES:
Note: Image is assumed 0 outside disk, non-zero inside.
Also center of array must be inside the disk.
MODIFICATION HISTORY:
R. Sterner, 21 Feb, 1991
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\diskcenter.pro)
NAME: display_help PURPOSE: This procedure displays parts of the template on screen CATEGORY: CASE_TOOLS CALLING SEQUENCE: display_help, file_name INPUTS: file_name: The name of an IDL Source File OUTPUTS: This procedure displays on the screen a short description of a routine EXAMPLE: display_help,'ncdf_gr.pro' MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), June 23 1997 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\display_help.pro)
NAME:
DISTRIBUTE
PURPOSE:
collect all the routine names and file names that are
used in a given program.
CATEGORY:
Administrative Tools
CALLING SEQUENCE:
DISTRIBUTE,ROUTINENAME
INPUTS:
ROUTINENAME --> The name of the routine to be searched.
KEYWORD PARAMETERS:
OUTFILE --> name of an output file where the output will be saved.
OUTPUTS:
A list of filenames with full pathnames and a list of routinenames
together with the filenames where they can be found.
Sorry, for local files, no pathname is provided.
SUBROUTINES:
REQUIREMENTS:
NOTES:
Unfortunately there is no way to figure out which routines
really belong to a given routinenname, so DISTRIBUTE will always
return too many routinenames and filenames, including itself
and FILE_EXIST, as well as a couple of IDL standard library
routines (The latter can be left out with the keyword NO_IDL).
In order to get the closest results, run DISTRIBUTE only at the
start of an IDL session.
With routine_info /source, there should now be a way to
overcome the previously mentioned handicap!!
EXAMPLE:
get all routines that belong to ITERATE.PRO:
DISTRIBUTE,'iterate'
A subsequent call with routinename 'create_master' will return
both, the routines for create_master and the routines for iterate.
MODIFICATION HISTORY:
mgs, 16 Nov 1997: VERSION 1.00
mgs, 20 Nov 1997: - added OUTFILE and NO_IDL keywords
mgs, 23 Aug 2000: - changed copyright to open source
- reverted to IDL routine resolve_all
instead of own modification resolve_every.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\mschultz\distribute.pro)
NAME:
DIST_SCALE
PURPOSE:
Display a distance scale on an image.
CATEGORY:
CALLING SEQUENCE:
dist_scale, x0, y0
INPUTS:
x0, y0 = pixel coordinates of the center of scale. in
KEYWORD PARAMETERS:
Keywords:
SCALE=sc Number of units per pixels (like 12.5 m).
LENGTH=len length of scale in units given in SCALE.
HEIGHT=ht height of scale in units given in SCALE.
TITLE=txt Scale title text (like 10 km).
SIZE=sz Text size (def=1).
COLOR=clr Color of scale (def=!p.color).
BACKGROUND=bclr Background color (def=!p.background).
THICK=thk Scale thickness.
OUTPUTS:
COMMON BLOCKS:
dist_scale_com
NOTES:
MODIFICATION HISTORY:
R. Sterner, 26 Jul, 1993
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dist_scale.pro)
NAME:
DIST_SCALE2
PURPOSE:
Display a distance scale on an image.
CATEGORY:
CALLING SEQUENCE:
dist_scale, x0, y0
INPUTS:
x0, y0 = pixel coordinates of the center of scale. in
KEYWORD PARAMETERS:
Keywords:
SCALE=sc Number of units per pixels (like 12.5 m).
LENGTH=len length of scale in units given in SCALE.
HEIGHT=ht height of scale in units given in SCALE.
TITLE=txt Scale title text (like 10 km).
SIZE=sz Text size (def=1).
COLOR=clr Color of scale (def=!p.color).
BACKGROUND=bclr Background color (def=!p.background).
THICK=thk Text thickness.
BORDER=brd Border thickness.
OUTPUTS:
COMMON BLOCKS:
dist_scale_com
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1997 Mar 7
Copyright (C) 1997, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dist_scale2.pro)
NAME: diurnal_statistics PURPOSE: This function returns statistics on time-averaged data sets. CATEGORY: TIME CALLING SEQUENCE: result = diurnal_statistics(time, data) INPUTS: time: Vector of time data in Js. data: Data vector. KEYWORD PARAMETERS: TIME_STEP = ts: averaging time window in seconds (default: 86400D0). FIRST_DAY = fd: dd.mm.yy - Date of first day to be considered (default: first day in data set). LAST_DAY = ld: dd.mm.yy - Date of last day to be considered (default: last day in data set). MISSING_VALUE = miss_value: Missing data value (Skalar must be of same type as y-data value). /MAKE_PLOT: If set the result of the time-averaging process is plotted. _EXTRA = e: Any valid plot_2c keyword parameters can be passed into the plot_2c procedure. OUTPUTS: This function returns a structure of arrays where the array dimension n is equal to the number of time bins in the density function. For each bin the start time and the statistical parameters mean, stdev, sterr, n, and median are returned (tag names: time, mean, stdev, sterr, n, median). The time step is returned as well (tag name: time_step). If a quantity is not defined (e.g. stdev for only one point in the bin), the value !VALUES.F_NAN is returned. EXAMPLE: a = DINDGEN(100) t = a * 3600.D result = diurnal_statistics(t, a, /MAKE_PLOT) --> a time axis plot should appear HELP, result, /STR ** Structure <1859af0>, 9 tags, length=192, refs=1: TIME DOUBLE Array[5] MEAN FLOAT Array[5] STDEV FLOAT Array[5] STERR FLOAT Array[5] N LONG Array[5] MEDIAN FLOAT Array[5] MIN FLOAT Array[5] MAX FLOAT Array[5] TIME_STEP DOUBLE 86400.000 MODIFICATION HISTORY: Written by: Frank Holland, 02.06.1999 14.06.1999: Added keyword parameter MISSING_VALUE = miss_value.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\diurnal_statistics.pro)
NAME:
dl_vms
PURPOSE:
Dummy procedure for preventing idl to search by resolve_all for rsi vms code
CATEGORY:
CASE_TOOLS
CALLING SEQUENCE:
DL_VMS ;For prompting.
DL_VMS, Name ;Extract documentation for procedure Name using
the current !PATH.
INPUTS:
Name: A string containing the name of the procedure.
KEYWORDS:
FILE: If this keyword is set, the output is sent to the file
"userlib.doc", in the current directory.
PRINT: If set, this keyword sends the output of DL_VMS to lpr.
PATH: An optional directory/library search path. This keyword uses
the same format and semantics as !PATH. If omitted, !PATH is
used.
OUTPUTS:
Documentation is output to terminal or printer.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Output is produced on terminal or printer.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward.
MODIFICATION HISTORY:
Written, DMS, Sept, 1982.
Added library param, Jul 1987.
Unix version, Feb, 1988.
Revised for VMS Version 2, 15 December 1989
Modified by Jim Pendleton, GRO/OSSE NU, July 30, 1992 to handle
!PATH's gt 255 characters.
AB, 21 September 1992, renamed from DOC_LIB_VMS to DL_VMS to
avoid DOS filename limitations.
ACY, 25 January 1993, file should be written with stream mode
1998-07-30 R.Bauer, all lines between PRO and END removed because of preventing idl in non vms
to search for special vms functions
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dl_vms.pro)
NAME:
DMS2D
PURPOSE:
Convert from Degrees, MInutes, and seconds to degrees.
CATEGORY:
CALLING SEQUENCE:
d = dms2d(s)
INPUTS:
s = input text string with deg, min, sec. in
Ex: "3d 08m 30s" or "3 8 30".
KEYWORD PARAMETERS:
OUTPUTS:
d = returned angle in degrees. out
COMMON BLOCKS:
NOTES:
Notes: scalar value only. Units symbols ignored,
first item assumed deg, 2nd minutes, 3rd seconds.
MODIFICATION HISTORY:
R. Sterner, 1998 Feb 3
Copyright (C) 1998, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dms2d.pro)
NAME:
DMS_FORM
PURPOSE:
Convert degrees to a deg, min, sec vector font string.
CATEGORY:
CALLING SEQUENCE:
dms = dms_form(deg)
INPUTS:
deg = degrees and decimal fraction. in
KEYWORD PARAMETERS:
Keywords:
/NOSEC Means suppress seconds.
DEGREES=n Force n digits in degrees, fill with 0s.
FONT=fnt Specify font string (def=!17).
OUTPUTS:
dms = string to be printed by xyouts out
using vector font.
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 22 Sep, 1992
Copyright (C) 1992, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dms_form.pro)
NAME:
dmyhms2js
PURPOSE:
convert date (d.m.y) and time (h:m:s) to JulianSeconds,
works with string array input
CATEGORY:
TIME
CALLING SEQUENCE:
Result= DMYHMS2JS(date_time)
INPUTS:
date_time: string ('d.m.y h:m:s')
KEYWORD PARAMETERS:
NO_SEC: if this keyword is set the sec of the string
are ignored, works with 'd.m.y h:m'
NOW: returns actual time instead
OUTPUTS:
julian sec: double
RESTRICTIONS:
1.1.70 ... 31.12.69 = 1.1.1970 ... 31.12.2069
only seperators matter, spaces and zeros ignored
the string array must contain all entries: 'd.m.y h:m:s'
EXAMPLE:
dt=['1.1.95 10:11:03', '1.1.96 1:11:36', '1.1.05 1:11:3']
jsec=dmyhms2js(dt)
dt=['1.1.95 10:11', '1.1.96 1:11', '1.1.05 1:11']
jsec=dmyhms2js(dt, /no_sec)
REVISION HISTORY:
Written Theo Brauers, Nov 1997
Modified T.B. bug with array and no_sec removed
T.B. bug with year < 1969 removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\dmyhms2js.pro)
ROUTINE: doc
PURPOSE: find and display help for a named procedure
USEAGE: doc,'name'
INPUT:
name name of idl .pro file. Asterisk characters, "*", in NAME
specify wild card matches to 1 or more arbitrary characters.
PROCEDURE: DOC searches through the files /local/idl/help/*.help
trying to find matches for the file specification, NAME.
if there are no matches a brief failure message is displayed
and control returns to the terminal
if 1 match is found, help for the specified procedure is
displayed and control returns to the terminal
if 2 or more matches are found a menu is generated
from which selections can be made. Control returns to
the terminal when the DONE button of the MENUW widget
is pressed.
EXAMPLE:
doc,'legend' ; exact match found in ESRG_LOCAL
doc,'tv*' ; many matches found, browse through
; choices. Notice that all procedure
; libraries are searched
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\doc.pro)
ROUTINE: dockey
PURPOSE: display help documententation of file headers which
contain matches for specified keywords
USEAGE: dockey,'name',keyword=keyword,all=all,minmatch=minmatch
INPUT:
keywords keyword string. Keywords withing the KEYWORDS must be
separated by blanks.
KEYWORD_INPUT
minmatch the minimum number of keyword hits required for a procedure
to be listed in the hit-list menu.
PROCEDURE: DOCKEY searches through the helpfiles in subdirectory
/local/idl/help, trying to find matches for the keywords.
If more than one file match is found a menu of procedure
names is displayed from which the desired procedure
can be selected. The parenthisized number next to each
procedure name is the number of keyword matches, which
can vary between one to the total number of keywords in
KEYWORDS.
MAN_PROC is used to display the text
EXAMPLE:
dockey,'simpson rule integration'; pick group 'numerical'
dockey,'polar orthographic' ; pick group 'esrg'
dockey,'color key image',m=2 ; pick group 'color'
;
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dockey.pro)
NAME:
DOT
PURPOSE:
Used by SUN_SHADE for dot prod. of surf. normal & sun vect.
CATEGORY:
CALLING SEQUENCE:
r = dot(s,[azi,alt])
INPUTS:
s = Surface array to be shaded. in
azi = Light azimuth (deg, def = 135). in
alt = Light altitude (deg, def = 60). in
KEYWORD PARAMETERS:
OUTPUTS:
r = dot products: surface normals and sun vector. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 8 Mar, 1989.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
Slightly modified version of routine by J. Culbertson.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dot.pro)
NAME: do_link PURPOSE: This procedure did the links of "good" files to the defined flightday directories of the icg-1 datalibrary. The link name ist always the lowercase experiment name +'.nc' CATEGORY: DATAFILES/FILE CALLING SEQUENCE: do_link,[/month] KEYWORD PARAMETERS: month: to link the data to month instead of flightday directories RESTRICTIONS: will at the moment only work whith icg1's data-base EXAMPLE: do_link,'stream1997' MODIFICATION HISTORY: Written by: R.Bauer (ICG-1),August 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\do_link.pro)
NAME: do_page_title PURPOSE: This procedure is used to write a centered title on a plot page CATEGORY: PLOT CALLING SEQUENCE: do_page_title,plot,text,[charsize=charsize],[color=color] INPUTS: plot: The by pl_init defined plot structure text: The text you want to show on the page OPTIONAL INPUTS: charsize: The charsize ot the text (default is 1) color: The color of the text (default is black) EXAMPLE: do_page_title,plot,'TEST' MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 5. Oct. 1997 1999-10-14 alignment added 1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\do_page_title.pro)
NAME:
do_pl2d
PURPOSE:
This procedure is an example routine for the use of the procedures
do_pl2d_define and do_pl2d_plot.
You can use it (with all keywords specified) or you can copy it and modify it in
the form which you want.
After the do_pl2d_define-call there is a comment, which substructures you can now use.
CATEGORY:
PLOT/PLOT2D
CALLING SEQUENCE:
do_pl2d,spec
INPUTS:
spec : the netCDF-variable which you want to plot.
some control keywords
OUTPUTS:
A contour plot with the variable, specified in plotstr.values.z, plotted against the x- and y-values.
EXAMPLE:
do_pl2d,'PV',f_name =file_search('box_970227_nh.nc',/use_path),dir='./'
Result: a plot of the species PV on a map-background with cylindrical projection
MODIFICATION HISTORY:
Written by: Juergen Ankenbrand , 11.5.98
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\ja_lib\do_pl2d.pro)
NAME:
do_pl2d_define
PURPOSE:
This procedure defines some substructures of the ICG - plot-structure.
It reads the variables, which the user wants, from a netCDF-file and
creates them as components of the plotstructure.
Some control attributes of the netCDF-file become components, too.
CATEGORY:
PLOT/PLOT2D
CALLING SEQUENCE:
do_pl2d_define,plot
INPUTS:
plot: Plotstructure of the ICG plot-environment, which has to have
a new subcomponent 'names', which must contain the components
'file' : the netcdf-filename
'paramnames' : a stringarray, which contains the names of the
variables of the netCDF-file, which should be read
from the file
'spec' : the name of the variable, which is later used as
z variable
'con' : if 1, then the spec-values are multiplicated with the
values of netCDF-variable 'TND'
OUTPUTS:
plot: The input Plotstructure has some new components:
'control' with the components:
'missing_value': the missing_value-attribute of the netCDF-file
'nparts' : the number of trajectories
'time' : the time dimension
'unit' : a string, where you can set later e.g. 'ppm'
'dim' : a component where you can set the dimension for a later defp2d -
call; default value 21
'maxval' : a component for a defp2d - call, too
'minval' : a component for a defp2d - call, too
'map' : a string, where you can later chose a map projection
'paramvalues' with the components:
'spec' : the values of the z-variable, which has been
declared in plot.names.spec,eventually multiplied
with TND
the names declared in plot.names.paramvalues: the values of these
netCDF-variables
SIDE EFFECTS:
The input-plot-structure has some new subcomponents.
EXAMPLE:
@init
;initialize Reimar Bauer's plotstructure
paramnames = ['LONG','LAT','LEVEL','time','TND']
;a stringarray with the names of the variables ,which are to read
my_struct1 = create_struct('file','test.nc','paramnames',paramnames,'spec','PV','con',0)
;create a new structure
plot=create_struct(plot,'names',my_struct1)
;and it becomes a substructure of the plot-structure
do_pl2d_define,plot
; now you have account of e.g. plot.paramvalues.spec, plot.paramvalues.LONG
MODIFICATION HISTORY:
Written by: Juergen Ankenbrand, 5.5.1998.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\ja_lib\do_pl2d_define.pro)
NAME:
do_pl2d_plot
PURPOSE:
This procedure calls the 'plot2d' procedure of Reimar Bauer.
Before, it searchs for x- and y-ranges of the axes-variables.
If you want, you can lay a map in the background.
If you have irregular values, which are in a regular gather,
these values can be transformed to a regular gather.
CATEGORY:
PLOT/PLOT2D
CALLING SEQUENCE:
do_pl2d_plot,plotstr
INPUTS:
plotstr: Plotstructure of the ICG plot-environment, which has to have
a new subcomponent 'names', which must contain the components:
'values': a new subcomponent with the components:
'x': an array with the x-values (mostly longitude)
'y': an array with the y-values (mostly latitude)
'z': an array with the z-values, the variable,
which will be plotted
'control' with the components(if ther has been a do_pl2d_define - call this
component already exists):
'missing_value': the missing_value-attribute of the netCDF-file
'nparts' : the number of trajectories
'time' : the time dimension
'unit' : a string, where you can set later e.g. 'ppm'
'dim' : a component where you can set the dimension for a later defp2d -
call; default value 21
'maxval' : a component for a defp2d - call, too
'minval' : a component for a defp2d - call, too
'map' : a string, where you can later chose a map projection
'regular' : default 0 ; must be set later to not 0 if there are pseudoregular values
'm','n' : the sizes of the pseudoregular transformation
OUTPUTS:
A contour plot with the variable, specified in plotstr.values.z, plotted against the x- and y-values.
If plotstr.control.map is set to 1, a cylindrical map is plotted in the background, if plotstr.control.map
is 2 a polarstereographical map is plotted, else no map is plotted.
EXAMPLE:
(for the first 5 lines see the 'do_pl2D_define' - description,too)
@init
paramnames = ['LONG','LAT','LEVEL','time','TND']
my_struct1 = create_struct('file','test.nc','paramnames',paramnames,'spec','PV','con',0)
plot=create_struct(plot,'names',my_struct1)
do_pl2d_define,plot
my_struct4 = create_struct('Z',plot.paramvalues.spec,'X',plot.paramvalues.long,'Y',plot.paramvalues.lat,
'contour'contour)
;Longitude is defined as x-axes, Latitude as y-axes and PV will be plotted.
plot = create_struct(plot,'values',my_struct4)
;values becomes a subcomponent of the 'plot' -structure
do_pl2d_plot,plot
;PV is plotted in a contour plot against longitude and latitude
MODIFICATION HISTORY:
Written by: Juergen Ankenbrand , 11.5.98,
14.6.98: P. Konopka, new switch plot.values.contour:
plot.values.contour=1: contour plots
plot.values.contour=0: Air parcels are plotted as small filled circles
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\ja_lib\do_pl2d_plot.pro)
NAME:
do_plxy
PURPOSE:
Using the plotxy environment possible types of plots are
1X-1Y, 2X-1Y, 1X-2Y, 2X-2Y
For more information look at the example do_plxy_instructions.
CATEGORY:
PLOT
CALLING SEQUENCE:
do_plxy, instruction_file
INPUTS:
instruction_file: an idl Script which holds the instruction how to make a plot
OUTPUTS:
belonging on the instruction file on screen or file
EXAMPLE:
do_plxy,'do_plxy_instructions'
PRO do_plxy_instructions,pict,init
ct_ncdf,color
seiten =1
zeilen =2
spalten =2
plot_width=15.60
plot_height=10.85
plot_width=20.
landscape=1
psflag = 0
psfile = 'idl'
init = {$
spalten:spalten,$
zeilen:zeilen,$
plot_width:plot_width,$
plot_height:plot_height,$
psflag:psflag,$
psfile:psfile,$
landscape:landscape,$
page_title:''$
}
pict = replicate({use:'plotxy',$
file:'',$
title:'',$
x:strarr(2),$
y:strarr(2),$
psym:[(0),(108)],$
color:[color.red,color.green],$
symsize:[1.,1.],$
linestyle:[0,0],$
thick:[1.,1.],$
timeformat:['!h$:m$:s$@!d$.nn$.Y$','!h$:m$:s$@!d$.nn$.Y$'],$
x_array_index:intarr(2),$
y_array_index:intarr(2)},$
zeilen*spalten*seiten)
pict[0].file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
pict[0].x = ['time','time']
pict[0].y = ['LAT','LAT']
pict[0].x_array_index = [0,0]
pict[0].y_array_index = [0,1]
pict.file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
pict[1].x = ['time','']
pict[1].y = ['LAT','LON']
pict[1].x_array_index = [0,0]
pict[1].y_array_index = [1,1]
pict[2].file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
pict[2].x = ['time','']
pict[2].y = ['LAT','']
pict[2].x_array_index = [0,0]
pict[2].y_array_index = [2,2]
pict[3].file='S:/links/idl_source/idl_work/rb_lib/examples/do_plxy.nc'
pict[3].x = ['time','time']
pict[3].y = ['LAT','']
pict[3].x_array_index = [0,0]
pict[3].y_array_index = [0,1]
END
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 13-Oct-1997
15.10 Part 1X 1Y corrected
22.10 ytitle corrected
1998-Jan-15 plot.xgap sey to 8640000.d
1998-Mar-03 the case of 1X and 1Y axis is corrected in case of plot.x_array_index and y_array_index
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\do_plxy.pro)
NAME: do_plxy_instructions PURPOSE: This is an instructions file for do_plxy CATEGORY: EXAMPLES/PLOT/PLOTXY CALLING SEQUENCE: do_plxy_instructions,pict,init OUTPUTS: pict: an array of structures holding the informations for the plot init: a structure holding the informations to initialize a plot EXAMPLE: do_plxy,'do_plxy_instructions' gif picture MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 13-Oct-1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\examples\plot\plotxy\do_plxy_instructions.pro)
NAME:
DRAW
PURPOSE:
Graphics draw from last point to given point.
CATEGORY:
CALLING SEQUENCE:
draw, x, y
INPUTS:
x,y = scalar coordinates of point to draw to. in
KEYWORD PARAMETERS:
Keywords:
COLOR=c color of line from last point.
OUTPUTS:
COMMON BLOCKS:
move_com
NOTES:
Note: see move.
MODIFICATION HISTORY:
R. Sterner, 22 Jan, 1990
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\draw.pro)
NAME:
DRAWCOLORS
FILENAME:
drawcolors__define.pro
PURPOSE:
The purpose of this object program is provide a flexible way
to handle and select drawing colors. The program combines
features of two previous programs: GetColor and PickColor,
as well as adding features of its own. Sixteen original
colors are supplied, but users can create any color they
wish using the tools provided.
By default, these 16 colors are defined: Black, Magenta, Cyan, Yellow,
Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
General programming.
CALLING SEQUENCE:
colors = Obj_New('DRAWCOLORS')
OPTIONAL INPUT PARAMETERS:
IDL> colors = Obj_New('DRAWCOLORS', red, green, blue, names)
RED -- A 16-element byte vector of red values for the drawing colors.
GREEN -- A 16-element byte vector of green values for the drawing colors.
BLUE -- A 16-element byte vector of blue values for the drawing colors.
NAMES -- A 16-element string vector of names for the drawing colors.
By default, these colors are defined: Black, Magenta, Cyan, Yellow,
Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White.
COMMON BLOCKS:
None.
RESTRICTIONS:
If you are going to use the XCOLORS method, you will need
the XColors program from the Coyote library:
http://www.dfanning.com/programs/xcolors.pro
The program is set up to handle 16 drawing colors. You may
modify the program to have a different number, but you will
have to modify the code in two places: (1) in the drawcolors__define
module and (2) in the INIT method.
FUNCTION METHODS:
COLOR24 ***************************************************************************
Purpose:
Turns a color triple into the equivalent 24-bit color integer value that
can be decomposed into the color.
Definition:
FUNCTION DrawColors::Color24, theColor
Parameters:
theColor -- A 3-element vector, representing a color triple.
Example:
yellow = colors->GetColor("yellow")
yellow24 = colors->Color24(yellow)
GETCOLOR ***************************************************************************
Purpose:
Returns the color triple, color index number, or the
24-bit integer representation, of the asked for color. In
normal operation, the colors are: Black, Magenta, Cyan, Yellow,
Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal,
Gray, and White.
Definition:
FUNCTION DrawColors::GetColor, theColor, startIndex, INDEXNUMBER=indexnumber, $
TRUECOLOR=truecolor, AutoDetermine=autodetermine
Parameters:
theColor -- A string representing the "name" of the color. If the name
can't be resolved or found, the first color is returned.
startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at
this index number. Otherwise, the self.startIndex is used.
Keywords:
AUTODETERMINE -- If this keyword is set. the state of DECOMPOSITION is
determined (IDL 5.2 and higher) and either the INDEXNUMBER or
TRUECOLOR keyword is set appropriately. If the decomposition state
cannot be determined, the INDEXNUMBER keyword is set.
INDEXNUMBER -- If this keyword is set the colors are loaded and the
index number of the color is returned.
TRUECOLOR -- If this keyword is set, the color triple is converted into
a 24-bit integer before being returned. This keyword is ignored
if the INDEXNUMBER keyword is set.
Examples:
drawColor = colors->GetColor("yellow")
drawColor = colors->GetColor("blue", /Indexnumber)
drawColor = colors->GetColor("sky", /Truecolor)
GETCOLORS **************************************************************************
Purpose:
Returns the color triples, the color index numbers of, or the
24-bit integer representations of, all the colors.
Definition:
FUNCTION DrawColors::GetColors, startindex, INDEXNUMBER=indexnumber, $
TRUECOLOR=truecolor, Structure=structure
Parameters:
startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at
this index number. If absent, startIndex = self.startIndex.
Keywords:
INDEXNUMBER -- If this keyword is set the colors are loaded and the
index numbers of all the colors are returned.
STRUCTURE -- If this keyword is set, the return value is a structure,
where each field of the structure is a color name and the value
of each field is either a color triple, an index number, or a
24-bit color value, depending upon the state of other keywords.
TRUECOLOR -- If this keyword is set, the color triples are converted to
24-bit integers before being returned. This keyword is ignored
if the INDEXNUMBER keyword is set.
Examples:
drawColors = colors->GetColors() ; drawColors is a 16-by-3 byte array.
drawColors = colors->GetColors(/IndexNumber) ; drawColors is a 16-element array of color indices.
drawColors = colors->GetColors(/TrueColor) ; drawColors is a 16-element array of 24-bit integers.
drawColors = colors->GetColors(/IndexNumber, /Structure) ; drawColors is a structure of index numbers.
Plot, data, Color=drawColors.yellow, Background=drawColors.charcoal
SELECT **************************************************************************
Purpose:
Puts up a blocking or modal widget dialog, allowing the user to select
from one of the 16 predefined colors available, or to mix their own color.
The user-defined color triple is returned as a result of the function.
Definition:
FUNCTION DrawColors::Select, Color=currentColor, StartIndex=startIndex, $
Title=title, Group_Leader=groupLeader, Cancel=cancelled, TrueColor=truecolor
Keywords:
CANCEL -- An output keyword that will return a value of 1 if the CANCEL
button is selected or if program operation is interrupted in any way.
COLOR -- The index number in the color table, where the current color
will be mixed. In other words, this color index will change when
the program is on the display. It will be restored to its previous
or entry color when the program exits.
GROUP_LEADER -- The group leader for the program. This keyword *must*
be set if calling this method from within a widget program if you
expect MODAL program operation.
NAME -- If this keyword is set, the return value of the function is
the "name" of the color.
STARTINDEX -- This is the starting index in the color table where the
16 predetermined colors will be loaded. The original colors will
be restored when the program exits. By default, this is set to
!D.Table-Size - (NCOLORS + 1).
TITLE -- The title of the program. By default: "Pick a Color"
TRUECOLOR -- If this keyword is set, the return value of the function
is a 24-bit eqivalent integer rather than the color triple.
Examples:
newColor = colors->Select() ; A blocking widget.
newColor = color->Select(Group_Leader=event.top, Cancel=cancelled)
IF NOT cancelled THEN TVLCT, newColor, info.dataColor
PROCEDURE METHODS:
GETPROPERTY ***********************************************************************
Purpose:
Allows the user to obtain the current properties of the object.
Definition:
PRO DrawColors::GetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $
STARTINDEX=startindex, NCOLORS=ncolors
Keywords:
NAMES -- Returns the current names of the colors as a string array.
RED -- Returns the current red values of the colors.
GREEN -- Returns the current green values of the colors.
BLUE -- Returns the current blue values of the colors.
STARTINDEX -- Returns the current starting index in the color table.
NCOLORS -- Returns the number of colors.
Example:
colors->GetProperty, Names=colorNames
Print, colorNames
LOADCOLORS ************************************************************************
Purpose:
Loads the predefined colors at a starting index.
Definition:
PRO DrawColors::LoadColors, startindex
Parameters:
STARTINDEX -- The starting color index in the color table. If not provided,
is set to !D.Table_Size - (self.ncolors + 1).
Example:
colors->LoadColors, 16
ORIGINALCOLORS *********************************************************************
Purpose:
Reloads the original 16 colors and their names
Definition:
PRO DrawColors::OriginalColors
Parameters:
None
Example:
colors->OriginalColors
REFRESH ***************************************************************************
Purpose:
Refreshes the modal GUI with the current drawing colors.
Definition:
PRO DrawColors::Refresh
Parameters:
None
Example:
colors->Refresh
SETPROPERTY ***********************************************************************
Purpose:
Allows the user to set the current properties of the object.
Definition:
PRO DrawColors::SetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $
STARTINDEX=startindex, NCOLORS=ncolors
Keywords:
NAMES -- The current names of the colors as a string array.
RED -- The current red values of the colors.
GREEN -- The current green values of the colors.
BLUE -- The current blue values of the colors.
STARTINDEX -- The current starting index in the color table.
NCOLORS -- The number of colors.
Example:
colorNames = 'Color ' + StrTrim(SIndGen(16),2)
colors->SetProperty, Names=colorNames
XCOLORS ***************************************************************************
Purpose:
Allows the user to select 16 new colors for the program by
using the XCOLORS program. The XColors program must be
somewhere in your !PATH.
Definition:
PRO DrawColors::XColors
Parameters:
None
Example:
colors->XColors
TUTORIAL:
Here is a short tutorial in how this object can be used. Note
that this doesn't exhaust all the possibilities.
1. Create the object.
IDL> colors = Obj_New("DrawColors")
2. Find out what colors it knows about.
IDL> colors->GetProperty, Names=colorNames
IDL> Print, colorNames
3. Ask for a color by name and load it at a color
index. Draw a plot in that color.
IDL> yellow = colors->GetColor("yellow")
IDL> TVLCT, yellow, 200
IDL> Device, Decomposed=0
IDL> Plot, Findgen(11), Color=200
4. Do the same thing, but in DECOMPOSED color.
IDL> Device, Decomposed=1
IDL> green = colors->GetColor("green", /TrueColor)
IDL> Plot, Findgen(11), Color=green
5. Find the color index number of the sky blue color.
IDL> Device, Decomposed=0
IDL> skyIndex = colors->GetColor("sky", /IndexNumber)
IDL> Plot, Findgen(11), Color=skyIndex
6. Load all 16 drawing colors at color index 32.
IDL> colors->LoadColors, 32
IDL> CIndex ; If them, if you have CINDEX from my library.
7. Get a structure of colors, with each field set to
the appropriate index number of its associated color.
IDL> Device, Decomposed=0
IDL> col = colors->GetColors(/IndexNumber, /Structure)
IDL> Plot, Findgen(11), Color=col.yellow, Background=col.charcoal
8. Allow the user to select a color from a GUI, then
load it and use it.
IDL> Device, Decomposed=0
IDL> theColor = colors->Select(Cancel=cancelled)
IDL> IF NOT cancelled THEN TVLCT, theColor, 10
IDL> Plot, Findgen(11), Color=10
9. Allow the user to choose 16 new drawing colors.
(Requires my XCOLORS program.)
IDL> colors->XColors
IDL> theseColors = colors->Select()
10. Let the object decide according to the device decomposition
state whether to return an index number or 24-bit value
for the color.
IDL> Plot, Findgen(11), Color=colors->GetColor('beige', /Autodetermine)
11. Call the GUI from within a widget program and load the
new color.
newcolor = info.colors->Select(Group_Leader=event.top, $
Cancel=cancelled)
IF NOT cancelled THEN TVLCT, newcolor, info.drawColor
12. Destroy the object.
IDL> Obj_Destroy, colors
MODIFICATION HISTORY:
Written by: David Fanning, 9 NOV 1999.
Added AUTODETERMINE keyword to the GetColor method. 10 NOV 1999. DWF.
Added NAME keyword to SELECT method. 18 MAR 2000. DWF.
Fixed a small bug in choosing the current color. 20 April 2000. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\drawcolors__define.pro)
NAME:
DRAWPOLY
PURPOSE:
Draw a polygon using mouse.
CATEGORY:
CALLING SEQUENCE:
drawpoly, x, y
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/CURVE draw a curve instead of a polygon.
/DEVICE use device coordinates (def).
/DATA use data coordinates.
/NORMAL use normalized coordinates.
/NOPLOT erase on exit (def=plot).
COLOR=c outline or curve color (def=!p.color).
THICK=t outline or curve thickness (def=0).
LINESTYLE=s outline or curve line style (def=0).
FILL=f polygon fill color (def= -1 = no fill).
OUTPUTS:
x,y = polygon vertices. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 2 Oct, 1990
R. Sterner, 23 Oct, 1990 --- added some keywords.
R. Sterner, 26 Feb, 1991 --- renamed from draw_polygon.pro
R. Sterner, 1994 Mar 17 --- Default color=!p.color.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\drawpoly.pro)
NAME:
draw_axis
PURPOSE:
This procedure draws the axes over an oplot. Normally this routines is used by plotxy, plot2d etc.
if they are called after set_frame procedure
CATEGORY:
PLOT/PLOTXY
CALLING SEQUENCE:
draw_axis,PLOT,pl_xy,time=time,xrange=xrange,yrange=yrange,xstyle=xstyle
INPUTS:
plot: The plot structure defined by pl_init
pl_xy: the siues structure
time: if set timeaxis is drawn
xrange: submitted at the moment xrange to draw
yrange: submitted at the moment yrange to draw
xstyle: submitted at the moment xstyle to use
PROCEDURE:
This procedure is under construction
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1) 2000-Apr-25
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\draw_axis.pro)
NAME:
DROP_COMMENTS
PURPOSE:
Drop comment and null lines from a text array.
CATEGORY:
CALLING SEQUENCE:
out = drop_comments(in)
INPUTS:
in = input text array. in
KEYWORD PARAMETERS:
Keywords:
IGNORE=ig Text string of allowed comment characters.
Default is ';*', so lines starting with the characters'
* or ; in column 1 are considered comments and dropped.
/NOTRIM means don't do a strtrim on text array.
By default any line with white space but no text is
considered a null line and dropped. If /NOTRIM is
specified only true null lines are dropped.
/TRAILING means drop any trailing comments on each line.
Be careful of the default comment characters for this.
ERROR=err Error flag: 0=OK, 1=All lines dropped.
/QUIET Means suppress error messages.
INDEX=indx Indices in original input of retained lines.
OUTPUTS:
out = processed text array. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 18 May, 1993
R. Sterner, 1995 Jun 26 --- added keyword INDEX=indx.
R. Sterner, 1995 Oct 27 --- added keyword /TRAILING.
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\drop_comments.pro)
NAME:
dtime2js
PURPOSE:
This function translates the year ,month, day, hour, minute, second, millisecond to Julian Seconds or a
string like 'YYYY-MM-DD HH:MM:SS mSc'
CATEGORY:
TIME
CALLING SEQUENCE:
Result = dtime2js(y,m,d,s,hh,mm,ss,mi) or Result = dtime2js('1997-06-13 13:31:13 313')
INPUTS:
y: four digits for the year
if y is a string the script goes in the char mode
m: the month
d: the day
hh: the hours
mm: the minutes
ss: the seconds
mi: the milliseconds
OPTIONAL INPUTS:
datstr:[obsolete] A string with the day time information
Format is: 'YYYY-MM-DD hh:mm:ss mi'
needed in the past to submit a string
KEYWORD PARAMETERS:
char: [obsolete] switch for the function to convert a string defined day time information
was used in the past to switch between integer and string input
OUTPUTS:
This function returns the Julian Seconds of a day time Information
EXAMPLE:
Result = dtime2js(1997,6,13,13,31,13,313)
Result= -80476126.687D
Result=dtime2js('1997-06-13 13:31:13 313')
Result= -80476126.687D
MODIFICATION HISTORY:
Written by: R.Bauer, Sep., 18, 1996
R.Bauer, Jan., 7, 1997 /char option added
R.Bauer, Aug., 14 1997 /Sep 2 easier handling of strings
R.Bauer, Mar., 8 1998 internal variable y changed to yy
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\dtime2js.pro)
NAME:
DT_TM_BRK
PURPOSE:
Break a date and time string into separate date and time.
CATEGORY:
CALLING SEQUENCE:
dt_tm_brk, txt, date, time
INPUTS:
txt = Input date and time string. in
May be an array.
KEYWORD PARAMETERS:
OUTPUTS:
date = returned date string, null if no date. out
time = returned time string, null if no time. out
COMMON BLOCKS:
NOTES:
Note: works for systime: dt_tm_brk, systime(), dt, tm
The word NOW (case insensitive) is replaced
by the current sysem time.
MODIFICATION HISTORY:
R. Sterner. 21 Nov, 1988.
RES 18 Sep, 1989 --- converted to SUN.
R. Sterner, 26 Feb, 1991 --- renamed from brk_date_time.pro
R. Sterner, 26 Feb, 1991 --- renamed from brk_dt_tm.pro
R. Sterner, 1994 Mar 29 --- Allowed arrays.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_brk.pro)
NAME:
DT_TM_CHK
PURPOSE:
Check date & time string that both parts exist & are valid.
CATEGORY:
CALLING SEQUENCE:
status = dt_tm_chk(txt)
INPUTS:
txt = Input data and time string. in
KEYWORD PARAMETERS:
OUTPUTS:
status = 1 if ok (true), 0 if error (false). out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 13 Apr, 1989.
R. Sterner, 26 Feb, 1991 --- renamed from chk_date_time.pro
R. Sterner, 27 Feb, 1991 --- renamed from chk_dt_tm.pro
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_chk.pro)
NAME:
DT_TM_DIF
PURPOSE:
Find time interval in seconds between two date/time strings.
CATEGORY:
CALLING SEQUENCE:
sec = dt_tm_dif(t1, t2)
INPUTS:
t1, t2 = date and time strings. in
KEYWORD PARAMETERS:
OUTPUTS:
sec = Time in seconds from t1 to t2. out
COMMON BLOCKS:
NOTES:
Note: date and time strings are strings like 21-Jan-1989 14:43:03
The format of the date and time strings is flexable, see date2ymd.
MODIFICATION HISTORY:
R. Sterner. 12 Apr, 1989.
Johns Hopkins University Applied Physics Laboratory.
RES 18 Sep, 1989 --- converted to SUN
R. Sterner, 26 Feb, 1991 --- Renamed from interval_sec.pro
R. Sterner, 27 Feb, 1991 --- Renamed from interv_sec.pro
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_dif.pro)
NAME:
DT_TM_FROMCR
PURPOSE:
Convert from Carrington Rotation Number to Date/Time.
CATEGORY:
CALLING SEQUENCE:
dt_tm = dt_tm_fromcr(cr)
INPUTS:
cr = Carrington Rotation Number. in
KEYWORD PARAMETERS:
Keywords:
/JS means return Julian Seconds, not date/time string.
OUTPUTS:
dt_tm = date/time string. out
COMMON BLOCKS:
NOTES:
Notes: Time is Ephemeris Time which is almost UT.
Ref: Astronomical Algorithms, Jean Meeus.
MODIFICATION HISTORY:
R. Sterner, 1996 Jun 21
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_fromcr.pro)
NAME:
DT_TM_FROMJS
PURPOSE:
Convert "Julian Seconds" to a date/time string.
CATEGORY:
CALLING SEQUENCE:
dt = dt_tm_fromjs(js)
INPUTS:
js = "Julian Seconds". in
KEYWORD PARAMETERS:
Keywords:
FORMAT=fmt format for dt (see dt_tm_mak).
Def = "Y$ n$ d$ h$:m$:s$ w$"
/FRACTION displays fraction of second in default format.
DECIMAL=dp Number of decimal places to use for fraction of
second (def=3) for f$ in format. f4 will include dec pt.
DENOMINATOR=den If given then fraction is listed as nnn/ddd
ddd is given by den. Over-rides DECIMAL keyword. Ex:
DENOM=1000 might give 087/1000 for f$ in format.
DDECIMAL=ddp Number of decimal places to use in day
of year (if doy$ included in format, def=none).
YEAR=yy returns extracted year.
MONTH=mm returns extracted month.
DAY=dd returns extracted day.
SECOND=ss returns extracted seconds after midnight.
JD=jd returns extracted Julian Day of date.
NUMBERS=st Returned structure with numeric values.
OUTPUTS:
dt = date/time string. out
COMMON BLOCKS:
NOTES:
Notes: Julian seconds (not an official unit) serve the
same purpose as Julian Days, interval computations.
The zero point is 0:00 1 Jan 2000, so js < 0 before then.
Julian Seconds are double precision and have a precision
better than 1 millisecond over a span of +/- 1000 years.
See also dt_tm_tojs, ymds2js, js2ymds, jscheck.
MODIFICATION HISTORY:
R. Sterner, 3 Sep, 1992
R. Sterner, 18 Aug, 1993 --- Added JD keyword.
R. Sterner, 2 Dec, 1993 --- Changed default format.
R. Sterner, 1998 Apr 15 --- Returned NUMBERS structure.
Copyright (C) 1992, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_fromjs.pro)
NAME:
DT_TM_FULL
PURPOSE:
Add missing parts of date to get a full date/time string.
CATEGORY:
CALLING SEQUENCE:
out = dt_tm_full(in,miss)
INPUTS:
in = input date/time string. in
May have missing date info: '12:34' 'May 7 7:00'
miss = Desired year, month, day in that order. in
Like '1996 May 12'. Default=current date.
KEYWORD PARAMETERS:
Keywords:
ERROR=err 0 if ok, 1 if result is not a valid date/time.
OUTPUTS:
out = Full date/time string. out
Like '1996 May 12 12:34' or '1996 May 7 7:00'
COMMON BLOCKS:
NOTES:
Notes: for scalar value only. Does only limited error
checking.
MODIFICATION HISTORY:
R. Sterner, 1997 Jul 10
Copyright (C) 1997, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_full.pro)
NAME:
DT_TM_INC
PURPOSE:
Increment a date/time by a given number of seconds.
CATEGORY:
CALLING SEQUENCE:
dt_tm_inc, t, s
INPUTS:
s = Time in seconds to add. in
KEYWORD PARAMETERS:
Keywords:
FORMAT = format string. Allows output date to be customized.
The default format string is 'y$ n$ d$ h$:m$:s$'
The following substitutions take place in the format string:
Y$ = 4 digit year.
y$ = 2 digit year.
N$ = full month name.
n$ = 3 letter month name.
d$ = day of month number.
W$ = full weekday name.
w$ = 3 letter week day name.
h$ = hour.
m$ = minute.
s$ = second.
@ = Carriage Return.
! = Line feed.
Some examples: 'h$:m$:s$' -> 09:12:04,
'd$ n$ Y$' -> 12 Jan 1991, 'd$D h$h' -> 3D 2h, ...
OUTPUTS:
t = date and time string. in, out
date/time strings are strings like 21-Jan-1989 14:43:03
The format of the date and time strings is flexible, see date2ymd.
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 18 Apr, 1989.
RES 25 Oct, 1991 --- renamed and rewrote from incsec_datetime.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_inc.pro)
NAME:
DT_TM_MAK
PURPOSE:
Set up a time and date string from reference JD and offset.
CATEGORY:
CALLING SEQUENCE:
s = dt_tm_mak(jd0, [sec])
INPUTS:
jd0 = Julian Date of a reference date (0:00 hr). in
sec = Seconds since JD0 at 0:00. in
KEYWORD PARAMETERS:
Keywords:
NUMBERS=st Structure with numeric values, useful at times.
FORMAT = format string. Allows output date to be customized.
The default format string is 'Y$ n$ d$ h$:m$:s$ w$'
The following substitutions take place in the format string:
Y$ = 4 digit year.
y$ = 2 digit year.
N$ = full month name.
n$ = 3 letter month name.
0n$= month as a 2 digit number: Jan=1, Feb=2, Dec=12.
d$ = day of month number.
0d$= 2 digit day of month number.
doy$= 3 digit day of year (see DDECIMAL below).
W$ = full weekday name.
w$ = 3 letter week day name.
0w$ = week day number: Sun=1, Mon=2, ... Sat=7.
h$ = hour.
m$ = minute.
s$ = second.
f$ = fraction of second (see DECIMAL, DENOMINATOR below).
I$ = time interval in days to 2 decimal places.
i$ = time interval in days as an integer.
I$ and i$ apply to sec in dt_tm_mak only.
H$ = time interval in integer hours.
sam$ = Time in seconds after midnight (DECIMAL works here).
@ = Carriage Return.
! = Line feed.
DECIMAL=dp Number of decimal places to use for fraction of
second (def=3) for f$ in format. f$ will include dec pt.
Also applies to fraction shown in sam$.
DENOMINATOR=den If given then fraction is listed as nnn/ddd
ddd is given by den. Over-rides DECIMAL keyword. Ex:
DENOM=1000 might give 087/1000 for f$ in format.
DDECIMAL=ddp Num of dec places in Day of Year (def=none).
OUTPUTS:
s = resulting string. out
COMMON BLOCKS:
NOTES:
Notes: Some examples: 'h$:m$:s$' -> 09:12:04,
'd$ n$ Y$' -> 12 Jan 1991, 'd$D h$h' -> 3D 2h, ...
MODIFICATION HISTORY:
R. Sterner. 17 Nov, 1988.
Johns Hopkins University Applied Physics Laboratory.
RES 20 Apr, 1989 --- 2 digit year.
R. Sterner, 26 Feb, 1991 --- Renamed from time_date_str.pro
R. Sterner, 27 Feb, 1991 --- Renamed from tm_dt_str.pro
R. Sterner, 28 Feb, 1991 --- changed format.
R. Sterner, 17 Jun, 1992 --- fixed a bug for large sec.
R. Sterner, 27 Sep, 1993 --- Modified to handle arrays.
R. Sterner, 2 Dec, 1993 --- Slightly modified def format.
R. Sterner, 1994 Jun 15 --- Added fraction of second.
R. Sterner, 1995 Mar 8 --- Added i$ format.
R. Sterner, 1995 Jul 6 --- Added 0d$ format.
R. Sterner, 1997 Feb 3 --- Added new keywords 0n$ and doy$ to
give month as 2 digit number and day of year.
Matthew Savoie, Systems Technology Associates --- 1997 Feb 5
fixed a bug by adding floor to: days = long(floor(idays)).
R. Sterner, 1997 Dec 18 --- Added DDECIMAL=ddec for number of
decimal places in Day of Year.
R. Sterner, 1998 Apr 14 --- added sam$ format.
R. Sterner, 1998 Apr 15 --- Added returned numeric structure.
R. Sterner, 1998 May 21 --- Fixed a bug found by Dave Watts and
Damian Murphy that caused a lost second sometimes.
R. Sterner, 1998 Jul 15 --- A bug was fixed by Tami Kovalick,
Raytheon STX, 2 digit years failed beyond 1999.
R. Sterner, 1998 Aug 10 --- Fixed a bug in the way structures are
indexed for single values.
R. Sterner, 2000 Jan 03 --- Fixed a problem that came up when year
ended in 0. Might even be a touch faster.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_mak.pro)
NAME:
DT_TM_RANGE
PURPOSE:
Extract date/time range from string with two date/times.
CATEGORY:
CALLING SEQUENCE:
dt_tm_range, in,js1,js2
INPUTS:
in = input string with 2 date/time strings. in
Must both have same form (at least same length).
KEYWORD PARAMETERS:
Keywords:
MISSING=def Defaults for missing date values:
Must be string with year, month, day in that order.
Ex: miss='1996 May 12'
Default for MISSING is current day.
ERROR=err Error flag: 0=ok.
OUTPUTS:
js1, js2 = returned times as Julian Seconds. out
COMMON BLOCKS:
NOTES:
Notes: Tries to split input string into 2 equal parts.
Missing year, month, or day may be added from default.
If second time is before first then 1 day is added.
This allows time ranges with only times, default
applies to first day.
MODIFICATION HISTORY:
R. Sterner, 1996 Nov 4
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_range.pro)
NAME:
DT_TM_TOCR
PURPOSE:
Convert from Date/Time to Carrington Rotation Number.
CATEGORY:
CALLING SEQUENCE:
cr = dt_tm_tocr(dt_tm)
INPUTS:
dt_tm = date/time string (or JS). in
KEYWORD PARAMETERS:
OUTPUTS:
cr = Carrington Rotation Number. out
COMMON BLOCKS:
NOTES:
Notes: Time is Ephemeris Time which is almost UT.
MODIFICATION HISTORY:
R. Sterner, 1996 Jun 21
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_tocr.pro)
NAME:
DT_TM_TOJS
PURPOSE:
Convert a date/time string to "Julian Seconds".
CATEGORY:
CALLING SEQUENCE:
js = dt_tm_tojs( dt)
INPUTS:
dt = date/time string (may be array). in
(see date2ymd for format)
KEYWORD PARAMETERS:
Keywords:
ERROR=err Error flag: 0=ok, else error.
/QUIET means inhibit error message.
OUTPUTS:
js = "Julian Seconds". out
COMMON BLOCKS:
NOTES:
Notes: Julian seconds (not an official unit) serve the
same purpose as Julian Days, interval computations.
The zero point is 0:00 1 Jan 2000, so js < 0 before then.
Julian Seconds are double precision and have a precision
better than 1 millisecond over a span of +/- 1000 years.
2 digit years (like 17 or 92) are changed to the closest
corresponding 4 digit year.
See also dt_tm_fromjs, ymds2js, js2ymds, jscheck.
MODIFICATION HISTORY:
R. Sterner, 23 Jul, 1992
R. Sterner, 1994 Mar 29 --- Modified to handle arrays.
R. Sterner, 1999 aug 04 --- Improved 2 digit year case.
R. Sterner, 2000 aug 17 --- Added /QUIET
Copyright (C) 1992, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\dt_tm_tojs.pro)
NAME: Dump2File PURPOSE: This procedure writes a variable into an ascii file CATEGORY: DATAFILES CALLING SEQUENCE: Dump2File, var, file, [/APPEND], [FORMAT = fmt] INPUTS: var: variable which should be written to an ascii file file: name of ascii file KEYWORD PARAMETERS: /APPEND: If set var will be appended to file FORMAT = fmt: Format string for formatted output of var EXAMPLE: a = findgen(10) Dump2File, TRANSPOSE(a), 'test.txt', FORMAT = '(5X, F4.1)' MODIFICATION HISTORY: Written by: Frank Holland, 03. Sep. 1998 21.01.99: debug statement removed 'Data were dumped into file ' message removed
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\dump2file.pro)
NAME:
DXBREAK
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Sets an IDL breakpoint
CALLING SEQUENCE:
DXBREAK, LINE ; current procedure (OR)"
DXBREAK, 'PROCNAME', LINE ; named procedure (OR)"
DXBREAK, 'path/procname.pro', LINE ; procedure path (OR)"
DXBREAK, PROCNAME, LINE ; without quotes"
DESCRIPTION:
DXBREAK is a convenience routine for setting IDL breakpoints.
The benefits over the built-in IDL procedure BREAKPOINT are:
* fewer characters to type;
* full pathname not required, just a procedure name; and
* for breakpoints within the current procedure, the file name
is not needed.
To clear breakpoints, use either DXCLEAR or BREAKPOINT, /CLEAR.
INPUTS:
LINE - the line number where the breakpoint is to be set. This
value is required.
PROCNAME - the procedure name in which the breakpoint is to be
set. Note that IDL requires that a procedure be
compiled on disk -- console-compiled or .RUN files
cannot have breakpoints set.
The name is one of:
* the procedure or function name;
* the full path to the procedure or function; OR
* an unquoted procedure or function name.
DXBREAK will search your path to find the correct
procedure. The first file found will be used.
KEYWORDS:
ONCE - if set, then the breakpoint will only occur once. The same
as the ONCE keyword to BREAKPOINT.
IS_FUNCTION - if set, and there is an ambiguity between whether
PROCNAME is a procedure or a function, then DXBREAK
will assume that it is a function.
EXAMPLE:
dxbreak, 'myfunc', 50
Set breakpoint in MYFUNC at line 50.
SEE ALSO:
BREAKPOINT, DXCLEAR
MODIFICATION HISTORY:
Written, 15 Apr 2000
Addition of NOCATCH keyword for internal testing, 21 Sep 2000, CM
Made mostly compatible with IDL v4, 21 Sep 2000, CM
Added AFTER keyword, 13 Dec 2000, CM
Removed AFTER, use _EXTRA instead, 08 Apr 2001, CM
$Id: dxbreak.pro,v 1.4 2001/04/08 16:59:55 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxbreak.pro)
NAME: DXCLEAR AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Clears an IDL breakpoint CALLING SEQUENCE: DXCLEAR, INDEX DESCRIPTION: DXBREAK is a convenience routine for clearing IDL breakpoints. Its primary benefits are that it is symmetric with DXBREAK, and it requires fewer characters to type. INPUTS: INDEX - the breakpoint number, as listed by HELP, /BREAKPOINT. EXAMPLE: dxclear, 0 Clear breakpoint number 0 SEE ALSO: BREAKPOINT, DXBREAK MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxclear.pro,v 1.2 2001/02/09 04:57:15 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxclear.pro)
NAME: DXCOMMON AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Defines DEBUG_LEVEL common block (INTERNAL) DESCRIPTION: This code fragment defines the DEBUG_LEVEL common block. This common is internal to the debugging procedures. $Id: dxcommon.pro,v 1.2 2001/02/09 04:57:15 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxcommon.pro)
NAME:
DXDOWN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Move the debugging focus deeper down the IDL call stack
CALLING SEQUENCE:
DXDOWN [ , NLEVELS ]
DESCRIPTION:
DXDOWN moves the debugging "focus" deeper down the IDL call stack.
By using this procedure and DXUP, one can navigate up and down an
existing call stack, and examine and set variables at various
levels.
While IDL always keeps the command line at the deepest call level
(i.e., where the breakpoint occurred), DXDOWN and its related
debugging procedures maintain a separate notion of which part of
the call stack they are examining -- the debugging "focus."
DXDOWN moves the debugging focus deeper by at least one level, but
never beyond the deepest level.
INPUTS:
NLEVELS - option number of levels to move. Default (and minimum)
value is 1.
EXAMPLE:
dxdown
Move the debugging focus down one level.
SEE ALSO:
DXUP, DXDOWN, DXGET, DXSET
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxdown.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxdown.pro)
NAME:
DXFINISH
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Sets an IDL breakpoint to stop upon return of the current procedure
CALLING SEQUENCE:
DXFINISH [ , NLEVELS ]
DESCRIPTION:
DXFINISH is a convenience routine for setting IDL breakpoints.
DXFINISH sets a breakpoint so that when the current procedure
finishes, execution will stop. Often when debugging one wants to
let the current procedure complete but stop at the next level.
DXFINISH does exactly that.
DXFINISH examines the state of the current IDL call stack,
determines at what point the current procedure will return, and
sets a breakpoint there. Note that the procedure in which the
breakpoint is set must be compiled and on disk.
By default the breakpoint is set with the ONCE keyword.
INPUTS:
NLEVELS - Number of call levels up to set breakpoint. Default is
1.
KEYWORDS:
ONCE - if set, then the breakpoint will only occur once. Default
value is SET, so ONCE=0 must be passed explicitly to
disable this function.
EXAMPLE:
dxfinish
Set breakpoint in calling procedure.
SEE ALSO:
BREAKPOINT, DXBREAK, DXCLEAR
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxfinish.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxfinish.pro)
NAME:
DXGET
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Gets IDL variable from a different IDL call level
CALLING SEQUENCE:
RESULT = DXGET('NAME') ; quoted variable name (OR)
RESULT = DXGET(NAME) ; unquoted variable name
DESCRIPTION:
DXGET retrieves a variable value from any point in the IDL call
stack. The DXGET and DXSET routines allow any variable at any
level to be examined and changed.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
If the variable doesn't exist, then an error message is reported.
INPUTS:
NAME - the name of the variable, either quoted or unquoted.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
EXAMPLE:
value = dxget('a')
Retrieve the value of the variable A from the debugged call level.
SEE ALSO:
DXGET, DXSET, DXUP, DXDOWN
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxget.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxget.pro)
NAME:
DXHELP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Perform HELP equivalent at any point in IDL call stack
CALLING SEQUENCE:
DXHELP, X0, X1, ..., [ LEVEL=LEVEL ]
DESCRIPTION:
DXHELP performs the equivalent of HELP for the variables at any
level in the IDL call stack.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
If the ALL keyword is set, then all variables are examined.
INPUTS:
Xi - variables to be examined, either quoted or unquoted.
Non-string expressions are diagnosed, but of course refer to
the deepest call level. If the ALL keyword is set then the
Xi parameters are ignored.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
ALL - if set, then all variables at the current focus level are
examined.
EXAMPLE:
dxhelp
Print all variables at current debugging focus level
SEE ALSO:
DXUP, DXDOWN, DXHELP, DXPRINT
MODIFICATION HISTORY:
Written, 15 Apr 2000
Added ALL keyword; changed N_PARAMS() EQ 0 behavior, CM 17 Apr
2000
DXHELP_VALUE now prints correct string and byte values, CM 23 Apr
2000
Add support for printing structures with FULL_STRUCT, CM 08 Feb
2001
Added forward_function for DXHELPFORM, CM 08 Apr 2001
Print more info about POINTER type, CM 30 Apr 2001
$Id: dxhelp.pro,v 1.5 2001/04/30 15:26:53 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxhelp.pro)
NAME: DXLRESET AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Reset the current debugging focus level (INTERNAL) CALLING SEQUENCE: DXLRESET DESCRIPTION: DXLRESET resets the current debugging focus level, if it has changed. This routine is internal to the debugging procedures. SEE ALSO: DXUP, DXDOWN, DXGET, DXSET MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxlreset.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxlreset.pro)
NAME: DXPLEVEL AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Print the current call stack (INTERNAL) CALLING SEQUENCE: DXPLEVEL DESCRIPTION: DXLRESET prints the current call stack, and highlights the debugging focus level.This routine is internal to the debugging procedures. SEE ALSO: DXUP, DXDOWN, DXGET, DXSET MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxplevel.pro,v 1.2 2001/02/09 04:57:17 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxplevel.pro)
NAME:
DXPRINT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Perform HELP equivalent at any point in IDL call stack
CALLING SEQUENCE:
DXPRINT, X0, X1, ... [, LEVEL=LEVEL, FORMAT=FORMAT ]
DESCRIPTION:
DXPRINT prints the values of variables from any level in the IDL
call stack.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
INPUTS:
Xi - variables to be printed, unquoted. Non-string expressions
are printed, but of course refer to the deepest call level.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
FORMAT - format string to be applied to data values.
EXAMPLE:
dxprint, a, b
Print A and B from the current debugging focus level
SEE ALSO:
DXUP, DXDOWN, DXHELP, DXPRINT
MODIFICATION HISTORY:
Written, 15 Apr 2000
Corrected FORMAT statement, 30 Jun 2001
$Id: dxprint.pro,v 1.3 2001/06/30 19:56:04 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxprint.pro)
NAME: DXPTRACE AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Parse the current call stack (INTERNAL) CALLING SEQUENCE: RESULT = DXPTRACE(STRING) DESCRIPTION: DXPTRACE is a function which parses the call stack, as returned by HELP, /CALL. It is internal to the debugging routines. SEE ALSO: DXUP, DXDOWN, DXGET, DXSET MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxptrace.pro,v 1.2 2001/02/09 04:57:17 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxptrace.pro)
NAME:
DXSET
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Sets IDL variable in a different IDL call level
CALLING SEQUENCE:
DXSET, 'NAME', VALUE ; quoted variable name (OR)
DXSET, NAME, VALUE ; unquoted variable name
DESCRIPTION:
DXSET sets a variable value at any point in the IDL call stack.
The DXGET and DXSET routines allow any variable at any level to be
examined and changed.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
If the variable doesn't exist, then an error message is reported,
and the variable is not set.
INPUTS:
NAME - the name of the variable, either quoted or unquoted.
VALUE - the new value of the variable.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
EXAMPLE:
dxset, 'a', 5
Set the value of the variable A to 5 in the currently debugged
call level.
SEE ALSO:
DXGET, DXSET, DXUP, DXDOWN
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxset.pro,v 1.2 2001/02/09 04:57:18 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxset.pro)
NAME:
DXUP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Move the debugging focus higher up the IDL call stack
CALLING SEQUENCE:
DXUP [ , NLEVELS ]
DESCRIPTION:
DXUP moves the debugging "focus" higher up the IDL call stack. By
using this procedure and DXDOWN, one can navigate up and down an
existing call stack, and examine and set variables at various
levels.
While IDL always keeps the command line at the deepest call level
(i.e., where the breakpoint occurred), DXUP and its related
debugging procedures maintain a separate notion of which part of
the call stack they are examining -- the debugging "focus."
DXUP moves the debugging focus higher by at least one level, but
never beyond the "root" $MAIN$ level.
INPUTS:
NLEVELS - option number of levels to move. Default (and minimum)
value is 1.
EXAMPLE:
dxup
Move the debugging focus up one level.
SEE ALSO:
DXUP, DXDOWN, DXGET, DXSET
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxup.pro,v 1.2 2001/02/09 04:57:18 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\dxup.pro)
ROUTINE: dydx
PURPOSE: compute numerical derivative accurate to second order.
In most cases this should be more accurate than the
IDL userlib procedure DERIV.
USEAGE: dydx(x,y)
INPUT:
x vector of independent variable (monitonic)
y vector of dependent variable
KEYWORD INPUT:
lin_end if set, use a one sided linear approximation for end points
OUTPUT: numerical derivative dy/dx
EXAMPLE:
!p.multi=[0,1,2]
x=[0.,1.,3.,8.,10.,13.,17.,19.,22.,25.]
y=x*(25-x) & yp=25-2*x & labels=['analytic','dydx','deriv']
plot,x,y,title='quadratic [dydx(x,y) is exact in this case]'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
x=[0.0,0.5,1.5,2.,3.,3.6,4.0,5.,6.,6.3]
y=sin(x) & yp=cos(x)
plot,x,y,title='sin(x)'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.25,0.7,0.50,0.98]
x=[-2.,-1.,-.7,-.3,-.1,0.,.1,.3,.7,1.,2]
y=exp(-x^2) & yp=-2*x*y
plot,x,y,title='gausian'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\dydx.pro)
NAME:
EARTHDIST
PURPOSE:
Calculate the great circle distance (in km) based on lats and lons.
CALLING SEQUENCE:
dist = earthdist(lat1,lon1,lat2,lon2)
INPUTS:
lat1 latitude of first point
lon1 longitude of first point
lat2 latitude of second point
lon2 longitude of second point
KEYWORD INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
Distance along great circle returned.
OPTIONAL OUTPUTS:
EXAMPLE:
print,earthdist(0,0,0,1)
111.189
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 4/05/94
MODIFICATION HISTORY:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\earthdist.pro)
NAME:
EARTHRAD
PURPOSE:
Return earth radius in specified units.
CATEGORY:
CALLING SEQUENCE:
r = earthrad(units)
INPUTS:
units = Units for earth radius (def='radians'). in
KEYWORD PARAMETERS:
OUTPUTS:
r = returned earth radius in requested units. out
COMMON BLOCKS:
NOTES:
Notes: Available units (use 2 letters min):
'radians' Radians (default).
'degrees' Degrees.
'nmiles' Nautical miles.
'miles' Statute miles.
'kms' Kilometers.
'meters' Meters.
'yards' Yards.
'feet' Feet.
MODIFICATION HISTORY:
R. Sterner, 1996 Sep 03
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\earthrad.pro)
NAME: easy_get_aix_setting PURPOSE: This procedure will type the contents of the file 'aix_setting.txt' into the log-window. CATEGORY: CASE_TOOLS CALLING SEQUENCE: easy_get_aix_setting OUTPUTS: result: correct combination of path and file EXAMPLE: easy_get_aix_setting MODIFICATION HISTORY: Written by Franz Rohrer Jan 1999
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\easy_get_aix_setting.pro)
NAME:
easy_plot_complex_example
PURPOSE:
This is a complex example to show the capabilities of easy_plot
CATEGORY:
EXAMPLES
CALLING SEQUENCE:
easy_plot_complex_example
MODIFICATION HISTORY:
Written by: Frank Holland, 15. Nov. 98.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\examples\easy_plot_complex_example.pro)
NAME:
easy_plot_simple_example
PURPOSE:
This is a simple example to show the capabilities of easy_plot
CATEGORY:
EXAMPLES
CALLING SEQUENCE:
easy_plot_simple_example
MODIFICATION HISTORY:
Written by: Frank Holland, 15. Nov. 98.
17.02.99: Added a 2nd example
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\examples\easy_plot_simple_example.pro)
NAME:
EI
PURPOSE:
Set the system variable to allow for large pasting of data using
X. Only necessary for the alphas. This has the side effect of
not allowing use of the editing (arrow) keys. This procedure
toggles this ability on and off. NOTE: This is probably a bug
in IDL and therefore the need for this procedure will disappear in
the near future.
CALLING SEQUENCE:
ei
INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
EXAMPLE:
ei
... paste in large amts of data ...
ei
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
Added change of prompt Jeff Hicke 05/20/94
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\ei.pro)
NAME:
ELECTRON_MFP
PURPOSE:
This function returns the elastic mean-free-path for electrons
of energy E, in a material having density N, and atomic number Z.
CALLING SEQUENCE:
Result = ELECTRON_MFP(Z,A,RHO,E)
INPUTS:
Z = Atomic number
A = Atomic weight (g/mole)
RHO = Density (g/cm3)
E = electron energy in keV
OUTPUTS:
This function returns the elastic mean-free-path, in angstroms.
EXAMPLE:
The elastic mean-free-path of tungsten (Z=74, Rho=19.35) at an
electron energy of 100 keV = ELECTRON_MFP(74,183.85,19.35,100.)
MODIFICATION HISTORY:
Written by D. L. Windt, Bell Labs, June 1994
windt@bell-labs.com
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\windt\electron_mfp.pro)
NAME:
ELLFIT
PURPOSE:
Fit an ellipse to a 2-d probability distribution.
CATEGORY:
CALLING SEQUENCE:
ellfit, pd, xm, ym, ang, ecc, a, b
INPUTS:
pd = 2-d probability distribution. in
KEYWORD PARAMETERS:
OUTPUTS:
xm, ym = Mean X and Y coordinates (array indices). out
ang = angle of major axis (deg). out
ecc = eccentricity of fitted ellipse. out
a, b = semimajor, semiminor axis of fitted ellipse. out
COMMON BLOCKS:
NOTES:
Notes: An ellipse is fit by matching its moment of inertia
to the given array. A threshold image should be
normalized to 1 before doing the fit, otherwise the
ellipse will not be the correct size.
See also genellipse.
Here is a simple example:
loadct,13
d = rebin(shift(dist(200),100,100),200,400)
z = rot(d,30) lt 50
tvscl,z
ellfit,z,xm,ym,ang,ecc,a,b
genellipse,xm,ym,ang,a,b,x,y
plots,x,y,/dev,color=!d.n_colors/2
MODIFICATION HISTORY:
R. Sterner. 10 June, 1986.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ellfit.pro)
NAME:
ELLIPSE
PURPOSE:
Plot specified ellipse on the current plot device.
CATEGORY:
CALLING SEQUENCE:
ellipse, a, b, tilt, a1, a2, [x0, y0]
INPUTS:
a = semi-major axis of ellipse (data units). in
b = semi-minor axis of ellipse (data units). in
[tilt] = angle of major axis (deg CCW from X axis, def=0). in
[a1] = Start angle of arc (deg CCW from major axis, def=0). in
[a2] = End angle of arc (deg CCW from major axis, def=360). in
[x0, y0] = optional arc center (def=0,0). in
KEYWORD PARAMETERS:
Keywords:
/DEVICE means use device coordinates .
/DATA means use data coordinates (default).
/NORM means use normalized coordinates.
COLOR=c plot color (scalar or array).
LINESTYLE=l linestyle (scalar or array).
OUTPUTS:
COMMON BLOCKS:
NOTES:
Note: all parameters may be scalars or arrays.
MODIFICATION HISTORY:
D P Steele, ISR, 27 Oct. 1994: modified from ARCS.PRO by R. Sterner.
Department of Physics and Astronomy
The University of Calgary
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\ellipse.pro)
NAME: ELLIPSE VERSION: 4.0 PURPOSE: Draws an ellipse, around CENTER, with radii given by RADII, optionally rotating it by angle ROT. The drawing is done in the currently defined plot area. Alternatively, a *SHAPE* representation (see SHAPE_VER for definition) of the ellipse may be returned through the SHAPEOUT keyword. DATA coordinate system is assumed unless specified otherwise by one of the keywords /DEVICE or /NORMAL. CATEGORY: General Graphics. CALLING SEQUENCE: ELLIPSE, CENTER = CENT, RADII = RD, [, optional keywords] INPUTS: None. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: CENTER 2 dimensional vector, ellipse center location, format [x,y], mandatory. RADII 2 dimensional vector, contains the x and y radii (in order), mandatory. ARC Optional. Allows to draw an elliptical arc. Accepts a vector of length 2 containing the start and end angles for the arc. If only one value is provided, the arc is drown from angle 0 to this value if it is positive, or from this value to 0 if it is negative. The angles are assumed to be in radians unless DEGREES is set. /DEGREES Switch. Specifies that the rotation (and arc) angles are given in degrees. ROTATE Optional. Angle of rotation in the mathematical positive direction. Assumed in radians, unless DEGREES is set. ROTATION_CENTER Optional. Accepts a two element vector specifying the center of rotation. Ignored if ROTATE is not given. Defaults to center of shape. /FILL Switch. Causes the ellipse to be filled with a solid pattern. /DEVICE Standard IDL plotting interpretation. /NORMAL Ditto. /NO_SHOW Switch. If set, no plotting is done, but the shape is generated and may be returned through SHAPEOUT. SHAPEOUT Optional output, see below. _EXTRA A formal keyword used to pass all plotting keywords. Not to be used directly. See comment in RESTRICTIONS. OUTPUTS: None. OPTIONAL OUTPUT PARAMETERS: SHAPEOUT When provided with the name of a variable,on return the variable contains the *SHAPE* representation of the ellipse. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: If the DATA coordinate system is used and the plot area is defined with nonlinear (logarithmic) axes, the shape won't look like an ellipse. ELLIPSE calls either PLOTS or (when /FILL is used) POLYFILL. Since some graphics keywords work only with PLOTS, or only with POLYFILL, some care must be exercised. PROCEDURE: Uses calls to DEFAULT, ONE_OF, SHAPE_COCON and SHAPE_TRANS from MIDL. Generates a (2,N) array containing a sufficient number of ellipse points to yield a smooth curve. N is variable, depending both on the ellipse size and on the pixel size of the current output device. MODIFICATION HISTORY: Created 15-JUL-1991 by Mati Meron. Modified 15-DEC-1991 by Mati Meron. Added size and device dependence of the number of plot points. Modified 15-OCT-1992 by Mati Meron. Added rotation. Modified 15-DEC-1993 by Mati Meron. Now ELLIPSE takes advantage of the keyword inheritance property and accepts all IDL plotting keywords. Modified 1-MAY-1995 by Mati Meron. Added capability to draw an elliptical arc. Modified 25-JUL-1999 by Mati Meron. Added keyword SHAPEOUT. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\ellipse.pro)
NAME:
EMBED
PURPOSE:
Embed an array in a larger array.
CATEGORY:
CALLING SEQUENCE:
b = embed(a,w)
INPUTS:
a = input array (2-d). in
w = number of elements to add around edge. in
KEYWORD PARAMETERS:
Keywords:
VALUE=v. Value for added border (def=0).
OUTPUTS:
b = resulting larger array with a centered. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 13 Dec, 1990
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\embed.pro)
NAME:
embedstr
PURPOSE:
This function attachs one stringarray to another stringarray reducing posibble n-dimensional fields to a vector
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
Result=embedstr(string1=string1,string2=string2)
INPUTS:
String1: first string array
String2: second string array
OUTPUTS:
The function returns a stringarray where stringarray 1 is concatenaded
to stringarray 2
EXAMPLE:
test1=sindgen(2,2)
test2=sindgen(3)
Result=embedstr(string1=test1,string2=test2)
print,result
0 1 2 3 0 1 2
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), Jan. 3 1997
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\embedstr.pro)
NAME:
emensch
PURPOSE:
This function can be used by 'axis' to define axis-labels in a better readable format
CATEGORY:
PLOT/PLOTXY
CALLING SEQUENCE:
emensch,axis,index,t
INPUTS:
axis : for future use
index : for future use
t : the value which should be formatted
EXAMPLE:
axis,xaxis=1,/xtype,xrange=[1e-4,10],xstyle=1,/save,xtickformat='emensch'
MODIFICATION HISTORY:
Written by: Franz Rohrer April 1997
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\emensch.pro)
NAME:
ENDIAN
PURPOSE:
Function indicating which endian the current machine uses.
CATEGORY:
CALLING SEQUENCE:
f = endian()
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/LIST means list result to screen.
/TEXT means return /LIST text.
OUTPUTS:
f = 0 if little, 1 if big. out
COMMON BLOCKS:
NOTES:
Note: this is the order the bytes are for multibyte
numeric values. Use the IDL procedure BYTEORDER
to switch endian (use /LSWAP for 4 byte integers,
/L64SWAP for 8 byte integers).
MODIFICATION HISTORY:
R. Sterner, 1999 Dec 13
R. Sterner, 2000 Apr 11 --- Added /TEXT
Copyright (C) 1999, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\endian.pro)
NAME:
ENDPS
PURPOSE:
close postscript file, reopen display
CALLING SEQUENCE:
ENDPS
INPUTS:
KEYWORD INPUTS:
notime don't timestamp
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 9/22/92
MODIFICATION HISTORY:
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ESRG\endps.pro)
NAME:
end_mplot
PURPOSE:
Restores default values of
!P.MULTI, !X.OMARGIN, !Y.OMARGIN, !X.MARGIN, !Y.MARGIN
which were changed in init_mplot
CATEGORY:
PLOT/MPLOT
CALLING SEQUENCE:
end_mplot [, save_sysvar]
OPTIONAL INPUTS:
save_sysvar: structure with the following tags (from init_mplot):
pm: !P.MULTI
xom: !X.OMARGIN
yom: !Y.OMARGIN
xm: !X.MARGIN
ym: !Y.MARGIN
The system variables will be restored to these data.
REVISION HISTORY:
Written Theo Brauers, Frank Holland, June 1997
02.02.2000: Added input parameter save_sysvar (FH)
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\end_mplot.pro)
NAME:
ENTER
PURPOSE:
Prompted entries allowing defaults. Help, IDL/DCL commands.
CATEGORY:
CALLING SEQUENCE:
value = enter(type, prompt, default, [exit_flag, help_text])
INPUTS:
type = Data type to return. in
Allowed types are:
'STRING' = string
'BYTE' = byte
'INTEGER' = integer
'LONG' = long integer
'FLOAT' = float
'DOUBLE' = double float
prompt = prompt string. in
Any occurence of $DEF in the prompt string
is replaced by the default value, so the
prompt message may display the default.
default = default value. in
help_text = text to display for ? command. in
String or string array for multiple lines.
$DEF in the help string is replaced by
the def. value.
KEYWORD PARAMETERS:
OUTPUTS:
exit_flag = exit status flag. out
Valid values are:
0 = normal exit.
1 = quit on return.
-1 = backup to last entry.
11 = invalid data type.
12 = def. val. cannot convert to desired
data type.
value = returned value of desired type. out
COMMON BLOCKS:
NOTES:
Notes: The following commands are allowed as ENTER entries:
Value requested.
Null entry. Gives default value
(for calling error may return error flag).
Expressions. Processes given IDL expression.
Q. Returns quit value (1) in exit flag.
B. Returns backup value (-1) in exit flag.
IDL statment. Executes given IDL statement.
$ statement. Executes given shell statement.
MODIFICATION HISTORY:
R. Sterner. 17 Oct, 1986.
RES 9 OCT, 1989 --- CONVERTED TO SUN.
RES 13 Nov, 1989 --- put $DEF in prompt and help_text.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\enter.pro)
NAME:
ENVELOPE
PURPOSE:
Return the min/max envelope of a time series.
CATEGORY:
CALLING SEQUENCE:
envelope, y, w, mn, mx, ind
INPUTS:
y = time series signal. in
w = window width in samples. in
KEYWORD PARAMETERS:
OUTPUTS:
mn = array of mins in each window. out
mx = array of maxes in each window. out
ind = array of window midpoint indices. out
COMMON BLOCKS:
NOTES:
Notes: data type of mn and mx are the same as
input array y.
To overplot envelope do:
oplot,ind,mn & oplot,ind,mx
To polyfill the envelope do:
polyfill, [ind,reverse(ind)],[mn,reverse(mx)]
MODIFICATION HISTORY:
R. Sterner, 19 Sep, 1991
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\envelope.pro)
NAME: enz2html PURPOSE: write a html file with info of about an enzfile, produce overview plots of the datasets. CATEGORY: DATAFILES/ZCHN CALLING SEQUENCE: ENZ2HTML, file_name, html_name, ps_name INPUTS: file_name: the name of the enz data File OUTPUTS: ps_name: the name of the ps graph html_name: the name of the htmlfile MODIFICATION HISTORY: Written by: T.Brauers
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\enz2html.pro)
NAME:
enztime2js
PURPOSE:
converts time info in ENZ/ZEICHN file to julsec
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
Result = ENZTIME2JS(dvalue, ix, ref)
INPUTS:
dvalue: array of values (output of IRZN)
ix: number of records (output of IRZN)
ref: reference date
OUTPUTS:
array with julian seconds
EXAMPLE:
IRZN, 'TEST.ZEICHN', dvalue, ix, iy, fb, text, header, err
ref = text[0]
js = ENZTIME2JS(dvalue, ix, ref)
REVISION HISTORY:
Written Theo Brauers, June 1997
Corrected
Revised T.B. Sep 1997
Revised T.B. Oct 1997, renamed to enztime2js
Modified T.B. Feb 1999, new keywords Reference and nomessage
different interpretation reference date
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\tb_lib\enztime2js.pro)
NAME:
enz_get_param
PURPOSE:
to read one parameter from a enz/zus-file and return the result as a ncdf-like structure
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
enz_get_param,file=file,name=name,inhalt=inhalt[,zus=zus][,fill_value=fill_value][,nocache=nocache]
INPUTS:
file : file name
name : parameter name
KEYWORD PARAMETERS:
zus : 0: enz-file (default) 1: zus-file
fill_value : fill_value for irzn
nocache : to suppress caching of enz/zus-file
OUTPUTS:
inhalt : ncdf-like structure
COMMENT:
Has to be improved to handle other ncdf-tags as defined in ncdf-header
EXAMPLE:
MODIFICATION HISTORY:
Written by: Franz Rohrer Aug 1998
Modified 7.10.98 FR nocache included
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\enz_get_param.pro)
NAME: enz_header2ncdf_structure PURPOSE: This procedure converts the header of an enz file into ncdf structures CATEGORY: DATAFILES/FILTER CALLING SEQUENCE: enz_header2ncdf_structure, header, global_struc, time_struc, param_struc INPUTS: header: header of enz file as returned by cache_enz KEYWORD PARAMETERS: /NO_TIME_FLAG: If set time_struc will be returned without flag: 'INTERVAL_T' /VERBOSE: Informational messages will be issued by this program OUTPUTS: global_struc: structure with global attributes of the dataset as defined for the ICG structure. Also includes experiment specific information. time_struc: structure with time attributes of the dataset as defined for the ICG structure. param_struc: structure with parameter attributes of the dataset as defined for the ICG structure. RESTRICTIONS: The translation of the enz header into ncdf structures requires the following structure of the enz header: ------------------------snip------------------------------------------- ... ; any information (not considered) X_HEADER=NETCDF_GLOBAL ... ; any entry (KEYWORD=VALUE) in this section ... ; is translated into global_struc ... ; if KEYWORD is identified as a valid global keyword. X_HEADER=NETCDF_EXPERIMENT ... ; any entry (EXP_NAME: KEYWORD=VALUE) in this section ... ; is translated into exp_struc which will be returned ... ; as tag of global_struc. X_HEADER=NETCDF_TIME ... ; any entry (KEYWORD=VALUE) in this section ... ; is translated into time_struc ... ; if KEYWORD is identified as a valid time keyword. X_HEADER=NETCDF_PARAMETER ... ; any entry (KEYWORD=VALUE) in this section ... ; is translated into param_struc ... ; if KEYWORD is identified as a valid parameter keyword. X_HEADER=ENZ ... ; any information (not considered) ------------------------snip------------------------------------------- EXAMPLE: see ex_enz_header2ncdf_structure MODIFICATION HISTORY: Written by: Frank Holland, 24.06.1999 25.06.1999: Kommentar eingefügt 09.08.1999: New keyword parameter NO_TIME_FLAG 10.08.1999: New keyword parameter VERBOSE 25.10.1999: Bug removed if pstruc was not defined 18.11.1999: Bug removed if enz file was written by write_enz [() entries in header] 10.03.2000: Added X_HEADER = NETCDF_EXPERIMENT section for experiment specific information 27.03.2000: Extract allowed tag names from nc_def_... routines (code not activated yet) 28.03.2000: Added alias time tags
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fh_lib\enz_header2ncdf_structure.pro)
NAME:
ENZ_INFO
PURPOSE:
returns a structure with info about
a ZEICHN file (KFA ICG3 data format)
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
file_info=ENZ_INFO(dvalue,ix,iy,fb,text,header,filename)
INPUTS:
the output of the irzn
KEYWORD PARAMETERS:
Keywords:
fill_value: do not process data equal fill_value
OPTIONAL INPUTS:
OUTPUTS:
a structure of info about a ncdf-file see create_info_struct for details
.file_info.name : name of file
.file_info.filetype : 'zus'
.file_info.filedate : date of file
.record_info.jstime[0] : start-time in julian seconds (double)
.record_info.jstime[1] : end-time in julian seconds (double)
.record_info.ntime[0] : start-time in normal date and time (string)
.record_info.ntime[1] : end-time in normal date and time (string)
.record_info.n_records :number of rows
.record_info.n_sets :number of columns
.pi.pi_name :
.pi.email :
.pi.phone_number :
.pi.organisation :
.hrefs.ps : 'ps' (reference to ps-file: filename+.ps )
.hrefs.data : 'data'
.hrefs.html : 'html' (reference to html-file: filename + .savinfo.html )
.data.text :string-array : description of a data columnstring-array
.data.nvalid :array containing the number of valid values of a column
.data.mean :array containing the avarage values of a data column
.data.median :array containing the median values of a data column
.data.stdev :array containing the standard deviation of a column
.data.minimum:array containing the lowest values of a data column
.data.maximum:array containing the greatest values of a data column
.header.text :string array containing the header of the file (like output of IRZN)
.experiment.text :containing the text of structure experiment
EXAMPLE:
IRZN, filename, dvalue, ix, iy, fb, text, header, err
file_info=ENZ_INFO(dvalue,ix,iy,fb,text,header,filename)
REVISION HISTORY:
Written Marsy Lisken, June 1998
Corrected 10.7. 1998
Revised
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\enz_info.pro)
NAME:
ENZ_NCDF
PURPOSE:
This Procedure generates the structure INHALT for an ENZ-file
and writes it to a ncdf-file
CATEGORY:
DATAFILES/ZCHN
CALLING SEQUENCE:
enz_ncdf,fname,new_fname,fillvalue=xl,err,errmess=errmess,options
INPUTS:
fname: the name of the ENZ-file (string-var)
new_fname: the name of the ncdf-file (string-var)
optional, default: new_fname=fname.nc
options: optional
KEYWORD PARAMETERS:
fillvalue: the numeric value for '====' input
default: -12345
errmess: returns a error message
nowrite: no netcdf file will be written
OUTPUTS:
err: flag indicating error err=1 : no parameter
err=2 : filesize <0 (output of IRZN)
err=3 : no header found ( " )
err=4 : number of columns=0 ( " )
err=5 : overwriting label ( " )
OPTIONAL OUTPUTS:
inhalt: the defined structure inhalt
SIDE EFFECTS:
uses the procedures IRZN, RPL_STR, HEADKEYS, ZCHN_KEYS
TENZ2JS,JS2INST
JD2YMD (Ray Sterner Lib)
@gen_inh2, NCDF_W, NCDF_CH
EXAMPLE:
ENZ_NCDF,'t.enz','test.nc',err
result=f_history('test.nc') ---> (history contains the whole header)
MODIFICATION HISTORY:
Written Theo Brauers, June 1997
Completed Marsy Lisken, January 1998
Revised
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\fr_lib\enz_ncdf.pro)
NAME:
EOPDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Read and interpolate tabulated earth orientation parameters
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
EOPDATA, JDUTC, PMX, PMY, UT1_UTC, DPSI, DEPS, $
/RESET, FILENAME=, ANGUNITS=, TBASE=
DESCRIPTION:
The procedure EOPDATA reads, interpolates and returns Earth
orientation parameters used for precision earth-base astronomy
applications.
** NOTE: The user is responsible for downloading and maintaining an
up-to-date file of earth orientation parameters from the
International Earth Rotation Service. See below. **
This interface is somewhat provisional. See OPEN QUESTIONS below.
The values returned are described below. These descriptions are
taken from the Explanatory Supplement to IERS Bulletins A and B.
* PMX and PMY, the coordinates of the Celestial Ephemeris Pole
(CEP) relative to the earth-fixed International Reference Pole
(IRP). The x-axis is in the direction of the IERS Reference
Meridian (IRM), the y-axis is in the direction 90 degrees West
longitude. The time series of PMX and PMY is referred to as
"polar motion."
These are the coordinates of the earth rotation pole, as seen
in an *earth-fixed* coordinate system. A station whose
coordinates are given in earth-fixed coordinates referred to
the ITRS can be transformed to the earth-fixed coordinates
referred to the true rotation pole of date using the following
matrix transformation:
R_TRUE = RX(PMY) ## RY(PMX) ## R_ITRS
where the matrices RX and RY are defined below.
* UT1, the the rotation angle about the pole. It is related to
the Greenwich mean sidereal time (GMST) by a conventional
relationship (Aoki et al., 1982). It gives access to the
direction of the International Reference Meridian IRM in the
ICRS, reckoned around the CEP axis. It is expressed as the
difference UT1-UTC. Thus, the value of UT1 is computed as:
UT1 = UT1_UTC + UTC
where UTC is the UTC time, expressed in seconds.
* DPSI and DEPS are the offsets in longitude and obliquity of the
celestial pole with respect to its direction defined using the
conventional IAU precession/nutation theory. An a priori
correction model is available in the IERS Conventions (1996),
(McCarthy, 1996). The expressions to compute the nutation
angles are:
DEPS_TRUE = DEPS_1980 + DEPS ;; Nutation in obliquity
DPSI_TRUE = DPSI_1980 + DPSI ;; Nutation in longitude
where DPSI_1980 and DEPS_1980 are the nutation values
determined from the IAU 1980 Nutation Theory; and DPSI_TRUE and
DEPS_TRUE are the nutations to be used as arguments to further
precession and nutation computations.
For requested times which are between tabular values, a linear
interpolation is performed. This is not exactly the correct
procedure, and can result in errors of +/- 0.1 mas in the earth
polar motion and 1 usec in UT1 (see McCarthy & Gambis 1997).
DATA FILES and MAINTENANCE
The user is responsible for downloading and maintaining the earth
orientation parameters file as supplied by the IERS. The format
of the files is the "Final" EOP data ASCII format. They can be
downloaded here:
ftp://maia.usno.navy.mil/ser7/finals.all ;; from May 1976-present
ftp://maia.usno.navy.mil/ser7/finals.data ;; from Jan 1992-present
The user must place this file in a known location, and in *at
least the first call*, this filename must be passed using the
FILENAME keyword.
EOPDATA will load the data once on the first call, and keep a
cached copy for subsequent calls. On a daily basis the file will
be reloaded in case the quantities have been updated from the
server. A reload of data can be forced using the RESET keyword.
ROTATION MATRICES
The rotation matrices RX(T) and RY(T) mentioned above in relation
to polar motion are:
RX(T) =EQ= [[1,0,0], [0,cos(T),sin(T)], [0,-sin(T),cos(T)]]
RY(T) =EQ= [[cos(T),0,-sin(T)], [0,1,0], [sin(T),0,cos(T)]]
RZ(T) =EQ= [[cos(T),sin(T),0], [-sin(T),cos(T),0], [0,0,1]]
and are meant to be applied to a vector R as, RX(T) ## R.
OPEN QUESTIONS
How will the transition to a new IERS EOP series be accomplished?
Using a keyword?
Should there be a quality flag? The EOP file contains a
"predicted" flag, and also there are rows which contain no value
at all. These should probably be flagged somehow.
INPUTS:
JDUTC - a vector or scalar, the UTC time for which earth
orientation parameters are requested, expressed in Julian
Days. The value of the keyword TBASE is added to this
quantity to arrive at the actual Julian date.
OUTPUTS:
PMX, PMY - the earth-fixed angular coordinates of the celestial
ephemeris pole, measured in ANGUNITS units.
UT1_UTC - the value of UT1 - UTC, expressed in seconds.
DPSI, DEPS - the corrections to the IAU 1980 theory of Nutation,
for nutation in longitude and obliquity, expressed in
ANGUNITS units.
KEYWORD PARAMETERS:
FILENAME - scalar string, on the first call, the name of the file
from which earth orientation parameters will be read.
Default value: (none)
TBASE - a fixed epoch time (Julian days) to be added to each value
of JDUTC. Since subtraction of large numbers occurs with
TBASE first, the greatest precision is achieved when TBASE
is expressed as a nearby julian epoch, JDUTC is expressed
as a small offset from the fixed epoch.
Default: 0
ANGUNITS - scalar string, output units of angular parameters.
Possible values are 'ARCSEC' or 'RADIAN'.
Default value: 'RADIAN'
RESET - if set, forces EOP file to be re-read.
EXAMPLE:
SEE ALSO:
HPRNUTANG, TAI_UTC (Markwardt Library)
PRECESS, PREMAT, JPRECESS, BPRECESS (IDL Astronomy Library)
REFERENCES:
Aoki, S., Guinot, B., Kaplan, G.H., Kinoshita, H., McCarthy, D.D.,
Seidelmann, P.K., 1982: Astron. Astrophys., 105, 359-361.
McCarthy, D. D. (ed.) 1996: IERS Conventions, IERS T.N. 21.
http://maia.usno.navy.mil/conventions.html
McCarthy, D. \& Gambis, D. 1997, "Interpolating the IERS Earth
Orientation Data," IERS Gazette No. 13,
http://maia.usno.navy.mil/iers-gaz13
Instructions for high precision EOP data interpolation, not done
in this procedure.
Ray, J. & Gambis, D. 2001, "Explanatory Supplement to IERS
Bulletins A and B,"
http://hpiers.obspm.fr/iers/bul/bulb/explanatory.html
Explains meanings of earth orientation parameters used and
returned by this procedure.
Definition of Final EOP data format
ftp://maia.usno.navy.mil/ser7/readme.finals
MODIFICATION HISTORY:
Written, 30 Jan 2002, CM
Documented, 14 Feb 2002, CM
Add default message, 01 Mar 2002, CM
More robust handling of input file, 10 Mar 2002, CM
$Id: eopdata.pro,v 1.4 2002/03/17 18:46:16 craigm Exp $
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\craigm\eopdata.pro)
NAME:
EPSINIT
PURPOSE:
Redirect plots and images to Encapsulated Postscript File.
CATEGORY:
CALLING SEQUENCE:
epsinit, outfile
INPUTS:
outfile = EPS file name (def=idl.eps). in
KEYWORD PARAMETERS:
Keywords:
XSIZE=xsz Plot size in X (def=6).
YSIZE=xsz Plot size in Y (def=6).
/CM Means size units are cm (else inches).
/COLOR means do color PostScript (def is B&W).
/VECTOR to use vector fonts instead of postscript fonts.
/QUIET turns off epsinit messages.
OUTPUTS:
COMMON BLOCKS:
eps_com,xsv,ysv,psv,dsv,ou
NOTES:
Notes: 8 bit gray scale or color is set. Times Roman
font is used. To over-ride just use a call to device
after epsinit to set desired values.
MODIFICATION HISTORY:
R. Sterner, 1996 Aug 2
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\epsinit.pro)
NAME:
EPSTERM
PURPOSE:
Terminate Encapsulated Postscript plotting.
CATEGORY:
CALLING SEQUENCE:
epsterm
INPUTS:
KEYWORD PARAMETERS:
Keywords:
/QUIET turns off epsterm messages.
OUTPUTS:
COMMON BLOCKS:
eps_com,xsv,ysv,psv,dsv
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1996 Aug 2
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\epsterm.pro)
NAME:
eps_get_boundingbox
PURPOSE:
This function returns the boundingbox of an eps file
CATEGORY:
PROG_TOOLS/EPS
CALLING SEQUENCE:
result=eps_get_boundingbox(eps_txt)
INPUTS:
eps_txt: This is the text of a eps file
EXAMPLE:
result=eps_get_boundingbox(get_file('idl.eps'))
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Oct-05
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\eps_get_boundingbox.pro)
NAME:
eps_set_boundingbox
PURPOSE:
This Routine exchanges the boundingbox variable of an eps file
CATEGORY:
PROG_TOOLS/EPS
CALLING SEQUENCE:
eps_set_boundingbox,eps_txt,boundingbox
INPUTS:
eps_txt: This is the text of a eps file
boundingbox: the boundingbox to set
OUTPUTS:
This routine replaces the boundingbox
EXAMPLE:
txt=eps_set_boundingbox(get_file('idl.eps'),[20, 100, 551, 525])
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1999-Sep-18
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\eps_set_boundingbox.pro)
NAME:
EQV
PURPOSE:
Interactive equation viewer and curve fitter.
CATEGORY:
CALLING SEQUENCE:
eqv
INPUTS:
KEYWORD PARAMETERS:
Keywords:
FILE=filename Name of equation file to view.
LIST=list List of equation file names. If LIST is
given then FILE is ignored.
XS=x, YS=y Optional arrays of scatterplot points.
Useful for interactive curve fitting.
PSYM=p Scatter plot symbol (def=2 (*)).
SNAPSHOT=file name of snapshot file (def=snapshot.eqv).
TITLE=tt plot title (over-rides value from eqv file).
XTITLE=tx X axis title (over-rides value from eqv file).
YTITLE=ty Y axis title (over-rides value from eqv file).
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 26 Oct, 1993
R. Sterner, 1998 Jan 15 --- Dropped use of !d.n_colors.
Copyright (C) 1993, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\eqv.pro)
NAME:
EQV2
PURPOSE:
Interactively plot a function on current plot.
CATEGORY:
CALLING SEQUENCE:
eqv2, file
INPUTS:
file = equation file. in
KEYWORD PARAMETERS:
Keywords:
COLOR=clr Plot color (def=!p.color).
TOP=top Returns widget ID of top level base.
Use widget_control to retrieve or store info structure.
OK=wid Given ID of widget to notify when OK button pressed.
If not given no OK button is displayed.
WID_OK=wid Widget ID of the OK button.
Can use to set /input_focus.
GROUP_LEADER=grp Set group leader.
OUTPUTS:
COMMON BLOCKS:
eqv2_help_com
eqv2_help_com
NOTES:
Note: The QUIT button allows burning in the final curve and lists its
values. The LIST button lists the current curve parameters.
Equation file format: This file defines the equation, the x range
and range of each adjustable parameter. The file is a text file with
certain tags. Null and comment lines (* in first column) are allowed.
The tags are shown by an example:
eq: y = a + b*x + c*x^2
title: Parabola
xrange: -10 10
n_points: 100
par: a -50 50 0
par: b -50 50 0
par: c -10 10 1
The parameter tags are followed by 4 items: Parameter name (as in the
equation), min value, max value, initial value. An optional 5th item
may be the word int to force an integer value (for flags or harmonics).
MODIFICATION HISTORY:
R. Sterner, 1998 Feb 24
R. Sterner, 1998 Apr 1 --- Added /NO_BLOCK to xmanager.
R. Sterner, 1998 May 12 --- Added plot color. Also added TOP=top.
R. Sterner, 1998 May 13 --- Added OK button to signal other program.
Also GROUP_LEADER.
R. Sterner, 1998 May 14 --- Added LOCK=lck and UNLOCK=ulck to
eqv2_set_val and eqv2_get_val. Locks parameters.
R. Sterner, 1998 Oct 27 --- Fixed bug added by the plot color addition.
Copyright (C) 1998, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\eqv2.pro)
NAME:
EQV3
PURPOSE:
Execute IDL code using interactively varied parameters.
CATEGORY:
CALLING SEQUENCE:
eqv3, file
INPUTS:
file = equation file. in
Instead of file name the contents of the file may be
given in a text array (same format).
KEYWORD PARAMETERS:
Keywords:
P1=var1, P2=var2, ... P5=var5 Up to 5 variables.
may be passed into the program using these keywords.
May reference p1, p2, ... in the IDL code to execute.
/WAIT means wait until the routine is exited instead
returning right after startup.
PARVALS=pv Structure with parameter names and values.
Must be used with /WAIT or pv will be undefined.
EXITCODE=excd 0=normal, 1=cancel. Must use with /WAIT.
RES=res Returned widget ID of an unused top level
base that will on exit from EQV3 contain a structure
with parameter names and final values.
widget_control,res,get_uval=s,/dest
s.name and s.val are arrays of names and values.
TOP=top Returns widget ID of top level base.
Use widget_control to retrieve or store info structure.
OK=wid ID of widget to notify when OK button pressed.
If not given no OK button is displayed.
Useful to allow a higher level widget routine to call
EQV3. The OK button then sends an event to the higher
level widget which can then destroy the eqv3 widget.
WID_OK=wid Returned widget ID of the OK button.
Can use to set /input_focus.
GROUP_LEADER=grp Set group leader.
XOFFSET=xoff, YOFFSET=yoff Widget position.
OUTPUTS:
COMMON BLOCKS:
eqv3_var_com
eqv3_var_com
eqv3_help_com
eqv3_var_com
eqv3_help_com
NOTES:
Notes: Use the Help button for more details.
Equation file format: This text file defines the IDL code,
and range of each adjustable parameter.
Null and comment lines (* in first column) are allowed.
The tags are shown by an example:
title: Parabola
eqv: x=maken(-10,10,100) & plot,a + b*x + c*x^2
par: a -50 50 0
par: b -50 50 0
par: c -10 10 1
The parameter tags are followed by 4 items: Parameter name (as in the
equation), min value, max value, initial value. An optional 5th item
may be the word int to force an integer value (for flags or harmonics).
MODIFICATION HISTORY:
R. Sterner, 2000 May 11 --- From EQV2.
R. Sterner, 2000 Aug 21 --- Added XOFFSET, YOFFSET.
Copyright (C) 2000, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\STERNER\eqv3.pro)
NAME: ERFINT_MM VERSION: 4.3 PURPOSE: Calculates a definite integral of the error function. CATEGORY: Mathematical function (general). CALLING SEQUENCE: Result = ERFINT_MM (Y [,X]) INPUTS: Y Numeric, otherwise arbitrary. Upper integration limit. OPTIONAL INPUT PARAMETERS: X Numeric, otherwise arbitrary. Lower integration limit. Defaults to 0. KEYWORD PARAMETERS: None. OUTPUTS: Returns an integral of the error function between X and Y. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: If both X and Y are arrays, they need to have same number of elements. Scalar-scalar and scalar-array combinations are permitted. PROCEDURE: Straightforward. Uses CALCTYPE, CAST, DEFAULT and ERRORF_MM from MIDL. MODIFICATION HISTORY: Created 10-MAY-2002 by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\erfint_mm.pro)
NAME: ERRBARS VEERSION: 4.0 PURPOSE: Overplots error bars over an existing plot. More general than the library routines ERRPLOT and PLOTERR, since it allows to independently vary both X and Y errors, and allows for nonsymmetric error bars. CATEGORY: Plotting. CALLING SEQUENCE: ERRBARS, [X,] Y [, XERR = XER, YERR = YER] INPUTS: X, Y Vectors containing the data points' coordinates. If only one is given it is taken to be Y, same as in the PLOT command. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: XERR Either a vector or a (2,N) array where N is the number of the data points. Contains the X-errors. If given as a 2 dimensional array, the entries XERR(0,i) and XERR(1,i) are taken as the errors of X(i) in the negative and positive directions, respectively. If given as a vector, the entry XERR(i) serves as both the negative and positive error of X(i) and therefore symmetric error bars are drawn. If not provided, the default is no X-errors. YERR Same as above, for the Y-errors. _EXTRA A formal keyword used to pass all plotting keywords. Not to be used directly. See comment in RESTRICTIONS. OUTPUTS: None. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: The keywords passed through _EXTRA are transferred to the PLOTS routine. No keyword verification is performed by ERRBARS. PROCEDURE: Straightforward. Uses DEFAULT from MIDL. MODIFICATION HISTORY: Created 10-DEC-1991 by Mati Meron. Modified 15-DEC-1993 by Mati Meron. Now ERRBARS takes advantage of the keyword inheritance property and accepts most of IDL plotting keywords. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\errbars.pro)
NAME: ERRORF_MM VERSION: 4.0 PURPOSE: Calculates the error function. Replacement for the IDL ERRORF function which accepts only real input. CATEGORY: Mathematical function (general). CALLING SEQUENCE: Result = ERRORF_MM (X [, /COMPLEMENTARY)] INPUTS: X Numeric, otherwise arbitrary. OPTIONAL INPUT PARAMETERS: None. KEYWORD PARAMETERS: /COMPLEMENTARY Switch. If set, 1 - ERRORF(X) is returned. OUTPUTS: Returns the error function of X or, if /COMPLEMENTARY is set, 1 - error_function. OPTIONAL OUTPUT PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: For very large (in absolute value) complex values of x, with pi/4 < |abs(phase(x))| < 3*pi/4 the results may be meaningless. A warning will be issued in this case. PROCEDURE: Uses CAST IGAMMA_MM and IMAGINARY_MM from MIDL. MODIFICATION HISTORY: Created 20-MAR-1996 by Mati Meron as M_ERRORF. Renamed 25-SEP-1999 by Mati Meron, to ERRORF_MM. Checked for operation under Windows, 25-JAN-2001, by Mati Meron.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\midl_lib\errorf_mm.pro)
NAME:
ERROR_MESSAGE
PURPOSE:
The purpose of this function is to have a device-independent
error messaging function. The error message is reported
to the user by using DIALOG_MESSAGE if widgets are
supported and MESSAGE otherwise.
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:
Utility.
CALLING SEQUENCE:
ok = Error_Message(the_Error_Message)
INPUTS:
the_Error_Message: This is a string argument containing the error
message you want reported. If undefined, this variable is set
to the string in the !Error_State.Msg system variable.
KEYWORDS:
NONAME: If this keyword is set the name of the calling routine
is not printed along with the message.
TRACEBACK: Setting this keyword results in an error traceback
being printed to standard output with the PRINT command.
In addition, any keyword appropriate for the MESSAGE or DIALOG_MESSAGE
routines can also be used.
OUTPUTS:
Currently the only output from the function is the string "OK".
RESTRICTIONS:
The "Warning" Dialog_Message dialog is used by default. Use keywords
/ERROR or /INFORMATION to select other dialog behaviors.
EXAMPLE:
To handle an undefined variable error:
IF N_Elements(variable) EQ 0 THEN $
ok = Error_Message('Variable is undefined', /Traceback)
MODIFICATION HISTORY:
Written by: David Fanning, 27 April 1999.
Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF.
Added _Extra keyword. 10 February 2000. DWF.
Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF.
Adding call routine's name to Traceback Report. 8 AUG 2000. DWF.
Switched default value for Dialog_Message to "Error" from "Warning". 7 OCT 2000. DWF.
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\coyote\error_message.pro)
NAME:
error_plot
PURPOSE:
Over-plot data points with accompanying X or Y error bars.
For use instead of PLOTERR or OPLOT or oploterr when the plotting system has already been
defined.
CATEGORY:
PLOT/PLOTXY
CALLING SEQUENCE:
error_plot, x, y, [x_err=x_err], [y_err=yerr], [s_hatlength=s_hatlength] ,
[s_thick=s_thick] , [s_linestyle=s_linestyle], [s_color =s_color ], [/s_hat],[/s_background],[s_nskip]
INPUTS:
plot : the by pl_init defined structure
X: array of abcissae, any datatype except string
Y: array of Y values, any datatype except string
OPTIONAL INPUTS:
X_ERR : vector of error bar values (along X)
Y_ERR : vector of error bar values (along Y)
For both: if only an element is submitted a vector with make_array will be builded
s_hatlength: the lengt of the hat
s_thick: the tickness of the error bar lines
s_linestyle: the linestyle of the error bar lines
s_color: the color of the error bar lines
KEYWORD PARAMETERS:
s_hat: 1 the error bar has an hat else 0 no hat
s_background: 1 error bar at background else 0 foreground
s_nskip: 1 no skip ; 0 skip
PROCEDURE:
A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR
and optionally from X - XERR to X + XERR is written to the output device
if sx or sy is a two dimensional array they have to be defined as min, max error
in this case it could be an asymmetrical error plotted.
WARNING:
This an enhanced version of a procedure that already exists in the
standard IDL V4.0 distribution. Any call to the standard IDL version
should also work with this version, but the reverse is not true.
MODIFICATION HISTORY:
Adapted from the most recent version of PLOTERR. M. R. Greason,
Hughes STX, 11 August 1992.
Removed spurious keywords for IDL V3.0.0 W. Landsman Jan. 1993
Added ability to plot a single point W. Landsman July 1993
Added COLOR keyword option to error bars W. Landsman November 1993
Remove CHANNEL call for V4.0 compatibility W. Landsman June 1995
Add ERRCOLOR, use _EXTRA keyword, W. Landsman, July 1995
Remove spurious call to PLOT_KEYWORDS W. Landsman, August 1995
OPLOT more than 32767 error bars W. Landsman, Feb 1996
Added NSKIP keyword W. Landsman, Dec 1996
==============================================================================
1998-Apr-04 R.Bauer
Adapted from olpoterr submitted by the astro lib
All is done by _extra
No symbol will be plotted only the error bars
An important difference is that's you are able to submit x, y data and x_err or (and) y_err
03.03.2000: (FH) Removed cause of the following IDL error message:
% Program caused arithmetic error: Floating illegal operand
% Detected at ERROR_PLOT 121 S:\links\idl_source\idl_work\rb_lib\error_plot.pro
05.04.2000: (FH) Set s_hat to 1 if not provided in structure pkey
EXAMPLE:
result=set_range([1,2,3,4],[10,20,30,40],xrange=[0,4],yrange=[0,40],sx=transpose([[0.9,1.8,2.9,3.5],[1.1,2.01,3.1,4.2]]))
plot,result.x,result.y,psym=4
error_plot,result.x,result.y,x_err=result.sx,s_color=5
x=[1,2,3,4] & y=[10,20,30,40] &sx=[0.1,0.12,0.1,0.1] & sy=[1.1,2.12,1.1,1.1]
plot,result.x,result.y,psym=4
error_plot,x,y,x_err=sx,y_err=sy,s_color=5
1999-Nov-06 help added
(See D:\MIRROR\BW1\TASCOM\IDL_PUB\ICG\IDL_SOURCE\IDL_WORK\rb_lib\error_plot.pro)
NAME:
ETC
PURPOSE:
Return estimated time to completion in seconds.
CATEGORY:
CALLING SEQUENCE:
stc = etc( fr )
INPUTS:
fr = fraction of work done. in
KEYWORD PARAMETERS:
Keywords:
DELTA=d interval in seconds for rate estimation (def=10).
DELTA must be given on each call.
/STATUS means display job status (at [10,12]).
STATUS=[x,y] display at column x, line y (from 1 at top).
OUTPUTS:
stc = estimated seconds t