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: Fri Aug 05 08:15:59 2011.
:Description:
Adds a directory to the beginning of the !PATH system variable.
:Categories:
Utility
:Params:
theDirectory: in, optional, type=string
The name of the directory to add to !PATH. If missing, the current directory.
:Keywords:
verbose: in, optional, type=boolean
Set this keyword if you wish to receive confirmation of action.
:Examples:
For example, to add a "programs" directory to the IDL path::
AddToPath, '/usr/david/IDL/programs/'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Written, 20 Sept 2010.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See addtopath.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 adjustposition.pro)
NAME:
ARCSAMPLE
PURPOSE:
Given X and Y points that describe a closed curve in 2D space,
this function returns an output curve that is sampled a specified
number of times at approximately equal arc distances.
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:
ArcSample, x_in, y_in, x_out, y_out
INPUT_PARAMETERS:
x_in: The input X vector of points.
y_in: The input Y vector of points.
OUTPUT_PARAMETERS:
x_out: The output X vector of points.
y_out: The output Y vector of points.
KEYWORDS:
POINTS: The number of points in the output vectors. Default: 50.
PHASE: A scalar between 0.0 and 1.0, for fine control of where interpolates
are sampled. Default: 0.0.
MODIFICATION HISTORY:
Written by David W. Fanning, 1 December 2003, based on code supplied
to me by Craig Markwardt.
(See arcsample.pro)
NAME:
ASINHSCL
PURPOSE:
This is a utility routine to perform an inverse hyperbolic sine
function intensity transformation on an image. I think of this
as a sort of "tuned" gamma or power-law function. The algorithm,
and notion of "asinh magnitudes", comes from a paper by Lupton,
et. al, in The Astronomical Journal, 118:1406-1410, 1999 September.
I've relied on the implementation of Erin Sheldon, found here:
http://cheops1.uchicago.edu/idlhelp/sdssidl/plotting/tvasinh.html
I'm also grateful of discussions with Marshall Perrin on the IDL
newsgroup with respect to the meaning of the "softening parameter", beta,
and for finding (and fixing!) small problems with the code.
Essentially this transformation allow linear scaling of noise values,
and logarithmic scaling of signal values, since there is a small
linear portion of the curve and a much large logarithmic portion of
the curve. (See the EXAMPLE section for some tips on how to view this
transformation curve.)
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:
outputImage = ASINHSCL(image)
ARGUMENTS:
image: The image or signal to be scaled. Written for 2D images, but arrays
of any size are treated alike.
KEYWORDS:
BETA: This keyword corresponds to the "softening parameter" in the Lupon et. al paper.
This factor determines the input level at which linear behavior sets in. Beta
should be set approximately equal to the amount of "noise" in the input signal.
IF BETA=0 there is a very small linear portion of the curve; if BETA=200 the
curve is essentially all linear. The default value of BETA is set to 3, which
is appropriate for a small amount of noise in your signal. The value is always
positive.
NEGATIVE: If set, the "negative" of the result is returned.
MAX: Any value in the input image greater than this value is
set to this value before scaling.
MIN: Any value in the input image less than this value is
set to this value before scaling.
OMAX: The output image is scaled between OMIN and OMAX. The
default value is 255.
OMIN: The output image is scaled between OMIN and OMAX. The
default value is 0.
RETURN VALUE:
outputImage: The output, scaled into the range OMIN to OMAX. A byte array.
COMMON BLOCKS:
None.
EXAMPLES:
Plot, ASinhScl(Indgen(256), Beta=0.0), LineStyle=0
OPlot, ASinhScl(Indgen(256), Beta=0.1), LineStyle=1
OPlot, ASinhScl(Indgen(256), Beta=1.0), LineStyle=2
OPlot, ASinhScl(Indgen(256), Beta=10.), LineStyle=3
OPlot, ASinhScl(Indgen(256), Beta=100), LineStyle=4
RESTRICTIONS:
Requires SCALE_VECTOR from the Coyote Library:
http://www.dfanning.com/programs/scale_vector.pro
Incorporates ASINH from the NASA Astronomy Library and renamed ASINHSCL_ASINH.
http://idlastro.gsfc.nasa.gov/homepage.html
MODIFICATION HISTORY:
Written by: David W. Fanning, 24 February 2006.
Removed ALPHA keyword and redefined the BETA keyword to correspond
to the "softening parameter" of Lupton et. al., following the
suggestions of Marshall Perrin. 25 April 2006. DWF.
(See asinhscl.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 aspect.pro)
NAME:
BINARY
PURPOSE:
This function is used to display a binary representation of byte,
integer, and long integer values.
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:
output = Binary(theNumber)
RETURN VALUE:
output: A string array of 0s and 1s to be printed (normally), in a
binary representation of the number. The number is represented with
the highest bits on the left and the lowest bits on the right,
when printed with the PRINT command.
ARGUMENTS:
theNumber: The number for which the user wants a binary representation.
It must be BYTE, INT, or LONG.
KEYWORDRS:
COLOR: If this keyword is set, the binary representation always
contains 24 bits of output.
SEPARATE: If this keyword is set, the output is separated with space
between each group of eight bits.
EXAMPLE:
IDL> Print, Binary(24B)
0 0 0 1 1 0 0 0
IDL> Print, Binary(24L)
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 1 1 0 0 0
IDL> Print, Binary(24L, /COLOR)
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0
IDL> Print, Binary(24L, /COLOR, /SEPARATE)
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0
MODIFICATION HISTORY:
Written by: David W. Fanning, November 10, 2007.
Fixed a problem with error handling. 13 March 2008. DWF.
(See binary.pro)
NAME:
BITGET
PURPOSE:
Returns the bit value (0 or 1) of a specified bit in a supplied number.
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:
bitValue = BitGet(number, bit)
INPUT_PARAMETERS:
number: The input number. Should be a scalar integer. If not, it is converted to
one by rounding.
bit: The number of the bit you are interested in. A value between 0 and 63.
If not supplied, all 64 bit values of the number are returned. May be
an array of bit numbers.
OUTPUT_PARAMETERS:
bitValue: The value, 0 or 1, of the specified bit in the number.
KEYWORDS:
SILENT: If set, suppresses informational messages regarding rounding operations.
MODIFICATION HISTORY:
Written by David W. Fanning, 14 June 2006.
(See bitget.pro)
NAME:
BLOB_ANALYZER__DEFINE
PURPOSE:
The purpose of this routine is to create a system for analyzing
regions of interest (ROIs) or (more commonly) "blobs" inside images.
In particular, given a suitable image (this will require judgement on
your part), the program will automatically select "blobs" or connected
regions in the image and make it possible for you to analyze these
blobs. An example program is provided to show you one way the program
can be used.
The code is a wrapper, essentially, for LABEL_REGION and HISTOGRAM, with
a couple of my other image processing routines (FIND_BOUNDARY and FIT_ELLIPSE)
used in a supporting role.
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:
Analysis, Image Processing
CALLING SEQUENCE:
analyzer = Obj_New("BLOB_ANALYZER", image)
INPUTS:
image: A two-dimensional image array. To make this program memory efficient,
a copy of the image is *not* stored in the object. You will be responsible
for image operations outside this program.
KEYWORDS:
ALL_NEIGHBORS: Set this keyword to look at all eight neighbors when searching
for connectivity. The default is to look for four neighbors on
each side of the starting pixel. Passed directly to LABEL_REGION.
MASK: A two-dimensional array, the same size as image, that identifies the
foreground and background pixels in the image. Applying the mask
should result in a bi-level image of 0s and 1s, where 1 identifies the
blobs you wish to analyze. If a mask is not provided, the mask is created
like this:
mask = image > 0
SCALE: A one- or two-dimensional given the pixel scaling parameters. By default [1.0, 1.0].
If passed a scalar, the scale parameter is applied to both the X and Y directions of
each pixel. Statistical output is reported with scaling unless the NOSCALE keyword
is set. Scaling also effects the data that is output from the various methods.
OBJECT METHODS:
The following methods are provided. Please see the documentation header for each method for
information on arguments and keywords that can be used with the method.
FitEllipse: This method fits an ellipse to the blob. It returns information about the fitted
ellipse, including the points that all the ellipse to be drawn.
GetIndices: This method returns the indices for a particular blob in the image.
GetStats: This method returns a structure containing statistics for a particular blob in the image.
The structure is defined as follows:
stats = {INDEX: indexNumber, $ ; The index number of this blob.
COUNT: N_Elements(indices), $ ; The number of indices in this blob.
PERIMETER_PTS: boundaryPts, $ ; A [2,n] array of points that describe the blob perimeter.
PIXEL_AREA: pixelArea, $ ; The area as calculated by pixels in the blob.
PERIMETER_AREA: perimeterArea, $ ; The area as calculated by the blob perimeter. (Smaller than pixel area.)
CENTER: centroid[0:1], $ ; The [x,y] array that identifies the centroid of the blob.
PERIMETER_LENGTH: perimeter_length, $ ; The perimenter length (scaled unless the NOSCALE keyword is set).
SCALE: scale, $ ; The [xscale, yscale] array used in scaling.
MINCOL: Min(xyindices[0,*]), $ ; The minimum column index in the blob.
MAXCOL: Max(xyindices[0,*]), $ ; The maximum column index in the blob.
MINROW: Min(xyindices[1,*]), $ ; The minimum row index in the blob.
MAXROW: Max(xyindices[1,*])} ; The maximum row index in the blob.
NumberOfBlobs: The number of blobs identified in the image.
ReportStats: This methods reports statistics on every identified blob in the image. The
report can be sent to the display (the default) or to a file. The format for
the report works for most images, but you may have to change the format or override
this method for your particular image. The reported statistics are basically the
output of the GetStats and FitEllipse methods.
Here is an example of statistical output from the example program below.
INDEX NUM_PIXELS CENTER_X CENTER_Y PIXEL_AREA PERIMETER_AREA PERIMETER_LENGTH MAJOR_AXIS MINOR_AXIS ANGLE
0 426 107.89 9.78 106.50 98.00 37.56 12.15 11.29 -8.05
1 580 151.97 10.22 145.00 134.25 49.21 17.49 11.77 -0.99
2 812 266.29 15.36 203.00 190.75 52.56 17.88 14.65 -107.48
3 1438 204.53 43.29 359.50 344.13 70.23 21.68 21.12 -76.47
RESTRICTIONS:
Requires programs from the Coyote Library. At the very least, those below are required.
It is *highly* recommended that you install the entire library. FIT_ELLIPSE has been
changed specifically for this release, so by sure you get a copy of that with this
source code.
http://www.dfanning.com/programs/coyoteprograms.zip
ERROR_MESSAGE http://www.dfanning.com/programs/error_message.pro
FIND_BOUNDARY http://www.dfanning.com/programs/find_boundary.pro
FIT_ELLIPSE http://www.dfanning.com/programs/fit_ellipse.pro
The program currently works only with 2D bi-level images.
EXAMPLE:
To run an example program. Compile the file and type "example" at the IDL command line.
IDL> .compile blob_analyzer__define
IDL> example
MODIFICATION HISTORY:
Written by David W. Fanning, Fanning Software Consulting, 17 August 2008.
Ideas taken from discussion with Ben Tupper and Ben's program HBB_ANALYZER.
(See blob_analyzer__define.pro)
NAME:
CANCONNECT
PURPOSE:
This function will check to see if it is possible to make
a connection with the window system. It is useful when
running IDL as a CRON job or from remote logins. The program
will establish a system variable named !FSC_Display_Connection the
first time it is run. Programs which need to know if a connection
can be established can consult this system variable as a faster
way of determining a connection than running this program. The
system variable is set to 1 if a connection can be made and to
0 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:
Utilities
CALLING SEQUENCE:
connection = CanConnect()
RETURN_VALUE:
connection: Will be set to 1 if a window connection is possible
Otherwise, it will be set to 0.
INPUT_PARAMETERS:
None.
KEYWORDS:
None.
NOTES:
A system variable, !FSC_Display_Connection is created.
MODIFICATION HISTORY:
Written by David W. Fanning, 10 February 2010.
Modified program to set the system variable !FSC_Display_Connection. This is primarily
a way for legacy code to run in cron jobs without continually checking for
a connection, which before this update required opening and closing a window.
7 October 2010. DWF.
(See canconnect.pro)
NAME:
CAPFIRSTLETTER
PURPOSE:
Given a string, separates the parts by white space, commas,
semi-colons, or colons. Each part has the first letter capitalized.
The returned string has the capitalized parts separated by a space.
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:
capitalizedString = CatFirstLetter(theString)
AUGUMENTS:
theString: The input string.
RETURN_VALUE:
capitalizedString: The capitalized output string. There is a space between parts
(words) of the input string.
KEYWORDS:
None.
MODIFICATION HISTORY:
Written by David W. Fanning, 29 July 2005.
(See capfirstletter.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, /DEVICE, CENTERONTLB=wOtherTLBID]
REQUIRED INPUTS:
tlb: The top-level base identifier of the widget program. This must
be a valid widget ID.
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:
DEVICE: Normally, the x and y parameters are specified in normalized
coordinates. If this keyword is set, they are taken to be in DEVICE
coordinates.
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.
CENTERONTLB: If provided, the center of the widget is positioned at
the center of the widget whose ID is provided here.
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.
Added a maximum value of 1280 for X screen size. This helps
center the widget on a single monitor when using dual
monitor settings with some graphics cards. 3 Feb 2003. DWF.
Added DEVICE keyword. 4 January 2006. DWF.
Added CenterOnTLB keyword. 7 March 2011. DJ.
(See centertlb.pro)
:Description:
Provides a device-independent and color-model-independent way of drawing an arrow
in a specified color.
:Categories:
Graphics
:Params:
x0: in, required, type=integer/float
The x location of the blunt end of the arrow. May be a vector. Assumes
device coordinates.
x1: in, required, type=integer/float
The x location of the sharp end of the arrow. May be a vector. Assumes
device coordinates.
y0: in, required, type=integer/float
The y location of the blunt end of the arrow. May be a vector. Assumes
device coordinates.
y1: in, required, type=integer/float
The y location of the sharp end of the arrow. May be a vector. Assumes
device coordinates.
:Keywords:
color: in, optional, type=string/integer/long, default='white'
An alternative way to specify the color to use in erasing the graphics window.
Color names are those used with cgColor. This parameter is used in
preference to the background_color parameter.
data: in, optional, type=boolean, default=0
Set this keyword of the arrow locations are in data coordinates.
Device coordinates are assumed.
hsize: in, optional, type=float
The size of the the arrow head. By default 1/64th the width
of the device. (!D.X_SIZE / 64.)
hthick: in, optional, type=float, default=1.0
The thickness of the line drawing the arrowhead.
linestyle: in, optional, type=integer, default=0
The line style of the arrow. Line style integers as in PLOT.
normal: in, optional, type=boolean, default=0
Set this keyword of the arrow locations are in normalized coordinates.
Device coordinates are assumed.
solid: in, optional, type=boolean, default=0
Set this keyword to draw solid, filled arrows.
thick: in, optional, type=float, default=1.0
The thickness of the line drawing the shaft of the arrow.
window: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow application.
:Examples:
Used to draw arrows::
IDL> cgArrow, 50, 50, 100, 100, /Solid
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 23 November 2010. DWF. Based on old Arrow routine in IDL.
Added Window keyword 24 January 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgarrow.pro)
:Description:
Provides a device-independent and color-model-independent way to draw an axis into
a graphics window. It is a wrapper to the AXIS command.
:Categories:
Graphics
:Params:
xloc: in, optional, type=depends
The X location of the axis.
yloc: in, optional, type=depends
The Y location of the axis.
zloc: in, optional, type=depends
The Z location of the axis.
:Keywords:
charsize: in, optional, type=float, default=cgDefCharSize()
The character size for axes annotations. Uses cgDefCharSize to select default
character size, unless !P.Charsize is set, in which case !P.Charsize is always used.
color: in, optional, type=string/integer/long
The color of the text. Color names are those used with cgColor. By default,
"black", unless the upper-right hand pixel in the display is black, then "white".
data: in, optional, type=boolean
Set this keyword to indicate xloc and yloc are in data coordinates. Data coordinates
are the default, unless DEVICE or NORMAL is set.
device: in, optional, type=boolean
Set this keyword to indicate xloc and yloc are in device coordinates.
font: in, optional, type=integer, default=!P.Font
The type of font desired. By default, !P.Font.
normal: in, optional, type=boolean
Set this keyword to indicate xloc and yloc are in normalized coordinates.
save: in, optional, type=boolean
Set this keyword to save the scaling parameters set by the axis for subsequent use.
window: in, optional, type=boolean
Set this keyword to add the command to the in the current cgWindow application.
xaxis: in, optional, type=integer, default=0
If set to 0, the axis is drawn under the plot with the tick marks pointing up; if set
to 1, the axis is drawn on top of the plot with the tick marks pointing down.
xlog: in, optional, type-boolean, default=0
Set this keyword to specify a logarithmic axis type.
yaxis: in, optional, type=integer, default=0
If set to 0, the axis is drawn under the plot with the tick marks pointing up; if set
to 1, the axis is drawn on top of the plot with the tick marks pointing down.
ylog: in, optional, type-boolean, default=0
Set this keyword to specify a logarithmic axis type.
ynozero: in, optional, type=boolean, default=0
Set this keyword to prevent the Y axis from starting at 0.
zaxis: in, optional, type=integer, default=0
Set to 0-3 to position the Z axis in various locatons. See the AXIS documentation.
zlog: in, optional, type-boolean, default=0
Set this keyword to specify a logarithmic axis type.
_extra: in, optional
Any keywords appropriate for the XYOUTS command.
:Examples:
Used like the IDL AXIS command::
IDL> cgPlot, cgDemoData(1), YStyle=8, Position=[0.1, 0.1, 0.85, 0.9], /Window
IDL> cgAxis, /YAxis, Color='red', YRange=[-500, 500], /Save, /Window
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 25 Janauray 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
Modifed the way I am handling brain dead AXIS command. 30 May 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgaxis.pro)
NAME:
cgBlendImage
PURPOSE:
This alpha blends two 24-bit images and displays them with the cgImage command.
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:
cgBlendImage, foregroundImage, backgroundImage
INPUTS:
foregroundImage: A 24-bit foreground image with the same dimensions as the background image.
backgroundImage: A 24-bit background image with the same dimensions as the foreground image.
KEYWORD PARAMETERS:
ALPHA: A number between 0 and 1 that indicates the percentage of the foreground image
to alpha-blend into the background image. For example, ALPHA=0.2 will give
a weigth of 20% to the foreground image pixels and 80% to the background image
pixels. By default, 0.5.
Note: Any keywords appropriate to the cgImage command are also accepted.
MODIFICATION HISTORY:
Written by: David W. Fanning, 26 May 2009.
(See cgblendimage.pro)
NAME:
cgBoxPlot
PURPOSE:
This is graphics routine to display a box plot, also known as a box and
whisker plot, in IDL direct graphics. The box encloses the interquartile
range (IQR), defined at IQR75-IQR25. The whiskers extend out to the maximum
or minimum value of the data, or to the 1.5 times either the IQR75 or IQR25,
if there is data beyond this range. Outliers are identified with small circles.
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:
cgBoxPlot, data
REQUIRED INPUTS:
data: A two-dimensional array. The data for each box plot will be in
the columns of the data array. There will be one box plot drawn
for each column in the data array. The maximum column size is 28.
As an alternative, data can be a pointer array, in which case
there will be one box plot drawn for each valid pointer in the array.
INPUT KEYWORDS:
ADDCMD: Set this keyword to add the command to the resizeable graphics window cgWindow.
AXES_COLOR: A string color name, as appropriate for the FSC_COLOR program.
By default, the same as the COLOR keyword. Used only if OVERPLOT
keyword is not set.
BACKGROUND_COLOR: A string color name, as appropriate for the FSC_COLOR program.
By default, 'white'. Used only if OVERPLOT keyword is not set.
BOXCOLOR: If FILLBOXES is set, the IQR box is filled with this color. By default, "ROSE".
CHARSIZE: Set this to the character size to use on the plot. If undefined, uses
the value of cgDefCharsize().
COLOR: A string color name, as appropriate for the cgColor program.
By default, 'charcoal'. The boxplot will be drawn in this color.
FILLBOXES: Set this keyword to fill the IQR box with a color, specified by BOXCOLOR.
LABELS: A string array of the same length as the number of columns of data.
The boxplots will be labeled with these labels along the X axis.
Used only if OVERPLOT keyword is not set.
MISSING_DATA_VALUE: Set this keyword to a value that will be used to identify missing data.
Missing data is not used in the calculations of the box plot.
OVERPLOT: If this keyword is set, the boxplots will be overdrawn on the current
set of axes. The X axis will be presumed to be scaled from 0 to 1 more
than the number of columns in data.
ROTATE: Set to a value between -90 and 90 degree. The labels will be rotated this
amount. Positive values rotate in CCW fashion, negative values in CW fashion.
WINDOW: Set this keyword to display the plot in a resizeable graphics window (cgWindow).
Any other keywords (e.g., POSITION, XTITLE, YTITLE, etc.) that are appropriate for
the PLOT command can be used with this procedure.
OUTPUT KEYWORDS:
STATS: Set this to a named variable that will return an array of structures
for each of the columns of data. The structure will be defined as
this:
struct = { Median:0.0D, Mean: 0.0D, Min:0.0D, Max:0.0D, $
Q25:0.0D, Q75:0.0D, IQR:0.0D, SDEV:0.0D, N:0L }
Where "mean" is the median value of the data, "Q25" and "Q75" are the 25th percent
quartile and 75th percent quartile of the data, repectively, "IRG" is the
Interquartile Range, SDEV is the standard deviation, and N is the number of points
used to construct the box plot.
REQUIRES:
Several program from the Coyote Library (http://www.dfanning.com/documents/programs.html)
are required. Among them are these:
ERROR_MESSAGE (http://www.dfanning.com/programs/error_message.pro)
cgColor (http://www.dfanning.com/programs/cgColor.pro)
SYMCAT (http://www.dfanning.com/programs/symcat.pro)
EXAMPLE:
Here is an example, using data from the Michaelson-Morley speed of light experiment,
in which they made five experiments of 20 measurements of the speed of light each.
The data can be downloaded from here:
http://www.dfanning.com/misc/mm_data.dat
Here are the IDL commands to read the data and produce a box plot of it.
OpenR, 1, Find_Resource_File('mm_data.dat')
header = Strarr(2)
Readf, 1, header
data = Intarr(5, 20)
Readf, 1, data
Close, 1
cgBoxPlot, data, XTITLE='Experiment Number', YTITLE='Speed of Light'
An article about his program can be found here:
http://www.dfanning.com/graphics_tips/box_whisker.html
MODIFICATION HISTORY:
Written by David W. Fanning, 4 March 2009.
Added STATS keyword to return data statistics. 5 March 2009. DWF.
Added MISSING_DATA_VALUE keyword to identify missing values. 14 March 2009. DWF.
Removed limitation of LABELS array having no more than 28 elements. 14 March 2009. DWF.
Made it possible to pass a pointer array containing the data, if desired. 14 March 2009. DWF.
Added ROTATE keyword to rotate labels. 16 March 2009. DWF.
Added several modifications to guard against ill-formed data in the cgBoxPlot_Draw
procedure. 23 March 2009. DWF.
Added keywords FILLBOXES and BOXCOLOR. 24 March 2009. DWF.
Redefined the STATS structure to include MEAN and to store values as doubles. 25 March 2009. DWF.
Fixed in a bug that resulted in incorrect behavior when the MISSING_DATA_VALUE keyword
was used. 8 April 2009. DWF.
Fixed a typo that didn't allow a single column vector to be displayed as a box plot. 17 May 2009. DWF.
Now allow a single row vector to be passed into program and displayed. 20 May 2009. DWF.
Added NOCLIP=0 keyword to PLOTS command when drawing outliers. 15 July 2009. DWF.
Minor adjustment of the X axis label position. 28 October 2010. DWF.
Add the ability to change the label character size and thickness via the normal
XCHARSIZE and XTHICK keywords you would use for a plot. 3 Dec 2010. DWF.
Fixed a couple of typos, added ADDCMD, CHARSIZE, LAYOUT and WINDOW keywords. 2 Feb 2011. DWF.
(See cgboxplot.pro)
NAME:
cgCOLOR
PURPOSE:
The purpose of this function is to obtain drawing colors
by name and in a device/decomposition independent way.
The color names and values may be read in as a file, or 192 color
names and values are supplied with the program. These colors were
obtained from the file rgb.txt, found on most X-Window distributions,
and from colors in the Brewer color tables (http://colorbrewer2.org/).
Representative colors were chosen from across the color spectrum. To
see a list of colors available, type:
Print, cgColor(/Names), Format='(6A18)'
If the color names '0', '1', '2', ..., '255' are used, they will
correspond to the colors in the current color table in effect at
the time the cgColor program is called.
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 = cgColor(theColor, theColorIndex)
NORMAL CALLING SEQUENCE FOR DEVICE-INDEPENDENT COLOR:
If you write your graphics code *exactly* as it is written below, then
the same code will work in all graphics devices I have tested.
These include the PRINTER, PS, and Z devices, as well as X, WIN, and MAC.
In practice, graphics code is seldom written like this. (For a variety of
reasons, but laziness is high on the list.) So I have made the
program reasonably tolerant of poor programming practices. I just
point this out as a place you might return to before you write me
a nice note saying my program "doesn't work". :-)
axisColor = cgColor("Green", !D.Table_Size-2)
backColor = cgColor("Charcoal", !D.Table_Size-3)
dataColor = cgColor("Yellow", !D.Table_Size-4)
thisDevice = !D.Name
Set_Plot, 'toWhateverYourDeviceIsGoingToBe', /Copy
Device, .... ; Whatever you need here to set things up properly.
IF (!D.Flags AND 256) EQ 0 THEN $
POLYFILL, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=backColor
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData, $
NoErase= ((!D.Flags AND 256) EQ 0)
OPlot, Findgen(11), Color=dataColor
Device, .... ; Whatever you need here to wrap things up properly.
Set_Plot, thisDevice
OPTIONAL INPUT PARAMETERS:
theColor: A string with the "name" of the color. To see a list
of the color names available set the NAMES keyword. This may
also be a vector of color names. Colors available are these:
Active Almond Antique White Aquamarine Beige Bisque
Black Blue Blue Violet Brown Burlywood Cadet Blue
Charcoal Chartreuse Chocolate Coral Cornflower Blue Cornsilk
Crimson Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki
Dark Orchid Dark Red Dark Salmon Dark Slate Blue Deep Pink Dodger Blue
Edge Face Firebrick Forest Green Frame Gold
Goldenrod Gray Green Green Yellow Highlight Honeydew
Hot Pink Indian Red Ivory Khaki Lavender Lawn Green
Light Coral Light Cyan Light Gray Light Salmon Light Sea Green Light Yellow
Lime Green Linen Magenta Maroon Medium Gray Medium Orchid
Moccasin Navy Olive Olive Drab Orange Orange Red
Orchid Pale Goldenrod Pale Green Papaya Peru Pink
Plum Powder Blue Purple Red Rose Rosy Brown
Royal Blue Saddle Brown Salmon Sandy Brown Sea Green Seashell
Selected Shadow Sienna Sky Blue Slate Blue Slate Gray
Snow Spring Green Steel Blue Tan Teal Text
Thistle Tomato Turquoise Violet Violet Red Wheat
White Yellow
The color OPPOSITE is used if this parameter is absent or a color name is mis-spelled. To see a list
of the color names available in the program, type this:
IDL> Print, cgColor(/Names), Format='(6A18)'
theColorIndex: The color table index (or vector of indices the same length
as the color name vector) where the specified color is loaded. The color table
index parameter should always be used if you wish to obtain a color value in a
color-decomposition-independent way in your code. See the NORMAL CALLING
SEQUENCE for details. If theColor is a vector, and theColorIndex is a scalar,
then the colors will be loaded starting at theColorIndex.
When the BREWER keyword is set, you must use more arbitrary and less descriptive color
names. To see a list of those names, use the command above with the BREWER keyword set,
or call PICKCOLORNAME with the BREWER keyword set:
IDL> Print, cgColor(/Names, /BREWER), Format='(8A10)'
IDL> color = PickColorName(/BREWER)
Here are the Brewer names:
WT1 WT2 WT3 WT4 WT5 WT6 WT7 WT8
TAN1 TAN2 TAN3 TAN4 TAN5 TAN6 TAN7 TAN8
BLK1 BLK2 BLK3 BLK4 BLK5 BLK6 BLK7 BLK8
GRN1 GRN2 GRN3 GRN4 GRN5 GRN6 GRN7 GRN8
BLU1 BLU2 BLU3 BLU4 BLU5 BLU6 BLU7 BLU8
ORG1 ORG2 ORG3 ORG4 ORG5 ORG6 ORG7 ORG8
RED1 RED2 RED3 RED4 RED5 RED6 RED7 RED8
PUR1 PUR2 PUR3 PUR4 PUR5 PUR6 PUR7 PUR8
PBG1 PBG2 PBG3 PBG4 PBG5 PBG6 PBG7 PBG8
YGB1 YGB2 YGB3 YGB4 YGB5 YGB6 YGB7 YGB8
RYB1 RYB2 RYB3 RYB4 RYB5 RYB6 RYB7 RYB8
TG1 TG2 TG3 TG4 TG5 TG6 TG7 TG8
As of 3 July 2008, the Brewer names are also now available to the user without using
the BREWER keyword. If the BREWER keyword is used, *only* Brewer names are available.
The color name "OPPOSITE" is also available. It chooses a color "opposite" to the
color of the pixel in the upper-right corner of the display, if a window is open.
Otherwise, this color is "black" in PostScript and "white" everywhere else.
RETURN VALUE:
The value that is returned by cgColor depends upon the keywords
used to call it, on the version of IDL you are using,and on the depth
of the display device when the program is invoked. In general,
the return value will be either a color index number where the specified
color is loaded by the program, or a 24-bit color value that can be
decomposed into the specified color on true-color systems. (Or a vector
of such numbers.)
If you are running IDL 5.2 or higher, the program will determine which
return value to use, based on the color decomposition state at the time
the program is called. If you are running a version of IDL before IDL 5.2,
then the program will return the color index number. This behavior can
be overruled in all versions of IDL by setting the DECOMPOSED keyword.
If this keyword is 0, the program always returns a color index number. If
the keyword is 1, the program always returns a 24-bit color value.
If the TRIPLE keyword is set, the program always returns the color triple,
no matter what the current decomposition state or the value of the DECOMPOSED
keyword. Normally, the color triple is returned as a 1 by 3 column vector.
This is appropriate for loading into a color index with TVLCT:
IDL> TVLCT, cgColor('Yellow', /Triple), !P.Color
But sometimes (e.g, in object graphics applications) you want the color
returned as a row vector. In this case, you should set the ROW keyword
as well as the TRIPLE keyword:
viewobj= Obj_New('IDLgrView', Color=cgColor('charcoal', /Triple, /Row))
If the ALLCOLORS keyword is used, then instead of a single value, modified
as described above, then all the color values are returned in an array. In
other words, the return value will be either an NCOLORS-element vector of color
table index numbers, an NCOLORS-element vector of 24-bit color values, or
an NCOLORS-by-3 array of color triples.
If the NAMES keyword is set, the program returns a vector of
color names known to the program.
If the color index parameter is not used, and a 24-bit value is not being
returned, then colorIndex is typically set to !D.Table_Size-1. However,
this behavior is changed on 8-bit devices (e.g., the PostScript device,
or the Z-graphics buffer) and on 24-bit devices that are *not* using
decomposed color. On these devices, the colors are loaded at an
offset of !D.Table_Size - ncolors - 2, and the color index parameter reflects
the actual index of the color where it will be loaded. This makes it possible
to use a formulation as below:
Plot, data, Color=cgColor('Dodger Blue')
on 24-bit displays *and* in PostScript output! Note that if you specify a color
index (the safest thing to do), then it will always be honored.
INPUT KEYWORD PARAMETERS:
ALLCOLORS: Set this keyword to return indices, or 24-bit values, or color
triples, for all the known colors, instead of for a single color.
DECOMPOSED: Set this keyword to 0 or 1 to force the return value to be
a color table index or a 24-bit color value, respectively.
FILENAME: The string name of an ASCII file that can be opened to read in
color values and color names. There should be one color per row
in the file. Please be sure there are no blank lines in the file.
The format of each row should be:
redValue greenValue blueValue colorName
Color values should be between 0 and 255. Any kind of white-space
separation (blank characters, commas, or tabs) are allowed. The color
name should be a string, but it should NOT be in quotes. A typical
entry into the file would look like this:
255 255 0 Yellow
NAMES: If this keyword is set, the return value of the function is
a ncolors-element string array containing the names of the colors.
These names would be appropriate, for example, in building
a list widget with the names of the colors. If the NAMES
keyword is set, the COLOR and INDEX parameters are ignored.
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
ROW: If this keyword is set, the return value of the function when the TRIPLE
keyword is set is returned as a row vector, rather than as the default
column vector. This is required, for example, when you are trying to
use the return value to set the color for object graphics objects. This
keyword is completely ignored, except when used in combination with the
TRIPLE keyword.
SELECTCOLOR: Set this keyword if you would like to select the color name with
the PICKCOLORNAME program. Selecting this keyword automaticallys sets
the INDEX positional parameter. If this keyword is used, any keywords
appropriate for PICKCOLORNAME can also be used. If this keyword is used,
the first positional parameter can be a color name that will appear in
the SelectColor box.
TRIPLE: Setting this keyword will force the return value of the function to
*always* be a color triple, regardless of color decomposition state or
visual depth of the machine. The value will be a three-element column
vector unless the ROW keyword is also set.
In addition, any keyword parameter appropriate for PICKCOLORNAME can be used.
These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE.
OUTPUT KEYWORD PARAMETERS:
CANCEL: This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME.
COLORSTRUCTURE: This output keyword (if set to a named variable) will return a
structure in which the fields will be the known color names (without spaces)
and the values of the fields will be either color table index numbers or
24-bit color values. If you have specified a vector of color names, then
this will be a structure containing just those color names as fields.
NCOLORS: The number of colors recognized by the program. It will be 104 by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
EXAMPLE:
To get drawing colors in a device-decomposed independent way:
axisColor = cgColor("Green", !D.Table_Size-2)
backColor = cgColor("Charcoal", !D.Table_Size-3)
dataColor = cgColor("Yellow", !D.Table_Size-4)
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
OPlot, Findgen(11), Color=dataColor
To set the viewport color in object graphics:
theView = Obj_New('IDLgrView', Color=cgColor('Charcoal', /Triple))
To change the viewport color later:
theView->SetProperty, Color=cgColor('Antique White', /Triple)
To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this:
IDL> TVLCT, cgColor(["red", "green", and "yellow"], /Triple), 100
MODIFICATION HISTORY:
Written by: David W. Fanning and transferred from CTLOAD on 4 February 2011 to the
Coyote Graphics system.
(See cgcolor.pro)
NAME:
cgCOLORBAR
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:
cgColorbar
INPUTS:
None.
KEYWORD PARAMETERS:
ADDCMD: Set this keyword to add the cgColorbar command to the current cgWindow
command list.
ANNOTATECOLOR: The name of the "annotation color" to use. The names are those for
cgCOLOR, and using the keyword implies that cgCOLOR is also in
your !PATH. If this keyword is used, the annotation color is loaded
*after* the color bar is displayed. The color will be represented
as theColor = cgCOLOR(ANNOTATECOLOR). This keyword is provide
to maintain backward compatibility, but also to solve the problem of
an extra line in the color bar when this kind of syntax is used in
conjunction with the indexed (DEVICE, DECOMPOSED=0) model is used:
LoadCT, 33
cgImage, image
cgColorbar, Color=cgColor('firebrick')
The proper syntax for device-independent color is like this:
LoadCT, 33
cgImage, image
cgColorbar, AnnotateColor='firebrick', Color=255
Set the Modification History note for 13 November 2010 for additional
information about default values.
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARPERCENT: A value from 0.0 go 1.0 that is multiplied by the CHARSIZE to produce
the character size for the color bar. The default is 0.85. This value
is only used if CHARSIZE is undefined. This keyword is primarily useful
for using color bars in resizeable graphics windows (cgWindow).
CHARSIZE: The character size of the color bar annotations. Default is
cgDefCharsize()*charPercent.
CLAMP: A two-element array in data units. The color bar is clamped to these
two values. This is mostly of interest if you are "window-leveling"
an image. The clamp is set to the "window" of the color bar.
Normally, when you are doing this, you would like the colors outside
the "window" to be set to a neutral color. Use the NEUTRALINDEX keyword
to set the netural color index in the color bar. (See the Example section
for more information.
COLOR: The color index of the bar outline and characters. Default
is !P.Color. To display the color bar in a device indpendent
way, you should use the ANNOTATECOLOR keyword instead of this keyword.
If this keyword is a string color name, then ANNOTATECOLOR=color.
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FIT: If this keyword is set, the colorbar "fits" itself to the normalized
coordinates of the last plot command executed. In other words, for
a horizontal color bar, postition[[0,2]] = !X.Window, and for a vertical
color bar, position[[1,3]] = !Y.Window. Other positions are adjusted
to put the colorbar "reasonably" close to the plot.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(I0)'.
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.
NEUTRALINDEX: This is the color index to use for color bar values outside the
clamping range when clamping the color bar with the CLAMP keyword.
If this keyword is absent, the highest color table value is used
for low range values and the lowest color table value is used
for high range values, in order to provide contrast with the
clamped region. See the Example section for more information.
NODISPLAY: cgColorBAR uses cgCOLOR to specify some of it colors. Normally,
cgCOLOR loads "system" colors as part of its palette of colors.
In order to do so, it has to create an IDL widget, which in turn
has to make a connection to the windowing system. If your program
is being run without a window connection, then this program will
fail. If you can live without the system colors (and most people
don't even know they are there, to tell you the truth), then setting
this keyword will keep them from being loaded, and you can run
cgCOLORBAR without a display. As of 19 Oct 2010, set to 1 by default.
PALETTE: A color palette containing the RGB color vectors to use for the color
bar. The program will sample NCOLORS from the color palette.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.10, 0.95, 0.90] for a vertical bar and
[0.10, 0.88, 0.90, 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.
REVERSE: Setting this keyword reverses the colors in the colorbar.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
TICKNAMES: A string array of names or values for the tick marks.
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.
WINDOW: Set this keyword if you want to add the cgColorbar command to
the current cgWindow application.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the graphics display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
Requires the cgCOLOR program from the Coyote Library:
http://www.dfanning.com/programs/cgcolor.pro
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
cgCOLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]
Example using the CLAMP and NEUTRALINDEX keywords.
LOADCT, 33, NCOLORS=254
TVLCT, cgCOLOR('gray', /TRIPLE), 255
cgCOLORBAR, NCOLORS=254, NEUTRALINDEX=255, RANGE=[0,1500], $
DIVISIONS=8, CLAMP=[400, 800]
MODIFICATION HISTORY:
Written by: David W. Fanning, 4 February 2011, as a direct descendant of cgColorbar.
Program developement stopped on cgColorbar as of this date, and this program has
become a part of the Coyote Graphics System.
Added FIT keyword. 28 Feb 2011. DWF
Made default character size cgDefCharsize*0.85. 28 Feb 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
Added CHARPERCENT keyword 18 March 2011. DWF.
Added XTITLE and YTITLE keywords, which do nothing except prevent these keywords
from being used inadvertently. 27 May 2011. DWF.
(See cgcolorbar.pro)
:Description:
Provides a device-independent and color-model-independent way to fill a polygon
with a particular color. This is a wrapper to the PolyFill command in IDL.
:Categories:
Graphics
:Params:
x: in, required, type=number
A vector argument providing the X coordinates of the points to be connected.
The vector must contain at least three elements. If only one argument is
specified, X must be an array of either two or three vectors (i.e., (2,*)
or (3,*)). In this special case, the vector X[0,*] specifies the X values,
X[1,*] specifies Y, and X[2,*] contain the Z values.
y: in, required, type=number
A vector argument providing the Y coordinates of the points to be connected.
Y must contain at least three elements.
z: in, optional, type=number
An optional vector argument providing the Z coordinates of the points to be
connected. Z must contain at least three elements.
:Keywords:
color: in, optional, type=string/integer/long, default='rose'
The name of the fill color. Color names are those used with cgColor.
This value can also be a long integer or an index into the current color
table.
device: in, optional, type=boolean, default=0
Set to indicate the polygon vertices are in device coordinates.
normalized: in, optional, type=boolean, default=0
Set to indicate the polygon vertices are in normalized coordinates.
window: in, optional, type=boolean, default=0
Set this keyword to add the command to the current cgWindow application.
_extra: in, optional, type=appropriate
Any other keywords to the IDL POLYFILL command may be used.
:Examples:
Used like the IDL Polyfill command::
IDL> cgColorFill, [0.25, 0.25, 0.75, 0.75, 0.25], [0.25, 0.75, 0.75, 0.25, 0.25], $
/NORMAL, COLOR='blue'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 24 December 2010. DWF.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Added WINDOW keyword. 24 Jan 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgcolorfill.pro)
:Description:
The purpose of cgContour is to create a wrapper for the traditional IDL graphics
command, Contour. The Contour command has a number of deficiencies that make it
difficult to use in a modern computing environment. cgContour corrects these
deficiencies and allows the user to produce traditional contour plots in a device
and machine independent manner.
:Categories:
Graphics
:Params:
data: in, required, type=any
A one- or two-dimensional array containing the values that make
up the contour surface.
x: in, optional, type=any
A vector or two-dimensional array specifying the X coordinates for
the contour surface.
y: in, optional, type=any
A vector or two-dimensional array specifying the Y coordinates for
the contour surface.
:Keywords:
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow. Setting this keyword
automatically sets the WINDOW keyword, but the command does not erase the
graphics window as it would normally.
axiscolor: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the axis color. By default, 'black'.
Otherwise, the keyword is assumed to be a color index into the current color table.
axescolor: in, optional, type=string/integer
Provisions for bad spellers.
background: in, optional, type=string/integer, default='white'
If this keyword is a string, the name of the background color. By default, 'white'.
Otherwise, the keyword is assumed to be a color index into the current color table.
c_colors: in, optional, type=integer/string vector
Set to the index values of the contour colors or to named colors. Must contain
the same number of colors as the number of requested contour levels.
c_labels: in, optional, type=integer vector
A vector that specifies which contour levels to label. If used, the LABEL
keyword is ignored.
cell_fill: in, optional, type=boolean, default=0
Set to indicate filled contours should be created using the "cell fill" method.
This keyword should always be set if displaying filled contours on map projections
or if missing data is present in the data you are contouring.
charsize: in, optional, type=float, default=cgDefCharSize()
The character size for axes annotations. Uses cgDefCharSize to select default
character size, unless !P.Charsize is set, in which case !P.Charsize is always used.
color: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the data color. By default, same as AXISCOLOR.
Otherwise, the keyword is assumed to be a color index into the current color table.
font: in, optional, type=integer, default=!P.Font
The type of font desired for axis annotation.
fill: in, optional, type=boolean, default=0
Set to indicate filled contours should be created.
irregular: in, optional, type=boolean
If this keyword is set, the data, x, and y input parameters are taken to be
irregularly gridded data, the the data is gridded for use in the contour plot
using the Triangulate and Trigrid method. The resolution of the gridded output
is set by the RESOLUTION keyword.
label: in, optional, type=integer, default=1
An number that tells how to label contour levels. A 0 means
no contour levels are labelled. A 1 (the default) means all contour levels are
labelled. A 2 means label every 2nd contour level is labelled. A 3 means every
3rd contour level is labelled, and so on.
layout: in, optional, type=intarr(3)
This keyword specifies a grid with a graphics window and determines where the
graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location].
The grid is determined by the number of columns (ncolumns) by the number of
rows (nrows). The location of the graphic is determined by the third number. The
grid numbering starts in the upper left (1) and goes sequentually by column and then
by row.
levels: in, optional, type=any
A vector of data levels to contour. If used, NLEVELS is ignored. If missing,
NLEVELS is used to construct N equally-spaced contour levels.
missingvalue: in, optional, type=any
Use this keyword to identify any missing data in the input data values.
nlevels: in, optional, type=integer, default=6
If the Contour plot LEVELS keyword is not used, this keyword will produce this
number of equally spaced contour intervals. Unlike the Contour NLEVELS keyword,
this keyword actually works!
noerase: in, optional, type=boolean, default=0
Set this keyword to prevent the window from erasing the contents before displaying
the contour plot.
overplot: in, optional, type=boolean
Set this keyword to overplot the contours onto a previously established
data coordinate system.
palette: in, optional, type=bytarr(256,3)
A color palette containing the RGB color vectors to use for coloring contours.
Contour colors will be sampled from the color table palette into the number
of contour levels required. If the palette is NOT 256 elements in length, then
it is assumed that the length corresponds to the number of levels to be contoured.
position: in, optional, type=float
Set this keyword to a four-element [x0,y0,x1,y1] array giving the contour plot
position in normalized coordinates.
resolution: in, optional, type=integer array, default=[41\,41]
If the IRREGULAR keyword is set, this keyword specifies the X and Y resolution
in a two element integer array of the final gridded data that is sent to the
contour plot.
traditional: in, optional, type=boolean, default=0
If this keyword is set, the traditional color scheme of a black background for
graphics windows on the display is used and PostScript files always use a white background.
window: in, optional, type=boolean, default=0
Set this keyword if you want to display the plot in a resizable graphics window.
xstyle: in, optional, type=integer, default=1
If unused in the program, set to 1 to force exact axis scaling.
ystyle: in, optional, type=integer, default=1
If unused in the program, set to 1 to force exact axis scaling.
_extra: in, optional, type=any
Any keyword appropriate for the IDL Contour command is allowed in the program.
:Examples:
Use as you would use the IDL CONTOUR command::
data = dist(51)
cgContour, data
LoadCT, 33
cgContour, data, /FILL
cgContour, data, /OVERPLOT
If you wish to overplot on top of an image, use the ONIMAGE keyword, rather
than the OVERPLOT keyword:
cgImage, data, /SCALE, XRANGE=[-10, 10], YRANGE=[-5,5], /AXES
cgContour, data, /ONIMAGE
See http://www.dfanning.com/graphics_tips/cgcontour.html for additional examples.
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 11 November 2010. DWF.
Restored the CELL_FILL keyword, which had been accidentally removed in
the earlier version. 12 November 2010. DWF.
Add the ability to specify the contour colors as color names. 16 November 2010. DWF.
Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF.
Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF.
Background keyword now applies in PostScript file as well. 17 November 2010. DWF.
Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF.
Fixed a small problem with the OVERPLOT keyword. 18 Nov 2010. DWF.
Changes so that color variables don't change type. 23 Nov 2010. DWF.
Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF
Modifications to allow cgContour to be drop-in replacement for old Contour commands in
indexed color mode. 24 Dec 2010. DWF.
Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF.
Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF.
Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF.
Change to DECOMPOSED color was using incorrect color tables. 29 Dec 2010. DWF.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Still working on getting contour colors to work in decomposed color mode in all
circumstances. 2 Jan 2011. DWF.
Fixed problem with FILL when no contour colors (C_COLORS) are specified. 3 Jan 2011. DWF.
Fixed a problem that preventing output keyword (e.g., PATH_INFO) from being returned properly.
3 Jan 2011. DWF.
Fixed a problem calculating NLEVELS when LEVELS keyword was used instead. 3 Jan 2011. DWF.
TVLCT commands protected from NULL device. 4 Jan 2011. DWF.
Fixed a no color problem when CELL_FILL was set. 11 Jan 2011. DWF.
Fixed a problem with overlaying filled contours with /OVERPLOT. 11 Jan 2011. DWF.
Selecting character size now with cgDefCharSize. 11 Jan 2011. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF.
Added ADDCMD keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 28 Jan 2011. DWF.
Added PALETTE keyword. 4 Feb 2011. DWF.
Color table vectors must be obtained AFTER loading the color palette. 6 March 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
Modifications to allow palettes of less than 256 elememts in length to be used. 1 April 2011. DWF.
Modifications to repair axes and tickmarks when creating filled contour plots. 28 May 2011. DWF.
Whoops! Last fix shouldn't apply to OVERPLOTTING. Fixed. 22 June 2011. DWF.
Still more work to get axes overplotting to work correct. 5 July 2011. DWF.
Added an ONIMAGE keyword that allows the contours to be overplotted on top of an image that
has been displayed with cgImage. This requires that the SAVE keyword is set in the
cgImage call.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgcontour.pro)
:Description:
Allows the user to set various properties of an cgWindow object. This is essentially
a wrapper to the cgWindow SetProperty method.
:Categories:
Graphics
:Params:
selection: in, required, type=varies
Normally, a window index number of an cgWindow application. But, the selection
can be a widget identifier, an object reference, or a window title, depending on
which keywords are set. The cgWindow matching the selection has its properties set.
:Keywords:
all: in, optional, type=boolean
This keyword applies only to keywords that manipulate commands in the command
list (e.g., DeleteCmd). It will select all the commands in the command list to
apply the action to.
adjustsize: in, optional, type=boolean
Set this keyword to adjust default character size to the display window size.
background: in, optional, type=string
The background color of the window. Only use if the ERASEIT property is also set.
cmdindex: in, optional, type=integer
This keyword applies only to keywords that manipulate commands in the command
list (e.g., DeleteCmd). It specifies the command index number of the command
for which the action is desired.
create_bmp: in, optional, type='string', default='cgwindow.bmp'
Set this keyword to the name of a bitmap file to create automatically from the window.
Using this keyword is a way to create a bitmap file programmatically from a cgWindow application.
The raster file will be created via ImageMagick if im_raster has been set (default).
create_gif: in, optional, type='string', default='cgwindow.gif'
Set this keyword to the name of a GIF file to create automatically from the window.
Using this keyword is a way to create a GIF file programmatically from a cgWindow application.
The raster file will be created via ImageMagick if im_raster has been set (default).
create_jpeg: in, optional, type='string', default='cgwindow.jpeg'
Set this keyword to the name of a JPEG file to create automatically from the window.
Using this keyword is a way to create a JPEG file programmatically from a cgWindow application.
The raster file will be created via ImageMagick if im_raster has been set (default).
create_png: in, optional, type='string', default='cgwindow.png'
Set this keyword to the name of a PNG file to create automatically from the window.
Using this keyword is a way to create a PNG file programmatically from a cgWindow application.
The raster file will be created via ImageMagick if im_raster has been set (default).
create_ps: in, optional, type='string', default='cgwindow.ps'
Set this keyword to the name of a PostScript file to create automatically from the window.
Using this keyword is a way to create a PostScript file programmatically from a cgWindow application.
create_tiff: in, optional, type='string', default='cgwindow.tiff'
Set this keyword to the name of a TIFF file to create automatically from the window.
Using this keyword is a way to create a TIFF file programmatically from a cgWindow application.
The raster file will be created via ImageMagick if im_raster has been set (default).
delay: in, optional, type=float
Set this keyword to the amount of "delay" you want between commands in the command list.
deletecmd: in, optional, type=boolean
Set this keyword to delete a command in the cgWindow. The keywords cmdIndex and All
are used in deleting the specified command.
destroy: in, optional, type=boolean
Set this keyword to destroy the cgWindow program. This keyword should not be used
with other keywords.
dimensions: in, optional, type=intarr(2)
Set this keyword to a two-element array giving the xsize and ysize
of the draw widget.
eraseit: in, optional, type=boolean
If this property is set, the cgWindow erases with the background color before
displaying the commands in the window's command list.
execute: in, optional, type=boolean
Set this keyword to 1 to exectute the commands in the window's command list.
Set this keyword to 0 to prevent command excution. This is useful, for example,
if you want to load commands without having them be executed immediately.
get_keycmdindex: in, optional, type=integer
Set this value to the number of the command (zero-based) for which you want to
obtain the keyword value. If not provided, the first command (command 0) is searched.
get_keyword: in, optional, type=string
The name of the keyword whose value you want to return in get_keyvalue. The name must
be spelled EXACTLY as you used the keyword, except that case does not matter. The string
is converted to UPPERCASE to locate the proper keyword. Although it was my intention to use
this to retrieve output keyword values, this is not possible using cgWindow due to the way
Call_Procedure and keyword inheritance work.
get_keyvalue: out, optional, type=any
The value of the keyword specified in get_keyword. If the keyword cannot be found, this
value will be undefined. You MUST check for this before using the return variable in your program.
im_transparent: in, optional, type=boolean, default=0
Set this keyword to allow ImageMagick to create transparent backgrounds when it
makes raster image files from PostScript output.
im_density: in, optional, type=integer, default=300
Set this keyword to the sampling density when ImageMagick creates raster image
file from PostScript outout.
im_options: in, optional, type=string, default=""
Set this keyword to any ImageMagick options you would like to pass along to the
ImageMagick convert command when creating raster image files from PostScript output.
im_resize: in, optional, type=integer, default=25
Set this keyword to percentage that the raster image file created my ImageMagick
from PostScript output should be resized.
im_raster: in, optional, type=boolean, default=1
Set this keyword to zero to create raster files using the create_png etc. keywords
directly, instead of via ImageMagick.
multi: in, optional, type=Intarr(5)
Set this keyword to the !P.MULTI setting you want to use for the window.
!P.MULTI is set to this setting before command execution, and set back to
it's default value when the commands are finished executing.
object: in, optional, type=boolean
If this keyword is set, the selection is assumed to be an object reference.
palette: in, optional, type=BytArr(N,3)
Use this keyword to pass in an N-by-3 (or 3-by-N) byte array containing the
R, G, and B vectors of a color table. It is probably easier to use cgLoadCT or
XCOLORS to load color tables for the window, but this is provided as another option.
ps_delete: in, optional, type=boolean, default=1
Set this keyword to zero if you want to keep the PostScript output ImageMagick creates
when making raster file output.
ps_encapsulated: in, optional, type=boolean, default=0
Set this keyword to configure PSCONFIG to produce encapsulated PostScript output by default.
ps_metric: in, optional, type=boolean, default=0
Set this keyword to configure PSCONFIG to use metric values and A4 page size in its interface.
ps_quiet: in, optional, type=boolean, default=0
Set this keyword to set the QUIET keyword on PS_Start.
title: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a window title. All
matching is done in uppercase characters.
update: in, optional, type=boolean, default=1
Set this keyword to zero if you do not want the updates to be done immediately
after the properties are changed.
widgetid: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a widget identifier.
xomargin: in, optional, type=intarr(2)
Sets the !X.OMargin system variable when multiple plots are displayed in the window.
yomargin: in, optional, type=intarr(2)
Sets the !Y.OMargin system variable when multiple plots are displayed in the window.
:Examples:
Used to set cgWindow properties::
IDL> cgControl, Background='gray', EraseIt=1
IDL> cgControl, Multi=[0,2,2]
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 28 January 2011. DWF.
Added im_raster and the create_... raster options. 18 Feb 2011. Jeremy Bailin
Added the ability to set and unset adjustable text size in
cgWindow with ADJUSTSIZE keyword. 24 April 2011. DWF.
Added the ability to set the dimensions of the draw widget programmatically. 14 June 2011.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
Added CREATE_PS keyword. 16 Feb 2011. DWF.
Added PS_QUIET, GET_KEYCMDINDEX, GET_KEYWORD, and GET_KEYVALUE keywords. 17 Feb 2011. DWF.
(See cgcontrol.pro)
NAME:
cgDCBar
PURPOSE:
The purpose of this routine is to add a discrete color bar to
a graphics plot. A "discrete" color bar is one with a handful
of colors. Labels are centered beneath or beside the color fields.
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:
cgDCBar
INPUTS:
colors: A vector of "colors" to be represented in the color bar. The
vector can be a vector of color "names" that are known to cgCOLOR.
Or, it can be a vector of 24-bit color values that can be decomposed
into color triples. Or, it can be a vector of byte or integer values
that can be used as indices into the current color table. If both colors
and NCOLORS (see below) are undefined, a 10-element color table will be
loaded and used.
KEYWORD PARAMETERS:
ADDCMD: Set this keyword to add the cgDCBar command to the current cgWindow
command list.
BARCOLOR: This is the name of a color known to cgCOLOR that can be
used to draw the color bar outlines. By default, the same as
specified with the COLOR keyword.
BOTTOM: The lowest color index of the colors to be loaded in
the color bar. Used in conjunction with NCOLORS when the colors
argument is not used.
CHARSIZE: The size of the color bar annotations. By default, !P.Charsize.
COLOR: This is the name of a color known to cgCOLOR that can be
used to draw the color bar annotations (labels and title).
By default, "Black" for the PostScript device, and "White"
for all other devices. If unspecified, the "color" of the
pixel in the upper-right corner of the display will be used
to choose either "black" or "white".
FILE: The name of a color table file that can be read by cgCOLOR.
This allows you to specify your own color names for your own colors.
FONT: Set this keyword to the type of font desired for labels. Similar to !P.FONT.
The default is to use the !P.FONT value.
LABELS: The labels that should annotate each color. Must be the same length
as the colors vector. Colors are labelled consecutively by default.
NCOLORS: An alternative way to specify the colors in the color bar is by
using the NCOLORS and BOTTOM keywords to locate the colors in the
current color table. The NCOLORS and BOTTOM keywords have the same
meaning as in the LOADCT, XLOADCT, XCOLORS, or cgCOLORBAR programs.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.85, 0.1, 0.90, 0.9] for a vertical color bar and
[0.1, 0.88, 0.9, 0.93] for a horizontal color bar.
RIGHT: Set this keyword to put the title to the right of a vertical
color bar. The default is to put the title to the left of a
vertical color bar. The keyword has no effect for a horizontal
color bar.
ROTATE: Set this keyword to a value that will rotate the label text.
Positive values between 0 and 180 degrees rotate in a counter-clockwise
sense. Negative values between 0 and 180 degress rotate in a
clockwise sense.
SPACING: When labels are rotated, it is a little difficult to determine where,
exactly, they should be located. This keyword gives the user some control
over this location. The default spacing is 1.0. The location "spacer" is
multiplied by this amount. So, for example, to move the labels a little
further away from the color bar, make this number greater than 1 (e.g, 1.25).
To move the labels a little closer, use a number less than 1 (e.g, 0.75).
TITLE: This is title for the color bar. The default is to have no title.
TCHARSIZE: The size of the title. By default, same as CHARSIZE.
VERTICAL: Setting this keyword give a vertical color bar. The default
is a horizontal color bar.
WINDOW: Set this keyword to add the color bar to an cgWindow display.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
REQUIRED PROGRAMS:
The number of programs are required from the Coyote Library.
http://www.dfanning.com/documents/programs.html
Known to be among these are the following.
http://www.dfanning.com/programs/color24.pro
http://www.dfanning.com/programs/cgLoadCT.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/cgcolor.pro
EXAMPLE:
To display a 12 color horizontal color bar, labels with a three-letter
month abbreviation.
IDL> Window
IDL> LoadCT, 5, NCOLORS=12, BOTTOM=1
IDL> cgDCBar, NCOLORS=12, BOTTOM=1, LABELS=theMonths(/Abbreviation)
To load a 5 color vertical color bar, with the labels rotated 45 degrees.
IDL> Window
IDL> labels = StrArr(5)
IDL> FOR j=0,4 DO labels[j] = 'City ' + StrTrim(j+1,2)
IDL> colors = ['dodger blue', 'yellow', 'forest green', 'purple', 'tan']
IDL> cgDCBar, colors, LABELS=labels, ROTATE=45, /VERTICAL
MODIFICATION HISTORY:
Written by: David W. Fanning, 15 March 2009.
Modification to code to avoid changing the colors vectors. 15 March 2009.
Added FONT keyword. 1 April 2009. DWF.
Code modified to support 24-bit PostScript printers. 23 September 2009. DWF.
Fixed a problem with determining visual depth in Z-buffer. 15 January 2010. DWF.
Added SPACING keyword and changed the default spacing on horizontal color bars slightly.
23 Apr 2010. DWF.
Modified the spacing of the labels on the color bar, specifically for the
PostScript device. 3 November 2010. DWF.
Added Window and AddCmd keywords. 28 Jan 2011. DWF.
Added a Right keyword and changed the title spacing a little bit for
aesthetic reasons. 2 July 2011. DWF.
(See cgdcbar.pro)
:Description:
Defines a default character size for Coyote Graphics routines (cgPlot, cgContour, etc.)
IF !P.Charsize is set, the function simply returns !P.Charsize.
:Categories:
Graphics, Utilities
:Params:
None.
:Keywords:
adjustsize: in, optional, type=boolean, default=0
If this keyword is set, the output character size is adjusted to
fit the size of the output graphics window. No adjustment is ever
done in PostScript. Applies only when !P.Charsize=0.
font: in, optional, type=integer, default=!P.Font
The font type: -1 = Hershey, 0 = hardware, 1 = true-type.
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 11 January 2011. DWF.
Added an ADJUSTSIZE keyword to allow adjustable sizing of characters
in resizeable graphics windows. 24 April 2011. DWF.
Made sure this program only adjusts text size on devices that support
windows. 20 July 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgdefcharsize.pro)
:Description:
Allows the user to delete one or more cgWindow applications. The cgWindow can
be identifed by window index number, widget identifier, title, or object reference,
depending on which keywords are set.
:Categories:
Graphics
:Params:
selection: in, optional, type=varies
Normally, a window index number of an cgWindow application. But, the selection
can be a widget identifier, an object reference, or a window title, depending on
which keywords are set. The cgWindow matching the selection is deleted. If not
provided, the current cgWindow is deleted.
:Keywords:
all: in, optional, type=boolean, default=0
If this keyword is set, all the cgWindow applications currently on the display
are deleted.
object: in, optional, type=boolean
If this keyword is set, the selection is assumed to be an object reference.
title: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a window title. All
matching is done in uppercase characters.
widgetid: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a widget identifier.
:Examples:
Used to delete an cgWindow application::
IDL> cgDelete, 'Window 1', /TITLE
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 24 January 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgdelete.pro)
NAME:
cgDemoData
PURPOSE:
The purpose of this function is to read a selection of standard
data sets that are found in the normal IDL distribution in the
subdirectory $IDL_DIR/examples/data. At least 25 data sets are
available in all categories of data. The user selects one of the
possible data sets with the mouse. Several of the data sets
simply create data used to illustrate graphics commands (numbers 1-3),
and two of the data sets produce random data. Data set 17 produces
a random vector of 101 elements. Data set 18 produces a 2D array of
random values, suitable for display as a contour plot or image.
CATEGORY:
File I/O.
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/
CALLING SEQUENCE:
If calling from the IDL command line:
data = cgDemoData()
If calling from within a widget program:
data = cgDemoData(Cancel=cancelled, Group_Leader=event.top)
If you know which data set you want, you can load it directly:
data = cgDemoData(7)
OPTIONAL INPUTS:
selection : The number of the data selection. Values start at 1,
and go up to the number of data sets available (currently 25).
KEYWORD PARAMETERS:
CANCEL : An output keyword that is 1 of the use clicked the CANCEL
button and 0 otherwise.
data = cgDemoData(Cancel=cancelled)
IF cancelled THEN RETURN
GROUP_LEADER: The group leader of the widget. This keyword
is required if you wish cgDemoData to be a modal widget program.
(Which you *always* do when calling it from a widget program.)
IMAGES: Set this keyword if you only want to select 2D image
data sets. Note that the selection number does *not* change
just because fewer data sets are available in the selection
widget.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To load the world elevation data set:
image = cgDemoData(7)
MODIFICATION HISTORY:
Written by: David W. Fanning, 5 March 1999.
Added some additonal random data capability. 29 April 99. DWF
Added IMAGES keyword. 31 March 2000. DWF.
Fixed a problem with the CANCEL button. 25 Oct 2002. DWF.
Added new JPEG, DICOM, TIFF, and PGN images. 30 Oct 2002. DWF.
Modified old program units to work with IDL strict arrays. 29 June 2003. DWF
(See cgdemodata.pro)
:Description:
The purpose of cgDisplay is to open a graphics window on the display, or in the
PostScript device, or in the Z-graphics buffer, depending upon the current graphics
device. In PostScript a window of the proper aspect ratio is created with PSWindow.
Using cgDisplay to open "windows" will allow you to more easily write device-independent
IDL programs.
:Categories:
Graphics
:Params:
xsize: in, optional, type=integer, default=640
The X size of the graphics window created. By default, 640.
ysize: in, optional, type=integer, default=512
The Y size of the graphics window created. By default, 512.
:Keywords:
color: in, optional, type=string/integer, default='white'
If this keyword is a string, the name of the data color. By default, 'white'.
Color names are those used with cgColor. Otherwise, the keyword is assumed
to be a color index into the current color table. The color is not used if
the "window" is opened in PostScript on the Z-graphics buffer.
free: in, optional, type=boolean, default=0
Set this keyword to open a window with a free or unused window index number.
This keyword applied only to graphics windows created on the computer display.
wid: in, optional, type=integer, default=0
The window index number of the IDL graphics window to create.
xsize: in, optional, type=integer, default=640
The X size of the graphics window created. By default, 640. The XSIZE parameter
is used in preference to the XSIZE keyword value.
ysize: in, optional, type=integer, default=512
The Y size of the graphics window created. By default, 512. The YSIZE parameter
is used in preference to the YSIZE keyword value.
_extra: in, optional, type=any
Any keywords supported by the WINDOW command are allowed.
:Examples:
Use like the IDL WINDOW command::
IDL> cgDisplay, XSIZE=500 YSIZE=400
IDL> cgDisplay, 500, 500, WID=1, COLOR='gray'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 15 November 2010. DWF.
Changes so that color variables don't change type. 23 Nov 2010. DWF.
Moved the window index argument to the WID keyword. 9 Dec 2010. DWF.
Modified to produce a window in PostScript and the Z-buffer, too. 15 Dec 2010. DWF.
Added the FREE keyword. 3 January 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgdisplay.pro)
:Description:
Provides a device-independent and color-model-independent way to erase a graphics
window with a particular color.
:Categories:
Graphics
:Params:
background_color: in, optional, type=string/integer/long, default='white'
The color to use in erasing the graphics window. Default is "white."
Color names are those used with cgColor.
:Keywords:
color: in, optional, type=string/integer/long, default='white'
An alternative way to specify the color to use in erasing the graphics window.
Color names are those used with cgColor. This parameter is used in
preference to the background_color parameter.
layout: in, optional, type=intarr(3)
This keyword specifies a grid with a graphics window and determines where the
graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location].
The grid is determined by the number of columns (ncolumns) by the number of
rows (nrows). The location of the graphic is determined by the third number. The
grid numbering starts in the upper left (1) and goes sequentually by column and then
by row. If this keyword is used, only this portion of the window is erased.
window: in, optional, type=boolean, default=0
Set this keyword to erase the current cgWindow application. "Erasing" in
this case means removing all the current commands.
:Examples:
Used to "erase" various things::
IDL> cgErase
IDL> cgErase, 'gray'
IDL> cgErase, COLOR='charcoal'
IDL> cgPlot, cgDemoData(1), /Window
IDL> cgErase, /Window
IDL> cgPlot, cgDemoData(17), Layout=[2,2,1]
IDL> cgPlot, cgDemoData(17), Layout=[2,2,4]
IDL> cgErase, Layout=[2,2,1]
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 12 November 2010. DWF.
Modified so that input variables are not changed. 18 Nov 2010. DWF.
Got my color selection algorithm right. COLOR keyword takes precedence
over the parameter. 18 Nov 2010. DWF.
Modified to erase in decomposed color, if possible.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Added WINDOW keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 1 Feb 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgerase.pro)
NAME:
cgHISTOPLOT
PURPOSE:
This program is used to draw a histogram in an IDL direct 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
CALLING SEQUENCE:
cgHistoplot, dataToHistogram
ARGUMENTS:
dataToHistogram: The data from which the histogram is created.
INPUT KEYWORDS:
ADDCMD: Set this keyword to add the command to an FSC_Window
command list. Setting this keyword automatically sets
the WINDOW keyword.
AXISCOLORNAME: The name of the axis color. Default: "Black". (All color names
derived from cgCOLOR.)
BACKCOLORNAME: The name of the background color. Default: "White".
BINSIZE: The binsize of the histogram. By default, Scott's Choice of
bin size for histograms is used:
binsize = (3.5 * StdDev(data)) / N_Elements(data)^(0.3333)
If BINSIZE in not defined, and NBINS is defined, the BINSIZE is
calcuated as:
binsize = (Max(dataToHistogram) - Min(dataToHistogram)) / (NBINS -1)
CHARSIZE: The character size. Default set by calling cgDefCharSize().
DATACOLORNAME: The name of the data color for drawing the histogram outlines.
Default: "Indian Red".
FILE: The name of a color name file to use with cgCOLOR.
FILLPOLYGON: Set this keyword to fill the histogram polygons. If this keyword
is set, the following keyword can also be used.
POLYCOLOR: The name, or vector of names, of polygon colors.
If a vector, the names are cycled though, as needed.
Defaults to 'ROSE'.
FREQUENCY: If this keyword is set, the relative frequency is plotted on the Y axis,
rather than the histogram density.
L64: If set, the return value of HISTOGRAM are 64-bit integers, rather than
the default 32-bit integers.
LAYOUT: This keyword specifies a grid with a graphics window and determines
where the graphic should appear. The syntax of LAYOUT is a 3-element
array: [ncolumns, nrows, location]. The grid is determined by the
number of columns (ncolumns) by the number of rows (nrows). The location
of the graphic is determined by the third number. The grid numbering
starts in the upper left (1) and goes sequentually by column and then
by row.
LINE_FILL: If set, the polygons are filled with lines instead of solid color. If
this keyword is set, the following keywords can also be used.
ORIENTATION: The orientation of the lines in line-filled polygons in degrees.
PATTERN: Set to rectangular array of pixel giving fill pattern.
POLYCOLOR: The name, or vector of names, of line colors.
If a vector, the names are cycled though, as needed.
SPACING: The spacing, in centimeters, between parallel lines.
MAXINPUT: The maximum value to use in calculating input histogram. Equivalent to MAX keyword
in HISTOGRAM documentation.
MAX_VALUE: The maximum Y data value to represent on graphics plot. Default: Max(histdataToPlot) * 1.05
MININPUT: The minimum value to use in calculating input histogram. Equivalent to MIN keyword
in HISTOGRAM documentation.
MIN_VALUE: The minimum Y data value to represent on graphics plot. Default: 0.
MISSING: The value that should be represented as "missing" and not used in the histogram.
Be aware that if the input data is not of type "float" or "double" that the input
data will be converted to floating point prior to calculating the histogram.
NAN: If set, ignore NAN values in calculating and plotting histogram.
NBINS: The number of output bins in the histogram. Meaning is slightly different from
meaning in the HISTOGRAM command. Used only to calculate BINSIZE when BINSIZE is
not specified. In this case, binsize = rangeofData/(nbins-1).
OPROBABILITY: Set this keyword if you want to overplot the cumulative probability on the plot.
OPLOT: Set this keyword if you want to overplot data on already established axes.
OUTLINE: Set this keyword if you wish to draw only the outline of the histogram plot,
in a manner similar to setting PSYM=10 on a PLOT command.
PROBCOLORNAME: The name of the probability color for overplotting the cumulative probability
on the plot. Default: "Blue".
THICK: Set this keyword to a value greater than 1 to draw thicker axes and lines.
WINDOW: Set this keyword to display the plot in a resizeable cgWindow program.
The user may also enter any other keywords suitable for the PLOT and POLYFILL commands in IDL.
OUTPUT KEYWORDS:
HISTDATA: The output value of the internal HISTOGRAM command.
LOCATIONS: Starting locations of each bin. (See HISTOGRAM documentation.)
OMAX: The maximum output value used to construct the histogram. (See HISTOGRAM documentation.)
OMIN: The minimum output value used to construct the histogram. (See HISTOGRAM documentation.)
PROBABILITY: The total cummulative probability of the histogram plot, scaled from 0 to 1.
REVERSE_INDICES: List of reverse indices. (See HISTOGRAM documentation.)
EXAMPLES:
IDL> cgHistoplot, Dist(256)
IDL> cgHistoplot, Fix(RandomU(seed, 200)*20), POLYCOLOR=['charcoal', 'steel blue'], /FILLPOLYGON
IDL> cgHistoplot, Fix(RandomU(seed, 200)*20), POLYCOLOR=['navy', 'forest green'], /LINE_FILL, ORIENTATION=[45,-45]
NOTE:
While it is pointed out in the HISTOGRAM documentation, it is extremely
important that the BINSIZE be of the same data type as the data you are going to
calculate the histogram of. If it is not VERY strange things can happen. I've
tried to protect you from most of the bad things, but I don't have a high confidence
level that I have done it for every situation. If you see something that "just don't
look right", I would check first to see if your data types match. That might solve
all the problems. :-)
MODIFICATION HISTORY:
Written by: David W. Fanning, 14 November 2007.
Modified to work with !P.MULTI. 20 Nov 2007. DWF.
Slight problem with extra space at the right end of the plot resolved. 20 Nov 2007. DWF.
Added FILE and NOLINES keywords. 24 Nov 2007. DWF.
Added additional HISTOGRAM access via keywords. 24 Nov 2007. DWF.
Fixed a small problem with FILLPOLY keyword. 26 Nov 2007. DWF.
Fixed a small problem with the OVERPLOTTED histogram being slightly offset. 12 Jan 2009. DWF
Major reconstructive surgery on the actual drawing part of the program. As far as I can
tell, all functionality is the same, but without drawing problems evidenced before. 14 March 2009. DWF.
A small problem with the way I was specifying ranges caused the bars to be slightly offset. 23 March 2009. DWF.
I fixed a small problem with BINSIZE and HISTOGRAM data type matching (see the Note), and I also
fixed a small problem with the range calculations when byte data is passed in. 1 April 2009. DWF.
I removed a NOLINES keyword, which was no longer being used. 1 April 2009. DWF.
MIN_VALUE and MAX_VALUE keywords now work again, thanks to Josiah Schwab. 22 April 2009. DWF.
Changed default POLYFILL color to "ROSE". 22 April 2009. DWF.
Having problems with binsize selection when data to histogram is an integer type. Fixed. 8 June 2009. DWF.
When the input array has a considerable number of NANs, the Histogram command complains with an error
"Array has too many elements." This happens even when the NAN keyword is set for the Histogram
command. So, I now screen for NANs before I process the histogram. 8 June 2009. DWF.
Added MISSING keyword to represent missing data. 18 July 2009. DWF.
Adding the MISSING keyword exposed a problem I had in restoring the original input data
to its original values when there were NANs and MISSING values. Fixed now by making
a copy of the data to work on internally. Everything else is too complex. 20 July 2009. DWF.
Yikes! Bad error in calculating start and end of histogram plot when overplotting fixed. 4 Sept 2009. DWF.
Added needed XSTYLE=1 to AXIS command to match Plot axis labelling. 19 Oct 2009. DWF.
Added a THICK keyword. 9 November 2009. DWF.
Added an OUTLINE keyword so only the outline of the histogram is plotted. 3 December 2009. DWF.
I was trying to be a good citizen by reloading the input color table when I exited
the program. But, of course, that makes it impossible to use the program in
the Z-buffer. Fixed by being less of a good citizen. 23 July 2010. DWF.
Because of the way I was dealing with NANs and MISSING data, the reverse indices were
inaccurate when they were returned, if there was NANs or MISSING data in the
input array. The data is now being handled correctly in all cases. This requires
that missing data must be set to !VALUES.F_NAN prior to calculating the histogram.
This means the data MUST be converted to floats for this operation. Since I am
always working on a *copy* of the data when this occurs, it should not affect
user input data. Also, I scan all input floating point and double data for NANs,
and if found, and the NAN keyword is not set, I issue a warning and set the NAN
keyword. This is a change in behavior. 1 October 2010. DWF.
Fixed a problem when specifying more than one POLYCOLOR. I made a change to the program
and forgot to propogate it everywhere. 4 October 2010. DWF.
Default axis color name changed from "Navy" to "Black". 28 October 2010. DWF.
Fixed a problem with restoring color tables in PostScript. 24 Nov 2010. DWF.
Added OPROBABILITY, PROBCOLOR, and PROBABILITY keywords. 24 Nov 2010. DWF.
Changed the way I find a default axis color. 3 Dec 2010. DWF.
Expanded search for "integers" from in BINSIZE calculation from DataType LE 3
to include DataType GE 12, too. 8 Dec 2010. DWF.
Added WINDOW keyword. 24 Jan 2011. DWF.
Added ADDCMD keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 28 Jan 2011. DWF.
Added CHARSIZE keyword. 2 Feb 2011. DWF.
Added YTITLE keyword. 9 May 2011. DWF.
Worked around a PLOT problem when setting the X axis range that caused the Y axis
range to be corrupted. 19 May 2011. DWF.
(See cghistoplot.pro)
NAME:
cgIMAGE
PURPOSE:
This purpose of cgIMAGE is to create a device-independent TV command
with the power and functionality to be used in sophisticated graphics
programs, as well as at the IDL command line. It can be thought of as
a "smart" TV command.
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.idlcoyote.com/
CATEGORY:
Graphics display.
CALLING SEQUENCE:
cgIMAGE, image
INPUTS:
image: A 2D (MxN) or 24-bit (e.g., MxNx3) byte array. A
24-bit image with an alpha channel (e.g., MxNx4) is
also permitted. The alpha channel will be blended with
the current background image. See the AlphaBackgroundImage
keyword for details.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
KEYWORD PARAMETERS:
ADDCMD: Set this keyword to add the cgImage command to an cgWindow
command list. Setting this command will force ERASEIT to be set
to 0, so the cgImage command can exist peacefully with other commands
in an cgWindow command list. Setting this keyword automatically sets
the WINDOW keyword.
ALPHABACKGROUNDIMAGE: Normally, when a image with an alpha channel is displayed,
the image is blended with the image currently in the display window.
This means, the program has to obtain that background image. This is not a
problem on devices (e.g., WIN, X, Z) that allow this kind of operation,
but it is on devices (e.g., the PostScript device, PS) that do not.
To get around this problem, you can pass the background image to the
cgImage program, along with the alpha channel image you wish to display
(via the image parameter) and the alpha channel image will be blended
with this image appropriately on all devices. If an alpha channel image
is displayed on a device in which there is no way to obtain the background
image, and this keyword is not used to pass a background image, then
the alpha channel image will be blended with a white background image.
This keyword is only used if an alpha channel image is passed to the
program via the image parameter. The AlphaBackgroundImage does not need
to have the same dimensions as the alpha channel image.
ALPHABGPOSITION: Normally, the alpha background image is displayed in the current graphics
window, or is taken from the current graphics window. This is not always correct.
Sometimes you want to actually position both the background and foreground image
in a window. If this keyword is used to specify a position, the alphabackground image
will be positioned at this location before the blending occurs.
AXES: Set this keyword to draw a set of axes around the image. Setting this
keyword also sets SAVE=1, unless told otherwise.
AXKEYWORDS: An IDL structure variable of PLOT keywords as structure fields
and keyword values as the values of the fields. Pass directly to the
PLOT command that draws the axes for the image. Ignored unless the
AXES keyword is set. For example,
cgImage, image, /AXES, AXKEYWORDS={TICKLEN:-0.025}
The axis color, range, title, font and character size must be
set with cgImage keywords ACOLOR, [XY]RANGE, [XY]TITLE, FONT, and
CHARSIZE.
BACKGROUND: This keyword specifies the name of the background color. The default is "white".
BOTTOM: IF SCALE=1, the image is scaled so that all displayed pixels have values
greater than or equal to BOTTOM and less than or equal to TOP.
The value of BOTTOM is 0 by default.
COLOR: Set this keyword to the name of an axis color. Default = "black".
CHARSIZE: Sets the character size. Used only if the AXES keyword is also set.
By default, the value from cgDefCharsize().
FONT: Set this to the type of font wanted on axis annotation. By default
FONT = !P.Font. Used only if the AXES keyword is also set.
_EXTRA: This keyword picks up any TV keywords you wish to use.
INTERPOLATE: Normally, nearest neightbor sampling is done when the image size changes.
Setting this keyword will cause linear interpolation to be used instead.
KEEP_ASPECT: An image uses the POSITION keyword to located itself in a graphics
window. If this keyword is set, then the image arranges itself in the
window in a manner that maintains its orginal aspect ratio (ratio of
height to width).
LAYOUT: This keyword specifies a grid with a graphics window and determines
where the graphic should appear. The syntax of LAYOUT is a 3-element
array: [ncolumns, nrows, location]. The grid is determined by the
number of columns (ncolumns) by the number of rows (nrows). The location
of the graphic is determined by the third number. The grid numbering
starts in the upper left (1) and goes sequentually by column and then
by row.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignored when cgImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics. The default margin is 0.05.
MAXVALUE: If defined, the data is linearly scaled between MINVALUE
and MAXVALUE. MAXVALUE is set to MAX(image) by default.
Setting this keyword to a value implies SCALE=1. If the maximum
value of the image is GT 255, this implies SCALE=1.
MINVALUE: If defined, the data is linearly scaled between MINVALUE
and MAXVALUE. MINVALUE is set to MIN(image) by default.
Setting this keyword to a value implies SCALE=1. If the minimum
value of the image is LT 0, this implies SCALE=1.
MULTIMARGIN: Sometimes, when displaying multiple images with !P.Multi, you
want the images to be slightly smaller than the position created
by !P.Multi so you can add, for example, a colorbar or an annotation
to the image. This keyword can be used to adjust the image position
by a small margin. A four-element array, the margins apply to the
[bottom, left, top, right] of the image position. So, to
leave room at the top of an image for a color bar, you might
type this:
cgImage, image, MultiMargin=[0, 0, 4, 0]
This keyword applies *only* to images displayed with !P.Multi, and if
passed a scalar value, will use the same value for all four positions.
MINUS_ONE: The value of this keyword is passed along to the FSC_RESIZE_IMAGE
command. It prevents FSC_RESIZE_IMAGE from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays. This keyword is set to 0 by default.
NCOLORS: If this keyword is supplied, the TOP keyword is ignored and
the TOP keyword is set equal to NCOLORS - 1. This
keyword is provided to make cgImage easier to use with the
color-loading programs such as LOADCT:
LoadCT, 5, NColors=100, Bottom=100
cgImage, image, NColors=100, Bottom=100
Setting this keyword to a value implies SCALE=1.
NOERASE: The default behavior is to erase the display before displaying
the image. Setting this keyword prevents the erasure.
NORMAL: Setting this keyword means image position coordinates x and y
are interpreted as being in normalized coordinates. This keyword
is only valid if the TV keyword is set.
OPOSITION: If the KEEP_ASPECT keyword is set, there is a good chance the
image's actual position in the window will differ from its input
position. This keyword will report the image's actual output
position, after it has been displayed and its position adjusted
to account for aspect ratio. Note that the POSITION keyword is
both an input and output keyword if the input position is passed
as a variable. The OPOSITION keyword allows you to obtain the
output position even if you pass the position in as a value.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
cgImage, image, /Overplot
PALETTE: Set this keyword to a 3 x N or N x 3 byte array containing
the RGB color vectors to be loaded before the image is displayed.
Such vectors can be obtained, for example, from cgLoadCT with the
RGB_TABLE keyword:
cgLoadCT, 4, /BREWER, /REVERSE, RGB_TABLE=palette
cgImage, cgDemoData(7), PALETTE=palette
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this keyword is ALSO
an output keyword. That is to say, upon return from cgImage
this keyword (if passed by reference) contains the actual
position in the window where the image was displayed. This
may be different from the input values if the KEEP_ASPECT_RATIO
keyword is set, or if you are using cgImage with the POSITION
keyword when !P.MULTI is set to something other than a single
plot. One use for the output values might be to position other
graphics (e.g., a colorbar) in relation to the image.
Note that the POSITION keyword should not, normally, be used
when displaying multiple images with !P.MULTI. If it *is* used,
its meaning differs slightly from its normal meaning. !P.MULTI
is responsible for calculating the position of graphics in the
display window. Normally, it would be a mistake to use a POSITION
graphics keyword on a graphics command that was being drawn with
!P.MULTI. But in this special case, cgImage will use the POSITION
coordinates to calculate an image position in the actual position
calculated for the image by !P.MULTI. The main purpose of this
functionality is to allow the user to display images along with
colorbars when using !P.MULTI. See the example below.
QUIET: There are situations when you would prefer that cgIMAGE does not
advertise itself by filling out the FSC_$CGIMAGE common block. For
example, if you are using cgImage to draw a color bar, it would
not be necessary. Setting this keyword means that cgImage just
goes quietly about it's business without bothering anyone else.
SAVE: Set this to cause a data coordinate system to be established
for the image. The XRANGE and YRANGE keyword values will be used
to establish a data coordinate system coincident with the final
image position. Setting the AXES keyword automatically sets SAVE=1.
SCALE: Set this keyword to byte scale the image before display. If this
keyword is not set, the image is not scaled before display.
TITLE: The title annotation. Used only if the keyword AXES is set.
TOP: IF SCALE=1, the image is scaled so that all displayed pixels have values
greater than or equal to BOTTOM and less than or equal to TOP.
The value of TOP is !D.Table_Size by default.
TV: Setting this keyword makes the cgImage command work much
like the TV command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored. Alpha channels are also ignored when this keyword
is set.
WINDOW: Set this keyword to add the command to an cgWindow application.
Setting this keyword ALWAYS sets the ERASEIT keyword. If you want
to add an image to an cgWindow without the ERASEIT keyword set,
use the ADDCMD keyword.
XRANGE: If the AXES keyword is set, this keyword is a two-element vector
giving the X axis range. By default, [0, size of image in X].
XTITLE: The X title string to use for the X image axis. Used only if the AXES
keyword is set.
YRANGE: If the AXES keyword is set, this keyword is a two-element vector
giving the Y axis range. By default, [0, size of image in Y].
YTITLE: The Y title string to use for the Y image axis. Used only if the AXES
keyword is set.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
thisPostion = [0.1, 0.1, 0.9, 0.9]
cgIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2]
cgImage, image, Margin=0
cgImage, image, Margin=0
cgImage, image, Margin=0
cgImage, image, Margin=0
!P.Multi = 0
To display four image in a window with associated color bars:
!P.Multi=[0,2,2]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 0
cgImage, image, Position=p
cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 2
cgImage, image, Position=p
cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 3
cgImage, image, Position=p
cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
p = [0.02, 0.3, 0.98, 0.98]
LoadCT, 5
cgImage, image, Position=p
cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05]
!P.Multi =0
MODIFICATION HISTORY:
Written by: David W. Fanning, from modifications to TVIMAGE. 3 Feb 2011.
8 Feb 2011. Added OPOSITION keyword. DWF.
27 Feb 2011. Added keywords to make cgImage more compatible with TVImage calls. DWF.
Color table vectors must be obtained AFTER loading the color palette. 6 March 2011. DWF.
I have been convinced (conversations with Wayne Landsman) that if the
CENTER keyword is set, the MINUS_ONE keyword is not needed, since
it was created to solve the same problem. So, I have changed the
default setting of MINUS_ONE to 0. 14 March 2011. DWF.
Corrected a problem with restoring color tables if a PALETTE is used. 31 March 2011. DWF.
Whoops! Documented a CHARSIZE keyword, but forgot to define it. 7 July 2011.
Damnation! I did the same thing with the FONT keyword! 25 July 2011.
(See cgimage.pro)
NAME:
cgImageInfo
PURPOSE:
The purpose of this program is allow interactive inquiry of image
position and values for images displayed with cgImage.
After a call to cgImage, cgImageInfo can be called and the user
can use the cursor to click in the image display window. If the user clicks
inside the image, the image location and value will be printed out in the
user's IDL console 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.idlcoyote.com/
CATEGORY:
Graphics display.
CALLING SEQUENCE:
cgImageInfo, image
INPUTS:
image: A 2D or 3D image array. Values will be returned from this (Required).
In versions of IDL < 8.0, it is possible to use a HASH object of
keys/images where this program will describe the value for each of
the images in the HASH object.
position: A four-element array giving image position in the window in normalized
coordinates. If not provided, uses the stored position from cgImage.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Image locations and values are printed in the IDL console window.
SIDE EFFECTS:
cgImageInfo blocks the IDL command line until the RIGHT mouse button is clicked
in the image display window.
RESTRICTIONS:
cgImageInfo *only* works for the last image displayed with cgImage
on a Windows or X device. Precautions are taken to help you avoid shooting
yourself in the foot, but I can't anticipate every foolish action at the
IDL command line. Expecially if you close the image window before exiting
the program with the RIGHT mouse button, you are COMPLETELY on your own!
Coyote Library programs are required to use cgImageInfo. Among the ones I know
about are these:
cgImage, SCALE_VECTOR, IMAGE_DIMENSIONS, ERROR_MESSAGE, CONVERT_TO_TYPE, FPUFIX.
If the program doesn't compile, you probably need library routines. They
can be found here:
http:/www.idlcoyote.com/documents/programs.html
EXAMPLE:
To display an image with axes and then inquire about it:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
thisPosition = [0.1, 0.1, 0.9, 0.9]
cgImage, image, /KEEP_ASPECT, POSITION=thisPosition, /AXES
cgImageInfo, image
MODIFICATION HISTORY:
Written by: David W Fanning, 16 March 2008.
Added ability to specify position directly in call. 20 March 2008. DWF
Changed cursor operation to conform with expected differences
between Windows and UNIX. 20 March 2008, DWF.
Slightly modified screen directions. 16 November 2010. DWF.
Modified so that multiple images/grids can be described 18 May 2011. MHS
(See cgimageinfo.pro)
Provide information about the selected xy-pixel from an image, or a hash of
images.
:Params:
iimage : in, required, type=image
a 2D or 3D image array
xpixel: in, required, type=int
the X location on the image to fetch information from
ypixel: in, required, type=int
the y location on the image to fetch information from
hsh :in, optional, type=HASH
if a valid HASH, it should contain key/Image (string/array) pairs that
will be described.
(See cgimageinfodescribevalues.pro)
NAME:
cgLoadCT
PURPOSE:
This is a drop-in replacement for the ITTVIS-supplied program LOADCT.
The same keywords used with LOADCT apply. In addition, a REVERSE keyword
is supplied to reverse the color table vectors, and a CLIP keyword is
supplied to be able to clip the normal LOADCT color table. This is
extremely useful if you wish to use a reduced number of colors. Also,
all color table loading is handled silently. (To fix a major pet-peeve
of mine.)
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:
cgLoadCT, table
AUGUMENTS:
table: Optional table number to load. Integer from 0 to the number of
tables in the file, minus 1. Default value is 0.
KEYWORDS:
ADDCMD: Set this keyword to add the cgLoadCT command to the current cgWindow
command list.
BOTTOM: The first color table index. Set to 0 by default.
BREWER: Set this keyword if you wish to use the Brewer Colors, as
implemented by Mike Galloy in the file brewer.tbl, and implemented
here as fsc_brewer.tbl. See these references:
Brewer Colors: http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
Mike Galloy Implementation: http://michaelgalloy.com/2007/10/30/colorbrewer.html
This program will look first in the $IDL_DIR/resource/colors directory for
the color table file, and failing to find it there will look in the same
directory that the source code of this program is located, then in the IDL path.
Finally, if it still can't find the file, it will ask you to locate it.
If you can't find it, the program will simply return without loading a color table.
NOTE: YOU WILL HAVE TO DOWNLOAD THE FSC_BREWER.TBL FILE FROM THE COYOTE LIBRARY AND
PLACE IT IN ONE OF THE THREE PLACES OUTLINED ABOVE:
http://www.dfanning.com/programs/fsc_brewer.tbl
CLIP: A one- or two-element integer array that indicates how to clip
the original color table vectors. This is useful if you are
restricting the number of colors, and do not which to have
black or white (the usual color table end members) in the
loaded color table. CLIP[0] is the lower bound. (A scalar
value of CLIP is treated as CLIP[0].) CLIP[1] is the upper
bound. For example, to load a blue-temperature color bar
with only blue colors, you might type this:
IDL> cgLoadCT, 1, CLIP=[110,240]
IDL> CINDEX
Or, alternatively, if you wanted to include white at the upper
end of the color table:
IDL> cgLoadCT, 1, CLIP=110
IDL> CINDEX
RGB_TABLE: If this keyword is set to a named variable, the color table
is returned as an [NCOLORS,3] array and no colors are loaded
in the display.
FILE: The name of a color table file to open. By default colors1.tbl in
the IDL directory.
GET_NAMES: If set to a named variable, the names of the color tables are returned
and no colors are loaded in the display. Note that RGB_TABLE cannot be
used concurrently with GET_NAMES. Use two separate calls if you want both.
NCOLORS: The number of colors loaded. By default, !D.TABLE_SIZE.
REVERSE: If this keyword is set, the color table vectors are reversed.
ROW: Set this keyword to indicate you are getting the RGB_TABLE vectors
for use in the IDL's object graphics routines. Whereas TVLCT expects color
tablesto be 256x3 (column vectors), the object graphics routines expect them
to be 3x256 (row vectors). Setting this keyword will transpose the vectors
before they are returned.
SILENT: This keyword is provided ONLY for compatibility with LOADCT. *All*
color table manipulations are handled silently.
WINDOW: Set this keyword to send the colors to an cgWindow program.
WINID: The window index number of an cgWindow to receive the color vectors.
EXAMPLES:
Suppose you wanted to create a color table that displayed negative values with
red-temperature values and positive values with blue-temperature values, and you
would like the red-temperature values to be reversed in the color table (so dark
colors adjoin in the color table and indicate values near zero). You could do this:
cgLoadCT, 0
cgLoadCT, 3, /REVERSE, CLIP=[32,240], BOTTOM=1, NCOLORS=10
cgLoadCT, 1, CLIP=[64, 245], BOTTOM=11, NCOLORS=10
cgColorbar, NCOLORS=20, BOTTOM=1, DIV=10, RANGE=[-10,10]
Here is an example that shows the difference between LOADCT and cgLoadCT:
ERASE, COLOR=cgCOLOR('Charcoal)
LoadCT, 5, NCOLORS=8
cgColorbar, NCOLORS=8, DIVISIONS=8, POSITION=[0.1, 0.65, 0.9, 0.75], XMINOR=0, XTICKLEN=1
cgLoadCT, 5, NCOLORS=8, CLIP=[16, 240]
cgColorbar, NCOLORS=8, DIVISIONS=8, POSITION=[0.1, 0.35, 0.9, 0.45], XMINOR=0, XTICKLEN=1
MODIFICATION HISTORY:
Written by David W. Fanning, 30 October 2007.
Added ability to read Brewer Color Table file, if available, with BREWER keyword. 14 May 2008. DWF.
Small change in the way the program looks for the Brewer file. 8 July 2008. DWF.
Changed the way the program looks for the Brewer color table file. Now use
the Coyote Library routine FIND_RESOURCE_FILE to look for the file. 29 June 2010. DWF.
Renamed Colorbar procedure to cgColorbar to avoid conflict with IDL 8 Colorbar function.
26 September 2010. DWF.
Added ROW keyword to transpose color table vectors for new graphics functions
in IDL 8. 23 Nov 2010. DWF.
Added WINDOW and WINID keywords. 26 January 2011. DWF.
Added ADDCMD keyword. 29 Jan 2011. DWF.
Program delevopment ended and code transferred to cgLoadCT as of 4 Feb 2011. DWF.
Added missing ADDCMD keyword. 28 April 2011. DWF.
Fixed a problem that occurred when the BOTTOM keyword was used in conjuntion with
the WINDOW keyword, resulting in incorrect colors in cgWindow programs. 28 April 2011. DWF.
(See cgloadct.pro)
NAME:
cgPickfile
PURPOSE:
This is a utility program for selecting data files. It is a wrapper
for DIALOG_PICKFILE, with the additional functionality of being
able to "remember" the name and directory of the last file
selected by the program. It basically allows you to start the
next file selection from the location of the previous file selection.
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:
Utilites
CALLING SEQUENCE:
filename = cgPickfile()
RETURN VALUE:
filename: The fully-qualified name of the selected file or a
null string if the CANCEL button was selected.
KEYWORDS:
DATADIR: Set this keyword to the name of the data directory.
If not set, the program assumes the data directory is rooted
in the directory that holds this program file, or the directory
just above it. If it can't find a "data" directory in either
of these two locations, the current directory is used as
the "data" directory. The data directory is ONLY used if
there is no "current" last directory. In other words, it is
only used if cgPickfile has not been called in the current
IDL session.
DEMO: If set, starts in the !DIR/examples/data directory.
JPEG: If set, starts in the "jpeg" directory. It assumes the jpeg
directory is rooted in the "data" directory.
HDF: If set, starts in the "hdf" directory. It assumes the hdf
directory is rooted in the "data" directory.
LAST_FILE: If set, the name of the last file opened is placed in the
filename widget.
LIDAR: If set, starts in the "lidar" directory. It assumes the lidar
directory is rooted in the "data" directory.
NCDF: If set, starts in the "ncdf" directory. It assumes the ncdf
directory is rooted in the "data" directory.
PNG: If set, starts in the "png" directory. It assumes the png
directory is rooted in the "data" directory.
TIFF: If set, starts in the "tiff" directory. It assumes the tiff
directory is rooted in the "data" directory.
EXTRA: Accepts any input keywords to DIALOG_PICKFILE (e.g., FILTER).
MODIFICATION HISTORY:
Adapted from FSC_PICKFILE to be a Coyote Graphics routine by David W. Fanning, 4 Aug 2011.
(See cgpickfile.pro)
:Description:
The purpose of cgPlot is to create a wrapper for the traditional IDL graphics
command, Plot. The primary purpose of this is to create plot commands that work
and look identically both on the display and in PostScript files.
:Categories:
Graphics
:Params:
x: in, required, type=any
If X is provided without Y, a vector representing the dependent values to be
plotted If both X and Y are provided, X is the independent parameter and
Y is the dependent parameter to be plotted.
y: in, optional, type=any
A vector representing the dependent values to be plotted.
:Keywords:
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow. Setting this keyword
automatically sets the WINDOW keyword, but the command does not erase the
graphics window as it would normally.
aspect: in, optional, type=float, default=none
Set this keyword to a floating point ratio that represents the aspect ratio
(ysize/xsize) of the resulting plot. The plot position may change as a result
of setting this keyword. Note that ASPECT cannot be used when plotting with
!P.MULTI.
axiscolor: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the axis color. By default, 'black'.
Otherwise, the keyword is assumed to be a color index into the current color table.
axescolor: in, optional, type=string/integer
Provisions for bad spellers.
background: in, optional, type=string/integer, default='white'
If this keyword is a string, the name of the background color. By default, 'white'.
Otherwise, the keyword is assumed to be a color index into the current color table.
charsize: in, optional, type=float, default=cgDefCharSize()
The character size for axes annotations. Uses cgDefCharSize to select default
character size, unless !P.Charsize is set, in which case !P.Charsize is always used.
color: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the data color. By default, 'black'.
Color names are those used with cgColor. Otherwise, the keyword is assumed
to be a color index into the current color table.
font: in, optional, type=integer, default=!P.Font
The type of font desired for axis annotation.
isotropic: in, optional, type=boolean, default=0
A short-hand way of setting the ASPECT keyword to 1.
layout: in, optional, type=intarr(3)
This keyword specifies a grid with a graphics window and determines where the
graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location].
The grid is determined by the number of columns (ncolumns) by the number of
rows (nrows). The location of the graphic is determined by the third number. The
grid numbering starts in the upper left (1) and goes sequentually by column and then
by row.
nodata: in, optional, type=boolean, default=0
Set this keyword to draw axes, but no data.
noerase: in, optional, type=boolean, default=0
Set this keyword to draw the plot without erasing the display first.
overplot: in, optional, type=boolean, default=0
Set this keyword if you wish to overplot data on an already exisiting set of
axes. It is like calling the IDL OPLOT command.
position: in, optional, type=vector
The usual four-element position vector for the Plot comamnd. Only monitored and
possibly set if the ASPECT keyword is used.
psym: in, optional, type=integer
Any normal IDL PSYM values, plus and value supported by the Coyote Library
routine SYMCAT. An integer between 0 and 46.
symcolor: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the symbol color. By default, 'black'.
Otherwise, the keyword is assumed to be a color index into the current color table.
symsize: in, optional, type=float, default=1.0
The symbol size.
traditional: in, optional, type=boolean, default=0
If this keyword is set, the traditional color scheme of a black background for
graphics windows on the display is used and PostScript files always use a white background.
window: in, optional, type=boolean, default=0
Set this keyword if you want to display the plot in a resizable graphics window.
_extra: in, optional, type=any
Any keyword appropriate for the IDL Plot command is allowed in the program.
:Examples:
Use as you would use the IDL PLOT command::
cgPlot, Findgen(11)
cgPlot, Findgen(11), Aspect=1.0
cgPlot, Findgen(11), Color='olive', AxisColor='red', Thick=2
cgPlot, Findgen(11), Color='blue', SymColor='red', PSym=-16
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 12 November 2010. DWF.
Added SYMCOLOR keyword, and allow all 46 symbols from SYMCAT. 15 November 2010. DWF.
Added NODATA keyword. 15 November 2010. DWF.
Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF.
Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF.
Fixed a problem with overplotting with symbols. 17 November 2010. DWF.
Background keyword now applies in PostScript file as well. 17 November 2010. DWF.
Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF.
Fixed a small problem with the OVERPLOT keyword. 18 Nov 2010. DWF.
Changes so that color inputs don't change type. 23 Nov 2010. DWF.
Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF
Modifications to allow cgPlot to be drop-in replacement for old PLOT commands in
indexed color mode. 24 Dec 2010. DWF.
Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF.
Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF.
Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Selecting character size now with cgDefCharSize. 11 Jan 2011. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Changed _EXTRA to _REF_EXTRA on procedure definition statement to be able to return
plot keywords such as XGET_TICKS. 13 Jan 2011. DWF.
Added SYMSIZE keyword. 16 Jan 2011. DWF.
Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF.
Added ADDCMD keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 28 Jan 2011. DWF.
Made a modification that allows THICK and COLOR keywords apply to symbols, too. 24 Feb 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
Somehow I had gotten independent and dependent data reversed in the code. Put right. 16 May 2011. DWF.
Allowed ASPECT (and /ISOTROPIC) to take into account input POSITION. 15 June 2011. Jeremy Bailin.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgplot.pro)
:Description:
The purpose of cgPlotS is to create a wrapper for the traditional IDL graphics
command, PlotS. The primary purpose of this is to create plot commands that work
and look identically both on the display and in PostScript files.
:Categories:
Graphics
:Params:
X: in, required, type=any
A vector or scalar argument providing the X components of the points to be
drawn or connected. May be a 2xN or 3xN array, if Y and Z parameters are
not used.
Y: in, optional, type=any
A vector or scalar argument providing the Y components of the points to be
drawn or connected.
Z: in, optional, type=any
A vector or scalar argument providing the Z components of the points to be
drawn or connected.
:Keywords:
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow display.
color: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the data color. By default, 'black'.
Color names are those used with cgColor. Otherwise, the keyword is assumed
to be a color index into the current color table. May be a vector of the same
length as X.
psym: in, optional, type=integer
Any normal IDL PSYM values, plus any value supported by the Coyote Library
routine SYMCAT. An integer between 0 and 46.
symcolor: in, optional, type=string/integer/vector, default=COLOR
If this keyword is a string, the name of the symbol color. By default, same as COLOR.
Otherwise, the keyword is assumed to be a color index into the current color table.
May be a vector of the same length as X.
symsize: in, optional, type=float/vector, default=1.0
A scalar or vector of symbol sizes. Default is 1.0. May be a vector of the same
length as X.
window: in, optional, type=boolean, default=0
Set this keyword to add the command to the current cgWindow application.
_extra: in, optional, type=any
Any keywords supported by the PLOTS command are allowed.
:Examples:
Use like the IDL PLOTS command::
IDL> cgPlot, Findgen(11)
IDL> cgPlotS, !X.CRange, [5,5], LINESTYLE=2, THICK=2, COLOR='red'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 12 November 2010. DWF.
Added SYMCOLOR keyword. PSYM accepts all values from SYMCAT. SYMCOLOR and SYMSIZE
keywords can be vectors the size of x. 15 November 2010. DWF
Added ability to support COLOR keyword as a vector the size of x. 15 November 2010. DWF
Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF.
Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF.
Changes so that color variables don't change type. 23 Nov 2010. DWF.
Modified to use decomposed color, if possible. 24 Dec 2010. DWF.
Whoops! Programming is like herding cats! 29 Dec 2010. DWF.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Added WINDOW keyword. 24 Jan 2011. DWF.
Made a modification that allows THICK and COLOR keywords apply to symbols, too. 24 Feb 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgplots.pro)
:Description:
Provides information about any cgWindow applications currently on the display. Returns
the window index numbers of any cgWindow applications current on the display.
:Categories:
Graphics
:Params:
none
:Keywords:
current: in, optional, type=boolean
If set, the current cgWindow application information is returned in the result
of the function and in the information keywords.
count: out, optional, type=long
The number of cgWindow applications currently on the display.
dimensions: out, optional, type=intarr(2,count)
The dimensions of the ctWindow application, [xdim, ydim, n].
objectref: out, optional, type=object
A vector of FSC_CMDWINDOW object references for each cgWindow application currently
on the display.
title: out, optional, type=string
A vector of window titles for each cgWindow application currently on the display.
widgetID: out, optional, type=long
A vector of widget identifiers of the top-level base widget for each cgWindow
application currently on the display.
:Return Value:
windowIndexID: out, type=long
An array of window index numbers for each cgWindow application currently on the display.
:Examples:
Used as a query routine::
IDL> wids = cgQuery(TITLE=titles, COUNT=count)
IDL> index = Where(StrUpCase(titles) EQ 'PLOT WINDOW', tcnt)
IDL> IF tcnt GT 0 THEN cgSet, wids[index]
IDL> cgWindow, 'Oplot', thisData, /AddCmd
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 23 January 2011. DWF.
Added DIMENSIONS keyword to return current dimensions of cgWindows. 24 Feb 2011. DWF.
Made sure this program only returns information on devices that support windows. 20 July 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgquery.pro)
:Description:
Allows the user to select the cgWindow application to be the "current" application.
Selection can be made based on window index number, widget identifier, object reference,
or window title.
:Categories:
Graphics
:Params:
selection: in, required, type=varies
Normally, a window index number of an cgWindow application. But, the selection
can be a widget identifier, an object reference, or a window title, depending on
which keywords are set. The cgWindow matching the selection is made the "current"
cgWindow and the application is moved forward on the display.
:Keywords:
object: in, optional, type=boolean
If this keyword is set, the selection is assumed to be an object reference.
title: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a window title. All
matching is done in uppercase characters.
widgetid: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a widget identifier.
:Examples:
Used with query routine::
IDL> wids = cgQuery(TITLE=titles, COUNT=count)
IDL> index = Where(StrUpCase(titles) EQ 'PLOT WINDOW', tcnt)
IDL> IF tcnt GT 0 THEN cgSet, wids[index]
IDL> cgWindow, 'Oplot', thisData, /AddCmd
IDL> cgSet ; Bring current window forwad on display
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 23 January 2011. DWF.
If selection match isn't provided, as like WShow to bring the current
window forward on display. 26 Jan 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgset.pro)
:Description:
Allows the user to select the cgWindow application to be the brought forward on the display.
Selection can be made based on window index number, widget identifier, object reference,
or window title. This is the equivalent of WShow for normal graphics windows.
:Categories:
Graphics
:Params:
selection: in, required, type=varies
Normally, a window index number of an cgWindow application. But, the selection
can be a widget identifier, an object reference, or a window title, depending on
which keywords are set. The cgWindow matching the selection is made the "current"
cgWindow and the application is moved forward on the display.
:Keywords:
object: in, optional, type=boolean
If this keyword is set, the selection is assumed to be an object reference.
title: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a window title. All
matching is done in uppercase characters.
widgetid: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a widget identifier.
:Examples:
Used with query routine::
IDL> wids = cgQuery(TITLE=titles, COUNT=count)
IDL> index = Where(StrUpCase(titles) EQ 'PLOT WINDOW', tcnt)
IDL> IF tcnt GT 0 THEN cgSet, wids[index]
IDL> cgWindow, 'Oplot', thisData, /AddCmd
IDL> cgShow ; Bring current window forwad on display
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 1 February 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgshow.pro)
NAME:
cgSnapshot
PURPOSE:
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics
CALLING SEQUENCE:
image = cgSnapshot(xstart, ystart, ncols, nrows)
The returned image will be a 2D image on 8-bit systems and
a 24-bit pixel interleaved true-color image on 24-bit systems.
A -1 will be returned if a file output keyword is used (e.g., JPEG, TIFF, etc.).
OPTIONAL INPUTS:
XSTART -- The starting column index. By default, 0.
YSTART -- The starting row index. By default, 0.
NCOLS -- The number of columns to read. By default, !D.X_Size - XSTART
NROWS -- The number of rows to read. By default, !D.Y_Size - YSTART.
KEYWORD PARAMETERS:
BMP -- Set this keyword to write the screen dump as a color BMP file.
CANCEL -- An output keyword set to 1 if the user cancels out of a
filename dialog. Set to 0 otherwise.
COLORS -- If a 24-bit image has to be quantized, this will set the number
of colors in the output image. Set to 256 by default. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
CUBE -- If this keyword is set to a value between 2 and 6 the color
quantization will use a cubic method of quantization. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
DITHER -- If this keyword is set the quantized image will be dithered.
Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.
(See the COLOR_QUAN documentation for details.)
FILENAME -- The base name of the output file. (No file extensions;
they will be added automatically.) This name may be changed by the user.
image = cgSnapshot(Filename='myfile', /JPEG)
No file will be written unless a file output keyword is used
(e.g., JPEG, TIFF, etc.) in the call. By default the FILENAME is
set to "idl". The file extension will be set automatically to match
the type of file created.
GIF -- Set this keyword to write the screen dump as a color GIF file.
JPEG -- Set this keyword to write the screen dump as a color JPEG file.
NODIALOG -- Set this keyword if you wish to avoid the DIALOG_PICKFILE
dialog that asks you to name the output file. This keyword should be
set, for example, if you are processing screens in batch mode.
ORDER -- Set this keyword to determine the image order for reading the
display. Corresponds to !Order and set to such as the default.
OVERWRITE_PROMPT -- Set this keyword if you would like to get a prompt
if you are overwriting a file. This applies only to operations with
DIALOG_PICKFILE.
PICT -- Set this keyword to write the screen dump as a color PICT file.
PNG -- Set this keyword to write the screen dump as a color PNG file.
TIFF -- Set this keyword to write the screen dump as a color TIFF file.
TRUE -- Set this keyword to the type of interleaving you want. 1 = Pixel
interleaved, 2 = row interleaved, 3 = band interleaved.
TYPE -- Can be set to the type of file to write. Use this instead of
setting BMP, GIF, JPEG, PICT, PNG, or TIFF keywords: TYPE='JPEG'. The
primary purpose of this is to make event handlers easier to write.
QUALITY -- This keyword sets the amount of compression for JPEG images.
It should be set to a value between 0 and 100. It is set to 75 by default.
(See the WRITE_JPEG documentation for details.)
WID -- The index number of the window to read from. The current graphics window
(!D.Window) is selected by default. An error is issued if no windows are
currently open on a device that supports windows.
_EXTRA -- Any keywords that are appropriate for the WRITE_*** routines are
also accepted via keyword inheritance.
COMMON BLOCKS:
None
RESTRICTIONS: Requires IDL 5.2 and higher.
MODIFICATION HISTORY:
Renamed TVRead to cgSnapshot and retired TVRead. 20 February 2011. DWF.
(See cgsnapshot.pro)
:Description:
The purpose of cgSurf is to create a wrapper for the traditional IDL graphics
commands, Surface and Shade_Surf. The primary purpose of this is to create surface
commands that work and look identically both on the display and in PostScript files.
:Categories:
Graphics
:Params:
data: in, required, type=any
A two-dimensional array of data to be displayed.
x: in, optional, type=any
A vector or two-dimensional array specifying the X coordinates of the
surface grid.
y: in, optional, type=any
A vector or two-dimensional array specifying the Y coordinates of the
surface grid.
:Keywords:
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow. Setting this keyword
automatically sets the WINDOW keyword, but the command does not erase the
graphics window as it would normally.
axiscolor: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the axis color. By default, 'black'.
Otherwise, the keyword is assumed to be a color index into the current color table.
axescolor: in, hidden, type=string/integer
Provisions for bad spellers.
background: in, optional, type=string/integer, default='white'
If this keyword is a string, the name of the background color. By default, 'white'.
Otherwise, the keyword is assumed to be a color index into the current color table.
bottom: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the bottom color. By default, same as COLOR.
Otherwise, the keyword is assumed to be a color index into the current color table.
charsize: in, optional, type=float, default=cgDefCharSize*1.25
The character size for axes annotations. Uses cgDefCharSize()*1.25 to select default
character size, unless !P.Charsize is set, in which case !P.Charsize*1.25 is always used.
color: in, optional, type=string/integer, default='blu6'
If this keyword is a string, the name of the data color. By default, "BLU6".
Otherwise, the keyword is assumed to be a color index into the current color table.
elevation_shading: in, optional, type=boolean, default=0
Set this keyword to put elevation shading into effect for the surface.
font: in, optional, type=integer, default=-1
The type of font desired. If undefined, and the current graphics device is PostScript,
the FONT keyword will be set to 1, indicating true-type fonts. The FONT keyword must
be set to -1 (Hershey fonts) or 1 (true-type fonts) for surface annotations to be
rotated correctly in PostScript output.
layout: in, optional, type=intarr(3)
This keyword specifies a grid with a graphics window and determines where the
graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location].
The grid is determined by the number of columns (ncolumns) by the number of
rows (nrows). The location of the graphic is determined by the third number. The
grid numbering starts in the upper left (1) and goes sequentually by column and then
by row.
noerase: in, optional, type=boolean, default=0
Set this keyword to prevent the window from erasing the contents before displaying
the surface plot.
palette: in, optional, type=bytarr(3,N)
Set this keyword to a 3 x N or N x 3 byte array containing the RGB color vectors
to be loaded before the surface is displayed. Such vectors can be obtained, for
example, from cgLoadCT with the RGB_TABLE keyword:
cgLoadCT, 33, RGB_TABLE=palette
cgSurf, cgDemoData(2), PALETTE=palette, /Elevation
rotx: in, optional, type=float, default=30
The rotation about the X axis.
rotz: in, optional, type=float, default=30
The rotation about the Z axis.
shaded: in, optional, type=boolean, default=0
Set this keyword if you wish to display a shaded surface. To display shaded surfaces
in a device-independent way, the shading values are confined to indices 0 to 253 with
SET_SHADING, and the background color is placed in color index 254. The color table vectors
are reduced to 254 elements when this happens. This all happens behind the stage,
and the original color table is restore upon exit. Because I can't tell how many values
SET_SHADING is using on entering the program, I just set it back to its default 256 values
on exiting the program.
shades: in, optional, type=byte
Set this keyword to a byte scaled 2D array of the same size as data to shade the surface
with these color indices.
skirt: in, optional, type=any
Set this keyword to a Z value where a skirt will be drawn for the surface.
title: in, optional, type=string
The title of the plot. It will be written "flat to the screen", rather than rotated.
traditional: in, optional, type=boolean, default=0
If this keyword is set, the traditional color scheme of a black background for
graphics windows on the display is used and PostScript files always use a white background.
tsize: in, optional, type=float
The character size for the title. Normally, the title character size is 1.1 times
the character size of the surface annotation.
tspace: in, optional, type=float
The title Y spacing. This should be a number, between 0 and 1 that is the fraction
of the distance between !Y.Window[1] and !Y.Window[0] to locate the title above
!Y.Window[1]. When Total(!P.MULTI) EQ 0, the default is 0.005, and it is 0.0025 otherwise.
window: in, optional, type=boolean, default=0
Set this keyword if you want to display the plot in a resizable graphics window.
xstyle: in, hidden
The normal XSTYLE keyword.
ystyle: in, hidden
The normal YSTYLE keyword.
zstyle: in, hidden
The normal ZSTYLE keyword.
_extra: in, optional, type=any
Any keyword appropriate for the IDL Plot command is allowed in the program.
:Examples:
Use as you would use the IDL SURFACE of SHADE_SURF command::
data = Dist(200)
LoadCT, 33
cgSurf, data
cgSurf, data, Shades=BytScl(data)
cgSurf, data, /Shaded
cgSurf, data, /Shaded, Shades=BytScl(data)
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 13 November 2010. DWF.
Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF.
Added TSIZE and TSPACE keywords to treak title size and placement,
as necessary. 17 November 2010. DWF.
Background keyword now applies in PostScript file as well. 17 November 2010. DWF.
Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF.
Changes so that color variables don't change type. 23 Nov 2010. DWF.
Added ELEVATION_SHADING keyword. 26 Nov 2010. DWF.
I had keyword conflicts with the AX and AZ rotation keywords. Now perform rotation with
ROTX and ROTZ keywords. 7 Dec 2010. DWF.
Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF
Changed the Title size to 1.1 times the character size of the plot. 14 Dec 2010. DWF.
Modifications to allow cgSurf to be drop-in replacement for old Surface commands in
indexed color mode. 24 Dec 2010. DWF.
Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF.
Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF.
Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF.
Change to DECOMPOSED color was using incorrect color tables. 29 Dec 2010. DWF.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF.
Added ADDCMD keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 28 Jan 2011. DWF.
Added PALETTE keyword. 3 Feb 2011. DWF.
Color table vectors must be obtained AFTER loading the color palette. 6 March 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
Modified the color decomposition state to properly handle shaded surfaces in PostScript. 20 July 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgsurf.pro)
:Description:
The purpose of cgSurface is to create a window where a surface is displayed. Surfaces
can be wire-framed, shaded surfaces, and surfaces with texture maps draped on top of
them, among other types of surfaces. LEFT mouse button rotates the surface, MIDDLE
mouse button zooms out from the surface, RIGHT mouse button zoom into the surface.
Clicking on the surface axes will allow the user to move or translate the surface, and
clicking on the plot title will allow the user to move the title.
:Categories:
Graphics
:Params:
data: in, required, type=any
A two-dimensional array of data to be displayed.
x: in, optional, type=any
A vector or two-dimensional array specifying the X coordinates of the
surface grid.
y: in, optional, type=any
A vector or two-dimensional array specifying the Y coordinates of the
surface grid.
:Keywords:
axiscolor: in, optional, type=string, default='black'
The name of the axis color. By default, 'black'..
background: in, optional, type=string, default='white'
The name of the background color. By default, 'white'.
block: in, optional, type=boolean, default=0
Set this keyword to make the program a blocking widget program.
bottom: in, optional, type=string, default=COLOR
The name of the bottom color. By default, same as COLOR.
brewer: in, optional, type=boolean, default=0
Set this keyword to indicate that the colortable (CTABLE) is
to use Brewer color tables rather than IDL standard color tables.
charsize: in, optional, type=float, default=1.0
The character size of the surface annotation.
color: in, optional, type=string, default='blu6'
The name of the data color.
constrain_aspect: in, optional, type=boolean, default=0
Set this keyword to maintain the aspect ratio of the Y size
of the data to the Y size of the data. The default is to let the
sizes conform to a unit square.
ctable: in, optional, type=integer
The color table to use with the surface. The default is to use the
current color table.
elevation_shading: in, optional, type=boolean, default=0
Set this keyword to put elevation shading into effect for the surface.
font: in, optional, type=string, default="Helvetica"
The name of the true-type font desired for axis annotation and the plot title.
If undefined, the default is "Helvetica".
hidden_lines: in, optional, type=boolean, default=1
Set this keyword to turn hidden line removal on for the surface. Turned
ON by default.
group_leader: in, optional, type=long
Set this keyword to the identifier of a widget that will serve as the
group leader for this widget program. When the group leader dies, this
program will die, too.
reverse: in, optional, type=boolean, default=0
Set this keyword to reverse the color table set by CTABLE.
shaded: in, optional, type=boolean, default=0
Set this keyword if you wish to display a shaded surface. The is the same as setting STYLE=2.
skirt: in, optional, type=any
Set this keyword to a Z value where a skirt will be drawn for the surface.
texture_image: in, optional, type=byte
Set this keyword to a 2d or true-color image that will be overlaid on the surface
as a texture map. If a 2D image is passed, the colortable specified with CTABLE will
be used to construct a true-color image for the texture map.
tcharsize: in, optional, type=float
The title character size. By default 1.25 times the CHARSIZE.
title: in, optional, type=string
The title of the plot. It will be written "flat to the screen", rather than rotated.
tsize: in, optional, type=float, default=1.25*CHARSIZE
The character size for the title. By default, the title character size is 1.25 times
the character size of the surface annotation.
xoffset: in, optional, type=integer, default=50
The number of pixels the surface window should be offset in the X direction
from the upper-left corner of the display.
xsize: in, optional, type=interger, default=640
The X size of the initial surface window. By default, 640 pixels.
xstyle: in, hidden
The normal XSTYLE keyword.
xtitle: in, optional, type=string
The text for the X axis of the surface plot.
yoffset: in, optional, type=integer, default=25
The number of pixels the surface window should be offset in the Y direction
from the upper-left corner of the display.
ysize: in, optional, type=integer, default=512
The Y size of the initial surface window. By default, 640 pixels.
ystyle: in, hidden
The normal YSTYLE keyword.
ytitle: in, optional, type=string
The text for the Y axis of the surface plot.
zscale: in, optional, type=float, default=1.0
A number between 0.001 and 1.0 that will "scale" the Z axis height. Default is 1.0.
zstyle: in, hidden
The normal ZSTYLE keyword.
ztitle: in, optional, type=string
The text for the Z axis of the surface plot.
_extra: in, optional, type=any
Any keyword appropriate for the IDLgrSurface object is allowed in the program.
:Examples:
Use as you would use the IDL SURFACE of SHADE_SURF command::
data = Dist(200)
LoadCT, 33
cgSurface, data
cgSurface, data, /Elevation_Shading
cgSurface, data, /Shaded
cgSurface, data, /Shaded, Texture_Image=cgDemoData(16)
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Completely re-written, 26 November 2010 from old cgSURFACE program. DWF.
Added ability to translate the surface by clicking on an axis. 28 Nov 2010. DWF.
Fixed a problem with light controls in which the light controls didn't show the
current light color. 28 Nov 2010. DWF.
I was ANDing [XYZ]Style keywords with 8 instead of 4 for hidded axes. Fixed. 4 Jan 2011. DWF.
Added Axes ON/OFF button. 4 Jan 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgsurface.pro)
:Description:
Provides a device-independent and color-model-independent way to write text into
a graphics window. It is a wrapper to the XYOUTS command.
:Categories:
Graphics
:Params:
xloc: in, required, type=depends
The X location of the text.
yloc: in, required, type=depends
The Y location of the text.
text: in, optional, type=string
The text to output. By default, the calling sequence of the program.
:Keywords:
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow. Setting this keyword
automatically sets the WINDOW keyword, but the command does not erase the
graphics window as it would normally.
alignment: in, optional, type=integer, default=0
Set this keyword to indicate the alignment of the text with respect to the
x and y location. 0 is left aligned, 0.5 is centered, and 1.0 is right aligned.
The alignment is set to 0.5 if PLACE is set and ALIGNMENT is unspecified.
Otherwise, the default is 0.
charsize: in, optional, type=float, default=cgDefCharSize()
The character size for axes annotations. Uses cgDefCharSize to select default
character size, unless !P.Charsize is set, in which case !P.Charsize is always used.
color: in, optional, type=string/integer/long
The color of the text. Color names are those used with cgColor. By default,
"black", unless the upper-right hand pixel in the display is black, then "white".
data: in, optional, type=boolean
Set this keyword to indicate xloc and yloc are in data coordinates. Data coordinates
are the default, unless DEVICE or NORMAL is set.
device: in, optional, type=boolean
Set this keyword to indicate xloc and yloc are in device coordinates.
font: in, optional, type=integer, default=!P.Font
The type of font desired. By default, !P.Font.
normal: in, optional, type=boolean
Set this keyword to indicate xloc and yloc are in normalized coordinates.
outloc: out, optional, type=various
Only used if PLACE is set, this is a two-element array containing the xloc and yloc
of the cursor position in the window.
place: in, optional, type=boolean
Set this keyword if you wish to click the cursor in the graphics window to place
the text. If this keyword is set, you do not need to specify the xloc and yloc
positional parameters. The first positional parameter is assumed to be the text.
The clicked location will be returned in the OUTLOC variable. If the ALIGNMENT
keyword is not set, it will be set to 0.5 to set "center" as the default placement
alignment.
tt_font: in, optional, type=string
The true-type font to use for the text. Only used if FONT=1.
width: out, optional, type=float
Set this keyword to a named variable in which to return the width of the text string,
in normalized coordinate units.
window: in, optional, type=boolean
Set this keyword to add the command to the in the current cgWindow application.
_extra: in, optional
Any keywords appropriate for the XYOUTS command.
:Examples:
Used like the IDL XYOUTS command::
IDL> cgText, 0.5, 0.5, 'This is sample text', ALIGNMENT=0.5, /NORMAL
IDL> cgText, /PLACE, 'Use the cursor to locate this text', COLOR='dodger blue'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 19 November 2010. DWF.
Corrected a problem with setting text color and added PLACE and OUTLOC
keywords. 25 Nov 2010. DWF.
Humm, that text color problem got reset to the old way! Sheesh! Fixed. 9 Dec 2010. DWF.
Modified the way the default color is selected. Drawing with DECOMPOSED
if possible. 30 Dec 2010. DWF.
Keywords collected with _REF_EXTRA so WIDTH can be returned. Added WIDTH keyword. 6 Jan 2011. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Added Window keyword. 24 Jan 2011. DWF.
Added ability to return WIDTH from resizeable graphics windows and added ADDCMD
keyword. 24 Feb 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See cgtext.pro)
:Name
cgWindow
:Description:
Creates a resizeable graphics window for IDL traditional commands (Plot, Contour,
Surface, etc. or for Coyote Graphics routines, cgPlot, cgContour, cgSurf, etc.).
In addition, the window contents can be saved as PostScript files or as raster image
files. If ImageMagick is installed on your machine, the raster image files can be
created in very high quality from PostScript files.
:Categories:
Graphics
:Params:
command: in, required, type=string
The graphics procedure command to be executed. This parameter
must be a string and the the command must be a procedure. Examples
are 'Surface', 'Contour', 'Plot', 'cgPlot', cgContour, etc.
p1: in, optional, type=any
The first positional parameter appropriate for the graphics command.
p2: in, optional, type=any
The second positional parameter appropriate for the graphics command.
p3: in, optional, type=any
The third positional parameter appropriate for the graphics command.
:Keywords:
addcmd: in, optional, type=boolean, default=0
Set this keyword to add an additional graphics command to an cgWindow.
The command is added to the last created cgWindow, unless the WinID
keyword is used to select another cgWindow. Adding a command causes
all the commands in the window to be immediately executed. If this is
not behavior you desire, use the LOADCMD keyword instead. If CMDINDEX
is used to select a command index, the new command is added before
the command currently occuping that index in the command list.
cmddelay: in, optional, type=float
If this keyword is set to a value other than zero, there will be a
delay of this many seconds between command execution. This will permit
"movies" of command sequences to be displayed.
cmdindex: in, optional, type=integer
This keyword is used to select which command in an cgWindow to act on
when the AllCmd, DeleteCmd, LoadCmd and ReplaceCmd keywords are used.
See the descriptions of these keywords for details on what happens when
CmdIndex is missing.
deletecmd: in, optional, type=boolean, default=0
Set this keyword to delete a graphics command from an cgWindow.
If CmdIndex is undefined the last command entered into the window is
deleted. It is not possible to delete the last command in the window.
Use WinID to identify the cgWindow you are interested in. If WinID
is undefined, the last cgWindow created is used.
evalKeywords: in, optional, type=string
A scalar or vector of keyword names. Keywords listed here will be evaluated
every time the command associated with the keyword is executed. For example,
this allows different values to be used for the keyword in different devices.
The actual value of the keyword should be a string that can be evaluated by
the IDL Execute function and assigned to a value. This value will be used as
the keyword value when the command is executed. See the example below or the article
http://www.idlcoyote.com/cg_tips/kwexpressions.php for additional information.
Use of this keyword precludes using cgWindow in a Virtual Machine application.
evalParams: in, optional, type=IntArr(3)
A three-element vector. Set the value of the vector to 1 to have the positional
parameter in that position of the command evaluated at run-time. The actual parameter
should be a string that can be evaluated by the IDL Execute function and assigned to
a value. This value will be used as the parameter value when the command is executed.
See the example below or the article http://www.idlcoyote.com/cg_tips/kwexpressions.php
for additional information. Use of this keyword precludes using cgWindow in a
Virtual Machine application.
executecmd: in, optional, type=boolean, default=0
Set this keyword to immediate execute all the commands in an cgWindow.
Normally, this is used after commands have been loaded with LOADCMD.
listcmd: in, optional, type=boolean, default=0
If this keyword is set, the commands currently in the cgWindow are
listed. Use WinID to identify the cgWindow you are interested in.
If WinID is undefined, the last cgWindow created is used.
loadcmd: in, optional, type=boolean, default=0
Set this keyword to add an additional graphics command to an cgWindow.
The command is added to the last created cgWindow, unless the WinID
keyword is used to select another cgWindow. Loaded commands are not
automatically executed. Set the EXECUTECMD keyword at the end of loading
to execute the loaded commands. If CMDINDEX is used to select a command
index, the new command is loaded before the command currently occuping
that index in the command list.
replacecmd: in, optional, type=boolean, default=0
Set this keyword to replace a graphics command from an cgWindow.
If CmdIndex is undefined, *all* commands in the window are replaced. Use
WinID to identify the cgWindow you are interested in. If WinID is
undefined, the last cgWindow created is used for the replacement.
group_leader: in, optional
The identifier of a widget to serve as a group leader for this program.
If the group leader is destroyed, this program is also destroyed. Used
when calling this program from another widget program.
method: in, optional, type=boolean, default=0
Set this keyword if the command is an object method call rather than a
procedure call. If this keyword is set, the first positional parameter, p1,
must be present and must be a valid object reference.
wbackground: in, optional, type=varies, default=!P.Background
The background color of the window. Specifying a background color
automatically sets the WErase keyword.
werase: in, optional, type=boolean, default=0
Set this keyword to cause the window to be erased before graphics commands
are drawn. This may need to be set, for example, to display images.
winid: in, optional, type=integer
Use this keyword to select the window cgWindow identifier (the number between
the parentheses in the title bar of cgWindow). The AddCmd, ReplaceCmd, ListCmd,
and DeleteCmd keywords will all apply to the commands in the last cgWindow
created unless this keyword is used to select another cgWindow to apply the
commands to.
wmulti: in, optional, type=intarr(5)
Set this keyword in exactly the same way you would set the !P.Multi keyword.
It will allow you to display multi-plots in the cgWindow graphics window.
wobject: out, optional, type=object
cgWindow creates a FSC_CmdWindow object. This object reference is returned
if this keyword is present.
wxpos: in, optional, type=integer, default=5
The x offset in device coordinates of the cgWindow from the upper-left corner of the display.
wypos: in, optional, type=integer, default=5
The y offset in device coordinates of the cgWindow from the upper-left corner of the display.
wxsize: in, optional, type=integer, default=640
The x size in device coordinates of the graphics window.
wysize: in, optional, type=integer, default=5
The y size in device coordinates of the the graphics window.
wtitle: in, opetional, type=string, default='Resizeable Graphics Window'
The title of the graphics window. A window index number is appended to the
title so multiple cgWindow programs can be selected.
:Examples:
Test code::
data = cgDemoData(17)
cgWindow, 'cgPlot', data, COLOR='red'
cgWindow, 'cgPlot', data, PSYM=2, /Overplot, COLOR='dodger blue', /AddCmd
cgWIndow, 'cgPlot', cgDemoData(17), color='olive', linestyle = 2, /Overplot, /AddCmd
cgWindow, /ListCmd
cgWindow, 'cgPlot', data, COLOR='purple', /ReplaceCMD, CMDINDEX=0
Additional examples can be found here:
http://www.idlcoyote.com/graphics_tips/cgwindow.html
Example using run-time evaluated keywords and parameters.
cgPlot, cgDemoData(1), /Window, EvalKeywords=['thick','title'], $
thick='(!d.name eq "PS")?5.0:1.0', $
title="textoidl('sin(x/\alpha) e^{-x/\beta}')", $
position=[0.1, 0.25, 0.9, 0.9]
cgText, 0.1, 0.1, /Normal, '"Greek Psi Symbol (" + Greek("psi") + ")"', EvalParams=[0,0,1], /AddCmd
:Notes:
Notes on using the program::
The program is designed to work with any IDL traditional graphics routine
that is a procedure and includes no more than three positional parameters.
Any number of keywords can be used to specify properties of the graphical
output. Any number of graphics commands can be "added" the the cgWindow.
Simply use the ADDCMD keyword to add commands.
If your program does not load its own color tables, the color tables in
effect when cgWindow is first called are used to display the graphics
commands.
To create PostScript output from within cgWindow, your graphics program
has to be written in such a way that it can work properly in the PostScript
device. This means there are no Window commands, WSet commands, and the like
that are not allowed in the PostScript device. Such commands are allowed in
programs, of course, if they are "protected". Usually such protection looks
like this:
IF (!D.Flags AND 256) NE 0 THEN Window, ...
cgDisplay is a good program for opening graphics "windows", because such
PostScript protection is built into the program. In a PostScript device,
cgDisplay produces a "window" with the same aspect ratio as the current
dislay graphics window, which is an aid in producing PostScript output that
looks like the same output in the display window.
Much better looking raster files can be created from the cgWindow contents,
if the raster files are created by converting PostScript files to the raster
file. If the ImageMagick "convert" command can be found on your machine, you
will have the option to create raster files using this method. I *highly*
recommend doing so, as fonts and other plot annotation will be of much higher
quality using this method.
cgWindow has been designed to work with other Coyote Graphics routines: cgPlot,
cgContour, cgSurf, and so on, although I expect it to work with any IDL
traditional graphics routine, if the routine is well written.
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@idlcoyote.com
Coyote's Guide to IDL Programming: http://www.idlcoyote.com
:History:
Change History::
Written, 17 January 2011. DWF.
Fixed a problem with the example code, and added EMPTY to end of Draw method
to force UNIX machines to empty the graphics buffer after CALL_PROCEDURE. 20 Jan 2011. DWF.
Improved documentation and error handling. 19 Jan 2011. DWF.
More improved error handling and messages. 26 Jan 2011. DWF.
Made changes to accommodate the new cgControl routine. 27 Jan 2011. DWF.
Added WXOMARGIN and WYOMARGIN keywords. 28 Jan 2011. DWF.
Numerous changes leading up to official release. 4 Feb 2011. DWF.
Added workaround for UNIX bug for draw widget creation. 5 Feb 2011. DWF.
Corrected a window aspect ratio problem with PostScript output by making the
window the current window before calling PS_Start. 17 Feb 2011. DWF.
Added machinery for programmatically generating raster files. 18 Feb 2011. Jeremy Bailin.
Problem with restoring visualizations fixed. 6 March 2011. DWF.
Fixed a problem with CALL_METHOD, which requires one positional parameter. 8 March 2011. DWF.
Added the ability to set and unset adjustable text size in the window. 24 April 2011. DWF.
Fixed a problem in the ReplaceCommand method that had input parameters reversed. 6 May 2011. DWF.
Added the ability to set the dimensions of the draw widget programmatically. 14 June 2011.
Added the keywords EvalKeywords and EvalParams to allow evaluation of command parameters and
keywords at run-time. See http://www.idlcoyote.com/cg_tips/kwexpressions.php for
additional details and explanations of how these keywords should be used. 2 Aug 2011.
Problem dereferencing a null pointer in DRAW method fixed. 3 Aug 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgwindow.pro)
:Description:
Allows the user to get the global defaults for resizeable cgWindow programs.
:Categories:
Graphics
:Params:
None
:Keywords:
adjustsize: out, optional, type=boolean
If set, adjust the default text size to match the display window size.
background: out, optional, type=string
The background color of the window.
delay: out, optional, type=float
The amount of delay between command execution.
eraseit: out, optional, type=boolean
The Erase status of the window.
im_density: out, optional, type=integer
The sampling density.
file from PostScript outout.
im_options: out, optional, type=string
Current ImageMagick convert options.
im_raster: out, optional, type=boolean
The raster via ImageMagick setting.
im_resize: out, optional, type=integer
The amount PostScript output is resized.
im_transparent: out, optional, type=boolean
The transparent background setting.
multi: out, optional, type=Intarr(5)
The !P.MULTI setting for the window.
palette: out, optional, type=BytArr(N,3)
The window color palette.
ps_delete: out, optional, type=boolean
The delete PostScript file status of the window.
ps_encapsulated: out, optional, type=boolean
The PostScript encapsulated status of the window.
ps_metric: out, optional, type=boolean
The metric status of the window.
title: out, optional, type=boolean
The window title.
xomargin: out, optional, type=intarr(2)
The !X.OMargin value for multiplots.
xpos: out, optional, type=integer
The X offset of the window from the upper-left corner of the display.
xsize: out, optional, type=integer
The starting X size of the window.
yomargin: out, optional, type=intarr(2)
The !Y.OMargin value for multiplots.
ypos: out, optional, type=integer
The Y offset of the window from the upper-left corner of the display.
ysize: out, optional, type=integer
The starting Y size of the window.
:Examples:
Used to get cgWindow global properties::
IDL> cgWindow_GetDefs, PALETTE=palette, PS_ENCAPSULATED=encap, PS_METRIC=metric
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 29 January 2011. DWF.
Added PS_QUIET keyword. 17 Feb 2011. DWF.
Added Raster_IM. 18 Feb 2011. Jeremy Bailin
Added the ability to set and unset adjustable text size in
cgWindow with ADJUSTSIZE keyword. 24 April 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See cgwindow_getdefs.pro)
:Description:
Allows the user to set global defaults for resizeable cgWindow programs.
:Categories:
Graphics
:Params:
None
:Keywords:
adjustsize: in, optional, type=boolean, default=0
Set this keyword to have the default text size adjusted to fit the size of the
display window.
background: in, optional, type=string
The background color of the window. Only use if the ERASEIT property is also set.
delay: in, optional, type=float, default=0
Set this keyword to the amount of delay desired between command execution. 0
eraseit: in, optional, type=boolean
If this property is set, the cgWindow erases with the background color before
displaying the commands in the window's command list.
im_transparent: in, optional, type=boolean, default=0
Set this keyword to allow ImageMagick to create transparent backgrounds when it
makes raster image files from PostScript output.
im_density: in, optional, type=integer, default=300
Set this keyword to the sampling density when ImageMagick creates raster image
file from PostScript outout.
im_options: in, optional, type=string, default=""
Set this keyword to any ImageMagick options you would like to pass along to the
ImageMagick convert command when creating raster image files from PostScript output.
im_raster: in, optional, type=boolean, default=1 (if ImageMagick is found)
When raster files are created programmatically, this keyword determines if the
raster file is created directly in IDL (value =0) or is created from a PostScript
intermediate file via ImageMagick (value =1). The default is via ImageMagick if the
convert program can be found on the machine running the program.
im_resize: in, optional, type=integer, default=25
Set this keyword to percentage that the raster image file created my ImageMagick
from PostScript output should be resized.
multi: in, optional, type=Intarr(5)
Set this keyword to the !P.MULTI setting you want to use for the window.
!P.MULTI is set to this setting before command execution, and set back to
it's default value when the commands are finished executing.
palette: in, optional, type=BytArr(N,3)
Use this keyword to pass in an N-by-3 (or 3-by-N) byte array containing the
R, G, and B vectors of a color table. It is probably easier to use cgLoadCT or
XCOLORS to load color tables for the window, but this is provided as another option.
ps_charsize: in, optional, type=float, default=0.0
Set this value to the !P.Charsize value to use when creating PostScript output. This
value is not used if !P.Charsize is set to anything other than 0.0.
ps_delete: in, optional, type=boolean, default=1
Set this keyword to zero if you want to keep the PostScript output ImageMagick creates
when making raster file output.
ps_encapsulated: in, optional, type=boolean, default=0
Set this keyword to configure PSCONFIG to produce encapsulated PostScript output by default.
ps_font: in, optional, type=integer, default=0
Set this to the !P.Font value to use for creating PostScript files.
ps_metric: in, optional, type=boolean, default=0
Set this keyword to configure PSCONFIG to use metric values and A4 page size in its interface.
ps_quiet: in, optional, type=boolean, default=0
Set this keyword to suppress output messages from PS_Start and PS_End.
ps_scale_factor: in, optional, type=float, default=1.0
Set this keyword to the PostScript scale factor you want to use for PostScript output.
ps_tt_font: in, optional, type=string, default="Helvetica"
Set this keyword to the name of the PostScript true-type font to use for PostScript output.
Not used, unless !P.Font=1.
title: in, optional, type=boolean
If this keyword is set, the selection is assumed to be a window title. All
matching is done in uppercase characters.
xomargin: in, optional, type=intarr(2)
Set this keyword to set !X.OMargin to this value for multiplots.
xpos: in, optional, type=integer
Set this keyword to the X offset of the window from the upper-left corner of the display.
xsize: in, optional, type=integer, default=640
Set this keyword to the starting X size of the window.
yomargin: in, optional, type=intarr(2)
Set this keyword to set !Y.OMargin to this value for multiplots.
ypos: in, optional, type=integer
Set this keyword to the Y offset of the window from the upper-left corner of the display.
ysize: in, optional, type=integer, default=512
Set this keyword to the starting Y size of the window.
:Examples:
Used to set cgWindow global properties::
IDL> cgLoadCT, 5, RGB_TABLE=palette
IDL> cgWindow_SetDefs, PALETTE=palette, $
ERASEIT=1, XSIZE=800, YSIZE=400, XPOS=100, YPOS=200, $
PS_ENCAPSULATED=1, PS_METRIC=1
IDL> cgImage, cgDemoData(7), /WINDOW, MARGIN=0.1
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 29 January 2011. DWF.
Added Raster_IM, 18 February 2011. Jeremy Bailin.
Added the ability to set and unset adjustable text size in
cgWindow with ADJUSTSIZE keyword. 24 April 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
Small bug fixes, and addition of PS_QUIET keyword. 17 Feb 2011. DWF.
(See cgwindow_setdefs.pro)
NAME:
Checkerboard
PURPOSE:
This function returns a 2D image, with boxes of alternating colors.
Checkerboard images are useful in certain types of image processing
procedures and for making blended image masks.
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:
Image Processing
CALLING SEQUENCE:
board = Checkerboard()
RETURN VALUE:
board: A 2D long array of alternating colored boxes.
ARGUMENTS:
boxes: The number of boxes of alternating colors on each side
of the resulting image. Must be an even integer greater
than or equal to two. Optional. Default is 8 (normal
checkerboard).
INPUT KEYWORDS:
BLACK: The value of the "black" boxes. By default, 0.
WHITE: The value of the "white" boxes. By default, 255.
XSIZE: The X size of the returned image. By default, 400.
YSIZE: The Y size of the returned image. By default, 400.
COMMON BLOCKS:
None.
EXAMPLE:
IDL> cgImage, Checkerboard()
MODIFICATION HISTORY:
Written by David W. Fanning, 26 September 2007, based on suggestions
of JD Smith on IDL newsgroup 25-26 Septermber 2007.
(See checkerboard.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.
INPUT KEYWORDS:
BREWER: If this keyword is set, the BREWER colors will be loaded with the
Change Colors button. (Assuming the brewer color table file, fsc_brewer.tbl,
has been installed.
OUTPUTS: None
OPTIONAL OUTPUTS: None
OUTPUT KEYWORDS:
NOTIFYID: A two-element array containing the Change Colors button widget
identifier and the identifier of the top-level base widget. This
array is meant to be sent to an XCOLORS routine via its NOTIFYID
keyword. This will allow instant updating of the CINDEX interface.
COMMON BLOCKS: None
SIDE EFFECTS: None
RESTRICTIONS: Reqires XCOLORS and cgImage from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
http://www.dfanning.com/programs/cgImage.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.
Added the NOTIFYID keyword, 15 Dec 2005. DWF.
Added BREWER keyword, 19 May 2008. DWF.
(See cindex.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.
KEYWORDS:
All COLOR_QUAN keywords are allowed. In particular, if you are
taking snapshots of line plots with few colors in them, you may
get better results by calling the program with the CUBE=6 keyword
set. Otherwise, white colors can sometimes be a bit gray.
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.
Added _EXTRA keyword to pass COLOR_QUAN keywords along. 28 Oct 2002. DWF.
(See clipboard.pro)
NAME:
CLIPSCL
PURPOSE:
This is a utility routine to perform linear scaling (similar to BYTSCL)
on image arrays. If differs from BYTSCL only in that a user-specified
percentage of pixels can be clipped from the image histogram, prior to
scaling. By default, two percent of the pixels are clipped. Clipping
occurs at both ends of the image histogram.
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:
scaledImage = CLIPSCL(image, clipPercent)
ARGUMENTS:
image: The image to be scaled. Written for 2D images, but arrays
of any size are treated alike.
clipPercent: The percent of image clipping. Optional argument is set
to 2 by default. Must be value between 0 and 49. Clipping
occurs from both ends of image histogram, so a clip of 2
linearly scales approximately 96% of the image histogram.
Clipping percents are approximations only, and depend
entirely on the distribution of pixels in the image. For
interactive scaling, see XSTRETCH.
INPUT KEYWORDS:
NEGATIVE: If set, the "negative" of the result is returned.
OMAX: The output image is scaled between OMIN and OMAX. The
default value is 255.
OMIN: The output image is scaled between OMIN and OMAX. The
default value is 0.
OUTPUT KEYWORDS:
THRESHOLD: A two-element array containing the image thresholds for clipping.
RETURN VALUE:
scaledImage: The output, scaled into the range OMIN to OMAX. A byte array.
COMMON BLOCKS:
None.
EXAMPLES:
LoadCT, 0 ; Gray-scale colors.
image = cgDemoData(22) ; Load image.
TV, ClipScl(image, 4)
RESTRICTIONS:
Requires SCALE_VECTOR from the Coyote Library:
http://www.dfanning.com/programs/scale_vector.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 6 September 2007.
(See clipscl.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 color24.pro)
NAME:
ColorButtonBitmap
PURPOSE:
The purpose of this program is to create a 24-bit bitmap that can be used to
create a colored widget button.
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:
Widget Programming
CALLING SEQUENCE:
bitmap = ColorButtonBitmap(theText)
button = Widget_Button(tlb, Value=bitmap)
REQUIRED INPUTS:
theText - The text you wish to have on the button.
OUTPUTS:
bitmap - A 3xMxN byte array, representing a 24-bit image that is used
as a button value.
OPTIONAL KEYWORDS:
BGCOLOR - The name of the background color. For example, 'Yellow', 'Tan', etc.
The name must be compatible with names appropriate for cgColor.
FGCOLOR - The name of the foreground color. For example, 'Navy', 'Black', etc.
The name must be compatible with names appropriate for cgColor.
DEPENDENCIES:
Reqires cgColor from the Coyote Library:
http://www.dfanning.com/programs/cgColor.pro
EXAMPLE:
tlb = Widget_Base(/Row, /Exclusive)
button1 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 1')) ; Normal button.
button2 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 2', FGCOLOR='YELLOW', BGCOLOR='NAVY'))
button3 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 3', BGCOLOR='YELLOW', FGCOLOR='NAVY'))
Widget_Control, tlb, /Realize
MODIFICATION HISTORY:
Written by David Fanning, May 25, 2007 based on code named BitmapForButtonText supplied to the IDL
newsgroup by Dick Jackson: http://www.dfanning.com/tip_examples/bitmapforbuttontext.pro.
Fixed a problem with foreground and background colors that caused them to work correctly only
when color decomposition is on--as it should be :-). 6 May 2009.
(See colorbuttonbitmap.pro)
:Description:
Returns a 1 if the two input colors refer to the same color, otherwise returns a 0.
:Categories:
Graphics Utility
:Params:
color_1: in, required, type=string/integer/long
The first color to compare for "equality".
color_2: in, required, type=string/integer/long
The second color to compare for "equality".
:Keywords:
None.
:Examples:
Used to compare if two different colors are the same color::
IDL> Print, ColorsAreIdentical('white', cgColor('white'))
IDL> Print, ColorsAreIdentical(252, !P.Color)
IDL> Print, ColorsAreIdentical('white', '255')
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 24 December 2010. DWF.
Fixed a typo when first color is INTEGER and second color is STRING. 3 Jan 2011. DWF.
Added error handling for out of bounds color values. 25 May 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See colorsareidentical.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 contrastzoom.pro)
NAME:
CONVERT_TO_TYPE
PURPOSE:
Converts its input argument to a specified data type.
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:
result = Convert_To_Type(input, type)
INPUT_PARAMETERS:
input: The input data to be converted.
type: The data type. Accepts values as given by Size(var, /TNAME) or Size(var, /TYPE).
If converting to integer types, values are truncated (similar to FLOOR keyword below),
unless keywords are set.
OUTPUT_PARAMETERS:
result: The input data is converted to specified data type.
KEYWORDS:
CEILING: If set and converting to an integer type, the CEIL function is applied before conversion.
FLOOR: If set and converting to an integer type, the FLOOR function is applied before conversion.
ROUND: If set and converting to an integer type, the ROUND function is applied before conversion.
RESTRICTIONS:
Data types STRUCT, POINTER, and OBJREF are not allowed.
MODIFICATION HISTORY:
Written by David W. Fanning, 19 February 2006.
Typo had "UNIT" instead of "UINT". 23 February 2009. DWF.
Added CEILING, FLOOR, and ROUND keywords. 1 April 2009. DWF.
Modified so that the "type" variable is not changed by the program. 5 May 2009. DWF.
(See convert_to_type.pro)
:Description:
This simple just identifies a routine as a Coyote Graphic routine. It is written
primarily so I can identify such routines before I assign a background color to
a graphics window.
:Categories:
Graphics
:Params:
None.
:Keywords:
None.
:Examples:
Used in graphics programs::
IDL> IF CoyoteGraphic() THEN background = 'white'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 18 January 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See coyotegraphic.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.
FILENAME - An optional input to pickcolorname specifying different
colors. See pickcolorname description for the file format.
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.
OBJECT PROCEDURE METHODS:
Set_Value -- this method takes one argument, the new color name.
It will change the color of the widget if it has
already been realized.
Get_Value -- this method returns the color name the widget is displaying
DEPENDENCIES:
Reqires cgColor and PICKCOLORNAME from the Coyote Library:
http://www.dfanning.com/programs/cgColor.pro
http://www.dfanning.com/programs/pickcolorname.pro
MODIFICATION HISTORY:
Written by David W. Fanning, March 2001.
Fixed a problem with self object cleanup. 7 March 2006. DWF.
Allow addition to already realized widget hierarchies, October 2007. L. Anderson.
Added set_value and get_value methods to the widget can be
updated after being realized. October 2007. L. Anderson.
Added option to pass filename on to pickcolorname. October
2007. L. Anderson
(See cw_drawcolor.pro)
NAME:
DBLTOSTR
PURPOSE:
This is a program for converting a double precision numerical value
to a string. It was originally offered by BioPhys on the IDL newsgroup.
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:
stringValue = DblToStr(value)
INPUTS:
value - A double-precision or floating point value to be converted to a string.
OUTPUTS:
stringValue - The converted string value.
KEYWORDS:
None.
RESTRICTIONS:
Assumes 14 significant digits of precision.
MODIFICATION HISTORY:
Written by BioPhys and offered to the IDL newsgroup, 7 November 2005.
Slightly modified and renamed by David Fanning, 30 November, 2005.
(See dbltostr.pro)
NAME:
DECOMPOSEDCOLOR
PURPOSE:
This function is used to determine, in a device independent way, if the
current graphics device is using color decomposition. The function returns
a 1 if color decomposition is turned on, and a 0 if it is turned off. When
color decomposition is turned on, we say the device is using a true-color
display. If color decomposition is turned off, we say the device is using
an indexed color 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:
result = DecomposedColor()
RETURN VALUE:
result: A 1 if color decomposition is turned on. A 0 if color decomposition is turned off.
ARGUMENTS:
device: The IDL graphics device whose color decomposition state you wish to know the
current value of. If undefined, the current graphics device is used.
KEYWORDRS:
DEPTH: An output keyword that returns the depth of the graphics device. Normally,
either 8 for index color devices, with color decomposition turned off, or 24
for true-color devices with color decomposition turned on.
EXAMPLE:
IDL> Print, DecomposedColor() ; Color decomposition state of current graphics device.
1
IDL> Print, DecomposedColor('PS') ; Color decomposition state of PostScript graphics device.
0
MODIFICATION HISTORY:
Written by: David W. Fanning, May 24, 2009.
Modified the way decomposition was obtained for PostScript devices IDL 7.1 and higher. 12 Dec 2010. DWF.
Fixed a problem in the CASE statement with ELSE clause and added a NULL device segment. 4 Jan 2011. DWF.
It now appears 24-bit PostScript support was added in IDL 7.1, although the Get_Decomposed keyword
didn't work until IDL 7.1.1. 13 January 2011. DWF
(See decomposedcolor.pro)
NAME:
DIRPATH
PURPOSE:
The purpose of this function is to return a device-independent
name of a directory. It is similar to the IDL-supplied FILEPATH
routine, except that a file name is not required.
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:
IDL> theDirectory = DIRPATH('examples')
IDL> Print, theDirectory
C:\IDL\IDL56\examples
INPUTS:
subDirectory: This is a string argument containing the name of the
sub-directory you wish to use. It can be a string
array of sub-directory names. By default, the subDirectory
is set to ['examples', 'data']. To only return the Root_Directory,
set the subDirectory to a null string ("").
KEYWORDS:
ROOT_DIRECTORY: The name of the root directory to use. By default,
the root directory is set to !DIR.
OUTPUTS:
The machine-independent directory path.
MODIFICATION HISTORY:
Written by: David W. Fanning, 28 April 2003.
(See dirpath.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 drawcolors__define.pro)
NAME:
DRAWCOUNTIES
PURPOSE:
Draws state counties in the USA from county shape files.
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:
DrawCounties, countyFile
ARGUMENTS:
countyFile: The name of the input shapefile containing county boundaries.
Must be defined, for example, 'co1990p020.shp'.
KEYWORDS:
ATTRIBUTE_NAME: The name of the attribute in the file that you wish to draw.
By default, this is set to the attribute name "STATE".
(In some shapefiles, the attribute might be named "STATE_ABBR".)
If you are unsure of the attribute names in your shapefile,
use the Coyote Library program SHAPEINFO to browse the file
ahead of time.
COLORS: The name of a color to draw the state outline or polygon in. This
may be a string array of the same size as STATENAMES. Color names
correspond to the colors available in cgColor. By default, "Sky Blue".
LINESTYLE: The normal LINESTYLE keyword index to choose plotting linestyles.
By default, set to 0 and solid lines. May be a vector of the same
size as STATENAMES.
STATENAMES: The names of the states you wish to draw counties for. Normally, these
are two-element state abbreviations, but this will depend upon the entity
attributes in your shape file. If this keyword is undefined, then the counties
in all the states will be drawn. If you are unsure of the entity names, use the
Coyote Library program SHAPEINFO to browse the file ahead of time.
THICK: The line thickness. By default, 1.0.
RESTRICTIONS:
It is assumed a map projection command has been issued and is in effect at
the time this program is called.
If STATENAMES is undefined, all states are drawn, but only a single value
for COLORS, LINESTYLE, and THICK is allowed.
Required Coyote Library programs:
Error_Message
cgColor
EXAMPLE:
Create a map with Nevada in yellow and other state's counties in blue.
Window, XSize=500, YSize=500, Title='County Boundaries'
Map_Set, 37.5, -120, /Albers, /IsoTropic, Limit=[30, -125, 45, -108], $
Position=[0.05, 0.05, 0.95, 0.95]
Erase, COLOR=cgColor('ivory')
Map_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color=cgColor('charcoal')
colors = [Replicate('dodger blue', 6), 'indian red']
DrawCounties, , 'co1990p020.shp', Statenames=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID', 'NV'], $
Colors=colors
MODIFICATION HISTORY:
Written by David W. Fanning, 24 June 2004.
(See drawcounties.pro)
NAME:
DRAWSHAPES
PURPOSE:
Draws entities in a shapefile, containing latitude and longitude
polygons, on a map projection. To draw the shapefile entities
automatically, no matter what kind of values the polygon vertices
have, set the AUTODRAW keyword.
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:
DrawShapes, shapeFile
ARGUMENTS:
shapeFile: The name of the input shapefile containing map polygons or shapes.
If undefined, the "states.shp" file in the IDL distribution is used
as an initial selection.
KEYWORDS:
ATTRNAME: The name of the attribute in the file that you wish to draw.
By default, this is set to the first attribute name in the file.
If you are unsure of the attribute names in your shapefile,
use the Coyote Library program SHAPEINFO to browse the file
ahead of time.
ATTRVALUE: The value of the attribute identified by ATTRNAME. This variable can
be a scalar or vector string array identifying a subset of attribute
values to be drawn. For example, if ATTRNAME='STATE_NAME', then
ATTRVALUE can identify the particular states to draw. For example,
ATTRVALUE=['ARIZONA', 'WYOMING', 'OREGON']. By default, the value
is "ALL", which means that all of the shape entities identified by
ATTRNAME will be drawn.
AUTODRAW: If set, the shapefile entities are examined to find the X and Y
boundaries and a data coordinate space is set up display the
entities automatically. If the shapefile is drawn automatically,
the restriction that the shapefile vertices be in latitude and
longitude values is removed. Do NOT set this keyword, if you
are using the MAPCOORD keyword, too.
COLORS: The name of a color to draw the shapefile polygon in. This
may be a string array of the same size as ATTRVALUES. Color names
correspond to the colors available in cgCOLOR. By default, "blu4".
FCOLORS: The name of the color to draw filled polygons in. If undefined,
the same as COLOR. This may be a string array of the same size as
ATTRVALUES.
FILL: Normally, the polygon outline is drawn. If this keyword is set,
the polygon is filled with a solid color. May be a vector of
the same size as ATTRVALUES.
LINESTYLE: The normal LINESTYLE keyword index to choose plotting linestyles.
By default, set to 0 and solid lines. May be a vector of the same
size as ATTRVALUES.
MAPCOORD: A MapCoord object which implements a map coordinate system using the
GCTP map projections, as implemented with MAP_PROJ_INIT. For more information
about MapCoord objects, see http://www.dfanning.com/catalyst/maponimage.html.
Note that this could also be a map structure as returned from MAP_PROJ_INIT,
but in that case the user is resposible for setting up the XY map
coordinate space independently and outside of this program. Details on
how this can be done can be found at http://www.dfanning.com/map_tips/ephemeral.html.
THICK: The line thickness. By default, 1.0.
RESTRICTIONS:
It is assumed a map projection command has been issued and is in effect at
the time this program is called. Alternatively, you can use a MapCoord object,
which will set up the map coordinate space and provide the map structure required
for plotting in that XY map coordinate space.
If ATTRVALUES is undefined, all entities are drawn, but only a single value
for COLORS, FCOLORS, FILL, LINESTYLE, and THICK is allowed.
Programs from the Coyote and Catalyst Libraries are required.
http://www.dfanning.com/catalyst/howtoinstall.html
EXAMPLES:
Window, XSize=700, YSize=800
Map_Set, 37.5, -117.5, /Albers, /IsoTropic, Limit=[30, -125, 45, -108], $
Position=[0.05, 0.05, 0.95, 0.95]
Erase, Color=cgColor('ivory')
DrawShapes, AttrName='STATE_ABBR', $
AttrValues=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID', 'NV'], Thick=1, $
FColors=['firebrick', 'grn4', 'pur4', 'tan4', 'steel blue', 'org4', 'yellow'], $
Fill = Replicate(1, 7), Colors='charcoal'
Map_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color=cgColor('charcoal')
Example using a MapCoord object.
Window, XSize=700, YSize=800
mapCoord = Obj_New('MapCoord', 'Albers Equal Area', LIMIT=[30, -125, 45, -108], $
Position=[0.05, 0.05, 0.95, 0.95], CENTER_LATITUDE=37.5, $
CENTER_LONGITUDE=-117, STANDARD_PAR1=40, STANDARD_PAR2=-39)
Erase, Color=cgColor('ivory')
DrawShapes, AttrName='STATE_ABBR', $
AttrValues=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID', 'NV'], Thick=1, $
FColors=['firebrick', 'grn4', 'pur4', 'tan4', 'steel blue', 'org4', 'yellow'], $
Fill = Replicate(1, 7), Colors='charcoal', MapCoord=mapCoord
Map_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color=cgColor('charcoal'), $
Map_Structure=mapCoord->GetMapStructure()
Example drawing the states.shp file automatically.
DrawShapes, Filepath(subdir=['examples','data'], 'states.shp'), /Autodraw
MODIFICATION HISTORY:
Written by David W. Fanning by modifiying DrawStates to be more
general, 13 May 2010. DWF.
Added the AUTODRAW keyword for automatic drawing. 15 May 2010. DWF.
Added COMPILE_OPT idl2 to make sure all loop variables are longs. 5 July 2010. DWF.
Corrected an aspect ratio problem with AUTODRAW and upgraded to Coyote Graphics. 3 January 2011. DWF.
(See drawshapes.pro)
NAME:
DRAWSTATES
PURPOSE:
Draws states in the USA in outline or as solid-color polygons
from a state shapefile.
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:
DrawStates, stateFile
ARGUMENTS:
stateFile: The name of the input shapefile containing state boundaries.
If undefined, the "states.shp" file in the IDL distribution is used.
KEYWORDS:
ATTRIBUTE_NAME: The name of the attribute in the file that you wish to draw.
By default, this is set to the attribute name "STATE_ABBR".
(In some shapefiles, the attribute might be named "STATE".)
If you are unsure of the attribute names in your shapefile,
use the Coyote Library program SHAPEINFO to browse the file
ahead of time.
COLORS: The name of a color to draw the state outline or polygon in. This
may be a string array of the same size as STATENAMES. Color names
correspond to the colors available in cgColor. By default, "Sky Blue".
FILL: Normally, the state outline is drawn. If this keyword is set,
the polygon representing the state is filled with a solid color.
May be a vector of the same size as STATENAMES.
LINESTYLE: The normal LINESTYLE keyword index to choose plotting linestyles.
By default, set to 0 and solid lines. May be a vector of the same
size as STATENAMES.
STATENAMES: The names of the states you wish to draw. Normally, these are two-element
state abbreviations, but this will depend upon the entity attributes in your
shapefile. If this keyword is undefined, then all the states in the
file will be drawn. If you are unsure of the entity names, use the
Coyote Library program SHAPEINFO to browse the file ahead of time.
THICK: The line thickness. By default, 1.0.
RESTRICTIONS:
It is assumed a map projection command has been issued and is in effect at
the time this program is called.
If STATENAMES is undefined, all states are drawn, but only a single value
for COLORS, FILL, LINESTYLE, and THICK is allowed.
Required Coyote Library programs:
Error_Message
cgColor
EXAMPLE:
Window, XSize=700, YSize=800
Map_Set, 37.5, -117.5, /Albers, /IsoTropic, Limit=[30, -125, 45, -108], Position=[0.05, 0.05, 0.95, 0.95]
Erase, Color=cgColor('ivory')
DrawStates, Statenames=['CA', 'OR', 'WA', 'AZ', 'UT', 'ID'], Thick=1, $
Colors=['firebrick', 'indian red', 'indian red', 'indian red', 'steel blue', 'indian red'], $
Fill = [1,0,0,0,1,0]
Map_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color=cgColor('charcoal')
MODIFICATION HISTORY:
Written by David W. Fanning, 2 April 2005.
(See drawstates.pro)
NAME:
ErrorLogger__Define
PURPOSE:
The purpose of this program is to log program errors or text messages during
program execution as an aid to debugging such a program at a later date. The
ErrorLogger program is written as an object so that it will persist in the IDL
session until it is destroyed.
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:
errorLogger = Obj_New("ErrorLogger")
ARGUMENTS:
filename: The name of the error log file. If not provided, a default name
will be created, based on the current system time. (Optional)
KEYWORDS:
ALERT: The default behavior of the error logger is simply to write text to a file.
But if the ALERT keyword is set, the program will alert the user via a
message dialog that an error has occurred when using the AddError method.
Default is 0. (Input)
DELETE_ON_DESTROY: If this keyword is set, the error log file will be deleted when the
ErrorLogger object is destroyed, but only if the ErrorLogger object is not
in an error state at that time (error status = 2). Default is 0. (Input)
NOCLUTTER: Believe it or not, some people who use an ErrorLogger prefer that an error log
file is never left behind. (They prefer that the program act like ERROR_MESSAGE.)
For those people, the NOCLUTTER keyword provides a way for them to automatically
set the ALERT and DESTROY_ON_DELETE keywords to 1. It also prevents the error
logger from ever setting the error status to 2. Thus, when the ErrorLogger is
destroyed, the file is always deleted. Default is 0. When set, overrides ALERT
and DELETE_ON_DESTROY settings. (Input)
NOTRACEBACK: Set this keyword to suppress traceback information in the error log output
and in any alerts issued by the program. Default is 0. (Input)
TIMESTAMP: Set this keyword if you wish a time stamp to be appended to the provided
filename. Otherwise, the filename is used as defined. Default filenames
always have a timestamp appended to the file name. (Input)
METHODS:
AddError: Adds an error text string or array to the error log file. By default,
it will add the HELP, LAST_MESSAGE=1, /TRACEBACE traceback
information to the file. (Procedure)
AddText: Adds a text string or array to the error log file. (Procedure)
ClearLog: Erases all the text currently in the error log file. (Procedure)
CloseFile: Closes the currently open error log file. (Procedure)
Flush: Forces a write of any current information to the disk (Procedure)
GetProperty: Gets properties of the object. (Procedure)
LastMessage: Returns the last message text written into the error log file. (Function)
OpenFile: Opens the error log file for writing. (Function)
PrintLastMessage: Writes the last message text written into the error log file to
standard output. (Procedure)
Status: Returns the current status of the error logger. (0 - waiting for input,
1 - normal operation, 2 - error operation.) (Function)
SetProperty: Sets properties of the object. (Procedure)
SetStatus: Sets the current status of the error logger. Normally not used by the
user, but used internally. (Procedure)
MODIFICATION HISTORY:
Written by David W. Fanning, November 2009.
Modified and expanded the way errors are written into the log file and displayed.
Also made it possible to automatically delete the log file when the object is
destroyed, if the error logger is not in an error state at the time. Added
DELETE_ON_DESTROY and NOTRACEBACK keywords to the INIT and SetProperty
methods. 28 Jan 2010. DWF.
Modified default filenames so that I am now guaranteed to get unique file names
by using Timestamp program from the Coyote Library. 8 Feb 2010. DWF.
Added NOCLUTTER keyword. 15 February 2010. DWF.
Added PRINT keyword to AddText method to allow users to log statements that should
also be printed easily to a file. 17 February 2010. DWF.
Small documentation changes to the program. 22 June 2010. DWF.
Made a change so that the file is not opened until something needs to be written
to it. 22 June 2010. DWF.
Added FLUSH method and keyword IMMEDIATE to the INIT method (defaults to 1) which
will immediately flush the log information to disk when log information is
added to the object. This will prevent missing information that is buffered
when a program crashes. Matt Savoie suggestion. DWF, 10 Sept 2010.
(See errorlogger__define.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.
In general, the ERROR_MESSAGE function is not called directly.
Rather, it is used in a CATCH error handler. Errors are thrown
to ERROR_MESSAGE with the MESSAGE command. A typical CATCH error
handler is shown below.
Catch, theError
IF theError NE 0 THEN BEGIN
Catch, /Cancel
void = Error_Message()
RETURN
ENDIF
Error messages would get into the ERROR_MESSAGE function by
throwing an error with the MESSAGE command, like this:
IF test NE 1 THEN Message, 'The test failed.'
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:
ERROR: Set this keyword to cause Dialog_Message to use the ERROR
reporting dialog. Note that a bug in IDL causes the ERROR dialog
to be used whether this keyword is set to 0 or 1!
INFORMATIONAL: Set this keyword to cause Dialog_Message to use the
INFORMATION dialog instead of the WARNING dialog. Note that a bug
in IDL causes the ERROR dialog to be used if this keyword is set to 0!
NONAME: Normally, the name of the routine in which the error occurs is
added to the error message. Setting this keyword will suppress this
behavior.
TITLE: Set this keyword to the title of the DIALOG_MESSAGE window. By
default the keyword is set to 'System Error' unless !ERROR_STATE.NAME
equals "IDL_M_USER_ERR", in which case it is set to "Trapped Error'.
TRACEBACK: Setting this keyword results in an error traceback
being printed to standard output with the PRINT command. Set to
1 (ON) by default. Use TRACEBACK=0 to turn this functionality off.
QUIET: Set this keyword to suppress the DIALOG_MESSAGE pop-up dialog.
OUTPUTS:
Currently the only output from the function is the string "OK".
RESTRICTIONS:
The WARNING Dialog_Message dialog is used by default.
EXAMPLE:
To handle an undefined variable error:
IF N_Elements(variable) EQ 0 THEN $
ok = Error_Message('Variable is undefined')
MODIFICATION HISTORY:
Written by: David W. 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.
Added ERROR, INFORMATIONAL, and TITLE keywords. 19 SEP 2002. DWF.
Removed the requirement that you use the NONAME keyword with the MESSAGE
command when generating user-trapped errors. 19 SEP 2002. DWF.
Added distinctions between trapped errors (errors generated with the
MESSAGE command) and IDL system errors. Note that if you call ERROR_MESSAGE
directly, then the state of the !ERROR_STATE.NAME variable is set
to the *last* error generated. It is better to access ERROR_MESSAGE
indirectly in a Catch error handler from the MESSAGE command. 19 SEP 2002. DWF.
Change on 19 SEP 2002 to eliminate NONAME requirement did not apply to object methods.
Fixed program to also handle messages from object methods. 30 JULY 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Made a traceback the default case without setting TRACEBACK keyword. 19 Nov 2004. DWF.
Added check for window connection specifically for CRON jobs. 6 May 2008. DWF.
Added QUIET keyword. 18 October 2008. DWF.
The traceback information was bypassed when in the PostScript device. Not what I
had in mind. Fixed. 6 July 2009. DWF.
(See error_message.pro)
NAME:
FINDMAPBOUNDARY
PURPOSE:
Utility routine to find the map projection grid boundary from a file,
if it is possible to do so. Currently works with GeoTIFF files, CF 1.4
compliant netCDF files, and GPD files created with the GPD_Viewer software
from the Catatlyst Library.
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:
success = FindMapBoundar(filename, boundary)
INPUTS:
filename: The name of a filename to open to see is a projected map
grid boundary can be found.
OUTPUTS:
boundary: A four-element array of boundary values in the form [x0,y0,x1,y1].
RETURN VALUE:
success: A 1 if a boundary can be found. A 0 otherwise.
KEYWORDS:
USE_LATLON: If the filename is a netCDF file, set this keyword to force
the boundary to be determined by reading the include latitude/longitude
arrays.
XRANGE: A two element vector: boundary[[0,2]].
YRANGE: A two element vector: boundary[[1,3]].
MODIFICATION HISTORY:
Written by: David W. Fanning, 21 February 2010.
Added XRANGE and YRANGE keywords. 25 February 2010. DWF
Added USE_LATLON keyword for finding boundary of netCDF files containing latitude
and longitude arrays. 6 April 2010. DWF.
(See findmapboundary.pro)
NAME:
FIND_BOUNDARY
PURPOSE:
This program finds the boundary points about a region of interest (ROI)
represented by pixel indices. It uses a "chain-code" algorithm for finding
the boundary pixels.
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, math.
CALLING SEQUENCE:
boundaryPts = Find_Boundary(indices, XSize=xsize, YSize=ysize)
OPTIONAL INPUTS:
indices - A 1D vector of pixel indices that describe the ROI. For example,
the indices may be returned as a result of the WHERE function.
OUTPUTS:
boundaryPts - A 2-by-n points array of the X and Y points that describe the
boundary. The points are scaled if the SCALE keyword is used.
INPUT KEYWORDS:
SCALE - A one-element or two-element array of the pixel scale factors, [xscale, yscale],
used to calculate the perimeter length or area of the ROI. The SCALE keyword is
NOT applied to the boundary points. By default, SCALE=[1,1].
XSIZE - The X size of the window or array from which the ROI indices are taken.
Set to !D.X_Size by default.
YSIZE - The Y size of the window or array from which the ROI indices are taken.
Set to !D.Y_Size by default.
OUTPUT KEYWORDS:
AREA - A named variable that contains the pixel area represented by the input pixel indices,
scaled by the SCALE factors.
CENTER - A named variable that contains a two-element array containing the center point or
centroid of the ROI. The centroid is the position in the ROI that the ROI would
balance on if all the index pixels were equally weighted. The output is a two-element
floating-point array in device coordinate system, unless the SCALE keyword is used,
in which case the values will be in the scaled coordinate system.
PERIM_AREA - A named variable that contains the (scaled) area represented by the perimeter
points, as indicated by John Russ in _The Image Processing Handbook, 2nd Edition_ on
page 490. This is the same "perimeter" that is returned by IDLanROI in its
ComputeGeometry method, for example. In general, the perimeter area will be
smaller than the pixel area.
PERIMETER - A named variable that will contain the perimeter length of the boundary
upon returning from the function, scaled by the SCALE factors.
EXAMPLE:
LoadCT, 0, /Silent
image = BytArr(400, 300)+125
image[125:175, 180:245] = 255B
indices = Where(image EQ 255)
Window, XSize=400, YSize=300
TV, image
PLOTS, Find_Boundary(indices, XSize=400, YSize=300, Perimeter=length), $
/Device, Color=cgColor('red')
Print, length
230.0
DEPENDENCIES:
Requires ERROR_MESSAGE from the Coyote Library.
http://www.dfanning.com/programs/error_message.pro
MODIFICATION HISTORY:
Written by David W. Fanning, April 2002. Based on an algorithm written by Guy
Blanchard and provided by Richard Adams.
Fixed a problem with distinction between solitary points and
isolated points (a single point connected on a diagonal to
the rest of the mask) in which the program can't get back to
the starting pixel. 2 Nov 2002. DWF
Added the ability to return the perimeter length with PERIMETER and
SCALE keywords. 2 Nov 2002. DWF.
Added AREA keyword to return area enclosed by boundary. 2 Nov 2002. DWF.
Fixed a problem with POLYFILLV under-reporting the area by removing
POLYFILLV and using a pixel counting method. 10 Dec 2002. DWF.
Added the PERIM_AREA and CENTER keywords. 15 December 2002. DWF.
Replaced the ERROR_MESSAGE routine with the latest version. 15 December 2002. DWF.
Fixed a problem in which XSIZE and YSIZE have to be specified as integers to work. 6 March 2006. DWF.
Fixed a small problem with very small ROIs that caused the program to crash. 1 October 2008. DWF.
Modified the algorithm that determines the number of boundary points for small ROIs. 28 Sept 2010. DWF.
(See find_boundary.pro)
NAME:
FIND_RESOURCE_FILE
PURPOSE:
This function is designed to search for and return the fully qualified
path to a resource file. The order of search is as follows:
1. In the directories rooted at the IDL resource directory (IDL_DIR/resource).
2. In the same directory as this file is found in.
3. In the directories rooted at a resource directory found in the same directory this file is in.
4. In the directories rooted at a resource directory found in the a directory one above the directory this file is in.
5. Anywhere in the IDL PATH. Note that a *.pro file *must* be in a directory for the directory to be on
the IDL PATH.
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:
fullPath = Find_Resource_File(resourceFilename)
INPUTS:
resourceFilename: The root name of a resource file. For example, 'arc.bmp'.
KEYWORD PARAMETERS:
SUCCESS: An output keyword whose value is set to 1 if the program
successfully finds the resource file. Otherwise, set to 0.
VERBOSE: Set this keyword to enable output that prints the full path
to the resource file, or tells you that the file cannot be found.
RETURN_VALUE:
fullpath: A fully-qualified file path to the resource file.
EXAMPLE:
IDL> print, find_resource_file('gshhs_i.b', success=s) & print, 'success: ', s
/home/fanning/IDL/incubator/gshhs_i.b
success: 1
IDL> print, find_resource_file('dataviewer_splash.jpg', success=s) & print, 'success: ', s
/home/fanning/IDL/dataviewer/resources/dataviewer_splash.jpg
success: 1
IDL> print, find_resource_file('arc.bmp', success=s) & print, 'success: ', s
/usr/local/rsi/idl70/resource/bitmaps/arc.bmp
success: 1
IDL> print, find_resource_file('toast_and_jam.txt', success=s) & print, 'success: ', s
success: 0
MODIFICATION HISTORY:
Written by: David W Fanning, December 12, 2008.
It seems all my resource files are in "resources" directories, not "resource" directories.
So now the program looks in both places. 6 January 2009.
The file did not seem to be looking in the IDL path. It does now. 21 April 2010. DWF.
The file will also look in the directory of the caller of this program. 21 April 2010. DWF.
Fixed a problem when File_Search finds several files with the same name. Always takes the
first file found now. 4 June 2010. DWF.
(See find_resource_file.pro)
NAME:
Fit_Ellipse
PURPOSE:
This program fits an ellipse to an ROI given by a vector of ROI indices.
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, math.
CALLING SEQUENCE:
ellipsePts = Fit_Ellipse(indices)
OPTIONAL INPUTS:
indices - A 1D vector of pixel indices that describe the ROI. For example,
the indices may be returned as a result of the WHERE function.
OUTPUTS:
ellipsePts - A 2-by-npoints array of the X and Y points that describe the
fitted ellipse. The points are in the device coodinate system.
INPUT KEYWORDS:
NPOINTS - The number of points in the fitted ellipse. Set to 120 by default.
SCALE - A two-element array that gives the scaling parameters for each X and Y pixel, respectively.
Set to [1.0,1.0] by default.
XSIZE - The X size of the window or array from which the ROI indices are taken.
Set to !D.X_Size by default.
YSIZE - The Y size of the window or array from which the ROI indices are taken.
Set to !D.Y_Size by default.
OUTPUT KEYWORDS:
CENTER -- Set to a named variable that contains the X and Y location of the center
of the fitted ellipse in device coordinates.
ORIENTATION - Set to a named variable that contains the orientation of the major
axis of the fitted ellipse. The direction is calculated in degrees
counter-clockwise from the X axis.
AXES - A two element array that contains the length of the major and minor
axes of the fitted ellipse, respectively.
SEMIAXES - A two element array that contains the length of the semi-major and semi-minor
axes of the fitted ellipse, respectively. (This is simple AXES/2.)
EXAMPLE:
LoadCT, 0, /Silent
image = BytArr(400, 300)+125
image[180:245, 125:175] = 255B
indices = Where(image EQ 255)
Window, XSize=400, YSize=300
TV, image
PLOTS, Fit_Ellipse(indices, XSize=400, YSize=300), /Device, Color=cgColor('red')
MODIFICATION HISTORY:
Written by David W. Fanning, April 2002. Based on algorithms provided by Craig Markwardt
and Wayne Landsman in his TVEllipse program.
Added SCALE keyword and modified the algorithm to use memory more efficiently.
I no longer have to make huge arrays. The arrays are only as big as the blob
being fitted. 17 AUG 2008. DWF.
Fixed small typo that caused blobs of indices with a longer X axis than Y axis
to misrepresent the center of the ellipse. 23 February 2009.
(See fit_ellipse.pro)
NAME:
FIXPS
PURPOSE:
Modifies an IDL-produced PostScript landscape mode file so that the output
is right side up rather than upside down.
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:
FixPS, inputFile, outputFile
Auguments:
inputFile: A IDL-produced PostScript file in Landscape mode.
outputFile: The name of the fixed output PostScript file. If not provided, the input
file is overwritten. Assumes proper read/write permission in TEMP directory
and in the directory where the input file is located.
KEYWORDS:
A4: Set this keyword if the PostScript file is using a A4 Europeran sized page.
LEDGER: Set this keyword if the PostScript file is using a US ledger size (11 x 17 inch) page.
LEGAL: Set this keyword if the PostScript file is using a US legal size (8.5 x 14 inch) page.
LETTER: Set this keyword if the PostScript file is using a US letter size (8.5 x 11 inch) page.
PAGETYPE: A generic way to set the page size. A string of "LETTER", "LEDGER", "LEGAL", or "A4".
By default, set to "LETTER".
QUIET: Set this keyword to suppress error messages from the program.
SUCCESS: If this keyword is set to a named variable, then on output the variable will
return a 1 if the operation was successful, and a 0 otherwise. Using this
keyword also supresses the program's ability to "throw" an error. Informational
messages are issued about program developments, but this program will allow the
program caller to decide what to do with unsuccessful program completion.
SIDE EFFECTS and RESTRICTIONS:
Files that are not currently in Landscape mode will be ignored. Tested with single and
multiple page PostScript output from IDL 7.0.1 and 7.1.
MODIFICATION HISTORY:
Written by: David W. Fanning, 6 August 2009.
Change to overwrite input file if output filename is not provided. 6 August 2009. DWF.
Incorporated checks for non-landscape mode files and files that have already been fixed. 6 August 2009. DWF.
Modified to fix multiple-page PostScript files and to work seamlessly with PS_START output. 8 August 2009. DWF.
Ran into a problem in which the PostScript file is stored in the directory pointed
to by the IDL_TMPDIR environment variable. Now check to see if the input filename
is the same as the output filename and make a change, if necessary. 22 July 2010. DWF.
Retreated to standard error handling with ERROR_MESSAGE as there are inevitable errors. 2 August 2010. DWF.
Output file was created, even if not used. Now deleting file and issuing messages to
explain why output file was not created. 1 November 2010. DWF.
Added SUCCESS and QUIET keywords. 15 Novemember 2010. DWF.
PostScript file structure changed in IDL 8. Made adjustment to find the
PageBoundingBox line. 19 Dec 2010. DWF.
(See fixps.pro)
NAME:
FLOATS_EQUAL
PURPOSE:
The purpose of this function is to compare two floating-point values or
arrays to determine if the values or arrays are equal. Arrays are equal
if they have the same number of elements, and each element is equal.
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:
result = FLOATS_EQUAL(array_1, array_2)
ARGUMENTS:
array_1 Any single or double precision value or array. Required parameter.
array_2 Any single or double precision value or array. Required parameter.
KEYWORDS:
ULP UNIT in the LAST PLACE. It is the gap or difference between two
floating point numbers in the last digit that can distinguish the
two numbers. Must be a positive integer. Set to 1 by default. Set
to a larger value if you suspect accumulative round-off errors
in your arrays.
RETURN VALUE:
result Set to 1 if the arrays are equal, which means that the arrays have
the same number of elements and each element is equal to the same
element in the other array. Set to 0 if the arrays are not equal.
COMMON BLOCKS:
None.
EXAMPLE:
IDL> a = Findgen(11)
IDL> b = Findgen(11)
IDL> Print, Floats_Equal(a,b)
1
IDL> b[4] = b[4] + 0.0001
IDL> Print, Floats_Equal(a,b)
0
RESTRICTIONS:
None.
MODIFICATION HISTORY:
Written by: David W. Fanning, 29 August 2007.
Fixed a problem when using large numbers with the TOTAL command
by setting the INTEGER keyword. 22 June 2011. DWF.
(See floats_equal.pro)
NAME:
FPUFIX
PURPOSE:
This is a utility routine to examine a variable and fix problems
that will create floating point underflow errors.
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:
fixedData = FPUFIX(data)
ARGUMENTS:
data : A numerical variable to be checked for values that will cause
floating point underflow errors. Suspect values are set to 0.
KEYWORDS:
None.
RETURN VALUE:
fixedData: The output is the same as the input, except that any values that
will cause subsequent floating point underflow errors are set to 0.
COMMON BLOCKS:
None.
EXAMPLES:
data = FPTFIX(data)
RESTRICTIONS:
None.
MODIFICATION HISTORY:
Written by David W. Fanning, from Mati Meron's example FPU_FIX. Mati's
program is more robust that this (ftp://cars3.uchicago.edu/midl/),
but this serves my needs and doesn't require other programs from
Mati's library. 24 February 2006.
(See fpufix.pro)
NAME:
FSC_BASE_FILENAME
PURPOSE:
The purpose of this is to extract from a long file path, the
base file name. That is, the name of the actual file without
the preceeding directory information or the final file extension.
The directory information and file extension can be obtained via
keywords. The file is named so as not to interfere with FILE_BASENAME,
which was introduced in IDL 6.0 and performs a similar function.
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:
baseFilename = FSC_Base_Filename(thePath)
INPUTS:
thePath: This is the file path you wish to extract a base file name from.
It is a string variable of the sort returned from Dialog_Pickfile.
KEYWORDS:
DIRECTORY: The directory information obtained from the input file path.
The directory always ends in a directory separator character.
EXTENSION: The file extension associated with the input file path.
PATH_SEPARATOR: The string to use as a path separator. If undefined, the output
of PATH_SEP() will be used.
RETURN_VALUE:
baseFilename: The base filename, stripped of directory and file extension information.
RESTRICTIONS:
This is a quick and dirty program. It has been tested on Windows machines and *lightly*
tested on UNIX machines. Please contact me at the e-mail address above if you discover
problems.
EXAMPLE:
IDL> thePath = "C:\rsi\idl7.8\lib\jester.pro"
IDL> Print, FSC_Base_Filename(thePath, Directory=theDirectory, Extension=theExtension)
jester
IDL> Print, theDirectory
C:\rsi\idl7.8\lib\
IDL> Print, theExtension
pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 31 July 2003.
Modified by KaRo, 13 Feb. 2005 to allow dots in the filename.
Added PATH_SEPARATOR keyword. 25 July 2005. DWF.
Added ability to recongnize directory by path separator in last character. 19 Sept 2005. DWF.
If directory is blank (because a relative filename was passed), set to current directory. 6 Aug 2009. DWF.
(See fsc_base_filename.pro)
NAME:
FSC_COLORBAR__DEFINE
Note: The name of the routine has been changed from COLORBAR__DEFINE
on 25 Sept 2010 to avoid conflicts with an IDL 8.0 routine of the
same name. See the article "IDL 8 Name Conflicts" here:
http://www.dfanning.com/ng_tips/idl8_name_conflicts.html
PURPOSE:
The purpose of this routine is to implement a FSC_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("FSC_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("FSC_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.
25 September 2010. Renamed to FSC_Colorbar__Define to avoid conflict with a
Colorbar__Define program introduced with IDL 8.0. DWF.
(See fsc_colorbar__define.pro)
NAME:
FSC_COLORSELECT
PURPOSE:
The purpose of this compound widget is to provide a means for selecting
a new color or color table in a widget program. The program consists of
a label, a non-editable text widget, and a button to make a color or
color table selection interactively. (See the example program.)
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:
objectRef = FSC_COLORSELECT(parent, Title='Annotate Color ", Color='red')
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
BREWER: Set if you want Brewer color tables, rather than the normal IDL color tables.
This requires the file fsc_brewer.tbl to be in your IDL path.
CFONT: Set to the name of a font to display the color name in.
COLOR: The name of the color to be displayed in the widget. If color
is not used, or if it is set to a null string, then the widget
will allow selection of a color table, instead of a color name.
CT_INDEX: The color table index number you wish to use. The actual name of the
color table will be displayed in the widget.
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.
FRAME: Set this keyword to put a frame around the compound widget.
LABELALIGN: Set this keyword to align label text. [0-center (default), 1-left, 2-right].
LABELFONT: The font name for the text in the Label Widget.
LABELSIZE: The X screen size of the Label Widget.
NAME: A scalar string name of the object. (Default = ''.)
SCR_XSIZE: The X screen size of the compound widget.
SCR_YSIZE: The Y screen size of the compound widget.
STYLE: The "style" of the text in the Text Widget. A value of 0 (the default)
capitalizes the first letter in the name. A style of 1 uses all lowercase.
A style of 2 uses all uppercase.
TITLE: The text to go on the Label Widget.
UVALUE: A user value for any purpose.
XSIZE: The X size of the Text Widget.
In addition, any keyword defined for WIDGET_TEXT, but not defined here (e.g., SENSITIVE), is
passed along without inspection to the text widget. Use of "extra" keywords is discouraged.
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.
event = { FSC_ColorSelect_Event, $; 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.
Color: "", $ ; The name of the current color or color table.
Index: 0L, $ ; The color table index selected if color tables are used.
Brewer: 0L, $ ; A flag that indicated Brewer color tables are being used.
NColors: 0L, $ ; The number of colors used for the color table.
ObjRef:Obj_New()} ; The "self" object.
GETTING and SETTING VALUES:
Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
But since traditional compound widgets have the ability to get and
set the value of the compound widget, this capability is implemented
as special methods: Get_Color/Set_Color and Get_Color_Index/Set_Color_Index.
To get the color of the widget, do this: color = objectRef->Get_Color()
To set the color of the widget, do this: objectRef->Set_Color, 'blue'.
Valid colors are those returned by FSC_Color. Getting and setting the
color table index number works similarly.
EXAMPLE:
An example program is provided at the end of the FSC_COLORSELECT code. To run it,
type these commands:
IDL> .Compile FSC_COLORSELECT
IDL> Example
DEPENDENCIES:
Requires the Coyote Library:
http://www.dfanning.com/programs/coyoteprograms.zip
MODIFICATION HISTORY:
Written by: David W. Fanning, 26 JULY 2010.
(See fsc_colorselect.pro)
NAME:
FSC_DROPLIST
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the DROPLIST widget offered in the IDL distribution. What has
always annoyed me about a droplist is that you can't get the current
"value" of a droplist easily. This compound widget makes this and
other tasks much easier.
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:
droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2)
The return value of the FSC_Droplist (droplistObj in this example) is
an object reference. Interaction with the droplist will occur through
object methods.
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Any keyword that is appropriate for the Widget_Droplist function can be used.
In addition, these keywords are explicitly defined.
EVENT_FUNC -- Set this keyword to the name of an Event Handler Function.
EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure.
FORMAT -- A format specifier for the "format" of the values in the droplist.
INDEX -- The index number of the current selection.
SPACES -- A two-element array that indicates the number of blank spaces to be added
to the the beginning and end of the formatted values. If a single number
is provided, this number of blank spaces is added to both the beginning
and the end of the value.
TITLE -- The title of the droplist widget.
UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.)
UVALUE -- The normal "user value" of the droplist.
VALUE -- An array of the droplist "selections". May be any data type.
COMMON BLOCKS:
None.
DEPENDENCIES:
Requires ERROR_MESSAGE from the Coyote Library..
EVENT STRUCTURE:
An event is returned each time the droplist value is changed. The event structure
is defined like this:
event = { FSC_DROPLIST_EVENT, $ ; 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.
INDEX: 0L, $ ; The index number of the current selection.
SELECTION:Ptr_New() $ ; A pointer to the current selection "value".
SELF:Obj_New() } ; The object reference of the compound widget.
PUBLIC OBJECT METHODS:
GetID -- A function with no arguments that returns the widget identifier
of the droplist widget.
droplistID = droplistObj->GetID()
GetIndex -- A function with no arguments that returns the index
number of the current droplist selection.
currentIndex = droplistObj->GetIndex()
GetSelection -- A function with no arguments that returns the current
droplist selection.
currentSelection = droplistObj->GetSelection()
GetUValue -- A function with no arguments that returns the "user value"
of the compound widget i.e., the value set with the UVALUE keyword).
myUValue = droplistObj->GetUValue()
GetValues -- A function with no arguments that returns the "values" or
"selections" for the droplist.
possibleSelections = droplistObj->GetValues()
Resize -- A procedure that sets the X screen size of the droplist. It is
defined like this:
PRO Resize, newSize, ParentSize=parentSize
The "newSize" keyword is the new X screen size. If this argument is
missing, the screen X size of the compound widget's parent is used.
The parentSize keyword is an output keyword that returns the X screen
size of the compound widget's parent.
droplistObj->Resize, 400
Note that not all devices (e.g., X Windows devices) support droplist resizing.
SetIndex -- A procedure that sets the current droplist selection based on
the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex
droplistObj->SetIndex, newIndex
SetSelection -- Whereas a regular droplist widget can only be set by index
number, this compound widget can also be set by a "selection". The new selection
can be any data type and corresponds to one of the "values" of the droplist.
droplistObj->SetSelection, newSelection
SetValues -- Sets the possible selections of the droplist widget. The CurrentIndex keyword
will allow the current index of the selection to be changed to:
newChoices = ['dog', 'cat', 'coyote']
droplistObj->SetValues, newChoices, CurrentIndex=2
EXAMPLE:
An example program is provided at the end of the FSC_DROPLIST code. To run it,
type these commands:
IDL> .Compile FSC_DROPLIST
IDL> Example
MODIFICATION HISTORY:
Written by: David W Fanning, 17 Jan 2000. DWF.
Added FORMAT and SPACES keywords 28 April 2000. DWF.
Fixed a small problem with event processing when the EVENT_FUNC keyword
was used. 29 Dec 2000. DWF.
Attached the UNAME value to the TLB of the compound widget instead
of to the droplist widget itself. 11 Jan 2001. DWF.
Fixed a problem when the droplist was part of a modal widget and used the
EVENT_PRO keyword. 27 Oct 2003. DWF.
Added a SetValue method for setting all the values in the droplist at once. 12 Nov 2004. DWF.
Fixed type on line 346/ 6 Feb 2008. DWF.
(See fsc_droplist.pro)
NAME:
FSC_FIELD
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. One weakness
of the CW_FIELD compound widget 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
will be helpful. For example, you can now assign an event handler
to the compound widget, ask for positive numbers only, and limit
the number of digits in a number, or the number of digits to the
right of a decimal point. The program is written as a widget object,
which allows the user to call object methods directly, affording
even more flexibility in use. This program replaces the earlier
programs FSC_INPUTFIELD and COYOTE_FIELD.
The program consists of a label widget next to a one-line text widget.
The "value" of the compound widget is shown in the text widget. If the
value is a number, it will not be possible (generally) to type
alphanumeric values in the text widget. String values behave like
strings in any one-line text 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.
TYPICAL CALLING SEQUENCE:
fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
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.
The default is to have the Label widget in a row with the Text widget.
CR_ONLY Set this keyword if you only want Carriage Return events returned to
your event handler. If this keyword is not set, all events are returned.
Setting this keyword has no effect unless either the EVENT_PRO or
EVENT_FUNC keyword is used.
DECIMAL Set this keyword to the number of digits to the right of the decimal
point in floating point or double precision numbers. Ignored for STRING values.
DIGITS Set this keyword to the number of digits permitted in integer numbers.
EVENT_FUNC Set this keyword to the name of an event handler 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 handler 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.
FRAME Set this keyword to put a frame around the compound widget.
FOCUS_EVENTS Set this keyword to enable event generation for keyboard focus
events. Ignored unless EVENT_FUNC or EVENT_PRO keywords are specified.
HIGHLIGHT Set this keyword to highlight the existing text if the widget gain
the keyboard focus. This keyword MUST be set for tabbing to work naturally
in IDL 6.2 and higher.
LABEL_LEFT Set this keyword to align the text on the label to the left.
LABEL_RIGHT Set this keyword to align the text on the label to the right.
LABELFONT The font name for the text in the label widget.
LABELSIZE The X screen size of the label widget.
NAME A string containing the name of the object. The default is ''.
NOEDIT Set this keyword to allow no user editing of the input text widget.
NONSENSITIVE Set this keyword to make the input text widget non-sensitive.
POSITIVE Set this keyword if you want only positive numbers allowed.
SCR_XSIZE The X screen size of the compound widget.
SCR_YSIZE The Y screen size of the compound widget.
TITLE The string text placed on the label widget.
UNDEFINED Set this keyword to the value to use for "undefined" values. If
not set, then !Value.F_NAN is used for numerical fields and a
NULL string is used for string fields. This applies to values
obtained with the GET_VALUE method or the GET_VALUE function.
UVALUE A user value for any purpose.
VALUE The "value" of the compound widget. Any type of integer, floating, or string
variable is allowed. The data "type" is determined automatically from the
value supplied with this keyword. Be sure you set the type appropriately for
your intended use of the value.
XSIZE The X size of the text widget in the usual character units.
OUTPUT KEYWORDS:
OBJECT Set this keyword to a named variable to receive the compound widget's
object reference. This is required if you wish to call methods on the object.
Note that the object reference is also available in the event structure
generated by the widget object. Note that the object reference will be
necessary if you want to get or set values in the compound widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
Requires DBLTOSTR from the Coyote Library:
http://www.dfanning.com/programs/dbltostr.pro
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 = { FSC_FIELD_EVENT, $ ; 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.
OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
VALUE: Ptr_New(), $ ; A pointer to the widget value.
TYPE:"" ; A string indicating the type of data in the VALUE field.
}
Note that if the field is "empty", the VALUE will be a pointer
to an undefined variable. You should check this value before you
use it. You code will look something like this:
IF N_Elements(*event.value) EQ 0 THEN $
Print, 'Current Value UNDEFINED.' ELSE $
Print, 'Current Value: ', *event.value
GETTING and SETTING VALUES:
Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
Traditional compound widgets have the ability to get and set the "value"
of the compound widget identifier (e.g., fieldID in the calling
sequence above). Unfortunately, it is impossible to retreive a variable
in this way when the variable is undefined. In practical terms, this
means that the undefined variable must be set to *something*. You can
determine what that something is with the UNDEFINED keyword, or I will set
it to !VALUES.F_NAN for numerical fields and to the null string for string
fields. In any case, you will have to check for undefined variables before
you try to do something with the value. For a numerical field, the code
might look something like this:
fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
currentValue = fieldObject->Get_Value()
IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue
Additional examples are provided in the numerical example fields in Example Program below.
Setting the value of the compound widget is the same as calling the Set_Value
method on the object reference. In other words, these two statements are equivalent.
fieldObject->Set_Value, 45.4
Widget_Control, fieldID, Set_Value=45.4
The data type of the value is determined from the value itself. Be sure you set it appropriately.
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
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 -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Has_Focus -- Set to 1 if the text widget currently has the keyboard focus.
Highlight -- The highlight flag.
NoEdit -- The NoEdit flag.
NonSensitive -- The NonSensitive flag.
Undefined -- The "value" of any undefined value.
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.
Name -- A scalar string name of the object.
Resize -- This method allows you to resize the compound widget's text field.
The value parameter is an X screen size for the entire widget. The text
widget is sized by using the value obtained from this value minus the
X screen size of the label widget.
objectRef->Resize, screen_xsize_value
Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.
objectRef->Set_Value, 5
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
CR_Only -- Set this keyword if you only want Carriage Return events.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOAT and DOUBLE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGER and LONG numbers.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
Highlight -- Set this keyword to highlight the existing text
when the widget gets the keyboard focus
LabelSize -- The X screen size of the Label Widget.
Name -- A scalar string name of the object. (default = '')
NoEdit -- Set this keyword to make the text widget uneditable
NonSensitive -- Set this keyword to make the widget nonsensitive
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
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.
SetTabNext -- This method allows you to specify which field to go to when a TAB character
is typed in the text widget. See the Example program below for an example of how to
use this method.
OBJECT FUNCTIONS METHODS:
Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:
IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.
GetLabelSize -- Returns the X screen size of the label widget. No parameters.
GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.
GetTextSize -- Returns the X screen size of the text widget. No parameters.
PRIVATE OBJECT METHODS:
Although there is really no such thing as a "private" method in IDL's
object implementation, some methods are used internally and not meant to
be acessed publicly. Here are a few of those methods. I list them because
it may be these private methods are ones you wish to override in subclassed
objects.
MoveTab -- This method moves the focus to the widget identified in the "next" field,
which must be set with the SetTabNext method. No parameters. Called automatically
when a TAB character is typed in the text widget.
Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.
ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.
Validate -- This function method examines all text input and removes unwanted
characters, depending upon the requested data type for the field. It makes it
impossible, for example, to type alphanumeric characters in an INTEGER field.
EXAMPLE:
An example program is provided at the end of the FSC_FIELD code. To run it,
type these commands:
IDL> .Compile FSC_Field
IDL> Example
MODIFICATION HISTORY:
Written by: David W. Fanning, 18 October 2000. Based heavily on an earlier
FSC_INPUTFIELD program and new ideas about the best way to write
widget objects.
Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF.
Modified the way the value is returned in the GET_VALUE method and the
GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF.
Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE
methods. 19 Jan 2001. DWF.
Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF.
Added GetTextSize and GetLabelSize methods for obtaining the X screen
size of the text and label widgets, respectively. 21 July 2001. DWF.
Fixed a problem in SetProperty method where I was setting self.xsize, which doesn't exist. 24 April 2002. DWF.
Small modification to the SetEdit method. 6 August 2003. DWF.
Added Highlight keyword. Ported Focus_Events keyword from
fsc_inputfield.pro. Updated documentation. 17 November
2004. DWF and Benjamin Hornberger
Added Has_Focus keyword to the GetProperty method. 18 November
2004. Benjamin Hornberger
Fixed bug in GetProperty method (set value to *self.undefined if
*self.value is undefined. 24 Feb 2004. Benjamin Hornberger
Modified FOCUS_EVENTS keyword handling so that *all* focus events are now
passed to specified event handlers. Check event.select to see if the
widget is gaining or losing focus. 10 August 2005. DWF.
Added new tabbing functionality, introduced in IDL 6.2. To use tabbing
functionality natually, the HIGHTLIGHT keywords must be set.
See included EXAMPLE program for details. 10 August 2005. DWF.
Added functionality to covert double precision values to strings properly. 30 Nov 2005. DWF.
Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
Fixed a problem with validating a float or double value when it was written with
exponential notation. 2 April 2010. DWF.
(See fsc_field.pro)
NAME:
FSC_FILESELECT
PURPOSE:
The purpose of this compound widget is to provide a means
by which the user can type or select a file name. The
program is written as an "object widget", meaning that
the guts of the program is an object of class FSC_FILESELECT.
This is meant to be an example of the obvious advantages of
writing compound widget programs as objects.
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:
filenameID = FSC_FileSelect(parent)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Event_Pro -- The event handler procedure for this compound widget.By default: "".
Event_Func -- The event handler function for this compound widget. By default: "".
If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget.
DirectoryName -- The initial name of the directory. By defaut: current directory.
Filename -- The initial file name in the filename text widget.
Filter -- The file filter. By default: "*".
Frame -- Set this keyword for a frame around the compound widget.
LabelFont -- The font for the label widget. By default: "".
LabelName -- The text on the label widgt. By default: "Filename: ".
LabelSize -- The X screen size of the label widget. By default: 0.
MustExist -- A flag that indicates selected files must exist. By default: 0.
NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0.
If this keyword is not set, the compound widget will automatically resize itself to
the largest widget in its parent base widget. It will do this by changing the size of
the text widgets holding the file and directory names.
Read -- Set this keyword to have file selection for reading a file. By default: 1.
SelectDirectory -- The default directory for file selection. In other words, this is the
default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons.
SelectFont -- The font for the "Browse" button. By default: "".
SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...".
TextFont -- The font for the filename text widget. By default: "".
UValue -- User value for any purpose.
Write -- Set this keyword to open a file for writing. By default: 0.
XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40.
OUTPUT KEYWORDS:
ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference.
With the object reference you can call object methods to easily change many properties of
the compound widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
Requires the folling files from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
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. All events
generated by the text widgets are passed to the assigned event handler.
event = { CW_FILESELECT, $ ; 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.
Basename: "", $ ; The base filename without directory specifiers.
Filename: "", $ ; The fully qualified filename.
Directory: "", $ ; The name of the current file directory.
}
EXAMPLE:
An example program is provided at the end of the FSC_FILESELECT code. To run it,
type these commands:
IDL> .Compile fsc_fileselect
IDL> Example
Or, if you want to obtain the object reference, type this:
IDL> Example, theObject
Now you can call the object's methods. For example:
IDL theObject->SetProperty, XSize=150
GETTING and SETTING VALUES:
So as not to disrupt the accepted paradigm in using compound widgets, you
can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to
get and set the "value" of the widget.
Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat'
The program will automatically separate the file name portion of the value
from the directory portion and put things in the correct text widgets.
Similarly, you can get the "value" of the widget:
Widget_Control, filenameID, Get_Value=theValue
Print, theValue
C:\RSI\IDL52\DATA\cyclone.dat
The return value is the fully qualified file path to the file.
USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES:
If you obtain the object reference, you have a great deal more control
over the properties of the compound widget. You obtain the object reference
by calling the function like this:
filenameID = FSC_FILESELECT(parent, ObjectRef=theObject)
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
DirectoryName -- The current directory.
Event_Func -- The name of the event handler function for this compound widget.
Event_Pro -- The name of the event handler procedure for this compound widget.
Filename -- The current base filename.
Filter -- The current file filter.
LabelName -- The text on the label widget.
LabelSize -- The X screen size of the label widget.
MustExist -- A flag that indicates selected files must exist to be selected.
Parent -- The parent widget of the compound widget.
Read=read -- The file selection for reading flag.
SelectTitle -- The title bar text on the file selection dialog.
TLB -- The top-level base of the compound widget.
UValue -- The user value of the compound widget.
Write -- The file selection for writing flag.
XSize -- The X size of the text widget holding the filename.
LabelSize -- This method makes sure that the directory name and file name labels
are the same size. Normally, this procedure is called internally. No parameters.
MatchSize -- This method resizes the compound widget so that it is as long as the
the longest widget in the parent base widget. This is done automatically upon
realization unless the NOMAXSIZE keyword is set. The method aids in writing
resizeable widget programs.
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
DirectoryName -- The current directory.
Event_Func -- The name of the event handler function for this compound widget.
Event_Pro -- The name of the event handler procedure for this compound widget.
Filename -- The current base filename.
Filter -- The current file filter.
LabelName -- The text on the label widget.
LabelSize -- The X screen size of the label widget.
MustExist -- A flag that indicates selected files must exist to be selected.
Read -- The file selection for reading flag.
SelectTitle -- The title bar text on the file selection dialog.
UValue -- The user value of the compound widget.
Write -- The file selection for writing flag.
XSize -- The X size of the text widget holding the filename.
TextSelect - Allows you to create a selection in filename text widget. See the
documentation for the SET_TEXT_SELECT keyword to Widget_Control.
selection -- A two-element array containing the starting position and selection length.
OBJECT FUNCTION METHODS:
GetFileName -- Returns the fully qualified filename. No parameters.
GetTLB -- Returns the top-level base ID of the compound widget. No Parameters.
Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter.
directoryName -- The name of the directory from the directory text widget.
textSelection -- The current text selection position.
At the moment all this does is remove any blank characters from either
end of the directory name and makes sure the last character of the directory
name does not end in a subdirectory specifier (except for VMS).
Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter.
filename -- The name of the file from the filename text widget.
textSelection -- The current text selection position.
At the moment all this does is remove any blank characters from either
end of the file name
MODIFICATION HISTORY:
Written by: David W. Fanning, 21 NOV 1999.
Fixed bug in File Name selection button. 18 MAR 2000. DWF.
Fixed an error in which directory the Browse buttons should start
searching. 29 SEP 2000. DWF.
Previously returned events only for typing in text widgets. Now
Browse button events are also returned. 29 SEP 2000. DWF.
Fixed a bug in setting the file filter. 29 SEP 2000. DWF.
Removed the Directory Browse button 10 AUG 2002. DWF.
Added ERROR_MESSAGE to error handling. 10 AUG 2002. DWF.
Changed the ability to specify a file filter as a string array, instead
of just as a scalar string. This required the use of a pointer, which
meant that I had to remove the FILTER field from the CW_FILESELECT
event structure to avoid likely memory leakage. This is a dangerous
change because it means programs that relied on this (I expect there
are very, very few) will break and it goes against my philosopy of
keeping my programs backward compatible. Let me know if you have
problems. In testing, I discoved no problems in my own code. 31 OCT 2002. DWF.
Fixed a problem with DIALOG_PICKFILE that sometimes allowed users to change
directories without selecting a file. 3 Nov 2002. DWF.
Fixed a problem with widget resizing with the help of Bob Portman that had plagued
me from the beginning. Thanks, Bob! 5 August 2003. DWF
Added TEXTSELECT method. 5 Aug 2003. DWF.
Had to add FORWARD_FUNCTION statement to get error handler compiled when using
DIRECTORY keyword. 24 Nov 2003. DWF.
Fixed a problem with too many events going to an event handler specified with
the EVENT_PRO or EVENT_FUNC keyword from the text widget. Now only Carriage
Return events are passed on to the user-specified event handler. 8 July 2004. DWF.
Replace all "\" characters with "/" characters in directory names. 8 Januay 2006. DWF.
Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
(See fsc_fileselect.pro)
NAME:
FSC_INPUTFIELD
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 bothered 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. The program is written entirely as an object.
A companion program, COYOTE_FIELD, has much the same functionality,
but is written as a traditional compound widget. The point of writing
the same program in two different ways is to give you the opportunity
to compare and contrast the two methods. I personally think there
is no substitute for the power of object programs. :-)
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:
objectRef = FSC_INPUTFIELD(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. Note that no
events are returned unless the EVENT_PRO or EVENT_FUNC keywords are also used.
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.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
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.
Focus_Events -- Set this keyword if you only want text events when the keyboard focus is
moved out of the text widget. Note that no events are returned unless the
EVENT_PRO or EVENT_FUNC keywords are also used.
Frame -- Set this keyword to put a frame around the compound widget.
IntegerValue -- Set this keyword for INTEGER values.
LabelAlign -- Set this keyword to align label text. [0-center (default), 1-left, 2-right].
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.
Name -- A scalar string name of the object. (default = '')
Positive -- Set this keyword if you want only positive numbers allowed.
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.
In addition, any keyword defined for WIDGET_TEXT, but not defined here (e.g., SENSITIVE), is
passed along without inspection to the text widget. Use of "extra" keywords is discouraged.
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 = { FSC_INPUTFIELD_EVENTS, $ ; 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.
ObjRef: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
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".
GETTING and SETTING VALUES:
Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
But since traditional compound widgets have the ability to get and
set the value of the compound widget, this capability is implemented
as special methods.
To get the value of the field, do this: value = objectRef->Get_Value()
To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue
The proper keyword should be used to set the data type of the value. If a keyword
is not used, the data type is determined from the value itself.
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
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 -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Positive -- Indicates if the Positive number flag is set (1) or not (0).
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.
Name -- A scalar string name of the object.
Resize -- This method allows you to resize the compound widget's text field.
The value parameter is an X screen size for the entire widget. The text
widget is sized by using the value obtained from this value minus the
X screen size of the label widget.
objectRef->Resize, screen_xsize_value
Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.
objectRef->Set_Value, 5
Keywords available are these to set the type of the data. If keywords
are not used, the data type is determined from the value.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
FloatValue -- Set this keyword for FLOAT values.
IntegerValue -- Set this keyword for INTEGER values.
LongValue -- Set this keyword for LONG values.
StringValue -- Set this keyword for STRING values. (The default.)
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
CR_Only -- Set this keyword if you only want Carriage Return events.
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.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
FloatValue -- Set this keyword for FLOAT values.
IntegerValue -- Set this keyword for INTEGER values.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Name -- A scalar string name of the object. (default = '')
Positive -- Set this keyword to indicate only positive numbers are allowed.
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
Sensitive -- Set to 1 to make the widget sensitive, and to 0 to make it insensitive.
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.
SetTabNext -- This method allows you to specify which field to go to when a TAB character
is typed in the text widget. See the Example program below for an example of how to
use this method.
OBJECT FUNCTIONS METHODS:
Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:
IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.
GetLabelSize -- Returns the X screen size of the label widget. No parameters.
GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.
GetTextSize -- Returns the X screen size of the text widget. No parameters.
PRIVATE OBJECT METHODS:
Although there is really no such thing as a "private" method in IDL's
object implementation, some methods are used internally and not meant to
be acessed publicly. Here are a few of those methods. I list them because
it may be these private methods are ones you wish to override in subclassed
objects.
MoveTab -- This method moves the focus to the widget identified in the "next" field,
which must be set with the SetTabNext method. No parameters. Called automatically
when a TAB character is typed in the text widget.
Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.
ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.
Validate -- This function method examines all text input and removes unwanted
characters, depending upon the requested data type for the field. It makes it
impossible, for example, to type alphanumeric characters in an INTEGER field.
EXAMPLE:
An example program is provided at the end of the FSC_INPUTFIELD code. To run it,
type these commands:
IDL> .Compile FSC_InputField
IDL> Example
NOTES:
IDL 6.2 introduced new TAB behavior, which broke the previous TAB behavior. New TAB behavior
is now supported, but FOCUS_EVENTS *must* be set on the widget for the new TAB events to
behave properly. See the EXAMPLE program for examples.
DEPENDENCIES:
Requires DBLTOSTR from the Coyote Library:
http://www.dfanning.com/programs/dbltostr.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 23 NOV 1999.
Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF.
Changed the calling sequence to that of a function rather than an object
creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF.
Added GetID and Resize methods. 7 Jan 00. DWF.
Added the Positive keyword and functionality. 12 Jan 00. DWF
Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF.
If a number field is blank, the Get_Value method will now return an undefined variable.
Be sure you check this value before you use it for something! 17 Jan 00. DWF.
Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext,
MoveTab, and GetTextID methods. 31 July 2000. DWF.
Added NAME field property, a scalar string name for the object 2 AUG 2000 BT
Added ObjRef field to the FSC_FIELD event structure and added field selection
for the TAB events added 31 July. 7 AUG 2000. DWF
Added GetTextSize and GetLabelSize methods for obtaining the X screen
size of the text and label widgets, respectively. 30 Jan 2001. DWF.
Added FOCUS_EVENTS keyword and fixed a problem with the event structure.
Also added better error handling. 5 January 2003. DWF.
Fixed a small problem in which input values were cast to strings inadvertently. 9 January 2004. DWF.
Fixed a small problem with error messages and using EVENT_FUNC. 14 January 2004. DWF.
Fixed a problem when setting ROW keyword. 23 February 2004. DWF.
IDL 6.2 introduced new TAB behavior, which broke the previous TAB behavior. New TAB behavior
is now supported, but FOCUS_EVENTS *must* be set for the new TAB events to behave properly.
10 August 2005. DWF.
Modified to covert double precision values to strings properly. 30 November 2005. DWF.
Added POSITIVE keyword to SETPROPERTY and GETPROPERTY methods. 25 February 2006. DWF.
Set the DYNAMIC_RESIZE keyword on the label widget. 25 February 2006. DWF.
Added SENSITIVE keyword to SetProperty documentation. 10 November 2006. DWF.
Fixed a small problem in which doubles were not being initialized correctly due
to an inadvertant extra line of code. 3 July 2007. DWF.
Fixed a small problem with input validation when the input is of BYTE type. 1 Oct 2008. DWF.
Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
Fixed a problem with validating a float or double value when it was written with
exponential notation. 2 April 2010. DWF.
(See fsc_inputfield.pro)
NAME:
FSC_NORMALIZE
PURPOSE:
This is a utility routine to calculate the scaling vector
required to position a graphics primitive of specified range
at a specific position in an arbitray coordinate system. The
scaling vector is given as a two-element array like this:
scalingVector = [translationFactor, scalingFactor]
The scaling vector should be used with the [XYZ]COORD_CONV
keywords of a graphics object or model. For example, if you
wanted to scale an X axis into the coordinate range of -0.5 to 0.5,
you might type something like this:
xAxis->GetProperty, Range=xRange
xScale = FSC_Normalize(xRange, Position=[-0.5, 0.5])
xAxis, XCoord_Conv=xScale
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:
Object Graphics
CALLING SEQUENCE:
xscaling = FSC_NORMALIZE(xrange, POSITION=position)
INPUTS:
XRANGE: A two-element vector specifying the data range.
KEYWORD PARAMETERS:
POSITION: A two-element vector specifying the location
in the coordinate system you are scaling into. The vector [0,1]
is used by default if POSITION is not specified.
COMMON BLOCKS:
None.
EXAMPLE:
See above.
MODIFICATION HISTORY:
Written by: David W. Fanning, OCT 1997.
Fixed a problem with illegal divide by zero. 21 April 2005. DWF.
Fixed a problem when range[0] is greater than range[1]. 11 July 2006. DWF.
Renamed to FSC_Normalize to avoid conflicts with 10,000 other programs named NORMALIZE. 17 October 2008. DWF.
(See fsc_normalize.pro)
NAME:
FSC_PLOTWINDOW
PURPOSE:
The purpose of this compound widget is to create a resizeable
"plot window" inside a larger "page window". I'm not sure it
has any value except as a utility routine for the PostScript
configuration object FSC_PSCONFIG__DEFINE, but it's a neat
program anyway. :-)
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 routine for FSC_PSCONFIG__DEFINE.
CALLING SEQUENCE:
plotwindowObject = CW_PlotWindow(parent)
REQUIRED INPUT PARAMETERS:
parent - The parent base widget of this compound widget.
RETURN VALUE:
plotwindowObject - The object reference of the compound widget.
KEYWORDS:
COLOR - If set, display the window in "color". This is the default on 24-bit devices.
DEBUG - Set this keyword to turn traceback error handling on in the error handling code.
EVENT_PRO - The event procedure for the widget. Required for events to be generated. Otherwise, all events are handled internally.
LANDSCAPE - If set, display the page in landscape mode. Otherwise the page is display in portrait mode.
PAGESIZE - The "pagesize" of the widget. Possible values are: "LETTER", "LEDGER", "LEGAL", "A4", and "DISPLAY".
UNITS - A string indicating INCHES or CENTIMETER units. DEVICE units represented by a null string, "".
UVALUE - A user value for the caller of this program.
WINDOWCOLOR - A three-element array specifying the background window color (RGB).
WINDOWSIZE - The size of the "window" on the page. A four-element array of normalized coordinates in the form [x0, y0, x1, y1].
EVENT STRUCTURE:
The event structure that is returned from this compound widget is defined like this,
where the sizes and offsets locate the target "window" on the page in normalized units:
event = {ID:0L, TOP:0L, HANDLER:0L, XSize:0.0, YSize:0.0, XOffset:0.0, YOffset:0.0}
MODIFICATIONS:
Written by David Fanning, 31 January 2000.
Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF.
Added a "DISPLAY" page size, so the program can be used to position
plots and other graphics in a display window. The "page area" will
have the same aspect ratio is the current graphics window. 17 March 2001. DWF.
Changed some of the tolerances for "closeness" from 0.1 to 0.025 to allow smaller
sizing for colorbars and other small objects. 6 July 2005. DWF.
(See fsc_plotwindow.pro)
NAME:
FSC_PSCONFIG__DEFINE
PURPOSE:
The purpose of this program is to implement an object that
can keep track of--and allow the user to change--the current
configuration of the PostScript device.
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.
DOCUMENTATION:
Complete documentation for the FSC_PSCONFIG object, including
keyword and method descriptions, and example programs using the object
can be found on the Coyote's Guide to IDL Programming web page:
http://www.dfanning.com/programs/docs/fsc_psconfig.html
Or, if you would prefer, you can download a self-contained PDF file:
http://www.dfanning.com/programs/docs/fsc_psconfig.pdf
KEYWORDS:
Any keyword accepted by the FSC_PSCONFIG object can be used with
this program. Here are a few of the most popular keywords.
Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
Color - Set this keyword to select Color PostScript output. Turned on by default.
DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
create and add your own to the source code) are the following:
"System (Portrait)" - The normal "default" system set-up. Also, "System".
"System (Landscape)" - The normal "default" landscape system set-up.
"Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
"Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
"Square (Portrait)" - A square plot, centered on the page.
"Square (Landscape)" - A square plot, centered on the landscape page.
"Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
"Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
"Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
"Color (Landscape)" - A "centered" landscape plot, with color turned on.
Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
Encapsulated - Set this keyword to select Encapsulated PostScript output. Turned off by default.
European - This keyword has been depreciated in favor of METRIC.
Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by Metric keyword by default.
Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
Language_Level - Set this keyword to select the Language Level interpreter. Default is 1.
Metric - Set this keyword to indicate metric mode (i.e., A4 page and centimeter units). Turned off by default.
PageType - Set this keyword to the "type" of page. Possible values are:
"Letter" - 8.5 by 11 inches. (Default, unless the Metric keyword is set.)
"Legal" - 8.5 by 14 inches.
"Ledger" - 11 by 17 inches.
"A4" - 21.0 by 29.7 centimeters. (Default, if the Metric keyword is set.)
XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.
In addition, the following keywords can be used:
CANCEL -- An output keyword that will be set to 1 if the user
chooses the Cancel button on the form. It will be 0 otherwise.
FONTINFO -- Set this keyword is you wish to have font information
appear on the form. The default is to not include font information.
FONTTYPE -- Set this keyword to a named variable that will indicate
the user's preference for font type. Values will be -1 (Hershey fonts),
0 (hardware fonts), and 1 (true-type fonts). This keyword will always
return -1 unless the FONTINFO keyword has also been set.
GROUP_LEADER -- Set this keyword to a widget identifier of the widget
you wish to be a group leader for this program.
EXAMPLE:
A simple sequence of using the object would look something like this:
psObject = Obj_New("FSC_PSCONFIG")
psObject->GUI
psKeywords = psObject->GetKeywords()
thisDevice = !D.Name
Set_Plot, 'PS'
Device, _Extra=psKeywords
cgImage, image
Device, /Close_File
Set_Plot, thisDevice
Obj_Destroy, psObject
Note that the object can also be called from the PS_CONFIG interface:
psKeywords = PSConfig()
OTHER PROGRAMS NEEDED:
The following programs are required to run this one:
fsc_droplist.pro
fsc_fileselect.pro
fsc_field.pro
fsc_plotwindow
MODIFICATIONS:
Written by David W. Fanning, 31 January 2000.
Added capability to call GUI methods when the current graphics device
doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF.
Changed the default value for the Color keyword to 1. 16 May 2000. DWF.
Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF.
Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF.
Added the ability to Get and Set the object's name via the SetProperty
and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF.
Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF.
Made a number of modifications at the request of Martin Schultz. 4 Dec 2000. DWF.
Fixed a bug when setting file and directory names with the SetProperty method. 18 Dec 2000. DWF.
Fixed a small problem in initializing the page size properly. 3 Jan 2001. DWF.
Corrected a problem that resulted from a change to FSC_DROPLIST. 6 Jan 2001. DWF.
Added the ability to restore the font type instead of always reverting to !P.Font. 7 Jan 2001. DWF.
Increased the length of the file/directory name fields. 7 Jan 2001. DWF.
Fixed another problem with Landscape mode interacting with A4 paper size. 7 Jan 2001. DWF.
Seems I only half fixed the previous problem. :-( 26 April 2001. DWF.
Forgot to update program to reflect change in FSC_FIELD. Fixed 26 April 2001. DWF.
Changed BOOKMAN keyword to BKMAN to avoid conflict with BOOKSTYLE keyword. 26 April 2001. DWF.
Modified the System Defaults to say "None" if none is used. Improved documentation. 10 September 2001. DWF.
Added the ability to specify a filename at the same time as a Default Setup. 10 September 2001. DWF.
Fixed a small problem in not setting new page sizes appropriately. 22 May 2002. DWF.
Fixed a problem that occurred when the Accept button was not named "Accept". 6 May 2003.DWF.
Whoops! I was a bit overly agressive on that last fix. :-( 17 July 2003. DWF.
Fixed a problem with setting page types when using the DEFAULTSETUP keyword. 31 July 2003. DWF.
Fixed a problem with turning encapsulation on in the GUI. Renamed ENCAPSULATE keyword ENCAPSULATED
to avoid obvious errors. 31 July 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Now honoring EUROPEAN keyword when setting system default setups in the INIT method. 12 Nov 2004. DWF.
Added CMYK output option 24 August 2007. Assumes LANGUAGE_LEVEL=2 printer. L. Anderson.
Fixed a problem with the filename on WINDOWS computers coming back with forward slashes instead of
backward slashes. 20 May 2008. DWF.
Modified the program to return as the default, ISOLATIN1=1. 18 July 2008. DWF.
Fixed a problem with filenames when a DEFAULTSETUP was used with it. 12 Nov 2008. DWF.
Changed default window size when LANDSCAPE keyword is set. 10 April 2009. DWF.
Changed the default window size for PORTRAIT mode to be a bit larger. 10 April 2009. DWF.
Updated for IDL 7.1 and 24-bit color PostScript support. 24 May 2009. DWF.
Added PAGETYPE field to returned structure to allow PostScript page type to be determined. 8 August 2009. DWF.
Fixed a problem with 24-bit color support that allowed only IDL 7 versions to work correctly. 20 Sept 2009. DWF.
Added a LANGUAGE_LEVEL keyword. 13 Dec 2010. DWF.
Added the FONTYPE value to the keyword return structure. 14 Dec 2010. DWF.
Modified the return structure to turn landscape mode off and set offsets to zero if in encapsulated mode. 19 Feb 2011. DWF.
(See fsc_psconfig__define.pro)
NAME:
FSC_PS_SETUP__DEFINE
PURPOSE:
The purpose of FSC_PS_SETUP__DEFINE is to define a structure that is
use with PS_START and PS_END, programs that make it easy to set-up
for and close a PostScript file. The programs work in close conjunction
with PSCONFIG, another program from the Coyote Library.
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, File Output, PostScript
CALLING SEQUENCE:
Used internally in PS_START and PS_END.
COMMON BLOCKS:
_$FSC_PS_START_ Contains the PS_STRUCT structure for communication between
PS_START and PS_END.
MODIFICATION HISTORY:
Separated from PS_START file, 7 April 2009, by David W. Fanning.
Added PAGETYPE field to structure. 8 August 2009. DWF.
(See fsc_ps_setup__define.pro)
:Description:
Provides a CONGRID like resizing of images, although it performs this service
correctly for both 2D and 3D images. Pixel locations do not change in the output
image, since the center of the pixel is used for interpolation purposes, rather than
the lower-left corner of the pixel. Unlike CONGRID, 3D images can use nearest neighbor
interpolation as well as bilinear interpolation.
:Categories:
Utilities
:Params:
image: in, required, type=any
The image variable to resize. Must be a 2D or 3D image. If a 3D image,
one of the image dimensions must be a 3.
cols: in, required, type=integer
The number of columns (i.e., XSIZE) in the output image.
rows: in, required, type=integer
The number of rows (i.e., YSIZE) in the output image.
:Keywords:
interpolate: in, optional, type=boolean, default=0
Is set, bilinear interpolation is used to resize the image. Otherwise,
nearest neighbor sampling is used instead.
minus_one: in, optional, type=boolean, default=0
Identical to CONGRID MINUS_ONE keyword.
:Examples:
Used in a similar fashion to the Congrid command, but for images::
IDL> bigEarth = FSC_Resize_Image(cgDemoData(7), 720, 720)
IDL> bigRose = FSC_Resize_Image(cgDemoData(16), 681, 447)
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 20 November 2010. DWF.
I have been convinced (conversations with Wayne Landsman) that if the
CENTER keyword is set, the MINUS_ONE keyword is not needed, since
it was created to solve the same problem. So, I have changed the
default setting of MINUS_ONE to 0. 11 Jan 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See fsc_resize_image.pro)
:Description:
Allows the user to interactively zoom into an image. Program controls are available
by right-clicking in the full-sized image window. Zoom factors from 2x to 16x are
available. Use the left mouse button to draw a box on the full-sized image to locate
the region of the image to zoom.
:Categories:
Graphics
:Params:
image: in, required, type=any
A 2D or true-color image of any normal data type. If not a BYTE array,
cgImage keywords for proper image scaling must be used to provide image
scaling parameters.
:Keywords:
bottom: in, optional, type=byte, default=0
As defined for the cgImage command.
boxcolor: in, optional, type=string, default='red8'
The name of a color to use for the rubberband selection box.
Color names are those used with cgColor.
group_leader: in, optional, type=long
The Group Leader widget identifier for this widget program.
maxvalue: in, optional, type=byte, default=0
As defined for the cgImage command.
minvalue: in, optional, type=byte, default=0
As defined for the cgImage command.
ncolors: in, optional, type=byte, default=0
As defined for the cgImage command.
nointerpolate: in, optional, type=byte, default=0
As defined for the cgImage command.
scale: in, optional, type=byte, default=0
As defined for the cgImage command.
top: in, optional, type=byte, default=0
As defined for the cgImage command.
:Examples:
Code examples::
IDL> image = cgDemoData(7)
IDL> FSC_ZImage, image ; 2D image
IDL> image = cgDemoData(16)
IDL> FSC_ZImage, image ; True-Color image
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 23 November 2010. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See fsc_zimage.pro)
:Description:
Allows the user to interactively zoom into a line plot. Use the left mouse button to
draw a arrow on the plot. Use the right mouse button to zoom all the way back out.
:Categories:
Graphics
x: in, required, type=any
If X is provided without Y, a vector representing the dependent values to be
plotted If both X and Y are provided, X is the independent parameter and
Y is the dependent parameter to be plotted.
y: in, optional, type=any
A vector representing the dependent values to be plotted.
:Keywords:
arrowcolor: in, optional, type=string/integer, default='red8'
If this keyword is a string, the name of the zoom arrow color. By default, 'red8'.
Otherwise, the keyword is assumed to be a color index into the current color table.
axiscolor: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the axis color. By default, 'black'.
Otherwise, the keyword is assumed to be a color index into the current color table.
axescolor: in, optional, type=string/integer
Provisions for bad spellers.
background: in, optional, type=string/integer, default='white'
If this keyword is a string, the name of the background color. By default, 'white'.
Otherwise, the keyword is assumed to be a color index into the current color table.
color: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the data color. By default, 'black'.
Color names are those used with cgColor. Otherwise, the keyword is assumed
to be a color index into the current color table.
group_leader: in, optional, type=long
The Group Leader widget identifier for this widget program.
symcolor: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the symbol color. By default, 'black'.
Color names are those used with cgColor. Otherwise, the keyword is assumed
to be a color index into the current color table.
xlog: in, optional, type=integer, default=0
Set this keyword if you want the X axis to be a log axis.
xsize: in, optional, type=integer, default=640
The X size of the initial plot window.
ylog: in, optional, type=integer, default=0
Set this keyword if you want the Y axis to be a log axis.
ysize: in, optional, type=integer, default=512
The Y size of the initial plot window.
_extra: in, optional
Any keywords appropriate for the cgPlot command.
:Examples:
Code examples::
IDL> Zplot, cgDemoData(1)
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 23 November 2010. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See fsc_zplot.pro)
NAME:
GAUSSSCL
PURPOSE:
This is a utility routine to perform a gaussian gray-level pixel
transformation stretch on a image.
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:
scaledImage = GAUSSSCL(image)
ARGUMENTS:
image: The image to be scaled. Written for 2D images, but arrays
of any size are treated alike.
KEYWORDS:
SIGMA: The sigma value or width of the Gaussian
function. Set to 1 by default.
MAX: Any value in the input image greater than this value is
set to this value before scaling.
MIN: Any value in the input image less than this value is
set to this value before scaling.
NEGATIVE: If set, the "negative" of the result is returned.
OMAX: The output image is scaled between OMIN and OMAX. The
default value is 255.
OMIN: The output image is scaled between OMIN and OMAX. The
default value is 0.
RETURN VALUE:
scaledImage: The output, scaled into the range OMIN to OMAX. A byte array.
COMMON BLOCKS:
None.
EXAMPLES:
LoadCT, 0 ; Gray-scale colors.
image = cgDemoData(11) ; Load image.
TV, GaussScl(image)
RESTRICTIONS:
Requires SCALE_VECTOR from the Coyote Library:
http://www.dfanning.com/programs/scale_vector.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 5 September 2007.
(See gaussscl.pro)
:Description:
Provides a device-independent way to get the color decomposition state of the
current graphics device.
:Categories:
Graphics, Utilities
:Params:
none
:Keywords:
Detph: out, optional, type=integer
The depth of the color display. Typically 8 for indexed color devices
and 24 for true-color devices.
:Examples:
IDL> currentState = GetDecomposedState()
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 12 December 2010 as a better named wrapper for DECOMPOSEDCOLOR program. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See getdecomposedstate.pro)
NAME:
GETIMAGE
PURPOSE:
The purpose of this function is to allow the user to open either
unformmated or XDR binary image files of up to eight dimensions.
CATEGORY:
Widgets, File I/O.
CALLING SEQUENCE:
image = GETIMAGE(filename)
OPTIONAL INPUTS:
filename: The name of the file to open for reading.
OPTIONAL KEYWORD PARAMETERS:
CANCEL: An output variable that can be set to a named variable.
The value of the return variable will be 1 if the user clicked
the "Cancel" button or if there was a problem reading the file.
DATATYPE: The "type" of data you wish to read out of the file.
The data type corresponds to the Size(image, /TYPE) value. Here
are the types supported:
BYTE 1 (default)
INTEGER 2
LONG INTEGER 3
FLOAT 4
DOUBLE 5
UNSIGNED INTEGER 12
UNSIGNED LONG INTEGER 13
64-bit LONG 14
64-bit UNSIGNED LONG 15
DIMENSIONS: A vector of image dimensions. The default value is [256, 256].
DIRECTORY: The name of the directory the file is located in. By
default the program looks in the "coyote" directory under the
main IDL directory, if one exists. Otherwise, it defaults to the
current directory.
ENDIAN: Set this keyword to an integer that indicates the byte
ordering of the data file. If you don't know what byte order means,
or you don't know anything about the byte order of the data, or
if you are sure the data was created on the same type of machine
you are now running IDL on, then just accept the default of 0 or
"native" ordering. If you are wrong, you will soon know it and you
can set the keyword to another value on your next try. :-)
If you know the machine was created on a big endian machine (such
as a Sun or HP workstation), set this value to 1 (Big Endian). If e
you are sur the image data was create on a little endian machine (such
as a Windows PC or laptop running LINUX), set the value to 2 (Little Endian).
HEADER: The size of any header information in the file in BYTES.
Default is 0.
HEADDATA: An optional output keyword that will contain the header
information read from the file.
PARENT: The group leader for this widget program. The PARENT is
required if GETIMAGE is called from another widget program in order
to make this program a MODAL widget program.
XDR: Set this keyword if the binary file is of XDR type. The default
type is "Unformatted".
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:
A "CANCEL" operation is indicated by a 0 return value.
Any error in reading the file results in a 0 return value.
RESTRICTIONS:
Requires the following Coyote Library files:
CENTER_TLB
ERROR_MESSAGE
FSC_FIELD
EXAMPLE:
To load the image "galaxy.dat" in the $IDL/examples/data
directory, type:
image = GETIMAGE('galaxy.dat', DIRECTORY=!DIR + '/examples/data', $
DIMENSIONS=[256,256], Cancel=cancelled, Parent=event.top)
IF NOT cancelled THEN TV, image
MODIFICATION HISTORY:
Written by: David Fanning, 3 February 96.
Fixed bug that prevented reading INTEGER data. 19 Dec 96.
Modifed program for IDL 5 MODAL operation. 19 Oct 97.
Added CANCEL keyword. 27 Oct 97. DWF.
Fixed CANCLE keyword spelling. Sigh... 29 JUN 98. DWF.
Added COYOTE_FIELD, improved appearance. 19 NOV 99. DWF.
Updated with latest version of COYOTE_FIELD. 18 FEB 2000. DWF.
Added CATCH keyword so the program will break when I want
it to. :-) 18 MAR 2000. DWF.
Added GROUP_LEADER keyword, which is synonymous with PARENT. 31 MAR 2000. DWF.
Updated obsolete PICKFILE call to DIALOG_PICKFILE. 17 JAN 2001. DWF.
Extensive update for IDL Programming Techniques, 3rd Edition. 1 November 2006. DWF.
XSIZE, YSIZE, CATCH, and FRAMES keyword made obsolete.
HEADDATA, ENDIAN, DATATYPE, DIMENSIONS keywords added.
Now dependent on FSC_FIELD, ERROR_MESSAGE, and CENTER_TLB from Coyote Library.
Added ability to parse fully qualified file names passed from Dialog_Pickfile. 30 Oct 2010. DWF.
IF a file name is not passed into the program, it asks the user to select one now. 10 Jan 2011. DWF.
Problem with SWAP_ENDIAN keywords fixed. 7 March 2011. DWF.
(See getimage.pro)
:Description:
Provides a way to get the screen size of the primary monitor, especially when
there are several being used.
:Categories:
Graphics
:Params:
none
:Keywords:
exclude_taskbar: in, optional, boolean, default=0
Set this keyword to exclude the taskbar from the monitor size.
This keyword is ignored on all but Windows machines.
:Author:
Dick Jackson, www.dick-jackson.com
:History:
Change History::
Written, 8 March 2011. DJ
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See getprimaryscreensize.pro)
NAME:
GET_OBJECT_ID
PURPOSE:
The purpose of this function is to be able to obtain a unique
object identifier string for a heap variable (object or pointer).
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:
objectID = Get_Object_ID(theObject)
INPUTS:
theObject: The object or pointer for which an identifier is requested. If
this is a null object, the function returns the string
"NullObject". If it is a null pointer, "NullPointer".
OUTPUTS:
objectID: The unique object or pointer identifier.
KEYWORDS:
NUMBER: If this keyword is set, the function returns the unique
number identifier associated with a valid pointer or object.
The number is returned as a STRING variable. The string
"-999" is returned if the pointer or object is invalid and
this keyword is set.
EXAMPLE:
Create a trackball object and obtain its unique object ID.
IDL> theObject = Obj_New('TRACKBALL', [100,100], 50)
IDL> objectID = Get_Object_ID(theObject, NUMBER=number)
IDL> Print, objectID
ObjHeapVar71(TRACKBALL)
IDL> Print, number
71
MODIFICATION HISTORY:
Written by: David W. Fanning, 4 September 2003.
Added NUMBER keyword. DWF, 22 September 2008.
(See get_object_id.pro)
NAME:
GMASCL
PURPOSE:
This is a utility routine to perform basic gray-level pixel
transformations of images. I think of it as BYTSCL on steroids.
It is similar to IMADJUST in _Digital Image Processing with MATLAB_
by Gonzales, Wood, and Eddins. It performs a log scaling of the
image array.
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:
scaledImage = GMASCL(image)
ARGUMENTS:
image: The image to be scaled. Written for 2D images, but arrays
of any size are treated alike.
KEYWORDS:
GAMMA: The exponent in a power-law transformation (image^gamma). A gamma
value of 1 results in a linear distribution of values between
OMIN and OMAX. Gamma values less than 1 map darker image values
into a wider range of output values, and Gamma values
greater than 1 maps lighter image values into a wider
range of output values. The gamma value is constrained to
be greater than 1.0e-6.
MAX: Any value in the input image greater than this value is
set to this value before scaling.
MIN: Any value in the input image less than this value is
set to this value before scaling.
NEGATIVE: If set, the "negative" of the result is returned.
OMAX: The output image is scaled between OMIN and OMAX. The
default value is 255.
OMIN: The output image is scaled between OMIN and OMAX. The
default value is 0.
RETURN VALUE:
scaledImage: The output, scaled into the range OMIN to OMAX. A byte array.
COMMON BLOCKS:
None.
EXAMPLES:
LoadCT, 0 ; Gray-scale colors.
image = cgDemoData(11) ; Load image.
TV, GmaScl(image, Min=30, Max=100) ; Similar to BytScl.
TV, GmaScl(image, /Negative) ; Produce negative image.
power = Shift(ALog(Abs(FFT(image,-1))), 124, 124) ; Create power spectrum.
TV, GmaScl(power, Gamma=2.5) ; View power specturm with gamma correction.
TV, GmaScl(power, Gamma=2.5, /Negative) ; Reverse power spectrum.
RESTRICTIONS:
Requires SCALE_VECTOR from the Coyote Library:
http://www.dfanning.com/programs/scale_vector.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 17 February 2006.
Fixed a problem with output scaling. 1 July 2009. DWF (with input from Bo Milvang-Jensen).
(See gmascl.pro)
NAME:
GREEK
PURPOSE:
This function provides a device-independent way to ask for a Greek letter as
a string that can be included, for example, in a plot title. It uses the Greek
simplex font (!4) when used with Hershey fonts, and the Symbol font (!9) when
used with PostScript or True-Type fonts. Selects the type of Greek character to
return based on value of !P.FONT. Updated now to return the UNICODE values for
Greek characters for those fonts that support them (Macintosh?).
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, Utilities
CALLING SEQUENCE:
greekString = Greek(greekLetter)
RETURN VALUE:
greekString A string that represents the Greek letter.
ARGUMENTS:
greekLetter: The name of the Greek letter desired. A string. Default: 'alpha'.
Valid string names are the 24 characters of the Greek alphabet.
alpha nu
beta xi
gamma omicron
delta pi
epsilon rho
zeta sigma
eta tau
theta upsilon
iota phi
kappa chi
lambda psi
mu omega
Note that if the first letter of the name is capitalized, this is
the equivalent of setting the CAPITAL keyword.
KEYWORDRS:
CAPTIAL: If this keyword is set, the captial Greek letter is returned rather
than the lowercase Greek letter. An alternative way of capitalizing
the letter is to make the first letter of the name an uppercase letter.
EXAMPLE: If this keyword is set, the names of the Greek characters and their
symbols are written out in the current graphics window.
UNICODE: If this keyword is set, the function returns the Unicode for the Greek
letter.
EXAMPLE:
Lowercase PSI:
IDL> Plot, findgen(11), XTitle='This title contains ' + $
Greek('psi') + ' as a Greek letter'
Uppercase PSI:
IDL> Plot, findgen(11), XTitle='This title contains ' + $
Greek('Psi') + ' as a Greek letter'
NOTES:
See the following article for additional information:
/http://www.dfanning.com/ps_tips/greeksym.pro
RESTRICTIONS:
For this program to work correctly on your graphics display, you should be using
Hershey fonts (!P.Font=-1). It will work correctly in PostScript with either
hardware fonts (!P.Font=0) or True-Type fonts (!P.Font=1).
MODIFICATION HISTORY:
Written by: David W. Fanning, 9 January 2010.
An alternative way to get an uppercase letter is to make the first letter of
the Greek name uppercase. (Maarten Sneep's suggestion!) 11 Jan 2010. DWF
Had the wrong value for the PostScript version of Phi. 26 January 2010. DWF
Added UNICODE keyword and values for Greek characters. 11 June 2010. DWF.
Changed the branching from !D.NAME EQ 'PS' to !P.FONT NE -1. (This is actually
what the documentation says, and what I intended.) 13 Dec 2010. DWF.
I don't think the last change did quite want I wanted. More tweaking to make
this more responsive to being in a PostScript file. 31 July 2011. DWF.
(See greek.pro)
NAME:
GRIDPOSITIONS
PURPOSE:
Sets up a column-row grid in the current graphics window in a fashion
similar to !P.MULTI, except that the grid can be confined to a portion
of the window, leaving room for color bars and other annotations.
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:
positions = GridPositions(columns, rows)
INPUT_PARAMETERS:
columns: The number of columns in the grid.
rows The number of rows in the grid.
OUTPUT_PARAMETERS:
positions: A 4xN array, where N=(columns*rows), giving the positions of the grid in
normalized coordinates.
KEYWORDS:
INCHES: If calculating the position in the PostScript device, indicates whether
the window size is given in centimeters (the default) or in inches. Set
this keyword to 1 to indicate inches. Ignored for other devices.
LANDSCAPE: If calculating the position in the PostScript device, set this keyword to
indicate a landscript page. Ignored for other devices.
ORDER: If this keyword is set to 0, the positions are calculated in row order. If
set to 1, the positions are calculated in column order.
XEXTENT: A one or two element array, with values from 0 to 1, giving the extent of
the grid in the X direction. For example XEXTENT=[.2, .8] will position
the X portion of the grid from 0.2 to 0.8 (normalized coordinates) in the
window. If a scalar value, the XEXTENT will be assumed to be [0, value].
XMARGIN: A one or two element array, giving the plot margin outside the grid position.
That is to say, the normal grid position will be reduced by this margin. This
corresponds to a plot margin, and as such is expressed in character units. See
the on-line help for graphics keywords for additional information. If a scalar,
the margin is taken from both the left and right sides of the position. In other
words, XMARGIN=[value, value]. By default, [0.05,0.05], which will cause grid
positions to have just a bit of space between them.
XSIZE: The X size of the window the positions are being calculated for. By
default, !D.X_SIZE.
XEXTENT: A one or two element array, with values from 0 to 1, giving the extent of
the grid in the X direction. For example XEXTENT=[.2, .8] will position
the X portion of the grid from 0.2 to 0.8 (normalized coordinates) in the
window. If a scalar value, the XEXTENT will be assumed to be [0, value].
XMARGIN: A one or two element array, giving the plot margin outside the grid position.
That is to say, the normal grid position will be reduced by this margin. This
corresponds to a plot margin, and as such is expressed in character units. See
the on-line help for graphics keywords for additional information. If a scalar,
the margin is taken from both the left and right sides of the position. In other
words, XMARGIN=[value, value]. By default, [0,0], which will cause grid
positions to abut one another.
XSIZE: The X size of the window the positions are being calculated for. By
default, !D.X_SIZE.
YEXTENT: A one or two element array, with values from 0 to 1, giving the extent of
the grid in the X direction. For example YEXTENT=[.2, .8] will position
the Y portion of the grid from 0.2 to 0.8 (normalized coordinates) in the
window. If a scalar value, the YEXTENT will be assumed to be [0, value].
YMARGIN: A one or two element array, giving the plot margin outside the grid position.
That is to say, the normal grid position will be reduced by this margin. This
corresponds to a plot margin, and as such is expressed in character units. See
the on-line help for graphics keywords for additional information. If a scalar,
the margin is taken from both the bottom and top sides of the position. In other
words, YMARGIN=[value, value]. By default, [0,0], which will cause grid
positions to abut one another.
YSIZE: The Y size of the window the positions are being calculated for. By
default, !D.Y_SIZE.
EXAMPLE:
To display four images, scaled differently, in the center of the display, with room
for a color bar:
positions = GridPositions(2, 2, YEXTENT=[0.15,0.85], XEXTENT=[0.2,0.8])
image = cgDemoData(11)
cgErase, 'rose'
cgLoadCt, 25, /Brewer
cgImage, image, POSITION=positions[*,0]
cgImage, BytScl(Sobel(image)), POSITION=positions[*,1], /NoErase
cgImage, BytScl(Hist_Equal(image)), POSITION=positions[*,2], /NoErase
cgImage, BytScl(Median(image,7)), POSITION=positions[*,3], /NoErase
MODIFICATION HISTORY:
Written by David W. Fanning, 17 March 2009.
Fixed problems in calculating default window sizes in the Z and PS devices. 25 June 2011. DWF.
Fixed the example code to work with Coyote Graphics routines. 27 June 2011.
(See gridpositions.pro)
:Description:
Searches for the ImageMagick "convert" command to see if ImageMagick is available
on the system.
:Categories:
Utilities
:Params:
none.
:Keywords:
version: out, optional, type=string
Returns the version number of the ImageMagick convert command, if found.
:Examples:
Used to determine if the ImageMagick convert command is available::
IDL> available = SearchForImageMagick(Version=version)
IDL> IF available THEN Print, version
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 17 January 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See hasimagemagick.pro)
NAME:
HCOLORBAR
FILENAME:
hcolorbar__define.pro
;
PURPOSE:
The purpose of this program is to create a horizontal
colorbar object to be used in conjunction with other
IDL 5 graphics objects.
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:
Object Graphics.
CALLING SEQUENCE:
thisColorBar = Obj_New('HColorBar')
REQUIRED INPUTS:
None.
INIT METHOD KEYWORD PARAMETERS:
COLOR: A three-element array representing the RGB values of a color
for the colorbar axes and annotation. The default value is
white: [255,255,255].
FONTSIZE: A floating value that is the point size of the font
used for the axis and title annotations. Set to 8 point by default.
NAME: The name associated with this object.
NCOLORS: The number of colors associated with the colorbar. The
default is 256.
MAJOR: The number of major tick divisions on the colorbar axes.
The default is 5.
MINOR: The number of minor tick marks on the colorbar axes.
The default is 4.
PALETTE: A palette object for the colorbar. The default palette
is a gray-scale palette object.
POSITION: A four-element array specifying the position of the
colorbar in normalized coordinate space. The default position
is [0.10, 0.90, 0.90, 0.95].
RANGE: The range associated with the colorbar axis. The default
is [0, NCOLORS].
TITLE: A string containing a title for the colorbar axis
annotation. The default is a null string.
OTHER METHODS:
Clamp (Procedure): Given a two-element array in the data range of
the colorbar, the colorbar image is clamped to this range. In
other words, the range of colors is clamped to the specified
range. Values above or below the range in the colorbar are set to
the minimum and maximum range values, respectively.
GetProperty (Procedure): Returns colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
MAJOR
MINOR
NAME
PALETTE
POSITION
RANGE
TEXT
TITLE
TRANSFORM
SetProperty (Procedure): Sets colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
MAJOR
MINOR
NAME
PALETTE
POSITION
RANGE
TEXT
TITLE
TRANSFORM
SIDE EFFECTS:
A HColorBar structure is created. The colorbar INHERITS IDLgrMODEL.
Thus, all IDLgrMODEL methods and keywords can also be used. It is
the model that is selected in a selection event, since the SELECT_TARGET
keyword is set for the model.
RESTRICTIONS:
Requires FSC_NORMALIZE from Coyote Library:
http://www.dfanning.com/programs/fsc_normalize.pro
EXAMPLE:
To create a colorbar object and add it to a plot view object, type:
thisColorBarObject = Obj_New('HColorBar')
plotView->Add, thisColorBarObject
plotWindow->Draw, plotView
MODIFICATION HISTORY:
Written by David Fanning, from VColorBar code, 20 Sept 98. DWF.
Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF.
Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF.
Fixed the same bug when getting the text using the TEXT keyword. :-( 16 Aug 2000. DWF.
Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF.
Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF.
Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF.
Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF.
Removed TEXT keyword (which was never used) and improved documentation. 15 AUG 2001. DWF.
Added ENABLE_FORMATTING keyword to title objects. 22 October 2001. DWF.
Added a CLAMP method. 18 November 2001. DWF.
Forgot to pass extra keywords along to the text widget. As a result, you couldn't
format tick labels, etc. Fixed this. Any keywords appropriate for IDLgrTick objects
are now available. 26 June 2002. DWF.
Fixed a problem with POSITION keyword in SetProperty method. 23 May 2003. DWF.
Fixed a problem with setting RANGE keyword in SetProperty method. 6 Sept 2003. DWF.
Removed NORMALIZE from source code. 19 November 2005. DWF.
Font sizes have changed. Now using a 12 point font. 6 May 2011. DWF.
(See hcolorbar__define.pro)
NAME:
HELP_VAR
PURPOSE:
The purpose of this program is to display HELP on just
the variables at the level in which HELP_VAR is called.
It is similar to the HELP command, except that compiled
functions and procedures are not displayed.
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:
HELP_VAR
REQUIRED INPUTS:
None.
SIDE EFFECTS:
Memory is allocated for each variable, in turn, then deleted.
Uses undefined and unsupported ROUTINE_NAMES function. May not
work in all versions of IDL, including future versions.
EXAMPLE:
PRO HELP_VAR_TEST
a = 4.0
b = Lindgen(11)
HELP_VAR
END
IDL> help_var
A FLOAT = 4.00000
B LONG = Array[11]
MODIFICATION HISTORY:
Written by David W. Fanning, 8 August 2003.
(See help_var.pro)
NAME:
HistoMatch
PURPOSE:
This is a function for Histogram Matching, in which an image
is manipulated in such a way that it's final histogram approximates
the histogram of an input image or histogram. Histogram matching
allows the user to specify the shape of the histogram of the final
product.
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:
Image Processing
CALLING SEQUENCE:
output_image = HistoMatch(image, histogram_to_match)
INPUTS:
image - The input image to be manipulated. Assumed to be a 2D byte array.
histogram_to_match - Can be either a 1D long vector of 256 elements specifying
the histogram to match, or a 2D byte array from which the histogram to
match is calculated.
OUTPUTS:
output_image - The manipulated image adjusted to the histogram specifications.
INPUT KEYWORDS:
None.
OUTPUT KEYWORDS:
None.
DEPENDENCIES:
None.
METHOD:
Based on the Histogram Matching method on pages 94-102 of Digital
Image Processing, 2nd Edition, Rafael C. Gonzalez and Richard E. Woods,
ISBN 0-20-118075-8.
EXAMPLE:
There is an example program at the end of this file. It will require cgImage
from the Coyote Library to run. You can also find an explanation of this program
at http://www.dfanning.com/ip_tips/histomatch.html.
MODIFICATION HISTORY:
Written by David W. Fanning, January 2003.
(See histomatch.pro)
NAME:
IMAGESELECT
PURPOSE:
The purpose of this program is to allow the user to select a formatted
image file for reading. The image data is returned as the result of the
function. The program allows the user to see a thumbnail version of the
image, along with information about the image, before selection. The
program uses the file extention to determine what kind of image is to
be read. The following image types are supported:
TYPE FILE EXTENSION
BMP *.bmp
DICOM *.dcm
FITS *.fits, *.fts (requires NASA ASTRO library on IDL Path)
GIF *.gif (IDL 6.2 and higher)
JPEG *.jpg, *.jpeg, *.jpe
JPEG2000 *.jpf, *.jpx, *.jp2, *.j2c, *.j2k
PICT *.pict
PNG *.png
TIFF *.tif, *tiff
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:
image = ImageSelect()
INPUT PARAMETERS:
None. All input is via keywords.
INPUT KEYWORDS:
BMP -- Set this keyword to select BMP files.
DEMO -- If this keyword is set, the program changes directory to !DIR/examples/data.
DICOM -- Set this keyword to select DICOM files.
DIRECTORY -- The initial input directory name. The current directory by default.
EXCLUDE -- A list of filenames that should excluded from the file selection list.
FILENAME -- The initial filename. If the initial directory has image files of the
correct type, the default is to display the first of these files. Otherwise, blank.
FILTER -- A string, representing the file filter. For example, '*.jpg'.
FITS -- Set the keyword to select FITS files. (Must have NASA Astro Library on path.)
FLIPIMAGE -- Set this keyword if you wish to flip the image from its current orientation. Setting
this keyword reverses the Y dimension of the image.
GIF -- Set this keyword to select GIF files. (IDL versions before 5.4 and after 6.0, only.)
GROUP_LEADER -- Set this keyword to a widget identifier group leader. This keyword MUST be
set when calling this program from another widget program to guarantee modal operation.
J2000 -- Set this keyword to select JPEG2000 files. (May also be set as J2K.) (IDL 6.1 or above.)
J2K -- Set this keyword to select JPEG2000 files. (May also be set as J2000.) (IDL 6.1 or above.)
JPEG -- Set this keyword to select JPEG files.
LISTXSIZE -- Set this keyword to the XSIZE of the list widget. Default is 30 or MAX(StrLen(filenames)), whichever is larger.
OFFSETS -- A two-element array containing the X and Y offsets of the program, from the upper left
corner of the display. On dismissal of the program, if this is a named variable (passed into
the program by reference), then it will contain the last offsets of the program. This is
useful if you want to call ImageSelect again and have it positioned in exactly the same
location it was before.
ONLY2D -- Set this keyword if you only want the user to be able to select 2D images. Note
that the user will be able to browse all images, but the Accept button will only
be sensitive for 2D images.
ONLY3D -- Set this keyword if you only want the user to be able to select 3D or true-color images.
Note that the user will be able to browse all images, but the Accept button will only
be sensitive for 3D or true-color images.
PICT -- Set this keyword to select PICT files.
PGM -- Set this keyword to select PGM files.
PPM -- Set this keyword to select PPM files.
PNG -- Set this keyword to select PNG files.
PREVIEWSIZE -- Set this keyword to the maximum size (in pixels) of the preview window. Default is 150.
SILENT -- Set this keyword to turn off Group_Leader educational message. Use only if you
are sure you know what you are doing. :-)
TIFF -- Set this keyword to select TIFF files. (This is the default filter selection.)
TITLE -- Set this keyword to the text to display as the title of the main image selection window.
NOTE: Any extra keywords passed into the program will collected and passed along to the READ_XXX routines
that actually do the image file reading. Using this keyword inheritance mechanism makes it impossible
to trap misspelled or misused keywords. Please take care when using ANY keyword for this routine!
OUTPUT KEYWORDS:
CANCEL -- This keyword is set to 1 if the user exits the program in any way except hitting the ACCEPT button.
The ACCEPT button will set this keyword to 0.
FHEADER -- Set this keyword to a named variable that will return the FITS header information for a FITS file.
FILEINFO -- This keyword returns information about the selected file. Obtained from the QUERY_**** functions.
GEOTIFF -- If the file is a GeoTIFF file, this keyword will return the GeoTIFF structure containing
the files GeoTags.
OUTDIRECTORY -- The directory where the selected file is found.
OUTFILENAME -- The short filename of the selected file.
PALETTE -- The current color table palette returned as a 256-by-3 byte array.
COMMON BLOCKS:
None.
RESTRICTIONS:
Requires other programs from the Coyote Library.
Note: Keyword inheritance to collect undefined keywords that may be passed into the
program for use in READ_XXX routines, make it impossible to trap keyword useage errors.
Please take care when using keywords.
EXAMPLE:
To read JPEG files from the directory:
IDL> image = ImageSelect(/JPEG)
MODIFICATION HISTORY:
Written by: David W. Fanning, 18 Jan 2001.
Added modification to read both 8-bit and 24-bit BMP files. 27 Jan 2001. DWF.
Fixed a problem with calculating the new size of the draw widget. 5 April 2002. DWF.
Fixed a problem with List Widgets not sizing correctly on UNIX machines. 10 Aug 2002. DWF.
Fixed a problem with the initial file not being selected correctly when you changed
the file type. 10 Aug 2002. DWF.
Added a FLIPIMAGE keyword 10 Aug 2002. DWF.
When user chooses to Flip Image, I now reverse the Y dimension of the image,
rather than set the !Order system variable. 10 Aug 2002. DWF.
Added OUTDIRECTORY and OUTFILENAME keywords. 18 Aug 2002. DWF.
Fairly extensive changes in the way this program works and selects images.
A new version of FSC_FileSelect is also required. Because of interactions
with the operating system with image filters, the program has probably
become more Windows-centric. The default is now to display all image
files the program is capable of reading. 31 October 2002. DWF.
Added ONLY2D keyword to allow the acceptance of 2D images only. 3 Nov 2002. DWF.
Added ability to center itself on the display. 8 Nov 2002. DWF.
Fixed a problem caused by reading old images with short color table vectors. 26 Nov 2002. DWF.
Fixed a problem with specifying a fully-qualified filename. 26 Nov 2002. DWF.
Now highlights the selected file in the directory. 26 Nov 2002. DWF.
Improved error handling. 9 Dec 2002. DWF.
Added PALETTE keyword and improved color operation on 8-bit displays. If the image file
contains a color palette, that palette is now loaded when the image is read from the file.
The current color palette can be obtained with the PALETTE keyword. 4 April 2003. DWF.
Added ONLY3D keyword. 19 April 2003. DWF.
Added ability to read PPM and PGM files. 24 November 2003. DWF.
Added TITLE keyword. 1 December 2003. DWF.
Added EXAMPLES keyword. 22 December 2005. DWF.
Added GIF and JPEG2000 file types. Rearranged and cleaned up code. 3 January 2006. DWF.
Added LISTXSIZE keyword. 3 January 2006. DWF.
Added file type checkmark buttons. Program now compatible with IDL 5.6 and higher. 3 January 2006. DWF.
Improved error handling with invalid file types. 5 January 2006. DWF.
Added OFFSETS and EXCLUDE keywords. 3 March 2006 DWF.
Modified the program to check for FITS unsigned integer data. 3 March 2006. DWF.
Added ability to double-click image name in list to Accept. 10 March 2006. DWF.
Added FHEADER keyword to return FITS header information. 3 April 2006. DWF.
Fixed a problem in which the file type was not set if the user cancelled. 10 July 2006. DWF.
Added a "fit" file extension for FITS images. 1 April 2008. DWF.
Added a FILTER keyword. 1 April 2008. DWF.
Updated for reading transparent images. 13 May 2009. DWF.
Provided check for PNG images with more than 8 bits per channel. 5 August 2009. DWF.
Fixed a problem in which the starting directory was changed on exit. 20 Nov 2010. DWF.
Change EXAMPLES to more easily remembered DEMO keyword. 29 Nov 2010. DWF.
Removed NOINTERPOLATION keywords in going from TVIMAGE to cgImage. 22 Feb 2011. DWF.
(See imageselect.pro)
NAME:
IMAGE_BLEND
PURPOSE:
The purpose of this program is to demonstrate how to
use the alpha channel to blend one image into another.
The specific purpose is to see a color image on top of
a gray-scale image, with the gray-scale image showing
through behind the color image.
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:
Image_Blend
REQUIRED INPUTS:
None. The images "worldelv.dat" and "ctscan.dat" from the
examples/data directory are used.
OPTIONAL INPUTS:
backgroundImage:: A 2D image variable that will be used for the background image.
foregroundImage: A 2D image variable that will be used for the foreground image.
OPTIONAL KEYWORD PARAMETERS:
COLORTABLE: The number of a color table to use for the foreground image.
Color table 3 (red temperature) is used as a default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None. The program XCOLORS is required from the Coyote library.
EXAMPLE:
Image_Blend, Colortable=5
MODIFICATION HISTORY:
Written by David Fanning, 30 March 99.
Fixed bug where I redefined the image parameter. Duh... 1 April 99. DWF.
Moved the program into the 21st century. :-) 21 March 2003. DWF.
Added TIFF, GIF (if version supports it), and PS output. 27 December 2006. DWF.
(See image_blend.pro)
NAME:
IMAGE_DIMENSIONS
PURPOSE:
The purpose of this function is to return the dimensions of the image,
and also to extract relevant image information via output keywords. The
function works only with 2D and 3D (24-bit) images.
CATEGORY:
File I/O.
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/
CALLING SEQUENCE:
dims = Image_Dimensions(image)
RETURN VALUE:
An array containing the size of each dimension of the image. It is equivalent
to calling the SIZE function with the DIMENSIONS keyword set.
INPUTS:
image: The image variable from which information is to be obtained.
OUTPUT KEYWORD PARAMETERS:
ALPHACHANNEL: This keyword is set to 1 if there is an alpha channel in the image. Otherwise,
the keyword is set to 0.
TRUEINDEX: The position of the "true color" index in the return value. Is -1 for 2D images.
XINDEX: The index (position) of the X dimension in the return value.
XSIZE: The X size of the image.
YINDEX: The index (position) of the Y dimension in the return value.
YSIZE: The Y size of the image.
COMMON_BLOCKS:
None.
SIDE_EFFECTS:
None.
RESTRICTIONS:
Only 8-bit and 24-bit images are allowed. (24-bit images with alpha channels are allowed.)
EXAMPLE:
To load open a window of the appropriate size and display a 24-bit image:
dims = Image_Dimensions(image24, XSize=xsize, YSize=ysize, TrueIndex=trueindex)
Window, XSize=xsize, YSize=ysize
TV, TRUE=trueIndex
MODIFICATION HISTORY:
Written by: David W. Fanning, 5 March 2003.
Added support for alpha channel images, include ALPHACHANNEL keyword. 13 May 2009. DWF.
(See image_dimensions.pro)
NAME:
INSIDE
PURPOSE:
The purpose of this function is to indicate whether a specified
2D point is inside (returns a 1) a specified 2D polygon or outside
(returns a 0).
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:
result = INSIDE(x, y, xpts, ypts)
INPUTS:
x: A scalar or vector of the x coordinates of the 2D point(s) to check.
y: A scalar or vector of the y coordinates of the 2D point(s) to check.
xpts: The x coordinates of the 2D polygon.
ypts: The y coordinates of the 2D polygon.
OUTPUTS:
result: A scalar or vector set to 1 if the point is inside the polygon and to
0 if the point is outside the polygon.
KEYWORDS:
INDEX: An output keyword. If set to a named variable, will return the indices
of the X and Y points that are inside the polygon.
ALGORITHM:
Based on discussions on the IDL newsgroup (comp.lang.idl-pvwave) and
discussed here:
http://www.dfanning.com/tips/point_in_polygon.html
Primarily the work of B�rd Krane and William Connelly.
MODIFICATION HISTORY:
Written by: David W. Fanning, 4 September 2003.
Vectorized the function in accord with William Connelly's suggestions 24 July 2005. DWF.
(See inside.pro)
NAME:
JD2TIME
PURPOSE:
The purpose of this function is to convert a Julian day number into
a time string of the form "16 Mar 2009".
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:
result = JD2TIME(jdnumber, jdyear)
INPUTS:
jdnumber: A Julian day number or array of Julian day numbers. If absent,
today's current Julian day number.
jdyear: The year for which the Julian day number applies. If absent, the current year.
OUTPUTS:
result: A scalar or vector of time strings of the form "16 Mar 2009 15:34:26".
KEYWORDS:
None.
DEPENDENCIES:
Requires THEMONTHS from the Coyote Library.
http://www.dfanning.com/programs/themonths.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 25 June 2009.
(See jd2time.pro)
NAME:
JN2TIME
PURPOSE:
The purpose of this function is to convert a Julian number into
a time string of the form "16 Mar 2009 15:34:26."
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:
result = JN2TIME(jnumber)
INPUTS:
jnumber: A Julian number or array of Julian numbers. If absent,
today's current local time is returned.
OUTPUTS:
result: A scalar or vector of time strings of the form "16 Mar 2009 15:34:26".
KEYWORDS:
SHORT: Set this keyword to return just the day, month, year portion of the string.
DEPENDENCIES:
Requires THEMONTHS from the Coyote Library.
http://www.dfanning.com/programs/themonths.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 25 June 2009.
(See jn2time.pro)
NAME:
LEFTJUSTIFY
PURPOSE:
This is a utility routine to create a string that is left-justified with
respect to a string width.
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:
justifiedString = LeftJustify(string, width)
AUGUMENTS:
string: The string that is to be left-justified. If not supplied, a null
string is returned and no error is issued.
width: The final width of the left-justified string. The width must be
longer than the length of the string or an error results. Default: 50.
KEYWORDS:
None.
RETURN VALUE:
justifiedString: A string of WIDTH, with the string left-justified and the rest of the string
filled with blank characters.
MODIFICATION HISTORY:
Written by: David W. Fanning, 26 January 2009.
(See leftjustify.pro)
NAME:
LINKEDLIST
FILENAME:
linkedlist__define.pro
PURPOSE:
The purpose of this program is to implement a list that
is linked in both the forward and backward directions. There
is no restriction as to what can be stored in a linked list
node. The linked list is implemented as an object.
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:
mylist = Obj_New('LINKEDLIST', item)
OPTIONAL INPUTS:
item: The first item added to the list. Items can be any
valid IDL variable type.
COMMON BLOCKS:
Are you kidding?!
RESTRICTIONS:
Be sure to destroy the LINKEDLIST object when you are finished
with it: Obj_Destroy, mylist
Node index numbers start at 0 and go to n-1, where n is the
number of items in the list.
PUBLIC METHODS:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::ADD, item, index, $
AFTER=after, $
BEFORE=before, $
ERROR=error, $
NO_COPY=no_copy, $
REPLACE=replace
The ADD method adds a data item to the list.
Parameters:
item: The data item to be added to the list. Required.
index: The location in the list where the data item is
to be added. If neither the AFTER or BEFORE keyword is
set, the item is added AFTER the item at the index location.
If index is missing, the index points to the last item in
the list. Optional.
Keywords:
AFTER: If this keyword is set, the item is added after the
item at the current index.
BEFORE: If this keyword is set, the item is added before the
item at the current index.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
NO_COPY: If set, the item is transferred to the internal pointer using
a no copy method. This will cause the item variable to become undefined.
REPLACE: If this keyword is set, the item will replace the current item at
the index location.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::DELETE, index, ALL=all, DESTROY=destroy, ERROR=error
The DELETE method deletes an item from the list.
Parameters:
index: The location in the list where the data item is
to be delete. If index is missing, the index points to
the last item in the list. Optional.
Keywords:
ALL: If this keyword is set, all items in the list are deleted.
DESTROY: If the item at the node is an object or pointer, the
item will be destroyed before the node is deleted. This keyword
is turned on (set to 1) by default. Set to 0 to prevent destruction.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_COUNT
The GET_COUNT method returns the number of items in the list.
Return Value: The number of items stored in the linked list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_ITEM, index, $
ALL=all, $ ; This ASSUMES all items stored are the same type!!!
Dereference=dereference, $ ; Obsolete. Ignored. Always returns item.
ItemPtr=itemPtr, $ ; The pointer to the item, if needed. Output.
NO_COPY=no_copy, $ ; Copy from location with NO_COPY.
ERROR=errorMsg ; The error message. Null string if no error.
Parameters:
index: The location in the list from which the data item is
to be retrieved. If not present, the last item in the list
is retrieved. Optional.
Keywords:
DEREFERENCE: This keyword obsolete and only provided for backward compatibility.
ALL: Set this keyword to return an n-element array containing all the list
items. This requires that all list items be of the same type, and
if they are arrays, they have 7 dimensions or fewer. If index is passed,
it is ignored.
ITEMPTR: The pointer to the data item.
NO_COPY: If this keyword is set, the item is transferred from the data
pointer using a NO_COPY method. This will undefine the item at that
indexed locaton.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
Return Value: The data item at this index on the list.
If ALL is set, then an array containing all the data items is returned.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_NODE, index, ERROR=error
The GET_NODE method returns a pointer to the specified node
from the list.
Parameters:
index: The location in the list from which the data node is
to be retrieved. If not present, the last node in the list
is retrieved. The node is a structure with three fields:
Previous is a pointer to the previous node in the list.
Next is a pointer to the next node in the list. A null pointer
in the previous field indicates the first node on the list. A
null pointer in the next field indicates the last node on the
list. The item field is a pointer to the item stored in the
node. Optional.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
Return Value: A pointer to the specified node structure in
the linked list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::HELP, PRINT=print
The HELP method performs a HELP command on each item
in the linked list.
Keywords:
PRINT: If this keyword is set, the PRINT command is used
instead of the HELP command on the items in the list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::MOVE_NODE, nodeIndex, location, BEFORE=before, ERROR=error
The MOVE_NODE method moves a list node from one location to another.
Parameters:
nodeIndex: The location in the list of the node you are moving.
Required.
location: The location (index) you are moving the node to. If
location is missing, the location points to the node at the
end of the list.
Keywords:
BEFORE: If this keyword is set, the node is added to the
list before the location node. Otherwise, it is added after
the location node.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::REPLACE_ITEM, newItem, index, ERROR=error
Use this method to replace any item in the list with any other value.
This allows the caller to change an item without stepping through the
process of deleting an item then adding a new one.
Parameters:
index: The location of the node you are replacing
newItem: Any value of any data type.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::HAVE_ITEM, index, ERROR=error
Use this method to check to see if an item exits at a particular location
on the list. Returns a 1 if the item is there, otherwise a 0.
Parameters:
index: The location of the node you are replacing
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
EXAMPLE:
mylist = Obj_New("LINKEDLIST", 5)
mylist->Add, 10
mylist->Add, 7, 1, /Before
mylist->Add, 12
print, mylist->Get_Item(/All)
mylist->Add, 'Bob', 2, /Replace
mylist->Help
mylist->Delete, 0
mylist->Help, /Print
MODIFICATION HISTORY:
Written by: David Fanning, 25 August 98.
25 August 99. Fixed several errors in various methods dealing with
moving nodes from one place to another. DWF.
13 June 2001. DWF. Added DEREFERENCE to the GET_ITEM method to
return the item itself, instead of the pointer to the item.
27 June 2001 Added REPLACE_ITEM method. Ben Tupper.
7 April 2003. Added DESTROY keyword to DELETE method so that objects
and pointers could be cleaned up properly when they are deleted
from the linked list. DWF.
9 April 2003. Fixed a problem that occurs when deleting the last node. DWF.
3 Feb 2004. Make sure loop index vars are long. Jeff Guerber
30 Jun 2004. Added /ALL to GET_ITEM function. Henry Throop, SWRI.
23 Nov 2004. Fixed GET_ITEM, /ALL to accomodate structures and empty
lists. Henry Throop.
21 February 2011. A complete refurbishing to incorporate changes and to fix bugs
I found in the SolarSoft version of this code. I've tried to make this compatible
with the version distributed with SolarSoft to reduce problems caused by two versions
of the software with the same name.
(See linkedlist__define.pro)
NAME:
LIST_SELECTOR
PURPOSE:
The purpose of this function is to implement a pop-up dialog widget
for the purpose of selecting "names". Names can be names of variables,
names of files, etc. Any string array can be used.
CALLING SEQUENCE:
selectedNames = List_Selector(theNames)
ARGUMENTS:
theNames: A string array of potential "names" that can be selected.
KEYWORDS:
ALL: Set this keyword if you wish all the names to be selected
initially.
CANCEL: An output keyword set to 1 if the user cancels or quits the
program without hitting the Accept button. Set to 0 if a proper
selection was made and the use hits the Accept button.
COUNT: An output keyword containing the number of elements in the return array.
GROUP_LEADER: The widget identifier of a widget who will be the group leader
for this dialog. Passing a group leader is the *only* way to
assure the dialog will be a MODAL dialog (as opposed to a blocking
dialog). A GROUP_LEADER is required if you will be using this
function in an IDL Virtual Machine application.
LABEL: A string that will be placed on a label above the selections.
If not used, no label is used in the program.
LIST_COUNTER: If this keyword is set, a number is associated and displayed with
each list item, starting with the number 1.
TITLE: A string that is used for the title of the dialog window. If
undefined, then "Selection Widget" is used.
SELECTED_INDICES: An output vector of the selected indices from theNames array.
RETURN VALUE:
selectedNames: Typically, an array of selected names. If there is only one item
in the selection, the variable will be a scalar string.
EXAMPLE:
See the List_Selector_Test procedure below. I use the program to allow the
user to select the names of scientific data sets in an HDF file for further
reading and processing.
MODIFICATION HISTORY:
Written by David W. Fanning, 11 January 2009, based on Name_Selector program.
Added "Accept on Double-Click" functionality. 14 January 2009. DWF.
Added LIST_COUNTER keyword. 25 May 2009. DWF.
Well, basically a RE-DO of yesterday's work, although done correctly today. 26 May 2009. DWF.
Fixed a problem when the user double-clicks an item in the list. 8 August 2009. DWF.
(See list_selector.pro)
NAME:
LOGSCL
PURPOSE:
This is a utility routine to perform a log intensity transformation
on an image. For exponent values greater than 1.0, the upper and
lower values of the image are compressed and centered on the mean.
Larger exponent values provide steeper compression. For exponent values
less than 1.0, the compression is similar to gamma compression. (See
IMGSCL.) See pages 68-70 in _Digital Image Processing with MATLAB_
by Gonzales, Wood, and Eddins. The function is used to improve contrast
in images.
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:
outputImage = LOGSCL(image)
ARGUMENTS:
image: The image to be scaled. Written for 2D images, but arrays
of any size are treated alike.
KEYWORDS:
EXPONENT: The exponent in a log transformation. By default, 4.0.
MEAN: Values on either side of the mean will be compressed by the log.
The value is a normalized value between 0.0 and 1.0. By default, 0.5.
NEGATIVE: If set, the "negative" of the result is returned.
MAX: Any value in the input image greater than this value is
set to this value before scaling.
MIN: Any value in the input image less than this value is
set to this value before scaling.
OMAX: The output image is scaled between OMIN and OMAX. The
default value is 255.
OMIN: The output image is scaled between OMIN and OMAX. The
default value is 0.
RETURN VALUE:
outputImage: The output, scaled into the range OMIN to OMAX. A byte array.
COMMON BLOCKS:
None.
EXAMPLES:
cgLoadCT, 0 ; Gray-scale colors.
image = cgDemoData(22) ; Load image.
cgImage, image ; No contrast.
cgImage, LogScl(image) ; Improved contrast.
cgImage, LogScl(image, Exponent=10, Mean=0.65) ; Even more contrast.
cgImage, LogScl(image, /Negative, Exponent=5) ; A negative image.
RESTRICTIONS:
Requires SCALE_VECTOR from the Coyote Library:
http://www.dfanning.com/programs/scale_vector.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 20 February 2006.
Fixed a problem with output scaling. 1 July 2009. DWF (with input from Bo Milvang-Jensen).
(See logscl.pro)
:Description:
Creates a transparent image from an input image or from the current display window.
The transparent color is set with the COLOR keyword.
:Categories:
Graphics
:Params:
image: in, optional, type=byte
A 2D image or a 24-bit image with or without an alpha channel.
:Keywords:
color: in, optional, type=various
If COLOR is a string, use cgColor to obtain a color triple. If
COLOR is a scalar, replicate the value to obtain a color triple.
Othersize, expect a color triple to indicate the "transparent"
color in the output image. The alpha channel in the output image
is set to 0 for the transparent color. If this keyword is not used,
the color of the pixels in the lower-left [0,0] corner of the image
is used instead.
filename: in, optional, type=string
If the SAVE_PNG keyword is used this keyword will specify the name
of the PNG file to create. If a filename is provided, no user dialog
will be displayed. If a filename is not provided, the user will be
prompted for the name of the output file.
save_png: in, optional, type=boolean
If this keyword is set, the resulting transparent image will
be written as a PNG image file.
wset: in, optional, type=long
If image parameter is not passed, make the window indicated with
this keyword the current graphics window for obtaining an image parameter.
If not passed, the current graphics window is used.
:Examples:
To create and display a transparent image::
cgDisplay, WID=0
cgLoadCT, 0
cgImage, cgDemoData(5)
timage = Make_Transparent_Image(COLOR='black')
cgDisplay, WID=1
cgLoadCT, 22
cgImage, cgDemoData(7)
cgImage, timage, Position=[0.2, 0.2, 0.8, 0.8]
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 4 November 2010. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See make_transparent_image.pro)
NAME:
MAP_GSHHS_SHORELINE
PURPOSE:
Uses files from the Globally Self-consistent Hierarchical High-resolution Shoreline
(GSHHS) data base to draw shorelines in the manner of MAP_CONTINENTS. In other words,
it is assumed that a map coordinate data space has been established prior to calling
this routine. See the example below. The GSHHS data files can be downloaded from this
location:
http://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html
An article describing how to use this program can be found here.
http://www.dfanning.com/map_tips/gshhs.html
Note, the authors of the GSHHS software *continually* change the header
structure, which you MUST know to read the data file. There are are now
at least four different structures in common use. Please find the one
you need from the commented list below. The current code uses the structure
for the 2.0 version of the GSHHS software.
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:
Mapping Utilities
CALLING SEQUENCE:
Map_GSHHS_Shoreline, filename
ARGUMENTS:
filename: The name of the GSHHS input file.
KEYWORDS:
COLOR: The name of the drawing color. By default, "WHITE".
FILL: Set this keyword to draw filled outlines.
LAND_COLOR: The name of the land color (for FILL). By default, "INDIAN RED".
LEVEL: The polygon LEVEL. All polygons less than or equal to this value
are drawn. 1-land, 2-lakes, 3-island in lake, 4-pond in island.
By default, 2 (land and lake outlines).
MAP_PROJECTION: A map projection structure (from MAP_PROJ_INIT). If using a map projection
structure, a map coordinate system must be set up for the entire display window.
MINAREA: The minimum feature area. By default, 500 km^2.
OUTLINE: Set this keyword to draw shorelines. Set by default if FILL=0.
WATER_COLOR: The name of the water color. By default, "SKY BLUE".
RESTRICTIONS:
Requires the following programs from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/cgColor.pro
http://www.dfanning.com/programs/undefine.pro
EXAMPLE:
Example using MAP_SET to set up the map coordinate space.
datafile = 'gshhs_h.b'
Window, XSize=500, YSize=350
pos = [0.1,0.1, 0.9, 0.8]
Map_Set, -25.0, 135.0, Position=pos, Scale=64e6, /Mercator, /NoBorder
Polyfill, [pos[0], pos[0], pos[2], pos[2], pos[0]], $
[pos[1], pos[3], pos[3], pos[1], pos[1]], $
/Normal, Color=cgColor('Almond')
Map_GSHHS_Shoreline, datafile, /Fill, Level=3, /Outline
XYOutS, 0.5, 0.85, 'Australia', Font=0, Color=cgColor('Almond'), $
/Normal, Alignment=0.5
Example using MAP_PROJ_INIT to set up the map coordinate space.
datafile = 'gshhs_h.b'
Window, XSize=500, YSize=350
Erase, Color=cgColor('IVORY')
; Lambert Azimuthal Projection
map = Map_Proj_Init(111, Limit=[40, -95, 50, -75], $
Center_Lat=45, Center_Lon=-85)
; Create a data coordinate space based on map positions.
Plot, map.uv_box[[0, 2]], map.uv_box[[1, 3]], Position=[0.1, 0.1, 0.90, 0.75], $
/NoData, XStyle=5, YStyle=5, /NoErase
Map_GSHHS_Shoreline, datafile, /Fill, Level=3, Map_Projection=map, $
Water='DODGER BLUE', NoClip=0
Map_Grid, /Label, /Box, Color=cgColor('CHARCOAL'), Map_Structure=map
Map_Continents, /USA, Map_Structure=map
XYOutS, 0.5, 0.85, 'Great Lakes Region', Font=0, Color=cgColor('CHARCOAL'), $
/Normal, Alignment=0.5
MODIFICATION HISTORY:
Written by David W. Fanning, 5 February 2006.
Based on programs by Liam Gumley at ftp://ftp.ssec.wisc.edu/pub/gumley/IDL/gshhs/.
Bit of a dog's dish at the moment reading GSHHS files. I've contacted the author or the
data files, but haven't heard yet. Choose *one* of the headers below and see which
one works for you on the data you have. Best I can do, sorry. 24 December 2008. DWF.
In version 2.0 of the GSHHS they have changed the header again! Unbelievable. Modified
the header structure once again to cope. 4 June 2010. DWF.
(See map_gshhs_shoreline.pro)
:Description:
Prints the maximum and minimum of an IDL variable.
:Categories:
Utility
:Params:
variable: in, required, type=any
The variable whose minimum and maximum you wish to know.
:Keywords:
NAN: in, optional, type=boolean
Set this keyword to ignore NANs in the variable. Default: 0.
TEXT: in, optional, type=string
Prepend this string to the output of MinMax. Default: "MinMax: ".
:Examples:
The MaxMin routine gives the range of the variable::
IDL> a = Findgen(11)
IDL> MaxMin, a, TEXT='Variable A:'
Variable A: 11 0
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 20 Sept 2010.
Changed name of program from MinMax to MaxMin to avoid conflict with
MinMax program in NASA Astronomy Library. 1 Nov 2010. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See maxmin.pro)
:Description:
Returns the resolution of the largest unobstructed graphics window that can be
created on this particular graphics device. Works properly for Windows and UNIX
computers, excluding Macintosh computers. There is no known way to find the resolution
of the largest unobstructed graphics window on a Macintosh computer, so a fudge factor
of 22 pixels is used to account for the Macintosh "dock".
:Categories:
Utility
:Params:
none:
:Keywords:
monitor_resolution: out, optional, type=long
Set this keyword to a named variable to return the resolution of the
primary display monitor.
:Examples:
To create a window of maximum size::
maxsize = MaxWindowSize()
Window, XSize=maxsize[0], YSize=maxsize[1], /Free
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 26 October 2010. DWF.
Misunderstood Macintosh result. Now Mac treated like UNIX. 27 Oct 2010. DWF.
No known method for Macintosh computers. Resorting to a fudge factor
of 22 pixels to account for the Macintosh dock. 27 Oct 2010. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See maxwindowsize.pro)
NAME:
MPI_AXIS__DEFINE
PURPOSE:
This is a compound widget program for interactively adjusting and keeping track
of keywords appropriate for configuing axis properties.
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:
xAxisObjext = Obj_New("MPI_AXIS", /XAxis)
xAxisID = xAxisObject->GUI(baseWidgetID)
INPUT PARAMETERS:
None.
INPUT KEYWORDS (Sent to the INIT method. The same keywords can be set with the SETPROPERTY method of the object.):
AUTOKEYWORDS - An anonymous struture of keywords that are passed to the AutoRange function.
AUTORANGE - The name of a function that can return axis range information as 2-element array.
CHARSIZE - The character size used for the axis. By default, 1.0.
EXACT - Set to indicate exact axis range scaling. (Can also be set with the STYLE keyword.)
EXTEND - Set to indicate extended axis range. (Can also be set with the STYLE keyword.)
GRIDSTYLE - The style used for drawing grid lines.
HIDE - Set to indicate hidden axis style. (Can also be set with the STYLE keyword.)
LOG - Set to indicate logarithmic axis.
MARGIN - The axis margin. (Currently unimplemented.)
MINOR - The number of minor tick marks between the major tick marks on the axis.
NAME = A user-defined "name" for the object.
NOBOX - Set to inhibit box-style axis. (Can also be set with the STYLE keyword.)
NOZERO - Set to indicate NO_ZERO axis style. (Can also be set with the STYLE keyword.)
RANGE - The axis range as a two-element array, [minrange, maxrange].
STYLE - The axis style. A 32-bit value whose bits select certain properties. See the
on-line documentation for the !X.STYLE system variable for more information. These
style properties can be set in a more natural way with other keywords.
THICK - The thickness of the axis. By default, 1.0.
TICKFORMAT - The format to use with tick marks. May be name of procedure.
TICKINTERVAL - The interval to space tick marks for first-level axis. (Currently not implemented.)
TICKLAYOUT - The type of tick layout desired. (Currently not implemented.)
TICKLEN - The length of the ticks on the axis. By default, 0.0. (Note that changing this
value will cause the Plot TICKLEN value to be ignored for the axis.)
TICKNAME - The string names associated with each tick mark. (Currently not implemented.)
TICKS - The number of major tick intervals.
TICKUNITS - The units to use for tick labeling. (Currently not implemented.)
TICKV - A vector of tick values. (Currently not implemented.)
TITLE - The axis title.
XAXIS - Set to indicate an X axis object. This is the default.
YAXIS - Set to indicate a Y axis object.
ZAXIS - Set to indicate a Z axis.
METHOD PROCEDURES:
GUI - This procedure method displays a graphical user interface that allows the user
to change the axis configuration parameters.
PARAMETERS:
parent - The parent of the compound widget.
KEYWORDS:
EVENT_PRO - The specified event handler procedure.
EVENT_FUNC - The specified event handler function.
ONLY_STYLE - If set, display only style parameters in the GUI.
ONLY_TICK - If set, display only tick parameters in the GUI.
SHORT_FORM - Normally, all the axis properties are displayed in the GUI. Setting
this keyword places the Tick and Style properties behind buttons on the interface.
UVALUE - The user value of the compound widget.
SETPROPERTY - This procedure can be used to set the properties of the axis
configuration object without using the graphical user interface. The
keywords are identical to those used in the INIT method, above.
METHOD FUNCTIONS:
GETKEYWORDS - This function method contains no arguments or keywords. It returns a
structure, with fields equivalent to PLOT keywords for setting axis properties.
The idea is that these keywords can be passed directly to the PLOT command using
the keyword inheritance mechanism via the _EXTRA keyword to the plot command. ished with it.
PROGRAM NOTES:
Required Programs: The following programs are required to reside in your !PATH. They can be
obtained from the Coyote Library:
http://www.dfanning.com/programs/cw_spacer.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/fsc_droplist.pro
http://www.dfanning.com/programs/fsc_field.pro
EXAMPLE:
A heavily documented program, named MPI_PLOT, is supplied with this program.
This program not only explains how to use the MPI_PLOTCONFIG__DEFINE and the
MPI_AXIS__DEFINE programs, it can be used as a wrapper program for the PLOT command
that you can use with your own data. The program can be downloaded here:
http://www.dfanning.com/programs/mpi_plot.pro
MODIFICATION HISTORY:
Written by David Fanning, March 2001.
(See mpi_axis__define.pro)
NAME:
MPI_PLOT
PURPOSE:
This program is a simple wrapper for the IDL PLOT command. The
main purpose of the program is to demonstrate one way the
MPI_PLOTCONFIG program can be used to update plot parameters.
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:
MPI_Plot, x, y
MPI_Plot, xx, yy, /Overplot
INPUT PARAMETERS:
x - The independent data. If y is not present, x is taken to be the dependent data.
y - The dependent data. The vectors x and y must be the same length.
xs - The independent data to overplot. If yy is not present, xx is taken to be the dependent data.
yy - The dependent data to overplot. The vectors xx and yy must be the same length.
INPUT KEYWORDS:
BACKGROUND - The name of a background color. (See below for a list of color names.)
By default on 24-bit systems: 'IVORY'. Uses 'GRAY' on 8-bit systems.
COLOR - The name of the plot color. (See below for a list of color names.)
By default on 24-bit systems: 'SADDLE BROWN'. Uses 'GREEN' on 8-bit systems.
When OVERPLOTing, use the COLOR keyword to specify the color of the overplot.
DATACOLOR - The name of the data color. By default the same as the COLOR keyword.
(See below for a list of color names.) When OVERPLOTing, use the COLOR keyword
to specify the color of the overplot.
OVERPLOT - Set this keyword to overplot data into the MPI_PLOT window.
If multiple windows are on the display, select the one to overplot into
by selecting it with the cursor.
PSYM - The plot symbol value. By default, 18. Possible values are:
0 - Dot
1 - Filled Circle
2 - Filled Upward Triangle
3 - Filled Downward Triangle
4 - Filled Diamond
5 - Filled Square
6 - Open Circle
7 - Open Upward Triangle
8 - Open Downward Triangle
9 - Open Diamond
10 - Open Square
11 - Plus Sign
12 - X
13 - Star
14 - Filed Rightfacing Triangle
15 - Filled Leftfacing Triangle
16 - Open Rightfacing Triangle
17 - Open Leftfacing Triangle
18 - No Symbol (the default).
TITLE - The title of the plot. By default, a null string.
XLOG = Set this keyword to use logarithmic axis styling on the X axis.
XTITLE - The title of the X axis of the plot. By default, a null string.
YLOG = Set this keyword to use logarithmic axis styling on the Y axis.
YTITLE - The title of the Y axis of the plot. By default, a null string.
In addition, any keyword appropriate for the MPI_PLOTCONFIG object program can be used.
Among those keywords, are these most popular ones:
CHARSIZE - The character size of the plot. By default, 1.0.
CHARTHICK - The character thickness of the plot. By default, 1.0.
FONT - The type of plot font: -1=Hershey, 0=Hardware, 1=True-Type. By default, !P.FONT.
LINESTYLE - The plot linestyle. By default, 0. Possible values are:
0 - Solid Line
1 - Dotted
2 - Dashed
3 - Dash Dot
4 - Dash Dot Dot
5 - Long Dash
6 - No Line
POSITION - The position of the plot in the plot window in normalized coordinates. By default, [0.20, 0.15, 0.95, 0.95].
SYMSIZE - The plot symbol size. By default, 1.0.
THICK - The plot line thickness. By default, 1.0.
TICKLEN - The plot tick length. By default, 0.02.
COLOR NAMES:
The following color names can be used for BACKGROUND, COLOR and DATACOLOR keywords:
White, Snow, Ivory, Light Yellow, Cornsilk, Beige, Seashell, Linen, Antique White,
Papaya, Almond, Bisque, Moccasin, Wheat, Burlywood, Tan, Light Gray, Lavender,
Medium Gray, Gray, Slate Gray, Dark Gray , Charcoal, Black, Light Cyan, Powder Blue,
Sky Blue, Steel Blue, Dodger Blue, Royal Blue, Blue, Navy, Honeydew, Pale Green,
Aquamarine, Spring Green, Cyan, Turquoise, Sea Green, Forest Green, Green Yellow,
Chartreuse, Lawn Green, Green, Lime Green, Olive Drab, Olive, Dark Green, Pale Goldenrod,
Khaki, Dark Khaki, Yellow, Gold, Goldenrod, Dark Goldenrod, Saddle Brown, Rose,
Pink, Rosy Brown, Sandy Brown, Peru, Indian Red, Chocolate, Sienna, Dark Salmon,
Salmon, Light Salmon, Orange, Coral, Light Coral, Firebrick, Brown, Hot Pink,
Deep Pink, Magenta, Tomato, Orange Red, Red, Violet Red, Maroon, Thistle, Plum,
Violet, Orchid, Medium Orchid, Dark Orchid, Blue Violet, and Purple.
REQUIRED PROGRAMS:
The following programs are required to reside in your !PATH. They can be
obtained from the Coyote Library:
http://www.dfanning.com/programs/adjustposition.pro
http://www.dfanning.com/programs/cw_drawcolor.pro
http://www.dfanning.com/programs/cw_spacer.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/cgColor.pro
http://www.dfanning.com/programs/fsc_droplist.pro
http://www.dfanning.com/programs/fsc_field.pro
http://www.dfanning.com/programs/fsc_fileselect.pro
http://www.dfanning.com/programs/fsc_inputfield.pro
http://www.dfanning.com/programs/fsc_psconfig__define.pro
http://www.dfanning.com/programs/mpi_plotconfig__define.pro
http://www.dfanning.com/programs/mpi_axis.pro
http://www.dfanning.com/programs/mpi_axis__define.pro
http://www.dfanning.com/programs/pickcolorname.pro
http://www.dfanning.com/programs/psconfig.pro
http://www.dfanning.com/programs/pswindow.pro
http://www.dfanning.com/programs/cgsnapshot.pro
All these programs can be obtained at once by downloading the MPI_PLOT zip file:
http://www.dfanning.com/programs/mpi_plot.zip
COMMON BLOCK:
The addition of the OVERPLOT keyword required a COMMON block named MPI_PLOT_COMMMON
to store the program information pointer. This pointer is loaded in the COMMON block
when the keyboard focus changes. Thus, to overplot into an MPI_PLOT window, first
select the window with the cursor.
RESTRICTIONS
Colors will be loaded in the color table.
EXAMPLE:
x = Findgen(11) & y = Findgen(11)
MPI_PLOT, x, y
MPT_PLOT, Reverse(x), y, /Overplot, Linestyle=2
MODIFICATION HISTORY:
Written by David W. Fanning, March 2001, and offered to the IDL user
community by the Max-Plank Institute of Meteorology in Hamburg, Germany.
Added OVERPLOT keyword and made numerous general improvements. 21 November 2001. DWF
Removed restriction for only one copy of MPI_PLOT on display at once. 25 November 2001. DWF.
Added XLOG and YLOG keywords. 7 May 2002. DWF.
PostScript configuration now opens up with a plot window the same aspect
ratio as the MPI_PLOT window. 21 August 2002. DWF.
Fixed a problem in which PSCONFIG was called as a blocking widget rather than as a
modal widget, as required. 11 March 2003. DWF.
Made a change to the GUI method that fixes a problem I have been having
on some Linux machines in widgets not always showing up. 15 July 2003. DWF.
Fixed a problem when ploting vectors with more that 32K elements. 7 March 2006. DWF.
Fixed a problem with initial display on Macs. 20 May 2009. DWF.
(See mpi_plot.pro)
NAME:
MPI_PLOTCONFIG__DEFINE
PURPOSE:
This is a program for interactively adjusting and keeping track
of keywords appropriate for configuring the PLOT command.
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:
plotConfigObj = Obj_New("MPI_PLOTCONFIG")
INPUT PARAMETERS:
None.
INPUT KEYWORDS (Sent to the INIT method. The same keywords can be set with the SETPROPERTY method of the object.):
BACKGROUND - The name of the background color. By default on 24-bit systems: 'IVORY'. ON 8-bit systems 'GRAY'.
CHARSIZE - The character size of the plot. By default, 1.0.
CHARTHICK - The character thickness of the plot. By default, 1.0.
COLOR - The name of the plot color. (This will be the axis color if DATACOLOR is also used.)
By default on 24-bit systems: 'SADDLE BROWN'. Uses 'GREEN' on 8-bit systems.
DATACOLOR - The name of the data color. (Requires use of USEDATACOLOR to be active.) By default
on 24-bit systems: 'NAVY'. Uses 'YELLOW' on 8-bit systems.
_EXTRA - Extra keywords to be passed to MPI_AXIS objects used internally.
FONT - The type of plot font: -1=Hershey, 0=Hardware, 1=True-Type. By default, !P.FONT.;
LINESTYLE - The plot linestyle. By default, 0. Possible values are:
0 - Solid Line
1 - Dotted
2 - Dashed
3 - Dash Dot
4 - Dash Dot Dot
5 - Long Dash
6 - No Line
NOAXISINFO - Set this keyword to inhibit axis information on the GUI. By default, 0.
POSITION - The position of the plot in the plot window in normalized coordinates. By default, [0.20, 0.15, 0.95, 0.95].
PSYM - The plot symbol value. By default, 18. Possible values are:
0 - Dot
1 - Filled Circle
2 - Filled Upward Triangle
3 - Filled Downward Triangle
4 - Filled Diamond
5 - Filled Square
6 - Open Circle
7 - Open Upward Triangle
8 - Open Downward Triangle
9 - Open Diamond
10 - Open Square
11 - Plus Sign
12 - X
13 - Star
14 - Filed Rightfacing Triangle
15 - Filled Leftfacing Triangle
16 - Open Rightfacing Triangle
17 - Open Leftfacing Triangle
18 - No Symbol (the default).
SYMSIZE - The plot symbol size. By default, 1.0.
SUBTITLE - The plot subtitle. By default, "".
TITLE - The plot title. By default, "".
THICK - The plot line thickness. By default, 1.0.
TICKLEN - The plot tick length. By default, 0.02.
USEDATACOLOR - Set this keyword to return a DATACOLOR field in the keyword structure. By default, 0.
XAXIS - An MPI_AXIS object for the X axis. One is created by default, if not provided.
YAXIS - An MPI_AXIS object for the Y axis. One is created by default, if not provided.
METHOD PROCEDURES:
GUI - This procedure method displays a graphical user interface that allows the user
to change plot configuration parameters. The following keywords can be used:
ALL_EVENTS - Set this keyword to have an event sent any time something in the
GUI changes. The default is to send an event only when the user hits the ACCEPT button.
Note that the NOTIFYID keyword must be used to generate events.
BLOCK - Set this keyword if you want to block the command line. The default is to NOT block the command line.
DEFAULTFONT - The name of a font to use as the default font.
GROUP_LEADER - The group leader for this GUI. If this keyword is used, the program will be
distroyed when the group leader is destroyed.
LABELDEFAULTSIZE - The default screen size for a label. All labels are offsets from this size. 55 by default.
The purpose of this keyword is to allow the user to modify the look of the GUI if different
fonts are used.
LABELFONT - The name of a font to use for program labels.
NOTIFYID - A two-element array containing the widget identifier and top-level base ID of a widget
designated to receive an event from this program. The event structure will be defined and sent
like this:
Widget_Control, notifyid[0], Send_Event={ MPI_PLOTCONFIG_EVENT, $
ID: notifyid[0], $
TOP:notifyid[1], $
HANDLER: 0L, $
OBJECT: self }
Most event handlers will be written so that they will get the plot keywords
from the plot configuration object and draw the plot. A sample event handler might
look like this:
PRO MPI_Plot_Configuration_Events, event
Widget_Control, event.top, Get_UValue=info, /No_Copy
WSet, info.wid
plotkeywords = event.object->GetKeywords()
Plot, info.indep, info.dep, _Extra=plotkeywords
Widget_Control, event.top, Set_UValue=info, /No_Copy
END
XLONGFORM - By default, the X axis information is displayed in "short" form, with only the
most relevant information readily available. Other axis information is accessed via buttons.
Set this keyword to display the X axis information in a "long" form, in which all the axis
information is immediately visible.
YLONGFORM - By default, the Y axis information is displayed in "short" form, with only the
most relevant information readily available. Other axis information is accessed via buttons.
Set this keyword to display the Y axis information in a "long" form, in which all the axis
information is immediately visible.
SETPROPERTY - This procedure can be used to set the properties of the plot
configuration object without using the graphical user interface. The
keywords are identical to those used in the INIT method, above.
METHOD FUNCTIONS:
GETKEYWORDS - This function method contains no arguments or keywords. It returns a
structure, with fields equivalent to PLOT keywords. The idea is that these
keywords can be passed directly to the PLOT command using the keyword inheritance
mechanism via the _EXTRA keyword to the plot command. A possible sequence of commands
might look like this:
IDL> plotConfigObj = Obj_New("MPI_PLOTCONFIG") ; Create the plot configuration object.
IDL> plotConfigObj->GUI, /Block ; Allow the user to configure the plot parameters.
IDL> plotKeywords = plotConfigObj->GetKeywords() ; Get the plot keywords.
IDL> Plot, x, y, _Extra=plotKeywords ; Draw the plot in the way the user specified.
IDL> Obj_Destroy, plotConfigObj ; Destroy the object when finished with it.
PROGRAM NOTES:
Color Names: Color names are those used with cgColor and PickColorName. See the
documentation for those programs for instuctions on loading your own colors.
To see the default colors and names, type this:
IDL> color = PickColorName('yellow')
Working with DataColor: Many people like to have the data color in a line plot
different from the axis color. This requires two commands in IDL: a PLOT command
with the NODATA keyword set, to draw in the axis color, followed by the OPLOT command,
with the data drawn in the data color. Unfortunately, IDL only has a single COLOR keyword
to represent both colors. So, you must be a bit resourceful to use this feature.
The proper sequence of commands to use this feature of the plot configuration object
will looks like this. First, initialize the object with the USEDATACOLOR keyword:
plotConfigObj = Obj_New("MPI_PLOTCONFIG", /UseDataColor) ; Use the DataColor option.
When you are ready to draw the plot, the keyword structure will have a new field named
DataColor. Since this keyword is not recognized by the PLOT command, it will be ignored
in the first PLOT command to draw the axes:
plotKeywords = plotConfigObj->GetKeywords() ; Get the plot keywords.
Plot, x, y, _Extra=plotKeywords, /NoData ; Just draw the axes.
Next, change the color field to the datacolor field value, and overplot the
data onto the axes you just drew:
plotKeywords.color = PlotKeywords.datacolor
OPlot, x, y, _Extra=plotKeywords
You can see an example of how this is done in the heavily documented example program
MPI_PLOT, which you can use as a wrapper for the PLOT command with your own data, if you like.
Required Programs: The following programs are required to reside in your !PATH. They can be
obtained from the Coyote Library:
http://www.dfanning.com/programs/adjustposition.pro
http://www.dfanning.com/programs/cw_drawcolor.pro
http://www.dfanning.com/programs/cw_spacer.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/cgColor.pro
http://www.dfanning.com/programs/fsc_droplist.pro
http://www.dfanning.com/programs/fsc_field.pro
http://www.dfanning.com/programs/fsc_plotwindow.pro
http://www.dfanning.com/programs/mpi_axis__define.pro
http://www.dfanning.com/programs/pickcolorname.pro
http://www.dfanning.com/programs/pswindow.pro
http://www.dfanning.com/programs/cgsnapshot.pro
EXAMPLE:
A heavily documented program, named MPI_PLOT, is supplied with this program.
This program not only explains how to use the MPI_PLOTCONFIG__DEFINE program,
it can be used as a wrapper program for the PLOT command that you can use with
your own data. The program can be downloaded here:
http://www.dfanning.com/programs/mpi_plot.pro
MODIFICATION HISTORY:
Written by David W. Fanning, March 2001.
Made a change to the GUI method that fixes a problem I have been having
on some Linux machines in widgets not always showing up. 15 July 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Fixed a problem when users tried to set PSYM to a negative value. 24 June 2008. DWF.
(See mpi_plotconfig__define.pro)
NAME:
NAME_SELECTOR
PURPOSE:
The purpose of this function is to implement a pop-up dialog widget
for the purpose of selecting "names". Names can be names of variables,
names of files, etc. Any string array can be used.
CALLING SEQUENCE:
selectedNames = Name_Selector(theNames)
ARGUMENTS:
theNames: A string array of potential "names" that can be selected.
KEYWORDS:
ALL: Set this keyword if you wish all the names to be selected
initially.
CANCEL: An output keyword set to 1 if the user cancels or quits the
program without hitting the Accept button. Set to 0 if a proper
selection was made and the use hits the Accept button.
COUNT: An output keyword containing the number of elements in the return array.
GROUP_LEADER: The widget identifier of a widget who will be the group leader
for this dialog. Passing a group leader is the *only* way to
assure the dialog will be a MODAL dialog (as opposed to a blocking
dialog). A GROUP_LEADER is required if you will be using this
function in an IDL Virtual Machine application.
LABEL: A string that will be placed on a label above the selections.
If not used, no label is used in the program.
NUMCOLS: The number of columns to organize the string array in. The default
is to use one column per approximately 20 strings.
TITLE: A string that is used for the title of the dialog window. If
undefined, then "Selection Widget" is used.
RETURN VALUE:
selectedNames: Typically, an array of selected names. If there is only one item
in the selection, the variable will be a scalar string.
EXAMPLE:
See the Name_Selector_Test procedure below. I use the program to allow the
user to select the names of scientific data sets in an HDF file for further
reading and processing.
MODIFICATION HISTORY:
Written by David W. Fanning, 21 December 2008.
Added a COUNT keyword. DWF. 6 January 2009.
(See name_selector.pro)
NAME:
NCDF_ATTRIBUTE
PURPOSE:
The pupose of this NCDF_Attribute object is to store information about
a netCDF global or variable attribute. The object is principally used
as a utility routine for the NCDF_FILE object. Given the attribute name,
the object will acquire additional information about the attribute from
the netCDF file containing the attribute.
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:
File I/O
CALLING SEQUENCE:
IDL> attrObj = Obj_New('NCDF_ATTRIBUTE', attrName, parent, VARNAME=varName)
ARGUMENTS:
attrName: The case sensitive name of a netCDF attribute that is stored in the
netCDF file. (Input and required.)
parent: The object reference (NCDF_FILE object) of the netCDF file. In other words, the
object reference of the file that contains this attribute. (Input and required.)
KEYWORD PARAMETERS:
varName: If this is a variable attribute, this is the case sensitive name of the
variable that the attribute is attached to. (Input and required for variable
attributes.) Note that a variable object reference may be used in place of the
variable name.
METHODS:
The following methods are available. Each is documented in front of the method.
attrName = attrObject -> GetName()
propertyValue = attrObject -> GetProperty(attrProperty)
attrValue = attrObject -> GetValue()
attrObject -> ParseAttribute
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 Feb 2010.
(See ncdf_attribute__define.pro)
NAME:
NCDF_BROWSER
PURPOSE:
This program is designed to make it easier to browse and read the
data and metadata in netCDF and HDF files. The user can browse files,
and read the data and metadata into main-level IDL variables. New netCDF
and HDF files can be opened at any time. The user interacts with the
program via a browser window (GUI). This program is a wrapper for the
NCDF_DATA object (ncdf_data__define.pro), which must also be downloaded.
Note that only HDF files with scientific datasets (SD) can be read currently.
There is no support for VDATA objects or other objects sometimes found in HDF
files. Also note that when variables are returned from HDF files, they are returned
in a calibrated form, if calibration information about the variable is present in the
file. Calibration information is presented as an extra variable attribute in the
browser.
calibratedData = calData.cal * (uncalibratedData - calData.offset)
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:
File I/O
CALLING SEQUENCE:
IDL> NCDF_Browser, filename
Arguments:
filename: The name of a netCDF and HDF file to open and browse.
KEYWORD PARAMETERS:
EXTENSION: In general, netCDF and HDF files use *.nc, *.ncf, *.ncdf and *.hdf file extensions to
identify themselves as netCDF and HDF files. Some users have their own file extensions.
You can use this keyword to identify the file extension you wish to use. If
set here, it will be used as the file filter in place of the normal file
extensions in DIALOG_PICKFILE.
obj = ('NCDF_DATA', file, EXTENSION='*.bin')
NO_NEW_FILE: If this keyword is set, then the button that allows a new file to be open
on the browser is not created.
NO_READ_ON_PARSE: Normally, when a file is opened it is parsed for information.
One piece of information is the minimum and maximum values of the variables.
This requires actually reading the variables. This can slow things down
considerably is the variable is large. Setting this keyword will suppress
the reading of the variables during the parsing of the data file, with the
result that no minimum or maximum values will be reported.
TITLE: Set this keyword to a string that is on the title bar of the browser.
XOFFSET: Set this keyword to the X offset in pixels of the top-left corner of the browser.
YOFFSET: Set this keyword to the Y offset in pixels of the top-left corner of the browser.
NOTES:
This program is only a (useful) front-end for a more flexible
object program of class NCDF_DATA. In this front end, the NCDF_DATA
object is created and then destroyed when the GUI is destroyed.
The NCDF_DATA object can be used to read netCDF data in a non-interactive
way, if you prefer not to use a GUI to interact with the data file.
REQUIRES:
The following programs are required from the Coyote Library.
http://www.dfanning.com/netcdf_data__define.pro
http://www.dfanning.com/error_message.pro
http://www.dfanning.com/centertlb.pro
http://www.dfanning.com/undefine.pro
http://www.dfanning.com/textbox.pro
http://www.dfanning.com/fsc_base_filename.pro
http://www.dfanning.com/textlineformat.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 03 Feb 2008. Used ideas from many
people, including Chris Torrence, Ken Bowman, Liam Gumely,
Andrew Slater, and Paul van Delst.
Added Extension keyword. DWF. 04 Feb 2008.
Added error handling and protection for NCDF variables that have a dimension of length zero. 22 April 2009. DWF.
Added NO_READ_ON_PARSE keyword. 22 April 2009. DWF.
Now convert NCDF CHAR type variables to strings on output. 22 April 2009. DWF
Made the default value of NO_READ_ON_PARSE set to 1. 25 June 2009. DWF.
Added NO_NEW_FILE keyword to suppress the Open File button. 3 February 2010. DWF.
Added TITLE, XOFFSET, and YOFFSET keywords. 5 February 2010. DWF.
Fixed a problem with memory leakage when the input file cannot be read. 1 May 2010. DWF.
(See ncdf_browser.pro)
NAME:
NCDF_CastDataType
PURPOSE:
This is a utility routine to turn IDL data types into the equivalent
netCDF data type. In other words, change 'STRING' to 'CHAR' and so on.
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:
ncdf_datatype = NCDF_CastDataType(variable)
ARGUMENTS:
variable: The IDL variable for which you want a netCDF data type.
Or, if the TYPE keyword is set, the variable type index you wish
to convert. Or, if the TNAME keyword is set, the variable type
name you wish to convert.
KEYWORDS:
TYPE: If set, the positional argument is an IDL variable type of
the sort returned by the SIZE function with the TYPE keyword set.
type = Size(variable, /TYPE)
TNAME: If set, the positional argument is an IDL variable type of
the sort returned by the SIZE function with the TNAME keyword set.
type = Size(variable, /TNAME)
RETURN VALUE:
ncdf_datatype: The netCDF data type of the variable. Possible values are
'BYTE', 'CHAR', 'SHORT', 'LONG', 'FLOAT' and 'DOUBLE'.
NOTES:
The program is designed to work with the NCDF_FILE object and related programs.
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 February 2010.
Made a UINT data type be cast to LONG, rather than SHORT. 29 April 2010. DWF.
Added TYPE and TNAME keywords. 5 May 2010. DWF.
(See ncdf_castdatatype.pro)
NAME:
NCDF_Container
PURPOSE:
This is a beefed-up IDL_CONTAINER object written as a utility object
for the NCDF_FILE object and related objects. In particular, two new
container methods have been added. The FindByID method searches container
objects by object ID, and the FindByName method searches container object
by object name. If found, the object reference is returned. This object
is a subclassed IDL_CONTAINER object and uses the IDL_CONTAINER
initialization routine.
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:
ncdf_container = NCDF_Container()
ARGUMENTS:
Those used in the IDL_CONTAINER method.
RETURN VALUE:
A sub-classed IDL_Container object.
NOTES:
The program is designed to work with the NCDF_FILE object and related programs.
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 February 2010.
(See ncdf_container__define.pro)
NAME:
NCDF_DATA__DEFINE
PURPOSE:
This program is designed to make it easier to browse and read the
data and metadata in netCDF and HDF files. The user can browse files,
and read the data and metadata into main-level IDL variables. New netCDF
and HDF files can be opened at any time. The user interacts with the
program via a browser window (GUI) or directly through the methods of
the object. The program implements an IDL object.
Note that only HDF files with scientific datasets (SD) can be read currently.
There is no support for VDATA objects or other objects sometimes found in HDF
files. Also note that when variables are returned from HDF files, they are returned
in a calibrated form, if calibration information about the variable is present in the
file. Calibration information is presented as an extra variable attribute in the
browser.
calibratedData = calData.cal * (uncalibratedData - calData.offset)
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:
File I/O
CALLING SEQUENCE:
IDL> nCDFObject = Obj_New('NCDF_DATA', filename)
ARGUMENTS:
filename: The name of a netCDF or HDF file to open and browse.
KEYWORD PARAMETERS:
BROWSE: If this keyword is set, the Browse Window is invoked as soon
as the object is initiated.
DESTROY_FROM_BROWSER: As with all objects, this object is persistent until
it is destroyed. However, with this keyword set, the object will
be destroyed when the user closes the Browse Window.
EXTENSION: In general, netCDF and HDF files use *.nc, *.ncf, *.ncdf of *.hdf file extensions to
identify themselves as netCDF or HDF files. Some users have their own file extensions.
You can use this keyword to identify the file extension you wish to use. If
set here, it will be used as the file filter in place of the normal file
extensions in DIALOG_PICKFILE.
obj = ('NCDF_DATA', file, EXTENSION='*.bin')
NO_READ_ON_PARSE: Normally, when a file is opened it is parsed for information.
One piece of information is the minimum and maximum values of the variables.
This requires actually reading the variables. This can slow things down
considerably is the variable is large. Setting this keyword will suppress
the reading of the variables during the parsing of the data file, with the
result that no minimum or maximum values will be reported.
NOTES:
This program is designed to be flexible in how it is used, so it
can be used in both interactive and non-interactive (called directly)
ways. A less flexible way of interacting with the program is via the
NCDF_BROWSER program, which is a front-end to this object.
The netCDF and HDF file formats are thought to be "standards". And to
a large extent, they are. But files are not always created to standards,
and both netCDF and HDF files can be quirky. If you look carefully at the
code you will see places where I work around quirks in the files I typically
use on a daily basis. If you find you can't read a particular file, let me know
about it. I may be able to improve the program in such as way that it can be read.
This program is not meant to be the be-all and end-all of programs. Rather, it is
a tool I use, and improve upon whenever necessary, in my own work with netCDF and HDF
files. It will get better for all of us if you report problems to me directly.
REQUIRES:
The following programs are required from the Coyote Library. And it is always a
good idea to make sure you have the latest version of the Coyote Library code,
as updates are irregular and frequent.
http://www.dfanning.com/programs/netcdf_data__define.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/centertlb.pro
http://www.dfanning.com/programs/undefine.pro
http://www.dfanning.com/programs/textbox.pro
http://www.dfanning.com/programs/fsc_base_filename.pro
http://www.dfanning.com/programs/textlineformat.pro
METHODS:
The following methods can be used directly.
ncdfObject -> Browse ; Use GUI to browse file data and metadata.
ncdfObject -> OpenFile, filename ; Opens a new netCDF or HDF file.
globalAttr = ncdfObject -> ReadGlobalAttr() ; Return a structure containing global attributes.
attribute = ncdfObject -> ReadAttribute(attrname); Return an attribute, identified by name.
dim = ncdfObject -> ReadDimension(dimName) ; Return a dimension, identified by name.
variable = ncdfObject -> ReadVariable(varname) ; Return a variable, identified by name.
varstruct = ncdfObject -> ReadVariableWithAttr(varname) ; Return a variable, identified by
; name, along with its attributes.
allData = ncdfObject -> ReadFile(filename) ; Read all the data in the file, into structures.
EXAMPLE:
IDL> filename = 'example.nc'
IDL> ncdfObj = Obj_New('NCDF_DATA', filename)
IDL> ncdfObj -> Browse
IDL> Obj_Destroy, ncdfObj
MODIFICATION HISTORY:
Written by: David W. Fanning, 03 Feb 2008. Used ideas from many
people, including Chris Torrence, Ken Bowman, Liam Gumely,
Andrew Slater, and Paul van Delst.
Added EXTENSION keyword, resizeable TLB, and ability to download
individual global attibutes. DWF. 04 Feb 2008.
Added ReadDimension and ReadVariableWithAttr methods. DWF. 05 Feb 2008.
Ill-formed attribute names giving me fits. Now doing checks with IDL_VALIDNAME
before creating structures. 06 February 2008. DWF.
Same problem. Wide use of IDL_VALIDNAME everywhere it seems wise. 06 Feb 2008. DWF.
Added functionality to read a variable with its attributes from the browser interface,
and fixed a problem with reading CHAR values. 2 March 2008. DWF.
Fixed a problem with changing variable name when reading variable plus attributes. 6 March 2008. DWF.
Fixed a problem with not setting GLOBAL keyword when inquiring about global attribute. 6 March 2008. DWF.
Made sure file was parsed before attempting to read variables and attributes to avoid errors. 7 March 2008. DWF.
Small bug with variable attributes fixed. 18 Dec 2008. DWF.
Added ability to read HDF files containing Scientific Datasets (SD). 21 February 2009. DWF.
Added error handling and protection for NCDF variables that have a dimension of length zero. 22 April 2009. DWF.
Added NO_READ_ON_PARSE keyword. 22 April 2009. DWF.
Now convert NCDF CHAR type variables to strings on output. 22 April 2009. DWF
Fixed a problem with the directory being correct when file name passed in. 11 May 2009. DWF.
Added COUNT, OFFSET, and STRIDE keywords to ReadVariable method. 25 June 2009. DWF.
When reading a netCDF variable by itself (without it's attributes), the program now looks for
a SCALE_FACTOR and ADD_OFFSET attribute, and if found will apply this to the variable before
it is returned to the user. 24 August 2009. DWF.
Added the methods GetAttrNames, GetVarNames, GetVarAttrNames, and ReadVarAttr to retrieve specfic
information from the data files. 16 November 2009. DWF.
Modified the ReadVariableWithAttr method to include the number of dimensions (in the NDIMS field,
and the dimensions (in the DIMS field) in the return structure. For HDF files, the DIMS field
is a vector of the dimensions of the variable. For netCDF files, the DIMS field is a vector
of dimension IDs for the dimensions of the variable. 27 Nov 2009. DWF.
Andy Meigs alerted me to a problem creating a structure when the ncdf variable name
is ill-formed according to IDL structure tag name rules. Fixed in the ReadFile method.
30 November 2009. DWF.
Added NO_NEW_FILE keyword to the BROWSE method. This keyword will suppress the OPEN FILE
button on the browse interface. 3 Feb 2010. DWF.
Made the default browser size a bit larger to accomodate longer variable names. 3 Feb 2010. DWF.
Add a check for HDF/netCDF file type in the INIT method to better accommodate reading data
from the file without first parsing the file. 16 March 2010. DWF.
Changed the ReadVariable for netCDF files to now check for missing data, using either the
depreciated missing_value attribute or the compliant _FillValue attribute. Missing data
is now identified via new output keywords MISSINGINDICES and FILLVALUE, and missing data
is not scaled or offset, if these operations are applied to the data prior to return.
21 March 2010. DWF. Problem with these changes, fixed 23 March 2010. DWF.
Fixed a problem with memory leakage when the input file cannot be read. 1 May 2010. DWF.
Fixed a problem with memory leakage from created structures. 1 May 2010. DWF.
Have done some work on parsing HDF-EOS swath files, but currently unused in code. 15 May 2010. DWF.
Modified the ReadVariable method to check for 0 length dimensions when reading variables
from HDF files. 21 July 2010. DWF.
Modified the global attribute structure so that the "filename" field, which holds the
name of the netCDF of HDF file is now named "ncdf_filename" or "hdf_filename". This
will avoid conflicts with global attributes with "filename". 20 January 2011. DWF.
(See ncdf_data__define.pro)
NAME:
NCDF_DIMENSION
PURPOSE:
The pupose of this NCDF_Dimension object is to store information about
a netCDF dimension. The object is principally used as a utility routine
for the NCDF_FILE object. Given the dimension name, the object will
acquire additional information about the dimension from the netCDF file
containing the dimension.
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:
File I/O
CALLING SEQUENCE:
IDL> dimObj = Obj_New('NCDF_DIMENSION', dimName, parent)
ARGUMENTS:
dimName: The case sensitive name of a netCDF dimension that is stored in the
netCDF file. (Input and required.)
parent: The object reference (NCDF_FILE object) of the netCDF file. In other words, the
object reference of the file that contains this attribute. (Input and required.)
KEYWORD PARAMETERS:
None.
METHODS:
The following methods are available. Each is documented in front of the method.
dimName = dimObject -> GetID()
dimName = dimObject -> GetName()
dimName = dimObject -> GetSize()
propertyValue = dimObject -> GetProperty(dimProperty)
dimValue = dimObject -> GetValue()
dimName = dimObject -> GetUnlimited()
dimObject -> ParseAttribute
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 Feb 2010.
(See ncdf_dimension__define.pro)
NAME:
NCDF_FILE
PURPOSE:
The pupose of this NCDF_File object is three-fold. (1) Allow the user to easily
determine what information is inside a netCDF file and allow easy access
to such information. (2) Allow the user to easily create a netCDF file from
scratch. (3) Allow the user to easily copy information from one netCDF
file to another.
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:
File I/O
CALLING SEQUENCE:
IDL> nCDFObject = Obj_New('NCDF_FILE', filename)
ARGUMENTS:
filename: The name of a netCDF file to read, write to, or browse.
KEYWORD PARAMETERS:
ALERT: Set this keyword if you wish to have alert from the object's error logger.
Input. Default is 1.
BROWSE: If this keyword is set, the Browse Window is invoked as soon
as the object is initiated. Input. Default is 0.
CLOBBER: Set this keyword if you are opening a netCDF file that already exists and
you want to overwrite the existing file. Input. Default is 0.
CREATE: Set this keyword if you wish to create a new netCDF file to write
into. Input. Default is 0, which means the file will be opened as
"read-only".
DELETE_ON_DESTROY: Set this keyword if you wish to delete the error log file when
the ErrorLogger object is destroyed. This will only happen if the ErrorLogger
object is not in an error state. Input. Default is 1.
MODIFY: Set this keyword if you wish to modify (write to) a file you are opening.
If not set, the file will be opened as "read-only".
REQUIRES:
The following programs are required from the Coyote Library. And it is always a
good idea to make sure you have the latest version of the Coyote Library code,
as updates are irregular and frequent.
http://www.dfanning.com/programs/ncdf_attribute__define.pro
http://www.dfanning.com/programs/ncdf_data__define.pro
http://www.dfanning.com/programs/ncdf_browser.pro
http://www.dfanning.com/programs/ncdf_castdatatype.pro
http://www.dfanning.com/programs/ncdf_container__define.pro
http://www.dfanning.com/programs/ncdf_dimension__define.pro
http://www.dfanning.com/programs/ncdf_variable__define.pro
http://www.dfanning.com/programs/errorlogger__define.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/centertlb.pro
http://www.dfanning.com/programs/undefine.pro
http://www.dfanning.com/programs/textbox.pro
http://www.dfanning.com/programs/fsc_base_filename.pro
http://www.dfanning.com/programs/textlineformat.pro
These files may be (almost certainly are!) dependent on other Coyote Library files.
METHODS:
The following methods are available. Each is documented in front of the method.
ncdfObject -> Browse
ncdfObject -> CopyVarAttrTo, varName, attrName, destObj
ncdfObject -> CopyVarDataTo, varName, destObj, COUNT=count, OFFSET=offset, STRIDE=stride
ncdfObject -> CopyVarDefTo, varName, destObj
ncdfObject -> CopyGlobalAttrTo, attrName, destObj
ncdfObject -> CopyDimTo, dimName, destObj
dimNames = ncdfObject -> GetDimNames(COUNT=dimCount)
dimValue = ncdfObject -> GetDimValue(dimName)
fileID = ncdfObject -> GetFileID()
globalAttrNames = ncdfObject -> GetGlobalAttrNames(COUNT=attrCount)
attrValue = ncdfObject -> GetGlobalAttrValue(attrName, DATATYPE=datatype)
ncdfObject -> GetProperty, ....
property = ncdfObject -> GetProperty(thisProperty)
varAttrNames = ncdfObject -> GetVarAttrNames(varName, COUNT=attrCount)
varAttrValue = ncdfObject -> GetVarAttrValue(varName, varAttrName, COUNT=attrCount)
varNames = ncdfObject -> GetVarNames(COUNT=varCount)
varData = ncdfObject -> GetVarData(varName, COUNT=count, OFFSET=offset, STRIDE=stride)
answer = ncdfObject -> HasGlobalAttr(attrName, OBJECT=object)
answer = ncdfObject -> HasDim(dimName, OBJECT=object)
answer = ncdfObject -> HasVar(varName, OBJECT=object)
answer = ncdfObject -> HasVarAttr(varName, attrName, OBJECT=object)
ncdfObject -> PrintFileInfo
ncdfObject -> ParseFile
ncdfObject -> SetMode, DEFINE=define, DATA=data
ncdfObject -> WriteVarData, varName, data, COUNT=count, OFFSET=offset, STRIDE=stride
ncdfObject -> WriteVarDef, varName, dimNames, DATATYPE=datatype, VAROBJ=varObj
ncdfObject -> WriteDim, dimName, dimSize, UNLIMITED=unlimited
ncdfObject -> WriteGlobalAttr, attrName, attrValue, DATATYPE=datatype
ncdfObject -> WriteVarAttr, attrName, attrValue, varObj, DATATYPE=datatype
NOTES:
Note that all variable, attribute, and dimension names in a netCDF file are CASE SENSITIIVE!!
Thus, it is a good idea to use the methods provided in this object to obtain and examine
information in the file, as these names are handled in a case sensitive manner.
Whenever you are creating a new netCDF file, you should try to create the file in
the following way.
1. Create your global attributes.
2. Create the dimensions you will be using to describe the variables.
3. Define the variables. To do this correctly, dimensions MUST be defined.
4. Define variable attributes.
5. Load your variables with data.
Note that the data type of the _FillValue variable attribute MUST match the
data type of the variable data. Otherwise, you will have MANY problems! This
is a common source of error.
Note that in almost all cases where you see the names "varName", "dimName", or
"attrName" used as input variables, you can substitute the proper object
reference in place of the actual name. In other words, you could get the value
of a variable attribute by doing something like this:
check = ncdfObject -> HasAttr('history', OBJECT=attrObj)
IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue(attrObj)
as opposed to this:
IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue('history')
EXAMPLE:
IDL> filename = 'example.nc'
IDL> ncdfObj = Obj_New('NCDF_FILE', filename)
IDL> ncdfObj -> Browse
IDL> Obj_Destroy, ncdfObj
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 Feb 2010, using (stealing, really) plenty of ideas
from Mark Hadfield's Motley Library. Mark's mghncfile object is terrific, but it
had a number of limitations for my particular application, which I have attemped
to correct in my version of the software. But I wouldn't have even attempted this
had Mark not blazed the trail and Matt Savoie not insisted that I look at Mark's
wonderful library.
Changes in the way dimensions with a zero length are handled. 11 Feb 2010, DWF.
Added GetVarInfo method. 20 March 2010. DWF.
Added MISSINGINIDCES and FILLVALUE output keywords to GetVarData method. 20 March 2010. DWF.
Added output keywords SCALE_FACTOR, ADD_OFFSET, and DATATYPE to GetVarData method
so that these values can be obtained with the data. 29 Apr 2010. DWF.
I changed "missingValue" to "fillValue" some time ago, but I missed one in
the GetVarData method. Fixed. 7 June 2010. DWF.
Used the undefine procedure OBJ_DELETE, rather than OBJ_DESTROY. Sheesh! 18 June 2010. DWF.
(See ncdf_file__define.pro)
NAME:
NCDF_FILE_EXAMPLES
PURPOSE:
This is a utility routine demonstrates the several ways it is possible
to use the NCDF_FILE object to create netCDF files, copy information
from one netCDF file to another, and to read information from a netCDF
file.
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:
NCDF_File_Examples
ARGUMENTS:
None.
KEYWORDS:
None.
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 February 2010.
(See ncdf_file_examples.pro)
NAME:
NCDF_ISVALIDFILE
PURPOSE:
Utility routine to determine if a file is a valid netCDF file or not.
Returns a 1 if the file is valid and a 0 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:
result = NCDF_IsValidFile(filename)
INPUTS:
filename: The name of a filename to open to see if it is a valid netCDF file.
RETURN VALUE:
result: A 1 if the file can be opened as a netCDF file. A 0 otherwise.
KEYWORDS:
None.
ALGORITHM:
Try to open the file. If you fail, it is not an netCDF file.
MODIFICATION HISTORY:
Written by: David W. Fanning, 21 February 2010.
(See ncdf_isvalidfile.pro)
NAME:
NCDF_VARIABLE
PURPOSE:
The pupose of this NCDF_Variable object is to store information about
a netCDF variable. The object is principally used as a utility routine
for the NCDF_FILE object. Given the variable name, the object will acquire
additional information about the variable from the netCDF file containing
the variable.
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:
File I/O
CALLING SEQUENCE:
IDL> varObj = Obj_New('NCDF_VARIABLE', varName, parent)
ARGUMENTS:
varName: The case sensitive name of a netCDF variable that is stored in the
netCDF file. (Input and required.)
parent: The object reference (NCDF_FILE object) of the netCDF file. In other words, the
object reference of the file that contains this attribute. (Input and required.)
KEYWORD PARAMETERS:
None.
METHODS:
The following methods are available. Each is documented in front of the method.
varObject -> AddAttr
varAttrNames = varObject -> GetAttrNames()
dimIDs = varObject -> GetDimIDs()
dimNames = varObject -> GetDimNames()
varAttrValue = varObject -> GetAttrValue()
varID = varObject -> GetID()
varName = varObject -> GetName()
propertyValue = varObject -> GetProperty(attrProperty)
varValue = varObject -> GetValue()
varObject -> ParseVariable
MODIFICATION HISTORY:
Written by: David W. Fanning, 3 Feb 2010.
Changes to the way dimensions of length 0 are handled. 11 Feb 2010. DWF.
Added GetInfo method. 20 Mar 2010. DWF.
Added MISSINGINDICES and FILLVALUE keywords to GetValue method to return the indices
and the value of missing data. 20 Mar 2010. DWF.
Modified the GetValue method so that if the data returned is scaled and/or offset
then the "missing" data value is preserved, although its data type may change.
In other words, the "missing" data is not scaled or offset. 20 Mar 2010. DWF.
Added output keywords SCALE_FACTOR, ADD_OFFSET, and DATATYPE to the GetValue method
so that these values can be returned to the caller at run-time. 29 April 2010. DWF.
(See ncdf_variable__define.pro)
NAME:
NUMBER_FORMATTER
PURPOSE:
This is a utility routine format a number into a string. It is
used primarily for formatting numbers that will appear in
text widgets in widget programs.
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, Widget Programming
CALLING SEQUENCE:
numberAsString = Number_Formatter(number)
ARGUMENTS:
number: The number to be turned into a string. May be any data type
except complex, double complex, pointer or object. Must be a scalar.
KEYWORDS:
DECIMALS: Set this keyword to the number of decimal places to
be included to the right of the decimal point in floats
and doubles. Set to 2 by default.
RETURN VALUE:
numberAsString: A string representation of the number.
COMMON BLOCKS:
None.
EXAMPLES:
IDL> Print, Number_Formatter(16.837574837e-14)
1.683757e-13
IDL> Print, Number_Formatter(16.837574837e-14, Decimals=2)
1.68e-13
RESTRICTIONS:
None.
MODIFICATION HISTORY:
Written by: David W. Fanning, 9 March 2006.
Fixed a small problem when presented with a number that ends in a decimal
after conversion to a string. 3 January 2007. DWF.
Small changes to do all calculations in DOUBLE and LONG64. 22 February 2007. DWF.
Made it possible to pass a vector of numbers to the program. 18 August 2007. DWF.
(See number_formatter.pro)
NAME:
OBJECT_SHADE_SURF
PURPOSE:
This program shows you the correct way to write an
elevation-shaded surface in object graphics. This would
be the equivalent of these direct graphics commands:
Surface, data, Shades=BytScl(data)
Shade_Surf, data, Shades=BytScl(data)
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:
Object Graphics
CALLING SEQUENCE:
OBJECT_SHADE_SURF, data, x, y
INPUTS:
data: The 2D surface data.
x: A vector of X values, corresponding to the X values of data.
y: A vector of Y values, corresponding to the Y values of data.
KEYWORD PARAMETERS:
STYLE: Set equal to 1 for a wire-frame surface. Set equal to 2 for
a solid surface (the default).
COMMON BLOCKS:
None.
EXAMPLE:
OBJECT_SHADE_SURF
MODIFICATION HISTORY:
Written by: David Fanning, November 1998.
(See object_shade_surf.pro)
NAME:
OWINDOW
PURPOSE:
The purpose of this program is to create an object window.
I use it mostly when I am creating and testing object graphics
programs, but it is also a nice template for larger object
graphics programs. The window is resizeable and it destroys
its objects when it is destroyed.
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, IDL 5 Object Graphics.
CALLING SEQUENCE:
thisWindow = OWindow(thisView)
REQUIRED INPUTS:
None. A default view object is created with a gray background and
a viewplane rectangle defined as [0,0,1,1].
OPTIONAL INPUTS:
thisView: A view or scene object that you wish to be displayed
in the window.
RETURN VALUE:
thisWindow: The window graphics object associated with this window.
OPTIONAL KEYWORD PARAMETERS:
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
TITLE: A string used as the title of the graphics window.
XSIZE: The X Size of the graphics window in device coordinates. The
default value is 300.
YSIZE: The Y Size of the graphics window in device coordinates. The
default value is 300.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To display a view object in this window, type:
IDL> thisWindow = OWindow(thisView)
Later, after you have modified the view object, you can type:
IDL> thisWindow->Draw, modifiedView
MODIFICATION HISTORY:
Written by David Fanning, 19 June 97.
Set RETAIN=1 on draw widget. 6 Oct 97. DWF.
Changed discredited IDLgrContainer to IDL_Container. 29 JUN 98. DWF.
Modified draw widget to use RETAIN=2 and do away with expose events. 6 May 2011. DWF.
(See owindow.pro)
NAME:
PICKCOLOR
PURPOSE:
A modal dialog widget allowing the user to select
the RGB color triple specifying a color. The return
value of the function is the color triple specifying the
color or the "name" of the color if the NAME keyword is set.
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. See related program cgColor.
CALLING SEQUENCE:
color = PickColor(colorindex)
RETURN VALUE:
The return value of the function is a 1-by-3 array containing
the values of the color triple that specifies the selected color.
The color can be loaded, for example, in any color index:
color = PickColor(240)
TVLCT, color, 240
The return value is the original color triple if the user
selects the CANCEL button.
IF the NAMES keyword is set, the return value of the function is
the "name" of the selected color. This would be appropriate for
passing to the cgColor program, for example.
OPTIONAL INPUT POSITIONAL PARAMETERS:
COLORINDEX: The color index of the color to be changed. If not
specified the color index !D.Table_Size - 2 is used.
The Current Color and the Color Sliders are set to the
values of the color at this color index.
OPTIONAL INPUT KEYWORD PARAMETERS:
BREWER: Set this keyword if you wish to use the Brewer Colors, as defined
in this reference:
http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
GROUP_LEADER: The group leader for this widget program. This
keyword is required for MODAL operation. If not supplied
the program is a BLOCKING widget. Be adviced, however, that
the program will NOT work if called from a blocking widget
program, unless a GROUP_LEADER is supplied.
NAMES: Set this keyword to return the "name" of the selected color
rather than its color triple.
STARTINDEX: 88 pre-determined colors are loaded The STARTINDEX
is the index in the color table where these 88 colors will
be loaded. By default, it is !D.Table_Size - 89.
TITLE: The title on the program's top-level base. By default the
title is "Pick a Color".
OPTIONAL INPUT KEYWORD PARAMETERS:
CANCEL: A keyword that is set to 1 if the CANCEL button is selected
and to 0 otherwise.
COMMON BLOCKS:
None.
SIDE EFFECTS:
88 pre-determined colors are loaded in the color table.
In addition, the color index at COLORINDEX is modified while
the program is on the display. When the program exits, the
entry color table is restored. Thus, on 8-bit displays there
might be some color effects in graphics windows while PICKCOLOR
is on the display. Changes in the color table are not noticable
on 16-bit and 24-bit displays.
EXAMPLE:
To specify a color for a plot in color decomposition OFF mode:
Device, Decomposed=0
!P.Color = !P.Color < (!D.Table_Size - 1)
color = PickColor(!P.Color, Cancel=cancelled)
IF NOT cancelled THEN BEGIN
TVLCT, color, !P.Color
Plot, data
ENDIF
To specify a color for a plot in color decomposition ON mode:
Device, Decomposed=1
color = PickColor(Cancel=cancelled)
!P.Color = Color24(color)
IF NOT cancelled THEN Plot, data
To obtain the name of the selected color to pass to GetColor:
selectedColor = PickColor(/Name)
axisColor = cgColor(selectedColor, !D.Table_Size-4)
MODIFICATION HISTORY:
Written by: David Fanning, 28 Oct 99.
Added NAME keyword. 18 March 2000, DWF.
Fixed a small bug when choosing a colorindex less than !D.Table_Size-17. 20 April 2000. DWF.
Added actual color names to label when NAMES keyword selected. 12 May 2000. DWF.
Modified to use 88 colors and cgColor instead of 16 colors and GETCOLOR. 4 Dec 2000. DWF.
Now drawing small box around each color. 13 March 2003. DWF.
Added CURRENTCOLOR keyword. 3 July 2003. DWF.
Added BREWER keyword. 15 May 2008. DWF.
Fixed a couple of problems with outline color. 19 May 2008. DWF.
Added all the colors available from cgColor. 28 Nov 2010. DWF.
(See pickcolor.pro)
NAME:
PICKCOLORNAME
PURPOSE:
The purpose of this program is to provide a blocking
or modal widget interface for selecting a color "name".
The program uses colors familiar to the cgColor program,
and is often used to select a color name for passing to cgColor.
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:
colorName = PickColorName(startColorName)
OPTIONAL INPUT PARAMETERS:
startColorName: A string with the "name" of the color. Colors available are these:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Cadet Blue Charcoal
Chartreuse Chocolate Coral Cornflower Blue Cornsilk Crimson
Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki Dark Orchid
Dark Red Dark Salmon Dark Slate Blue Deep Pink Dodger Blue Firebrick
Forest Green Gold Goldenrod Gray Green Green Yellow
Honeydew Hot Pink Indian Red Ivory Khaki Lavender
Lawn Green Light Coral Light Cyan Light Gray Light Salmon Light Sea Green
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Blue Slate Gray Snow
Spring Green Steel Blue Tan Teal Thistle Tomato
Turquoise Violet Violet Red Wheat White Yellow
The color WHITE is used if this parameter is absent.
If the BREWER keyword is set, you can use the Brewer Color names:
WT1 WT2 WT3 WT4 WT5 WT6 WT7 WT8
TAN1 TAN2 TAN3 TAN4 TAN5 TAN6 TAN7 TAN8
BLK1 BLK2 BLK3 BLK4 BLK5 BLK6 BLK7 BLK8
GRN1 GRN2 GRN3 GRN4 GRN5 GRN6 GRN7 GRN8
BLU1 BLU2 BLU3 BLU4 BLU5 BLU6 BLU7 BLU8
ORG1 ORG2 ORG3 ORG4 ORG5 ORG6 ORG7 ORG8
RED1 RED2 RED3 RED4 RED5 RED6 RED7 RED8
PUR1 PUR2 PUR3 PUR4 PUR5 PUR6 PUR7 PUR8
PBG1 PBG2 PBG3 PBG4 PBG5 PBG6 PBG7 PBG8
YGB1 YGB2 YGB3 YGB4 YGB5 YGB6 YGB7 YGB8
RYB1 RYB2 RYB3 RYB4 RYB5 RYB6 RYB7 RYB8
TG1 TG2 TG3 TG4 TG5 TG6 TG7 TG8
As of 3 JULY 2008, the BREWER names are always available. If the BREWER keyword is set, only
the BREWER names are available.
INPUT KEYWORD PARAMETERS:
BOTTOM: The colors used in the program must be loaded somewhere
in the color table. This keyword indicates where the colors
start loading. By default BOTTOM is set equal to !D.Table_Size-NCOLORS-1.
BREWER: Set this keyword if you wish to use the Brewer Colors, as defined
in this reference:
http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
COLUMNS: Set this keyword to the number of columns the colors should
be arranged in.
FILENAME: The string name of an ASCII file that can be opened to read in
color values and color names. There should be one color per row
in the file. Please be sure there are no blank lines in the file.
The format of each row should be:
redValue greenValue blueValue colorName
Color values should be between 0 and 255. Any kind of white-space
separation (blank characters, commas, or tabs) are allowed. The color
name should be a string, but it should NOT be in quotes. A typical
entry into the file would look like this:
255 255 0 Yellow
GROUP_LEADER: This identifies a group leader if the program is called
from within a widget program. Note that this keyword MUST be provided
if you want to guarantee modal widget functionality. (If you don't know
what this means, believe me, you WANT to use this keyword, always.)
INDEX: This keyword identifies a color table index where the selected color
is to be loaded when the program exits. The default behavior is to restore
the input color table and NOT load a color.
TITLE: This keyword accepts a string value for the window title. The default
is "Select a Color".
OUTPUT KEYWORD PARAMETERS:
CANCEL: On exit, this keyword value is set to 0 if the user selected
the ACCEPT button. IF the user selected the CANCEL button, or
closed the window in any other way, this keyword value is set to 1.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Colors are loaded in the current color table. The input color table
is restored when the program exits. This will only be noticable on
8-bit displays. The startColorName is returned if the user cancels
or destroys the widget before a selection is made. Users should
check the CANCEL flag before using the returned color.
EXAMPLE:
To call the program from the IDL comamnd line:
IDL> color = PickColorName("red") & Print, color
To call the program from within a widget program:
color = PickColorName("red", Group_Leader=event.top) & Print, color
MODIFICATION HISTORY:
Written by: David W. Fanning, 31 August 2000.
Modified program to read colors from a file and to use more
colors on 24-bit platforms. 16 October 2000. DWF.
Added the COLUMNS keyword. 16 October 2000. DWF.
Fixed a small problem with mapping a modal widget. 2 Jan 2001. DWF
Now drawing small box around each color. 13 March 2003. DWF.
Added eight new colors. Total now of 104 colors. 11 August 2005. DWF.
Modified GUI to display system colors. 13 Dec 2005. DWF.
Added BREWER keyword to allow Brewer Colors. 15 May 2008. DWF.
Added all BREWER names to the default naming scheme. 3 July 2008. DWF.
Set a size for the color name label widget. Otherwise, the widget always
jumps back to the center of the display when I select a color on UNIX
machines. Also had to remove TLB updating with UPDATE keyword to avoid
tickling the same IDL bug. Sigh... 13 March (Friday) 2009.
Removed system color names, since these are no longer available in cgColor.
27 Nov 2010. DWF
(See pickcolorname.pro)
NAME:
PrecipMap
PURPOSE:
This is a program that demonstrates how to place an IDL map projection
onto an image that is already in a map projection space. It uses a NOAA
precipitation image that is in a polar stereographic map projection, and
for which the latitudes and longitudes of its four corners are known.
For additional details, see http://www.dfanning.com/map_tips/precipmap.html.
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:
Map Projection
CALLING SEQUENCE:
IDL> PrecipMap, filename
INPUTS:
filename: The name of the precipitation file. For demo, download
ST4.2005010112.24h.bin from ftp://ftp.dfanning.com/pub/dfanning/outgoing/misc.
RESTRICTIONS:
Requires files from the Coyote Library:
http://www.dfanning.com/documents/programs.html
MODIFICATION HISTORY:
Written by David W. Fanning, 28 April 2006 from code and discussion supplied
by James Kuyper in the IDL newsgroup.
Renamed Colorbar procedure to cgColorbar to avoid conflict with IDL 8 Colorbar function.
26 September 2010. DWF.
(See precipmap.pro)
NAME:
PRINTWINDOW
This program sends the contents of the specified
window to the default printer. The current window
is used if a window index number is not provided.
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:
IDL> PrintWindow, wid
OPTIONAL POSITIONAL PARAMETERS:
WID The window index number of the window to send to the
printer. !D.Window used by default.
KEYWORD PARAMETERS:
LANDSCAPE If this keyword is set, the output is in Landscape
mode. Otherwise, Portrait mode is used.
PAGESIZE: Set this keyword to a string indicating the type
of PostScript page size you want. Current values are "LETTER",
"LEGAL", and "A4". Default is "LETTER".
RGB_ERROR: Some printers (particularly attached to LINUX machines) cannot
load a 24-bit image. You get this error message:
%Can't set RGB color on an indexed destination.
If this happens to you, set this keyword and the 24-bit image will
be made into a 2D image with color table vectors. Colors are not
quaranteed to be accurate with this method, but in practice it is
not usually too bad.
IDL> PrintWindow, /RGB_Error
MODIFICATION HISTORY:
Written by David W. Fanning based on previous PRINT_IT program. 29 July 2000.
Added RGB_Error keyword. 2 Nov 2004. DWF.
(See printwindow.pro)
NAME:
ProgramRootDir
PURPOSE:
The purpose of this function is to provide a portable way of finding
the root directory of a program distribution. The directory that is returned
is the directory in which the source file using ProgramRootDir resides.
The program is useful for distributing applications that have a large number
of files in specific program directories.
AUTHOR:
FANNING SOFTWARE CONSULTING
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
SYNTAX:
theDirectory = ProgramRootDir()
RETURN_VALUE:
theDirectory: The directory in which the program module running ProgramRootDir resides.
ARGUMENTS:
None.
KEYWORDS:
NOMARK: Normally, the directory that is returned contains a path separator at its
end, so that the directory can easily be concatinated with other file names.
If this keyword is set, the final path separator mark is removed from the
directory name.
ONEUP: Set this keyword if you want to start your search one directory
*above* where your source program resides (i.e., "../Source").
This allows you, for example, to put your source files in a Source
directory that it at the same level as your Data directory, Utility
directory, etc. See the example below.
TWOUP: Set this keyword if you want to start your search two directories
*above* where your source program resides (i.e., "../../Source").
EXAMPLE:
Assume that your application files (and source programs) reside in this root directory:
../app
You have placed a DATA directory immediately under the APP directiory, and a RESOURCES
directory immedately under the DATA directory. Your directory structure looks like this:
../app ; Contains your application and source (*.pro) files.
../app/data ; Contains your application data files.
...app/data/resources ; Contains your application resource files.
The end user can install the APP directory wherever he or she likes. In your
program, you will identify the DATA and RESOURCES directory like this:
; Get icon image in resources directory.
filename = Filepath(Root_Dir=ProgramRootDir(), Subdirectory=['data','resources'], 'myicon.tif')
; Get default image in data directory.
filename = Filepath(Root_Dir=ProgramRootDir(), Subdirectory='data', 'ctscan.tif')
Alternatively, you might set up an application directory structure like this:
../app ; Contains your application files.
../app/source ; Contains your application source (*.pro) files.
../app/data ; Contains your application data files.
...app/data/resources ; Contains your application resource files.
In this case, you would use the ONEUP keyword to find your data and resource files, like this:
; Get icon image in resources directory.
filename = Filepath(Root_Dir=ProgramRootDir(/ONEUP), Subdirectory=['data','resources'], 'myicon.tif')
; Get default image in data directory.
filename = Filepath(Root_Dir=ProgramRootDir(/ONEUP), Subdirectory='data', 'ctscan.tif')
MODIFICATION_HISTORY:
Written by: David W. Fanning, 23 November 2003. Based on program SOURCEROOT, written by
Jim Pendleton at RSI (http://www.rsinc.com/codebank/search.asp?FID=35).
Added ONEUP keyword. 10 December 2003. DWF.
Added TWOUP keyword. 8 June 2007. DWF.
Added NOMARK keyword. 8 June 2007. DWF.
(See programrootdir.pro)
NAME:
PROGRESSBAR__DEFINE
PURPOSE:
Creates a simple progress bar for indicating the progess of a looping
operation in IDL.
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:
progressBar = Obj_New("PROGRESSBAR")
ARGUMENTS:
None.
KEYWORDS:
BACKGROUND: The name of the background color of the progress bar. By default, "black".
COLOR: The name of the color for the progress bar. By default: "red".
Possible color names are those defined by cgColor:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Charcoal Chartreuse
Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray
Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue
Firebrick Forest Green Gold Goldenrod Gray Green
Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki
Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Gray Snow Spring Green
Steel Blue Tan Thistle Tomato Turquoise Violet
Violet Red Wheat White Yellow
FAST_LOOP: Set this keyword if what you are doing in the loop doesn't involve
any color operations and you want the progress bar to update as fast
as possible. With this keyword set, the program will eliminate extra
calls to cgColor, which can be slow if you are calling it, say,
10,000 times!
GROUP_LEADER: The group leader for the progress bar.
NOCANCEL: Set this keyword to eliminate the CANCEL button from the progres bar.
PERCENT: The initial percent on the progress bar. Used only if the START keyword is
also set.
START: Set this keyword if you wish to call the START method immediately upon initialization.
TEXT: The textual message that goes above the progress bar. By default:
"Operation in progress..."
TITLE: The title of the progress bar window. By default: "Progress Bar".
XSIZE: The X size of the progress bar itself. By default, 150 pixels.
YSIZE: The Y size of the progress bar itself. By default, 10 pixels.
PROCEDURE:
The user is responsible for starting, updating, checking for CANCEL events, and
destroying the progress indicator. The sequence of commands might look
like this:
progressBar = Obj_New("PROGRESSBAR")
progressBar -> Start
FOR j=0,9 DO BEGIN
IF progressBar -> CheckCancel() THEN BEGIN
ok = Dialog_Message('The user cancelled operation.')
RETURN
ENDIF
Wait, 0.5 ; Would probably be doing something ELSE here!
progressBar -> Update, (j+1)*10
ENDFOR
progressBar -> Destroy
See the example program at the end of this file for a working example of code.
METHODS:
CHECKCANCEL: This function method returns a 1 if the user has clicked
the CANCEL button. Otherwise, it returns a 0.
cancelled = progressBar -> CheckCancel()
IF cancelled THEN progressBar->Destroy
DESTROY: Destroys the progress bar widgets as well as the object.
progressBar -> Destroy
GETPROPERTY: Gets certain properties of the object.
progressBar -> GetProperty, Color=currentColor
SETPROPERTY: Allows the user to set certain properties of the object.
progressBar -> SetProperty, Color='green'
START: Puts the progress bar on the display and enables it to receive events.
progressBar -> Start
UPDATE: Updates the progress bar. Requires on argument, a number between 0
and 100 that indicates the percent of progress bar that should be filled
with a color. Can optional specify TEXT that is displayed above the progress
bar.
progressBar -> Update, 50
progressBar -> Update, 50, Text='Operation 50% completed...'
EXAMPLE:
See the example program at the bottom of this file.
RESTRICTIONS:
Note that the progress bar cannot be run as a MODAL widget program and
still capture CANCEL button events. Thus, the user *may* be able to generate events
in the calling program while this progress bar is in operation.
DEPENDENCIES:
This program requires cgColor from the Coyote Library:
http://www.dfanning.com/programs/cgColor.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 19 September 2002.
Added TEXT keyword to Update method. 12 Nov 2002. DWF.
Added FAST_LOOP keyword. 19 Dec 2002. DWF.
Fixed a problem in where I was checking for CANCEL button event. 2 April 2003. DWF.
Removed the XMANAGER call in the START method, since it wasn't needed. 7 October 2003. DWF.
General maintenance updates. Added START keyword to INIT method to allow immediate
starting upon initialization. Added better error handling and checking. 10 October 2003. DWF.
Added ACCEPT button and CheckButton method. Modified Example program to demonstrate new
functionality. 1 December 2003. DWF.
Added XOFFSET and YOFFSET keywords. 4 March 2004. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Added keyword keyword TITLE to Update method. 23 Feb 2005. Benjamin Hornberger
Added BACKGROUND keyword. 22 Dec 2006. DWF.
Added RETAIN=1 keyword to Widget_Draw command. 9 Dec 2007. DWF.
(See progressbar__define.pro)
NAME:
PSCONFIG
PURPOSE:
This program is simply a function wrapper for the FSC_PSCONFIG
object program (fsc_psconfig__define.pro). It was written so
that it could serve as a drop-in replacement for the PS_FORM
program it replaces. It calls the object program's graphical
user interface as a modal widget and returns the DEVICE keywords
collected from the form in a form that is appropriate for
configuring the PostScript device.
It is now possible to call the program without a graphical user
interface, thus getting the default keywords directly. This is
appropriate for many applications. Use the NOGUI keyword when
you call the program. For example, like this:
Set_Plot, 'PS'
Device, _Extra=PSConfig(/NoGUI, Filename='myfilename.eps')
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/
CALLING SEQUENCE:
psKeywords = PSConfig()
CATEGORY:
Configuring PostScript output.
DOCUMENTATION:
Complete documentation for the FSC_PSCONFIG object, including
keyword and method descriptions, and example programs using the object
can be found on the Coyote's Guide to IDL Programming web page:
http://www.dfanning.com/programs/docs/fsc_psconfig.html
INPUT:
psConfigObject -- An optional FSC_PSCONFIG object reference can be
passed as an argument to the function. The object is not destroyed
if passed in as an argument.
psConfigObject = Obj_New("FSC_PSCONFIG")
keywords = PSConfig(psConfigObject)
Having the object means that you have an on-going and current record
of exactly how your PostScript device is configured. Be sure to destroy
the object when you are finished with it.
KEYWORDS:
NOGUI: Setting this keyword returns the default keyword settings directly,
without allowing user interaction.
Any keyword accepted by the FSC_PSCONFIG object can be used with
this program. Here are a few of the most popular keywords.
Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
Color - Set this keyword to select Color PostScript output. Turned on by default.
Decomposed - Set this keyword to turn on 24-bit color support. Set to zero to select indexed color
support. Default is 0. Applies only to IDL versions 7.1 and higher.
DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
create and add your own to the source code) are the following:
"System (Portrait)" - The normal "default" system set-up. Also, "System".
"System (Landcape)" - The normal "default" landscape system set-up.
"Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
"Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
"Square (Portrait)" - A square plot, centered on the page.
"Square (Landscape)" - A square plot, centered on the landscape page.
"Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
"Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
"Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
"Color (Landscape)" - A "centered" landscape plot, with color turned on.
Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
Encapsulated - Set this keyword to select Encapsulated PostScript output. Turned off by default.
European - This keyword is depreciated in favor or "METRIC".
Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by Metric keyword by default.
Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
Match - If this keyword is set, the initial PostScript window will match the aspect ratio of the current graphics window.
Metric - Set this keyword to indicate metric mode (i.e., A4 page and centimeter units). Turned off by default.
NoGUI - Set this keyword if you don't want a graphical user interface, but just want to get the return structure.
PageType - Set this keyword to the "type" of page. Possible values are:
"Letter" - 8.5 by 11 inches. (Default, unless the Metric keyword is set.)
"Legal" - 8.5 by 14 inches.
"Ledger" - 11 by 17 inches.
"A4" - 21.0 by 29.7 centimeters. (Default, if the Metric keyword is set.)
XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.
In addition, the following keywords can be used:
CANCEL -- An output keyword that will be set to 1 if the user
chooses the Cancel button on the form. It will be 0 otherwise.
FONTINFO -- Set this keyword is you wish to have font information
appear on the form. The default is to not include font information.
FONTTYPE -- Set this keyword to a named variable that will indicate
the user's preference for font type. Values will be -1 (Hershey fonts),
0 (hardware fonts), and 1 (true-type fonts). This keyword will always
return -1 unless the FONTINFO keyword has also been set.
GROUP_LEADER -- Set this keyword to a widget identifier of the widget
you wish to be a group leader for this program.
EXAMPLE:
To have the user specify PostScript configuration parameters, use
the program like this:
keywords = PSConfig(Cancel=cancelled)
IF cancelled THEN RETURN
thisDevice = !D.Name
Set_Plot, 'PS'
Device, _Extra=keywords
Plot, findgen(11) ; Or whatever graphics commands you use.
Device, /Close_File
Set_Plot, thisDevice
OTHER PROGRAMS NEEDED:
The following programs are required to run this one:
fsc_droplist.pro
fsc_fileselect.pro
fsc_inputfield.pro
fsc_plotwindow
fsc_psconfig__define.pro
MODIFICATIONS:
Written by David W. Fanning, 31 January 2000.
Added NOGUI keyword to allow default keywords to be obtained without
user interaction. 11 Oct 2004. DWF.
Added CMYK option 24 August 2007. Requires LANGUAGE_LEVEL=2 printer. L. Anderson
Updated for IDL 7.1 and 24-bt color PostScript support. 24 May 2009. DWF.
Added MATCH keyword. 14 Dec 2010. DWF.
Changed ENCAPSULATE keyword to ENCAPSULATED, which is what I always type! 29 Jan 2011. DWF.
Depreciated EUROPEAN keyword in favor of METRIC. 31 Jan 2011. DWF.
(See psconfig.pro)
NAME:
PSWINDOW
PURPOSE:
This function is used to calculate the size of a PostScript
window that has the same aspect ratio (ratio of height to
width) as the current display graphics window. It creates
the largest possible PostScript output window with the
desired aspect ratio. This assures that PostScript output
looks similar, if not identical, to normal graphics output
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:
Graphics.
CALLING SEQUENCE:
pageInfo = PSWINDOW()
INPUTS:
None.
KEYWORD PARAMETERS:
ASPECTRATIO: Normally the aspect ratio is matched to the
aspect ratio (ratio of height divided by width) of the current
graphics window. However, this keyword can be used to select
a particular aspect ratio for the PostScript window. This should
be a floating point value.
CM: Normally the structure value that is returned from this
function reports its values in inches. Setting this keyword
causes the return values to be in units of centimeters.
EUROPEAN: This keyword is depreciated in favor of METRIC.
FUDGE: A quick way to set symetrical XFUDGE and YFUDGE factors.
If this keyword is set to a value, XFUDGE and YFUDGE keywords are
set to the same value. Fudge factors are used only with some
printers and generally only when output is being sent to the
PRINTER device. (See the description of the XFUDGE and YFUDGE
keywords for additional information.)
LANDSCAPE: Normally, a landscape page is selected if the current
graphics window is wider than it is tall. If you prefer a landscape
aspect window on a Portrait page, set the LANDSCAPE keywword to 0.
Setting this keyword to 1 will result in a landscape page no
matter the size of the current graphics window.
MARGIN: The margin around the edges of the plot. The value must be
a floating point value between 0.0 and 0.35. It is expressed in
normalized coordinate units. The default margin is 0.05.
METRIC: If this keyword is set, the program defaults change
so that the CM keyword is set to 1 and the PAGESIZE keyword is
set to "A4".
PAGESIZE: Set this keyword to a string indicating the type
of PostScript page size you want. Current values are "LETTER",
"LEGAL", and "A4". Default is "LETTER".
PRINTER: Set this keyword if the output will be used to
configure the PRINTER device, rather than the PS device.
(In the PRINTER device, offsets are always calculated from
the lower-left corner of the page and do not rotate in
Landscape mode, as they do with the PS device.) Note that
the PRINTER device is only able to accept these keywords
in IDL 5.1 and higher.
XFUDGE: Printers calculate the offset point from the printable
edge of the paper (sometimes), rather from the corner of the paper.
For example, on my Lexmark printer, both X and Y offsets are
calculated from a point 0.25 inches in from the edge. This keyword
allows you to set a "fudge" factor that will be subtracted from
the XOFFSET that is returned to the user. This allows you to create
output that is centered on the page. The fudge factor should be in
the same units as the returned size and offset values.
YFUDGE: Printers calculate the offset point from the printable
edge of the paper (sometimes), rather from the corner of the paper.
For example, on my Lexmark printer, both X and Y offsets are
calculated from a point 0.25 inches in from the edge. This keyword
allows you to set a "fudge" factor that will be subtracted from
the YOFFSET that is returned to the user. This allows you to create
output that is centered on the page. The fudge factor should be in
the same units as the returned size and offset values.
OUTPUTS:
pageInfo: The output value is a named structure defined like
this:
pageInfo = {PSWINDOW_STRUCT, XSIZE:0.0, YSIZE:0.0, $
XOFSET:0.0, YOFFSET:0.0, INCHES:0, PORTRAIT:0, LANDSCAPE:0}
The units of the four size fields are inches unless the CM
keyword is set.
The output can be used to immediately configure the PostScript
or Printer device, like this:
Set_Plot, 'PS' ; or 'PRINTER'
Device, _Extra=pageInfo
RESTRICTIONS:
The aspect ratio of the current graphics window is calculated
like this:
aspectRatio = FLOAT(!D.Y_VSIZE) / !D.X_VSIZE
EXAMPLE:
To create a PostScript output window with the same aspect
ratio as the curently active display window, type:
pageInfo = PSWINDOW()
SET_PLOT, 'PS'
DEVICE, _Extra=pageInfo
To configure the PRINTER device:
pageInfo = PSWINDOW(/Printer, Fudge=0.25)
SET_PLOT, 'PRINTER'
DEVICE, _Extra=pageInfo
MODIFICATION HISTORY:
Written by: David W. Fanning, November 1996.
Fixed a bug in which the YOFFSET was calculated incorrectly
in Landscape mode. 12 Feb 97.
Took out a line of code that wasn't being used. 14 Mar 97.
Added correct units keyword to return structure. 29 JUN 98. DWF
Fixed a bug in how landscape offsets were calculated. 19 JUL 99. DWF.
Fixed a bug in the way margins were used to conform to my
original conception of the program. 19 JUL 99. DWF.
Added Landscape and Portrait fields to the return structure. 19 JUL 99. DWF.
Added PageSize keyword, changed MARGIN keyword, and completely
rewrote most of the intenal code. 9 FEB 2000. DWF.
Fixed a bug in how I calculated the aspect ratio. 1 MAR 2000. DWF.
Added PRINTER keyword to return proper offset values for the
PRINTER device, where the offset location is not rotated. 1 MAR 2000. DWF.
Added PRINTER fudge factors to take into account that printer offsets are
calculated from the printable area of the paper, rather than the corner
of the paper. 8 AUG 2000. DWF.
Changed the default margin to 0.05 from 0.15. 29 Nov 2004, DWF.
Added EUROPEAN keyword and set LANDSCAPE mode if window wider than higher
as the default if LANDSCAPE is not set. 13 Dec 2010. DWF.
Added ASPECTRATIO keyword to allow user-specified window aspect ratio. 13 Dec 2010. DWF.
Depreciated EUROPEAN keyword in favor of METRIC. 31 Jan 2011. DWF.
(See pswindow.pro)
:Description:
Provides a device-independent way to set the background color in the PostScript device.
:Categories:
Graphics, Utilities
:Params:
color: in, required, type=string/integer, default='white'
The color that is used for the PostScript background. A polygon of
this color is written to the PostScript file and fills the PostScript
"window".
:Examples:
IDL> PS_Background, 'rose'
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 17 November 2010. DWF.
Modified to use gcColorFill so that color is done with decomposed color. 24 Dec 2010. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See ps_background.pro)
NAME:
PS_END
PURPOSE:
The purpose of PS_START and PS_END is to make it easy to set-up
for and close a PostScript file. The programs work in close conjunction
with PSCONFIG, another program from the Coyote Library.
If ImageMagick (http://www.imagemagick.org/script/index.php) is installed
on your computer, you can easily convert PostScript output to JPEG, PNG, and TIFF
image output. (See the keywords to PS_END.)
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, File Output, PostScript
CALLING SEQUENCE:
PS_START
Various graphics commands here...
PS_END
KEYWORD PARAMETERS FOR PS_END:
All keywords for PS_END require that ImageMagick is installed on your computer
and is configured correctly. Image conversion is done by spawning a "convert"
command to ImageMagick.
ALLOW_TRANSPARENT: To make the background of some image files white, rather than transparent,
you have to set the "-alpha off" string in the ImageMagick call. This
string is automatically added to the ImageMagick call unless this keyword
is set, in which case the string is not added and the image background will
be transparent. (See RESTRICTIONS note below for more information.)
DELETE_PS: This keyword will delete the PostScript file that is created to make
other raster file types. It is only used if the PostScript file is being
converted to a raster file type with ImageMagick.
DENSITY: The horizontal and vertical density of the image when the PostScript file
is converted to an image format by ImageMagick. By default, 300. Use this
keyword to set another value.
GIF: Set this keyword to convert the PostScript output file to a GIF image.
JPEG: Set this keyword to convert the PostScript output file to a JPEG image.
NOFIX: If this keyword is set, then the FixPS program to fix IDL landscape
PostScript files is not called.
PNG: Set this keyword to convert the PostScript output file to a PNG image.
IM_OPTIONS: A string of ImageMagick "convert" options that can be passed to
the ImageMagick convert command. By default, a null string. No
error checking occurs with this string.
RESIZE: If an image is being created from the PostScript file, it is often
resized by some amount. The default value is 25 percent. You can use
this keyword to change the value to some other amount (e.g, RESIZE=100).
The value is passed on to resize argument as a percentage in the
ImageMagick call.
TIFF: Set this keyword to convert the PostScript output file to a TIFF image.
The convert command looks like this. You can modify it in the code if you want it to
do something else for you.
convert inputPostScriptFilename -resize 50% -density 300 -alpha off outputImageFilename
COMMON BLOCKS:
_$FSC_PS_START_ Contains the PS_STRUCT structure for communication between
PS_START and PS_END.
SIDE EFFECTS:
When PS_START is called, the current graphics device is set to "PS" (the PostScript
device). When PS_END is called the current graphics device is returned to the device
in effect when PS_START was called.
RESTRICTIONS:
Requires numerous programs from the Coyote Library. To convert PostScript files
to PNG, JPEG, and TIFF files requires ImageMagick be installed on your
computer and configured correctly. You can download Coyote Library programs here:
http://www.dfanning.com/programs/coyoteprograms.zip
ImageMagick can be found here:
http://www.imagemagick.org/script/index.php
NOTE: In this version of PS_END, I have added the "alpha" option to the ImageMagick
command. This is a relatively recent addition to the convert command. (Added in ImageMagick
version 6.3.4). I believe PS_END can discover which version of ImageMagick you are useing
and act accordingly, but if it can't, set this alpha option to your liking.
EXAMPLE:
To create a line plot in a PostScript file named lineplot.ps and
also create a PNG file named lineplot.png for display in a browser,
type these commands.
PS_Start, FILENAME='lineplot.ps'
Plot, Findgen(11), COLOR=cgColor('navy'), /NODATA, XTITLE='Time', YTITLE='Signal'
OPlot, Findgen(11), COLOR=cgColor('indian red')
OPlot, Findgen(11), COLOR=cgColor('olive'), PSYM=2
PS_End, /PNG
NOTES:
You can easily configure any modifications you like for your PostScript output
by setting fields in the plot and axis system variables (!P, !X, !Y, and !Z).
The modifications currently made by default in this program are these:
!P.Thick = 2
!X.Thick = 2
!Y.Thick = 2
!Z.Thick = 2
!P.Font = 1
MODIFICATION HISTORY:
Written by: David W. Fanning, 20 May 2008.
Slight modification to allow filenames with spaces in them.
Added NoMatch keyword. 17 March 2009. DWF.
Added a number of keywords to make these commands more configurable. 19 March 2009. DWF.
Only set thickness system variables if starting system variables are set to their
default values (namely, 0). This allows users to set their own system variables
before they call PS_START, rather than after. 23 March 2009. DWF.
Moved PS_END to its own file to allow the IDLExBr_Assistant to work properly. 7 April 2009. DWF.
Reordered ImageMagick commands to put them in the proper sequence to get "alpha" switch to work. 23 April 2009. DWF.
Put the switches *ahead* of the PostScript file name. Now resizing works and default size reduction
returned to 25%. 23 April 2009. DWF.
Still having a devil of a time getting the ImageMagick "convert" command right. Fonts
have become a problem. Now trying a "flatten" option in the command. 12 May 2009. DWF.
If the PostScript file is in Landscape mode, it is now "fixed" with FixPS to allow it
to be displayed right-side up in PostScript viewers. 8 August 2009. DWF.
Fixed a problem in not checking the GIF keyword properly. 4 December 2009. DWF.
Added NOFIX keyword to the program. 1 November 2010. DWF.
Added better handing of errors coming from FIXPS after update to FIXPS. 15 November 2010. DWF.
Added DELETE_PS keyword. 16 Jan 2011. DWF.
Better protection of code from not finding ImageMagick. 17 Jan 2011. DWF.
Collecting result of SPAWN command. Only printing if QUIET=0. 16 Feb 2011. DWF.
(See ps_end.pro)
NAME:
PS_START
PURPOSE:
The purpose of PS_START and PS_END is to make it easy to set-up
for and close a PostScript file. The programs work in close conjunction
with PSCONFIG, another program from the Coyote Library.
If ImageMagick (http://www.imagemagick.org/script/index.php) is installed
on your computer, you can easily convert PostScript output to JPEG, PNG, and TIFF
image output. (See the keywords to PS_END.)
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, File Output, PostScript
CALLING SEQUENCE:
PS_START
Various graphics commands here...
PS_END
KEYWORD PARAMETERS FOR PS_START:
CANCEL: An output keyword that is set to 1 if the user cancelled from
PS_Config. Otherwise, set to 0.
CHARSIZE: If this keyword is set, the !P.Charsize variable is set to this
value until PS_END is called.
FONT: Set this to the type of font you want. A -1 selects Hershey
fonts, a 0 selects hardware fonts (Helvetica, normally), and
a 1 selects a True-Type font. Set to 0 by default.
GUI: The default behavior is to use PSCONFIG to configure the
PostScript device silently. If you wish to allow the user
to interatively configure the PostScript device, set this
keyword.
KEYWORDS: This output keyword contains the keyword structure returned
from PS_Config.
NOMATCH: Normally, PS_Start will try to "match" the aspect ratio of the
PostScript file "window" to the current display window. If this
keyword is set, then this doesn't occur, giving the user the
option of specifying the size and offsets of the PostScript
window directly though appropriate keywords.
QUIET: If set, informational messages are not set.
SCALE_FACTOR: Set this to the PostScript scale factor. By default: 1.
TT_FONT: The name of a true-type font to use if FONT=1. By default, "HELVETICA".
Any keyword supported by PSCONFIG can be used to configure the PostScript device.
Common keywords would include FILENAME, XSIZE, YSIZE, XOFFSET, YOFFSET, etc. See
the PSCONFIG documentation for details. If size keywords are used, you *must* set
the NOMATCH keyword.
COMMON BLOCKS:
_$FSC_PS_START_ Contains the PS_STRUCT structure for communication between
PS_START and PS_END.
SIDE EFFECTS:
When PS_START is called, the current graphics device is set to "PS" (the PostScript
device). When PS_END is called the current graphics device is returned to the device
in effect when PS_START was called.
PS_Start uses the current display window as a template for the Postscript
file. Thus, if the display window is wider than it is higher, output is
in Landscape mode. To set the size of the PostScript "window" yourself, be
sure to set the NOMATCH keyword to 1.
To display surface plots correctly the FONT keyword should be set to 1.
Otherwise, the default font is 0, or hardware fonts when outputting to
PostScript.
RESTRICTIONS:
Requires numerous programs from the Coyote Library. To convert PostScript files
to PNG, JPEG, GIF, and TIFF files requires ImageMagick be installed on your
computer and configured correctly. You can download Coyote Library programs here:
http://www.dfanning.com/programs/coyoteprograms.zip
ImageMagick can be found here:
http://www.imagemagick.org/script/index.php
NOTE: In this version of PS_START, I have added the "alpha" option to the ImageMagick
command. This is a relatively recent addition to the convert command. (Added in ImageMagick
version 6.3.4). Your version of ImageMagick may not allow it. If so, simply comment out the
alpha command in the code below (on or about line 242), or uncomment it, as the case may be.
EXAMPLE:
To create a line plot in a PostScript file named lineplot.ps and
also create a PNG file named lineplot.png for display in a browser,
type these commands.
PS_Start, FILENAME='lineplot.ps'
Plot, Findgen(11), COLOR=cgColor('navy'), /NODATA, XTITLE='Time', YTITLE='Signal'
OPlot, Findgen(11), COLOR=cgColor('indian red')
OPlot, Findgen(11), COLOR=cgColor('olive'), PSYM=2
PS_End, /PNG
NOTES:
You can easily configure any modifications you like for your PostScript output
by setting fields in the plot and axis system variables (!P, !X, !Y, and !Z).
The modifications currently made by default in this program are these:
!P.Thick = 2
!P.CharThick = 2
!X.Thick = 2
!Y.Thick = 2
!Z.Thick = 2
!P.Font = 0
The !P.Charsize variable is set differently on Windows computers, and depending
on whether !P.MULTI is being used. On Windows the default is 1.25, or 1.00 for
multiple plots. On other computers, the default is 1.5, or 1.25 for multiple plots.
If true-type fonts are being used (FONT=1), the default is 1.5, or 1.25 for
multiple plots.
MODIFICATION HISTORY:
Written by: David W. Fanning, 20 May 2008.
Slight modification to allow filenames with spaces in them.
Added NoMatch keyword. 17 March 2009. DWF.
Added a number of keywords to make these commands more configurable. 19 March 2009. DWF.
Only set thickness system variables if starting system variables are set to their
default values (namely, 0). This allows users to set their own system variables
before they call PS_START, rather than after. 23 March 2009. DWF.
Moved PS_END to its own file to allow the IDLExBr_Assistant to work properly. 7 April 2009. DWF.
Modified to allow PostScript page type to be stored for future processing with FixPS. 9 August 2009. DWF.
Added NoFix keyword to PS_END calls to repair previous, but unused set-ups. 1 Nov 2010. DWF.
Added Charsize keyword to PS_START. 14 Nov 2010. DWF.
Changed the way default character sizes are set. 19 Nov 2010. DWF.
Added CANCEL and KEYWORDS output keywords. 16 Jan 2011. DWF.
(See ps_start.pro)
NAME:
RANDOMNUMBERGENERATOR
PURPOSE:
Allows the user to obtain a sequence of pseudo-random numbers. The
object maintains the random number generator seed in such a way that
subsequent calls to GetRandomNumbers will guarentee that you don't
get the same random numbers each time you ask for random numbers.
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:
Generate three random numbers.
IDL> rng = Obj_New('RandomNumberGenerator', initialSeed)
IDL> numberOfNumbersNeeded = 3
IDL> randomNumbers = rng -> GetRandomNumbers(numberOfNumbersNeeded)
IDL> Print, randomNumbers
0.80952855 0.35878432 0.52150406
Generate a sequence of 8 random digits.
IDL> Print, rng -> GetRandomDigits(8)
21855786
INPUT PARAMETERS FOR INIT METHOD:
initialSeed: The initial seed for the random number generator. If undefined
or absent, the number of seconds after 1 January 1970 is used.
METHODS:
randomNumbers -> GetRandomNumbers(d1, d2, d3, d4 d5, d6, d7, d8)
randomDigits = obj -> GetRandomDigits(numDigets)
obj -> SetSeed, seed
MODIFICATION HISTORY:
Written by David W. Fanning, 13 November 2009.
Added GetRandomDigits method. 7 February 2010. DWF.
Incorrect cleanup of the seed pointer fixed in the CLEANUP procedure.
25 February 2010, DWF.
(See randomnumbergenerator__define.pro)
NAME:
RANGEOF
PURPOSE:
This function returns the range (i.e., the minimum and maximum value)
of its argument.
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:
range = RangeOf(variable)
INPUTS:
variable: Any numeric IDL variable, except complex.
KEYWORD PARAMETERS:
None.
OUTPUTS:
range: A two-element vector containing the minimum and maximum value
of the variable.
EXAMPLE:
x = RandomU(3L, 10) * 100
Print, RangeOf(x)
3.78892 98.4703
MODIFICATION HISTORY:
Written by: David W. Fanning, 15 February 2009.
(See rangeof.pro)
NAME:
REPMAT
PURPOSE:
This program replicates a matrix or array in the style of
the MATLAB RebMat command. The matrix or array is "tiled"
in some integer number of columns and rows.
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:
tiledMatrix = RepMat(matrix, ncol, nrow)
AUGUMENTS:
matix: The matrix or array to be tiled.
ncol: The number of columns in the tile.
nrow: The number of rows in the tile.
RETURN_VALUE:
tiledMatrix: If (xdim,ydim) is the size of the original 2D matrix, then the
output matrix is sized (ncol*xdim, nrow*ydim).
KEYWORDS:
None.
EXAMPLE:
IDL> matrix = Reform(Indgen(6) + 1, 3, 2)
IDL> Print, matrix, FORMAT='(3I3)'
1 2 3
4 5 6
IDL> Print, RepMat(matrix, 3, 2), FORMAT='(9I3)'
1 2 3 1 2 3 1 2 3
4 5 6 4 5 6 4 5 6
1 2 3 1 2 3 1 2 3
4 5 6 4 5 6 4 5 6
MODIFICATION HISTORY:
Written by David W. Fanning, 8 May 2009.
Algorithm significantly improved by Ronn Kling, 4 August 2009.
Added line to handle an input matrix with a trailing 1 dimension correctly. DJ 8 March 2011.
(See repmat.pro)
NAME:
RESOLVE_OBJECT
PURPOSE:
The purpose of this function is to resolve object methods in files that have the object
methods in the same file as the object class definition module (i.e., object__define.pro).
It is particularly useful in restoring object methods for objects that have been saved and
are being restored. Restored objects often do not know about their methods unless an object
of the same object class has been previously compiled in that IDL session.
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:
Resolve_Object, obj_or_class
ARGUMENTS:
obj_or_class: Either an IDL object or the class name of an IDL object. Required parameter.
KEYWORDRS:
ROUTINE_INFO: Not strictly used by the user of the program, but this provides a mechanism by which
currently compiled routine names can be checked, so that object code is not being
recompiled unnecessarily. It is actually used internally in the code in a sort of
recursive approach to handling object superclasses.
INFORMATION:
A discussion of this routine, and of the problem the routine was written to address can
be found here:
http://www.dfanning.com/tips/saved_objects.html
MODIFICATION HISTORY:
Written by: David W. Fanning, August 20, 2009, and based on code written by JD Smith and
discussed in the article above.
(See resolve_object.pro)
:Description:
Provides a simple way to obtain the data indices from a Histogram REVERSE_INDICES
vector. Returns a -1 if no indices are available. Check the COUNT keyword for the
number of indices returned.
:Categories:
Utilities
:Params:
reverse_indices: in, required, type=integer
The REVERSE_INDICES vector that is returned from the HISTOGRAM command.
index: in, required, type=integer
The zero-based index into the REVERSE_INDICES vector from which to obtain
the indices. For example, and index value of 4 will return the indices in
the 5th bin (zero based counting) of the histogram.
:Keywords:
count: out, optional, type=Long
The number of indices returned by the function.
:Return Value:
indices:
The indices that were put into the indexth bin of the histogram. A -1
is returned if no indices are in that particular bin.
:Examples:
Used with the HISTOGRAM command::
IDL> image = cgDemoData(7)
IDL> h = Histogram(image, REVERSE_INDICES=ri)
IDL> indices = ReverseIndices(ri, 4, COUNT=cnt)
IDL> Help, indices, cnt, h[4]
INDICES LONG = Array[948]
CNT LONG = 948
LONG = 948
IDL> image[indices] = 0
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Written by David W. Fanning at suggestion of Ben Tupper. 7 January 2011.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See reverseindices.pro)
NAME:
REVERSE_AXES
PURPOSE:
The purpose of this program is to extend the SIMPLE_SURFACE
program to demonstrate how to create reversible axes in
object graphics.
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:
REVERSE_AXES, data, x, y
REQUIRED INPUTS:
None. Fake data will be used if no data is supplied in call.
OPTIONAL INPUTS
data: A 2D array of surface data.
x: A vector of X data values.
y: A vector of Y data values.
OPTIONAL KEYWORD PARAMETERS:
EXACT: Set this keyword to get exact axis scaling.
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the surface initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
VECTOR: Set this keyword if you want vector printing (as opposed to
the default bitmap printing).
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
ZTITLE: A string used as the Z title of the plot.
COMMON BLOCKS:
None.
EXAMPLE:
To use this program with your 2D data, type:
IDL> Reverse_Axes, data
MODIFICATION HISTORY:
Written by: David Fanning, October 2001.
(See reverse_axes.pro)
NAME:
SAVETOMAIN
PURPOSE:
This is used primarily in debugging mode to save a variable to
the main IDL level for later inspection.
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:
SaveToMain, variable, nameOfVariable
ARGUMENTS:
variable: The variable you wish to save at the main IDL level.
nameOfVariable: The name of the variable at the main IDL level. If undefined,
the variable will have the same name as the variable that was
used as the variable argument.
KEYWORDRS:
None.
MODIFICATION HISTORY:
Written by: David W. Fanning, 2 July 2009.
(See savetomain.pro)
NAME:
SCALEMODIS
PURPOSE:
MODIS corrected reflectance images often appear drab when initially processed
and displayed on a computer using BYTSCL. In fact, the resulting true-color
images look nothing like the images you can find on the MODIS Rapid Response
web page (http://rapidfire.sci.gsfc.nasa.gov/gallery/). After poking around on
the Internet for awhile, I discovered that the Rapid Response Team doesn't use
BYTSCL to prepare the images. Rather, they selectively scale portions of the
reflectance image, using a piecewise scaling with different slopes. This program
implements this Rapid Response Team algorithm.
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:
scaledBand = ScaleModis(red, green, blue)
ARGUMENTS:
red: A two-dimensional array representing the corrected reflectance
values of a MODIS image. This is a required parameter. If the
green and blue parameters are also used, this parameter will
represent the red band of a RGB 24-bit scaled image that is returned.
green: If the three parameters--red, green, and blue--are present, the returned
array is a 24-bit true-color image, scaled appropriately. This parameter
is used as the green band in such an image. The parameter is a two-dimensional
array of corrected reflectance values.
blue: If the three parameters--red, green, and blue--are present, the returned
array is a 24-bit true-color image, scaled appropriately. This parameter
is used as the blue band in such an image. The parameter is a two-dimensional
array of corrected reflectance values.
KEYWORD PARAMETERS:
RANGE: A two-dimensional array that the input bands are first scaled into, prior to
the differential scaling using the MODIS Rapid Response algorithm. The default
input range is [-0.01, 1.10]. These values will be used to set the MIN and MAX
keywords for the BYTSCL command in the initial scaling of the input bands.
CLOUD: The MODIS Rapid Response team uses a slightly different scaling algorithm when
the idea is to emphasize clouds in a MODIS scene. Set this keyword to use the
alternate cloud scaling algorithm.
OUTPUTS:
scaledBand: If a single 2D array is passed as the argument, then scaledBand is the scaled
2D output array. If all three arguments are passed to the program, then scaledBand
is a scaled 24-bit image that represents a true-color or false color representation
of the three input bands.
MODIFICATION HISTORY:
Written by: David W. Fanning, July 2009, using the IDL programs MODIS_FALSE_COLOR and
and SCALE_IMAGE for inspiration. I found these programs on the Internet when poking
around MODIS web pages. I suspect, but I am not sure, these programs were originally
written by Liam Gumley.
Minor changes to the ScaleIt function to be sure partitioning is done correctly. 5 Aug 2009. DWF.
(See scalemodis.pro)
NAME:
SCALE_VECTOR
PURPOSE:
This is a utility routine to scale the elements of a vector
(or an array) into a given data range. The processed vector
[MINVALUE > vector < MAXVECTOR] is scaled into the data range
given by MINRANGE and MAXRANGE.
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:
scaledVector = SCALE_VECTOR(vector, [minRange], [maxRange], [MINVALUE=minvalue], [MAXVALUE=maxvalue])
INPUT POSITIONAL PARAMETERS:
vector: The vector (or array) to be scaled. Required.
minRange: The minimum value of the scaled vector. Set to 0 by default. Optional.
maxRange: The maximum value of the scaled vector. Set to 1 by default. Optional.
Note that it is the processed vector [MINVALUE > vector < MAXVALUE] that is
scaled between minRange and maxRange. See the MINVALUE and MAXVALUE keywords below.
INPUT KEYWORD PARAMETERS:
DOUBLE: Set this keyword to perform scaling in double precision.
Otherwise, scaling is done in floating point precision.
MAXVALUE: MAXVALUE is set equal to (vector < MAXVALUE) prior to scaling.
The default value is MAXVALUE = Max(vector).
MINVALUE: MINVALUE is set equal to (vector > MAXVALUE) prior to scaling.
The default value is MINXVALUE = Min(vector).
NAN: Set this keyword to enable not-a-number checking. NANs
in vector will be ignored.
PRESERVE_TYPE: Set this keyword to preserve the input data type in the output.
RETURN VALUE:
scaledVector: The vector (or array) values scaled into the data range.
COMMON BLOCKS:
None.
EXAMPLES:
x = [3, 5, 0, 10]
xscaled = SCALE_VECTOR(x, -50, 50)
Print, xscaled
-20.0000 0.000000 -50.0000 50.0000
Suppose your image has a minimum value of -1.7 and a maximum value = 2.5.
You wish to scale this data into the range 0 to 255, but you want to use
a diverging color table. Thus, you want to make sure value 0.0 is scaled to 128.
You proceed like this:
scaledImage = SCALE_VECTOR(image, 0, 255, MINVALUE=-2.5, MAXVALUE=2.5)
RESTRICTIONS:
Requires the following programs from the Coyote Library:
http://www.dfanning.com/programs/convert_to_type.pro
http://www.dfanning.com/programs/fpufix.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 12 Dec 1998.
Added MAXVALUE and MINVALUE keywords. 5 Dec 1999. DWF.
Added NAN keyword. 18 Sept 2000. DWF.
Removed check that made minRange less than maxRange to allow ranges to be
reversed on axes, etc. 28 Dec 2003. DWF.
Added PRESERVE_TYPE and DOUBLE keywords. 19 February 2006. DWF.
Added FPUFIX to cut down on floating underflow errors. 11 March 2006. DWF.
(See scale_vector.pro)
NAME:
SCROLLWINDOW
PURPOSE:
This procedure is more or less a drop-in replacement for the WINDOW
command. The main difference is that if the requested window size
is larger then the current display size, the window is created in a
base widget with scroll bars so the user can scroll around
the larger window. Use the WID keyword to pass in the window
index number of the window you want to create (a small change
from the WINDOW syntax). If the program can create a window with
this window index number, it will. Otherwise, this keyword will
return the window index number of the window that was actually
created.
I use ScrollWindow to create windows that I can view both on
my large monitor at work and on my smaller laptop monitor when
I travel.
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:
ScrollWindow, xsize, ysize
ARGUMENTS:
xsize: The x size of the graphics window. By default, 640.
ysize: The y size of the graphics window. By default, 512.
KEYWORD PARAMETERS:
FREE: Get a window with a free or unused window index number.
This is *always* done with a scrollable window. The window
index number of the window is returned in the WID keyword.
PIXMAP: Set to create a pixmap window. In this case, no scrollable
window is possible. A normal IDL graphics window is
always created.
TITLE: The title string that is displayed on the window.
WID: The window index number. If supplied as an IDL variable,
this can be both an input and an output keyword. If a
window with this window index number can be created, it
is. Otherwise, this varible upon exit from the program
contains the window index number of the graphics window
that was created.
XPOS: The x offset of the upper-left corner of the window.
XSIZE: The same as the xsize argument. Provided so ScrollWindow
can be a drop-in replacement for the Window command.
YPOS: The y offset of the upper-left corner of the window.
YSIZE: The same as the ysize argument. Provided so ScrollWindow
can be a drop-in replacement for the Window command.
EXAMPLE:
ScrollWindow, XSIZE=800, YSIZE=400 ; Produces normal IDL graphics window.
ScrollWindow, XSIZE=1800, YSIZE=1200 ; Produces a scrollable graphics window.
MODIFICATION HISTORY:
Written by: David W. Fanning, 25 March 2009
(See scrollwindow.pro)
NAME:
SELECT_OBJECTS
PURPOSE:
The purpose of this program is to demonstrate how to select
and move objects in an object graphics window. Once the objects
appear in the window, use your mouse to select the objects and
move them in the window. The window is resizeable.
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:
Object Graphics.
CALLING SEQUENCE:
SELECT_OBJECTS
REQUIRED INPUTS:
None.
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Requires VCOLORBAR from the Coyote Library:
http://www.dfanning.com/programs/vcolorbar__define.pro.
EXAMPLE:
Select_Objects
MODIFICATION HISTORY:
Written by David Fanning, 21 September 98.
Added the ability to shrink and expand the objects. 27 Sept 98. DWF.
(See select_objects.pro)
:Description:
Provides a device-independent way to set the color decomposition state of the
current graphics device. Devices that do not have a DECOMPOSED keyword to the
DEVICE command are assumed to be in indexed color mode always.
:Categories:
Graphics, Utilities
:Params:
state: in, required, type=integer, default=0
Set to 1 to set the current graphics device to decomposed color. Set to 0
to set the current graphics device to indexed color. Devices lacking a
DECOMPOSED keyword are assumed to be perpetually in indexed color mode.
:Keywords:
currentstate: out, optional, type=integer
The current decomposition state of the current graphics device when the
program is called. A 1 indicates decomposed color. A 0 indicates indexed
color.
depth: out, optional, type=integer
The currnet pixel depth of the graphics device.
zdepth: in, optional, type=integer
The pixel depth of the Z-graphics device. Set to 8 or 24. Applies ONLY
when setting the Z-graphics device state to 0. If undefined, the current
depth of the Z-graphics device is unchanged from its current state.
:Examples:
IDL> SetDecomposedState, 0, CurrentState=mode
: Restrictions:
If you set color decomposition on in the Z-graphics buffer, the pixel depth
automatically gets set to 24. It does not change back to 8 if color decomposition
is turned off.
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 16 November 2010. DWF.
Changes to include SET_PIXEL_DEPTH in Z-graphics buffer. 19 Nov 2010. DWF.
Allow PostScript 7.0 to set the decomposition keyword. 12 Dec 2010. DWF.
Added DEPTH and ZDEPTH keywords. 31 Dec 2010. DWF.
Added a do-nothing NULL device to Case statement. 4 Jan 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See setdecomposedstate.pro)
NAME:
SetDefaultValue
PURPOSE:
This procedure sets default values for positional and keyword arguments to
IDL procedures and functions.
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:
SetDefaultValue, argument, defaultValue
ARGUMENTS:
argument: The augument variable you are setting the default value of. If this variable
is undefined, the defaultValue will be assigned to it. Otherwise, the argument
variable will not change.
defaultValue: The default value that will be assigned to the argument variable ONLY if the argument
variable is undefined. If this variable is undefined, the argument variable will
be treated as if the BOOLEAN keyword had been set.
KEYWORDS:
BOOLEAN: If this keyword is set, the argument value will always be forced to return with a
value of 0 or 1.
EXAMPLE:
FUNCTION Action, arg1, arg2, MULTIPLY=multiply
SetDefaultValue, arg1, 1
SetDefaultValue, arg2, 2
SetDefaultValue, multiply, 1, /BOOLEAN
IF multiply THEN RETURN, arg1 * arg2 ELSE RETURN, arg1 + arg2
END
MODIFICATION HISTORY:
Written by: David W. Fanning, November 26, 2008, from suggestion by Carsten Lechte on
IDL newsgroup on this date.
Made a change to the way the BOOLEAN keyword works. Now argument is set to BOOLEAN before
return, if required. 3 Dec 2008. DWF.
(See setdefaultvalue.pro)
NAME:
SETDIFFERENCE
PURPOSE:
This function is used to find the difference between two sets of integers.
In other words, the function will find the values that are in Set A but
are missing in Set B.
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:
difference = SetDifference(set_a, set_b)
RETURN VALUE:
difference: A vector of values that are found in set_a but are missing in set_b.
ARGUMENTS:
set_a: A vector of integers.
set_b: A vector of integers.
KEYWORDRS:
NORESULT: Set this keyword to a value that will be returned from the function
if no difference between the two sets of numbers is found. By default, set_a.
SUCCESS: An output keyword that is set to 1 if a difference was found, and to 0 otherwise.
EXAMPLE:
IDL> set_a = [1,2,3,4,5]
IDL> set_b = [4,5,6,7,8,9,10,11]
IDL> Print, SetDifference(set_a, set_b)
1 2 3
See http://www.dfanning.com/tips/set_operations.html for other types of set operations.
NOTES:
If you read the Set Operations article pointed to above, you will see quite a lot of
discussion about what kinds of algorithms are faster than others. The Histogram
algorithms implemented here are sometimes NOT the fastest algorithms, especially
for sparse arrays. If this is a concern in your application, please be sure to read
that article.
MODIFICATION HISTORY:
Written by: David W. Fanning, November 25, 2009, from code originally supplied to the IDL
newsgroup by Research Systems software engineers.
(See setdifference.pro)
NAME:
SETINTERSECTION
PURPOSE:
This function is used to find the intersection between two sets of integers.
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:
intersection = SetIntersection(set_a, set_b)
RETURN VALUE:
intersection: A vector of values that are found in both set_a and set_b.
ARGUMENTS:
set_a: A vector of integers.
set_b: A vector of integers.
KEYWORDRS:
NORESULT: Set this keyword to a value that will be returned from the function
if no intersection between the two sets of numbers is found. By default, -1.
SUCCESS: An output keyword that is set to 1 if an intersection was found, and to 0 otherwise.
EXAMPLE:
IDL> set_a = [1,2,3,4,5]
IDL> set_b = [4,5,6,7,8,9,10,11]
IDL> Print, SetIntersection(set_a, set_b)
4 5
See http://www.dfanning.com/tips/set_operations.html for other types of set operations.
NOTES:
If you read the Set Operations article pointed to above, you will see quite a lot of
discussion about what kinds of algorithms are faster than others. The Histogram
algorithms implemented here are sometimes NOT the fastest algorithms, especially
for sparse arrays. If this is a concern in your application, please be sure to read
that article.
MODIFICATION HISTORY:
Written by: David W. Fanning, October 31, 2009, from code originally supplied to the IDL
newsgroup by Research Systems software engineers.
Yikes, bug in original code only allowed positive integers. Fixed now. 2 Nov 2009. DWF.
Fixed a problem when one or both of the sets was a scalar value. 18 Nov 2009. DWF.
(See setintersection.pro)
NAME:
SETUNION
PURPOSE:
This function is used to find the union between two sets of integers.
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:
union = SetUnion(set_a, set_b)
RETURN VALUE:
union: A vector of values that are found in the combined integer sets.
ARGUMENTS:
set_a: A vector of integers.
set_b: A vector of integers.
KEYWORDRS:
None.
EXAMPLE:
IDL> set_a = [1,2,3,4,5]
IDL> set_b = [4,5,6,7,8,9,10,11]
IDL> Print, SetUnion(set_a, set_b)
1 2 3 4 5 6 7 8 9 10 11
See http://www.dfanning.com/tips/set_operations.html for other types of set operations.
NOTES:
If you read the Set Operations article pointed to above, you will see quite a lot of
discussion about what kinds of algorithms are faster than others. The Histogram
algorithms implemented here are sometimes NOT the fastest algorithms, especially
for sparse arrays. If this is a concern in your application, please be sure to read
that article.
One alternative for the SetUnion algorithm, provided by Maarten Sneep, is simply this:
superset = [set_a, set_b]
union = superset[Uniq(superset, Sort(superset))]
MODIFICATION HISTORY:
Written by: David W. Fanning, November 25, 2009, from code originally supplied to the IDL
newsgroup by Research Systems software engineers.
(See setunion.pro)
NAME:
SHAPEINFO
PURPOSE:
The purpose of this program is allow the user to browse a very narrow
selection of shapefiles. Namely, those containing geographical shapes
in latitude and longitude coordinates. In other words, shapefiles
containing maps. File attributes are listed in the left-hand list
widget. Clicking on a file attribute, will list all the entity
attributes for that file attribute in the right-hand list. Clicking
an entity attribute with list the type of entity, and the X and Y
bounds of that entity (shown as LON and LAT, respectively), in the
statusbar at the bottom of the display.
Knowing the attribute and entity names of a shapefile will give
you insight into how to read and display the information in the file.
For examples, see the Coyote Library programs DrawCounties and DrawStates.
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:
ShapeInfo, shapefile
ARGUMENTS:
shapefile: The name of the input shapefile. If not provided, the user
will be prompted to select a shapefile.
OUTPUT KEYWORDS:
XRANGE: An output two-element vector containing the minimum and maximum
X boundary of the shapefile entities.
YRANGE: An output two-element vector containing the minimum and maximum
Y boundary of the shapefile entities.
RESTRICTIONS:
It is assumed the shapefile contains 2D map information. The X and Y bounds of
each shapefile entity are reported as LON and LAT values, respectively.
Required Coyote Library programs:
CenterTLB
Error_Message
EXAMPLE:
filename = Filepath(SubDir=['examples','data'], 'states.shp')
ShapeInfo, filename, XRANGE=xr, YRANGE=yr
Plot, xr, yr, /NoData, XStyle=1, YStyle=1
DrawShapes, filename
MODIFICATION HISTORY:
Written by David W. Fanning, 21 October 2006.
Slight modifications to the interface. 14 May 2010. DWF.
Added XRANGE and YRANGE output keywords. 15 May 2010. DWF.
(See shapeinfo.pro)
NAME:
Sharpen
PURPOSE:
This function sharpens an image using a Laplacian kernel.
The final result is color adjusted to match the histogram
of the input image.
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:
Image Processing
CALLING SEQUENCE:
sharp_image = Sharpen(image)
INPUTS:
image - The input image to be sharpened. Assumed to be a 2D byte array.
OUTPUTS:
sharp_image - The sharpened image.
INPUT KEYWORDS:
KERNEL -- By default the image is convolved with this 3-by-3 Laplacian kernel:
[ [-1, -1, -1], [-1, +8, -1], [-1, -1, -1] ]. You can pass in any kernel
of odd width. The filtered image is added back to the original image to provide
the sharpening effect.
DISPLAY -- If this keyword is set a window is opened and the details of the sharpening
process are displayed.
OUTPUT KEYWORDS:
None.
DEPENDENCIES:
None.
METHOD:
This function is based on the Laplacian kernel sharpening method on pages 128-131
of Digital Image Processing, 2nd Edition, Rafael C. Gonzalez and Richard E. Woods,
ISBN 0-20-118075-8.
EXAMPLE:
There is an example program at the end of this file.
MODIFICATION HISTORY:
Written by David W. Fanning, January 2003.
Updated slightly to use Coyote Library routines. 3 Dec. 2010. DWF.
Modified the example to work with cgImage. 29 March 2011. DWF.
(See sharpen.pro)
NAME:
SIMPLE_SURFACE
PURPOSE:
The purpose of this program is to demonstrate how to
create a simple surface plot with axes and rotational
capability in object graphics.
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:
SIMPLE_SURFACE, data, x, y
REQUIRED INPUTS:
None. Fake data will be used if no data is supplied in call.
OPTIONAL INPUTS
data: A 2D array of surface data.
x: A vector of X data values.
y: A vector of Y data values.
OPTIONAL KEYWORD PARAMETERS:
EXACT: Set this keyword to get exact axis scaling.
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the surface initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
VECTOR: Set this keyword if you want vector printing (as opposed to
the default bitmap printing).
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
ZTITLE: A string used as the Z title of the plot.
COMMON BLOCKS:
None.
RESTRICTIONS:
Requires FSC_NORMALIZE from the Coyote Library.
http://www.dfanning.com/programs/fsc_normalize.pro
EXAMPLE:
To use this program with your 2D data, type:
IDL> Simple_Surface, data
(See simple_surface.pro)
NAME:
SORT_ND
PURPOSE:
Efficiently perform an N-dimensional sort along any dimension
of an array.
CALLING SEQUENCE:
inds=sort_nd(array,dimension)
INPUTS:
array: An array of at least 2 dimensions to sort.
dimension: The dimension along which to sort, starting at 1
(1:rows, 2:columns, ...).
OUTPUTS:
inds: An index array with the same dimensions as the input
array, containing the (1D) sorted indices. Can be used
directly to index the arary (ala SORT).
EXAMPLE:
a=randomu(sd,5,4,3,2)
sorted=a[sort_nd(a,2)]
SEE ALSO:
HISTOGRAM
MODIFICATION HISTORY:
Tue Aug 22 15:51:12 2006, J.D. Smith
Written, based on discussion on c.l.i-p, 08/2006.
(See sort_nd.pro)
NAME:
STATIONPLOT
PURPOSE:
This is routine for drawing station plots on a map or other display.
Normally, this routine is used in conjunction with WINDBARB.
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:
StationPlot, x, y
REQUIRED INPUTS:
x: The X location of the center of the station plot, expressed in data coordinates.
y: The Y location of the center of the station plot, expressed in data coordinates.
KEYWORDS:
COLOR: The name of the color to draw the station plot in. May be a vector
the same length as X. Colors are those available in cgColor.
RADIUS: The radius of the station plot circle in normalized coordinates.
RESTRICTIONS:
Requires cgColor from the Coyote Library:
http://www.dfanning.com/programs/cgColor.pro
EXAMPLE:
seed = -3L
lon = Randomu(seed, 20) * 360 - 180
lat = Randomu(seed, 20) * 180 - 90
speed = Randomu(seed, 20) * 100
direction = Randomu(seed, 20) * 180 + 90
Erase, Color=cgColor('Ivory', !P.Background)
Map_Set, /Cylindrical,Position=[0.1, 0.1, 0.9, 0.9], Color=cgColor('Steel Blue'), /NoErase
Map_Grid, Color=cgColor('Charcoal', !D.Table_Size-2)
Map_Continents, Color=cgColor('Sea Green', !D.Table_Size-3)
StationPlot, lon, lat, Color='Indian Red'
MODIFICATION HISTORY:
Written by: David W. Fanning, 20 May 2003, based on TVCircle from the
NASA Astonomy Library.
Added THICK keyword. 23 February 2005. DWF.
(See stationplot.pro)
NAME:
STR_SIZE
PURPOSE:
The purpose of this function is to return the proper
character size to make a specified string a specifed
width in a window. The width is specified in normalized
coordinates. The function is extremely useful for sizing
strings and labels in resizeable graphics windows.
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 Programs, Widgets.
CALLING SEQUENCE:
thisCharSize = STR_SIZE(thisSting, targetWidth)
INPUTS:
thisString: This is the string that you want to make a specifed
target size or width.
OPTIONAL INPUTS:
targetWidth: This is the target width of the string in normalized
coordinates in the current graphics window. The character
size of the string (returned as thisCharSize) will be
calculated to get the string width as close as possible to
the target width. The default is 0.25.
KEYWORD PARAMETERS:
INITSIZE: This is the initial size of the string. Default is 1.0.
STEP: This is the amount the string size will change in each step
of the interative process of calculating the string size.
The default value is 0.05.
XPOS: X position of the output test string. This can be
used on the Postscript device, where no pixmap windows are
available and where therefore the test strings would appear on
the printable area. Default is 0.5 on most devices. If !D.NAME
is PS, the default is 2.0 to draw the test string out of the
drawable window area.
YPOS: Y position of the output test string. This can be
used on the Postscript device, where no pixmap windows are
available and where therefore the test strings would appear on
the printable area. Default is 0.5 on most devices. If !D.NAME
is PS, the default is 2.0 to draw the test string out of the
drawable window area.
OUTPUTS:
thisCharSize: This is the size the specified string should be set
to if you want to produce output of the specified target
width. The value is in standard character size units where
1.0 is the standard character size.
EXAMPLE:
To make the string "Happy Holidays" take up 30% of the width of
the current graphics window, type this:
XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
MODIFICATION HISTORY:
Written by: David Fanning, 17 DEC 96.
Added a scaling factor to take into account the aspect ratio
of the window in determing the character size. 28 Oct 97. DWF
Added check to be sure hardware fonts are not selected. 29 April 2000. DWF.
Added a pixmap to get proper scaling in skinny windows. 16 May 2000. DWF.
Forgot I can't do pixmaps in all devices. :-( Fixed. 7 Aug 2000. DWF.
Added support of PostScript at behest of Benjamin Hornberger. 11 November 2004. DWF.
Cleaned up the code a bit. 28 Feb 2011. DWF.
Fixed non-square window algorithm to reflect my original intentions. 10 June 2011.
(See str_size.pro)
NAME:
SYMCAT
PURPOSE:
This function provides a symbol catalog for specifying a number of plotting symbols.
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:
Plot, findgen(11), PSYM=SYMCAT(theSymbol)
To connect symbols with lines, use a negative value for the PSYM keyword:
Plot, findgen(11), PSYM=-SYMCAT(theSymbol)
INPUTS:
theSymbol: The number of the symbol you wish to use. Possible values are:
0 : No symbol.
1 : Plus sign.
2 : Asterisk.
3 : Dot (period).
4 : Open diamond.
5 : Open upward triangle.
6 : Open square.
7 : X.
8 : Defined by the user with USERSYM.
9 : Open circle.
10 : Histogram style plot.
11 : Open downward triangle.
12 : Open rightfacing triangle.
13 : Open leftfacing triangle.
14 : Filled diamond.
15 : Filled square.
16 : Filled circle.
17 : Filled upward triangle.
18 : Filled downward triangle.
19 : Filled rightfacing triangle.
20 : Filled leftfacing triangle.
21 : Hourglass.
22 : Filled Hourglass.
23 : Bowtie.
24 : Filled bowtie.
25 : Standing Bar.
26 : Filled Standing Bar.
27 : Laying Bar.
28 : Filled Laying Bar.
29 : Hat up.
30 : Hat down.
31 : Hat right.
32 : Hat down.
33 : Big cross.
34 : Filled big cross.
35 : Circle with plus.
36 : Circle with X.
37 : Upper half circle.
38 : Filled upper half circle.
39 : Lower half circle.
40 : Filled lower half circle.
41 : Left half circle.
42 : Filled left half circle.
43 : Right half circle.
44 : Filled right half circle.
45 : Star.
46 : Filled star.
RETURN VALUE:
The return value is whatever is appropriate for passing along
to the PSYM keyword of (for example) a PLOT or OPLOT command.
For the vast majority of the symbols, the return value is 8.
KEYWORDS:
COLOR: Set this keyword to the color (index or 24-bit value) of
the color desired. For example:
Plot, Findgen(11), COLOR=cgColor('yellow'), PSYM=-SYMCAT(4, COLOR=cgColor('green'))
THICK: Set this keyword to the thickness desired. Default is 1.
MODIFICATION HISTORY:
Written by David W. Fanning, 2 September 2006. Loosely based on the
program MC_SYMBOL introduced on the IDL newsgroup 1 September 2006,
and MPI_PLOTCONFIG__DEFINE from the Coyote Library.
2 October 2006. DWF. Modified to allow PSYM=8 and PSYM=10 to have
their normal meanings. This shifted previous symbols by two values
from their old meanings. For example, an hourglass went from symbol
number 19 to 21.
Whoops! Added two symbols but forgot to change limits to allow for them. 4 May 2007. DWF.
Added THICK keyword. 21 Aug 2007. DWF.
Added COLOR keyword and made THICK keyword apply to all symbols. 11 Nov 2008. DWF.
(See symcat.pro)
NAME:
TEXTBOX
PURPOSE:
This function allows the user to type some text in a
pop-up dialog widget and have it returned to the program.
This is an example of a Pop-Up Dialog 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:
Utility, Widgets
CALLING SEQUENCE:
thetext = TextBox()
INPUTS:
None.
KEYWORD PARAMETERS:
CANCEL: An output parameter. If the user kills the widget or clicks the Cancel
button this keyword is set to 1. It is set to 0 otherwise. It
allows you to determine if the user canceled the dialog without
having to check the validity of the answer.
theText = TextBox(Title='Provide Phone Number...', Label='Number:', Cancel=cancelled)
IF cancelled THEN Return
GROUP_LEADER: The widget ID of the group leader of this pop-up
dialog. This should be provided if you are calling
the program from within a widget program:
thetext = TextBox(Group_Leader=event.top)
If a group leader is not provided, an unmapped top-level base widget
will be created as a group leader.
LABEL: A string the appears to the left of the text box.
TITLE: The title of the top-level base. If not specified, the
string 'Provide Input:' is used by default.
VALUE: A string variable that is the intial value of the textbox. By default, a null string.
XSIZE: The size of the text widget in pixel units. By default, 200.
OUTPUTS:
theText: The string of characters the user typed in the
text widget. No error checking is done.
RESTRICTIONS:
The widget is destroyed if the user clicks on either button or
if they hit a carriage return (CR) in the text widget. The
text is recorded if the user hits the ACCEPT button or hits
a CR in the text widget.
MODIFICATION HISTORY:
Written by: David W. Fanning, December 20, 2001.
Added VALUE keyword to set the initial value of the text box. 4 Nov 2002. DWF.
(See textbox.pro)
NAME:
TextLineFormat
PURPOSE:
This is a utility program for taking a line of text and shortening
it to a defined maximum length. The result of the function is a string
array in which no line of text in the string array is longer than the maximum
length. The text is broken into "words" by white space. The algorithm is
modified slightly if there are LF (line feeds) in the text, or if any single
word in the text is too large to fit on a line.
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:
formattedText = TextLineFormat(theText)
INPUTS:
theText: The line of text that is to be formatted.
KEYWORDS:
LENGTH: The maximum line length allowed in the resulting text array.
Set to 60 characters by default. Lines greater than length
can be permitted if Line Feeds (ASCII 10B) are found
in the text or single words are too large to fit on a line.
MODIFICATION HISTORY:
Written by David Fanning, June 2005.
Fixed a small problem with cumulative total not counting spaces between
words. Changed the default size to 60. DWF. 18 August 2005.
Added check for LF in text to accommodate reading netCDF file attributes.
If LF are present, I break on these, and return. 15 Feb 2008. DWF.
Better handling of lines with no white space in them for breaking. 23 March 2009. DWF.
(See textlineformat.pro)
NAME:
TEXTURE_SURFACE
PURPOSE:
The purpose of this program is to demonstrate how to
create a simple surface plot with an image applied as
a texture in object graphics.
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:
TEXTURE_SURFACE, data, x, y, Image=image
REQUIRED INPUTS:
None. Fake data will be used if no data is supplied in call.
OPTIONAL INPUTS
data: A 2D array of surface data.
x: A vector of X data values.
y: A vector of Y data values.
OPTIONAL KEYWORD PARAMETERS:
BORDERCOLOR : A three element array [R, G, B] describing the color
used to draw the non-textured part of the surface if POSITION is
specified.
COLORTABLE: The number of an IDL color table to use for the image
texture. Used only if the supplied image is 2D. Ignored otherwise.
EXACT: Set this keyword to get exact axis scaling.
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the surface initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
IMAGE: An 8-bit or 24-bit image you wish to use for the image texture.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
POSITION: A four element array of the form [x1, y1, x2, y2] that will
position the image with its lower-left corner at (x1,y1) and its upper-
right corner at (x2,y2) in the device coordinate system of the surface.
In other words, if my surface is a 41 by 41 array, and I want the image
positioned with lower-left at (5,10) and upper-right at (25,18), then
I call the program like this: Texture_Surface, Position=[5, 10, 25, 18].
VECTOR: Set this keyword if you want vector printing (as opposed to
the default bitmap printing).
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
ZSCALE: A number larger than or equal to 0.001 and less than or equal to 1.0 that affects Z scaling.
ZTITLE: A string used as the Z title of the plot.
COMMON BLOCKS:
None.
EXAMPLE:
To use this program with your surface data and 2D image, type:
IDL> data = cgDemoData(2)
IDL> image = cgDemoData(7)
IDL> Texture_Surface, data, Image=image, Colortable=33
RESTRICTIONS:
Requires the ASPECT program from the Coyote Library:
http://www.idlcoyote.com/programs/aspect.pro
MODIFICATION HISTORY
Written by David W. Fanning, 1 Nov 2001, from previous Simple_Surface code.
Modifications suggested by Karl Shultz added to allow surface color
specification and improved resolution about image edges when
positioning images. BORDERCOLOR keyword added. DWF. 4 Nov 2001.
The surface now maintains the same X/Y aspect ratio as the surface data. DWF. 8 April 2002.
Added ZSCALE keyword. DWF. 8 April 2002.
(See texture_surface.pro)
NAME:
TRANSFORM_VOLUME
PURPOSE:
The purpose of this program is to transform (e.g., rotate,
scale, and translate) a 3D array or volume.
AUTHOR:
Martin Downing,
Clinical Research Physicist,
Grampian Orthopaedic RSA Research Centre,
Woodend Hospital, Aberdeen, AB15 6LS.
Pnone: 01224 556055 / 07903901612
Fa: 01224 556662
E-mail: m.downing@abdn.ac.uk
CATEGORY:
Mathematics, graphics.
CALLING SEQUENCE:
result = TRANSFORM_VOLUME( volume )
INPUTS:
volume: The 3D array or volume to be transformed.
OPTIONAL KEYWORDS:
BUFFER_SIZE: To reduce memory overhead the routine processes the job in chunks, the number
of elements of which can be set using the BUFFER_SIZE keyword, set this keyword to
0 to force the whole array to be processed at one time. The default value is 128.
MISSING: The value to return for transformed values outside the bounds of
the volume. (Passed to the INTERPOLATE function.) Default is 0.
T3DMAT: The homogeneous transforamtion matrix. If this keyword is not present,
the following keywords can be used to create a homogeneous transformation matrix:
ROTATION - The rotation vector [rx,ry,rz]. The order of rotation is ZYX.
TRANSLATE - The translation vector [tx,ty,tz].
SCALE - The scale vector [sx,sy,sz].
CENTRE_ROTATION - The centre of rotation [cx,cy,cz].
OUTPUTS:
result: The transformed array or volume.
COMMON BLOCKS:
None.
DEPENDENCIES:
The program uses the library INTERPLOLATE routine, which currently (IDL 5.4)
uses linear interpolation. Note that the operation is performed in chunks,
each of which is independant of the result of the others, so the operation
could easiliy be parallelised.
MODIFICATION HISTORY:
Written by: Martin Downing, 16 September 2001.
Added MISSING keyword. Removed INPLACE keyword. 25 Nov 2001. MD
(See transform_volume.pro)
NAME:
UNDEFINE
PURPOSE:
The purpose of this program is to delete or undefine
an IDL program variable from within an IDL program or
at the IDL command line. It is a more powerful DELVAR.
Pointer and structure variables are traversed recursively
to undefine any variables pointed to in the pointer or in
a structure dereference.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1642 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:
UNDEFINE, variable
REQUIRED INPUTS:
variable: The variable to be deleted. Up to 10 variables may be specified as arguments.
SIDE EFFECTS:
The variable no longer exists.
EXAMPLE:
To delete the variable "info", type:
IDL> Undefine, info
IDL> var = ptr_new({a:ptr_New(5), b:findgen(11), c: {d:ptr_New(10), f:findgen(11)}})
IDL> Help, /Heap
Heap Variables:
# Pointer: 3
# Object : 0
LONG = 5
LONG = 10
STRUCT = -> Array[1]
IDL> Undefine, var
IDL> Help, /Heap
Heap Variables:
# Pointer: 0
# Object : 0
IDL> Help, var
VAR UNDEFINED =
MODIFICATION HISTORY:
Written by David W. Fanning, 8 June 97, from an original program
given to me by Andrew Cool, DSTO, Adelaide, Australia.
Simplified program so you can pass it an undefined variable. :-) 17 May 2000. DWF
Simplified it even more by removing the unnecessary SIZE function. 28 June 2002. DWF.
Added capability to delete up to 10 variables at suggestion of Craig Markwardt. 10 Jan 2008. DWF.
If the variable is a pointer, object or structure reference the variable is recursively traversed
to free up all variables pointed to before the variable is itself destroyed. 10 June 2009. DWF.
Updated to allow undefining of pointer arrays. 8 October 2009. DWF.
(See undefine.pro)
NAME:
VCOLORBAR
FILENAME:
vcolorbar__define.pro
PURPOSE:
The purpose of this program is to create a vertical
colorbar object to be used in conjunction with other
IDL 5 graphics objects.
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:
IDL Object Graphics.
CALLING SEQUENCE:
thisColorBar = Obj_New('VColorBar')
REQUIRED INPUTS:
None.
INIT METHOD KEYWORD PARAMETERS:
COLOR: A three-element array representing the RGB values of a color
for the colorbar axes and annotation. The default value is
white: [255,255,255].
NAME: The name associated with this object.
NCOLORS: The number of colors associated with the colorbar. The
default is 256.
MAJOR: The number of major tick divisions on the colorbar axes.
The default is 5.
MINOR: The number of minor tick marks on the colorbar axes.
The default is 4.
PALETTE: A palette object for the colorbar. The default palette
is a gray-scale palette object.
POSITION: A four-element array specifying the position of the
colorbar in the arbitary coordinate system of the viewplane
rectangle. The default position is [0.90, 0.10, 0.95, 0.90].
RANGE: The range associated with the colorbar axis. The default
is [0, NCOLORS].
TITLE: A string containing a title for the colorbar axis
annotation. The default is a null string.
OTHER METHODS:
Clamp (Procedure): Given a two-element array in the data range of
the colorbar, the colorbar image is clamped to this range. In
other words, the range of colors is clamped to the specified
range. Values above or below the range in the colorbar are set to
the minimum and maximum range values, respectively.
GetProperty (Procedure): Returns colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
MAJOR
MINOR
NAME
PALETTE
POSITION
RANGE
TITLE
TRANSFORM
SetProperty (Procedure): Sets colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
NAME
MAJOR
MINOR
PALETTE
POSITION
RANGE
TITLE
TRANSFORM
SIDE EFFECTS:
A VCOLORBAR object is created. The colorbar INHERITS IDLgrMODEL.
Thus, all IDLgrMODEL methods and keywords can also be used. It is
the model that is selected in a selection event, since the SELECT_TARGET
keyword is set for the model.
RESTRICTIONS:
Requires FSC_NORMALIZE from Coyote Library:
http://www.dfanning.com/programs/fsc_normalize.pro
EXAMPLE:
To create a colorbar object and add it to a plot view object, type:
thisColorBarObject = Obj_New('VColorBar')
plotView->Add, thisColorBarObject
plotWindow->Draw, plotView
MODIFICATION HISTORY:
Written by David W. Fanning, 19 June 97.
Changed the optional "colorbarmodel" parameter to an
optional GETMODEL parameter. 26 June 97. DWF.
Fixed bug in the way the color palette was assigned. 13 Aug 97. DWF.
Added missing container object to self structure. 13 Aug 97. DWF.
Removed image model, which was a workaround for
broken 5.0 objects. 5 Oct 97. DWF
Fixed cleanup procedure to clean up ALL objects. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Modified colorbar to INHERIT an IDLgrModel object. This allows me to
add the colorbar to other models directly. 20 Sept 98. DWF.
Added NAME keyword to give the colorbar a name. 20 Sept 98. DWF.
Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF.
Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF.
Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF.
Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF.
Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF.
Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF.
Removed TEXT keyword (which was never used) and fixed TITLE keyword. 8 Dec 2000. DWF.
Added ENABLE_FORMATTING keyword to title objects. 22 October 2001. DWF.
Added a CLAMP method. 18 November 2001. DWF.
Forgot to pass extra keywords along to the text widget. As a result, you couldn't
format tick labels, etc. Fixed this. Any keywords appropriate for IDLgrTick objects
are now available. 26 June 2002. DWF.
Fixed a problem with POSITION keyword in SetProperty method. 23 May 2003. DWF.
Removed NORMALIZE from source code. 29 Nov 2005. DWF.
Font sizes have changed. Now using a 12 point font. 6 May 2011. DWF.
(See vcolorbar__define.pro)
:Description:
This is a function that will identify the name of the procedure or function which
calls this function.
:Categories:
Utilities
:Params:
none
:Keywords:
none
: Return Value:
caller:
A string in uppercase letters identifying the name of the program
module containing this function.
:Examples:
Used to a module by name::
IDL> Print, WhoAmI()
; Compile and run the following main level program.
;***************************
PRO junker
Print, WhoAmI()
END
PRO junk
Print, WhoAmI()
END
junk
END
;**************************
IDL> .go
JUNK
JUNKER
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 28 January 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See whoami.pro)
:Description:
This is a function that will identify the caller of the program module
that contains this funciton.
:Categories:
Utilities
:Params:
none
:Keywords:
none
: Return Value:
caller:
A string in uppercase letters identifying the caller of the program
module from which this program was called.
:Examples:
Used to determine which module called this module containing WhoCalledMe::
IDL> Print, WhoCalledMe()
; Compile and run the following main level program.
;***************************
PRO junker
Print, WhoCalledMe()
END
PRO junk
Print, WhoCalledMe()
END
junk
END
;**************************
IDL> .go
$MAIN$
JUNK
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 16 January 2011. DWF.
:Copyright:
Copyright (c) 2011, Fanning Software Consulting, Inc.
(See whocalledme.pro)
NAME:
WINDBARB
PURPOSE:
This is routine for drawing wind barbs on a map.
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:
Windbarb, x, y, speed, direction
REQUIRED INPUTS:
x: The X location of the wind barb, expressed in data coordinates.
Positive X is pointing in EAST direction.
y: The Y location of the wind barb, expressed in data coordinates.
Positive Y is pointing in NORTH direction.
speed: The wind speed, expressed in knots.
direction: The wind direction in degrees clockwise from north. Winds from
the NE come at 45 degrees, and the wind "arrow" points in the
direction from which the window is blowing. (The wind arrow
points in the direction of the station circle, with the "barbs"
of the arrow at the end of the arrow from which the wind is coming.)
KEYWORDS:
ASPECT: The aspect ratio of the map or plot in the display window.
CLIP: A four-element array in normalized coordinates [x0,y0,x1,y1] giving
the lower-left and upper-right corner of a cliping rectangle. This
is normally the extent of your plot. See the example below.
COLOR: The name of the color to draw the wind barbs in. May be a vector
the same length as X.
LENGTH: The approximate length of the wind barb in normalized coordinates.
Will be set to 0.066 of the plot distance in the X direction by default.
MAP_ROTATION: The clockwise rotation in degrees of the map North from the
top of the plot. Will be set to 0.0 by default.
SOUTHERN_HEMISPHERE: Windbarb "feathers" are traditionally drawn in the clockwise
direction in the northern hemispere and countercolockwise in the
southern hemisphere. Default is "northern" type feathers. Set this
keyword to select "southern" type feathers.
STATION: Set this keyword if you want to draw the wind barbs with station symbols.
(Requires STATIONPLOT from the Coyote Library.)
RESTRICTIONS:
Requires cgColor and STATIONPLOT from the Coyote Library:
http://www.dfanning.com/programs/cgColor.pro
http://www.dfanning.com/programs/stationplot.pro
EXAMPLE:
Window, Title='Wind Barbs', /Free
seed = -3L
lon = Randomu(seed, 9) * 360 - 180
lat = Randomu(seed, 9) * 180 - 90
speed = Randomu(seed, 9) * 100 + 5.0
direction = Indgen(9)*45
Erase, Color=cgColor('Ivory', !P.Background)
Polyfill,[0.1, 0.1, 0.9, 0.9, 0.1], [0.1, 0.9, 0.9, 0.1, 0.1], /Normal, Color=cgColor('light gray')
Map_Set, /Cylindrical, Position=[0.1, 0.1, 0.9, 0.9], Color=cgColor('Steel Blue'), /NoErase
Map_Grid, Color=cgColor('Charcoal', !D.Table_Size-2)
Map_Continents, Color=cgColor('Sea Green', !D.Table_Size-3)
Windbarb, lon, lat, speed, direction, /Station, Color='Indian Red', /Southern_Hemisphere
To clip the windbards that fall outside the plot, substitute these two lines
for the last line in the example above:
clip = [0.1, 0.1, 0.9, 0.9]
Windbarb, lon, lat, speed, direction, /Station, Color='Indian Red', Clip=clip
MODIFICATION HISTORY:
Written by: David W. Fanning, 20 May 2003.
It has been called to my attention that the wind barbs are pointing
in *exactly* the wrong direction. Sigh... Rotated by 180 degrees. DWF. 8 June 2004.
Now someone complains that the *corrected* version is off by 180 degrees! Sheesh!
Clearly, I'm no meteorologist. Both lines of code are in the file. Please use the one
you like the best. :-) (Line 177-178) 20 July 2004. DWF.
Added a CLIP keyword so you can clip the output to the extend of your graphics plot. 12 Nov 2004. DWF.
Added THICK keyword 23 February 2005. DWF.
After further research, I've reverted to the direction specified originally.
And I have changed the "feathers" to point clockwise normally, and counterdlockwise
if the SOUTHERN_HEMISPHERE keyword is set. Here are my sources (21 July 2005. DWF):
http://ww2010.atmos.uiuc.edu/(Gh)/guides/maps/sfcobs/wnd.rxml
http://www.al.noaa.gov/WWWHD/pubdocs/windbarb.html
Fixed a small CLIP problem. 21 July 2005. DWF.
(See windbarb.pro)
NAME:
WindowAvailable
PURPOSE:
This function returns a 1 if the specified window index number is
currently open or available. It returns a 0 if the window is currently
closed or unavailable.
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:
available = WindowAvaiable(windowIndexNumber)
INPUTS:
windowIndexNumber: The window index number of the window you wish to
know is available or not.
KEYWORDS:
None.
NOTES:
The window vector obtained from the DEVICE command is not always the same length. It
is normally (on my machine) 65 elements long, but can be much longer if you have lots
of IDL windows open (by calling PickColorName, for example). But if no windows with
index numbers greater than 65 are open, IDL shinks the larger vector to the smaller one
as part of its housekeeping operations, which means it happens on their timetable, not yours.
This can result in the user having "stale" index numbers greater than 65, but no larger vector
to check them against. I have modified the code to return a 0 in this case, assuming that
whatever window your index number points to is long gone. I have not experience any ill effects
by doing this, but I STRONGLY advice you to ALWAYS know what window you are drawing into
when you issue a graphics command.
MODIFICATION HISTORY:
Written by David W. Fanning, June 2005.
Modified to return 0 if the window index number is larger than the number of elements
in the WINDOW_STATE array. 25 June 2008. DWF.
(See windowavailable.pro)
:Description:
Allows the user to interactively adjust image contrast by means of "windowing and
leveling" the image. Move the cursor vertically in the window to adjust the image
stretch "window". Move the cursor horizontally in the window to adjust the image
"level".
:Categories:
Graphics
:Params:
image: in, required, type=any
Any 2D array that you wish to adjust the contrast of.
:Keywords:
brewer: in, optional, type=boolean, default=0
Set this keyword to indicate a Brewer color table is desired.
colortable: in, optional, type=integer, default=0
The index number of a color table to load with cgLoadCT.
neutralcolor: in, optional, type=string
The name of the color to use for values outside the image "window" in
the color table. If a default grayscale color table is loaded, the default
color is "rose", otherwise the default is "black".
reverse: in, optional, type=boolean, default=0
Set this keyword if you wish to reverse the color table.
:Examples:
To see a demonstation::
IDL> WindowImage
:Author:
FANNING SOFTWARE CONSULTING::
David W. Fanning
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
:History:
Change History::
Written, 29 November 2010. DWF.
Added color protection to the program. 30 Nov 2010. DWF.
Modification of cgImage command to prevent flashing. 27 Feb 2011. DWF.
:Copyright:
Copyright (c) 2010, Fanning Software Consulting, Inc.
(See windowimage.pro)
NAME:
xcd
PURPOSE:
Change current directory via mouse.
Two lists are displayed side by side. The one on the left shows
directories. Click on a directory to cd there. The list
on the right shows files to help you see where you are.
(The list on the right does not respond to mouse clicks.)
CATEGORY:
Utility.
CALLING SEQUENCE:
xcd
INPUTS:
None.
KEYWORD PARAMETERS:
None
OUTPUTS:
None.
SIDE EFFECTS:
Your current directory can be changed.
RESTRICTIONS:
Windows & OpenVMS platforms only. Originally written on Windows95.
Should work on other Windows platforms, but I (Paul) havn't tried it.
With a little effort, one probably could port Xcd to other platforms
(i.e. Unix or Mac).
Note that drive names (e.g. "a:", "c:", etc.) are hardcoded in
xcd::init. Change that line of code to show drive letters
appropriate for your system.
PROCEDURE:
Xcd creates an object that has a reference to a DirListing, and
widgets for displaying that DirListing. If the user clicks on a
sub-directory (or "..\") in the xcd object, or droplist-selects
a different drive via the xcd object, the xcd object changes
IDL's current directory to that location, and refreshes with a
new current-directory DirListing.
MODIFICATION HISTORY:
Paul C. Sorenson, July 1997. paulcs@netcom.com.
Written with IDL 5.0. The object-oriented design of Xcd is
based in part on an example authored by Mark Rivers.
Jim Pendleton, July 1997. jimp@rsinc.com
Modified for compatability with OpenVMS as a basis for
platform independent code
Paul C. Sorenson, July 13 1997. Changes so that DirListing class
methods do not return pointers to data members. (Better
object-oriented design that way.)
(See xcd.pro)
NAME:
XCOLORS
PURPOSE:
The purpose of this routine is to interactively change color tables
in a manner similar to XLOADCT. No common blocks are used so
multiple copies of XCOLORS can be on the display at the same
time (if each has a different TITLE). XCOLORS has the ability
to notify a widget event handler, an object method, or an IDL
procedure if and when a new color table has been loaded. Brewer
color tables can also be accessed from this program, if the file
fsc_brewer.tbl can be found somewhere in your IDL path.
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, Command line.
CALLING SEQUENCE:
XCOLORS
INPUTS:
None.
KEYWORD PARAMETERS:
BLOCK: If this keyword is set, the program will try to block the
IDL command line. Note that this is only possible if no other
widget program is currently blocking the IDL command line. It
is much more reliable to make XCOLORS a modal widget (see the MODAL
keyword), although this can generally only be done when XCOLORS
is called from another widget program.
BREWER: Set this keyword if you wish to use the Brewer Colors, as explained
in this reference: http://www.dfanning.com/color_tips/brewer.html. The
Brewer color table file, fsc_brewer.tbl must be found somewhere in your
IDL path for this option to be available. The file can be downloaded here.
http://www.dfanning.com/programs/fsc_brewer.tbl
Note that if this file is found, the Brewer colors are automatically added
to the program as an option. In this case, the BREWER keyword just makes sure
this is the initial user choice.
BOTTOM: The lowest color index of the colors to be changed.
COLORINFO: This output keyword will return either a pointer to
a color information structure (if the program is called in
a non-modal fashion) or a color information structure (if the program
is called in modal or blocking fashion). The color information
structure is an anonymous structure defined like this:
struct = { R: BytArr(!D.Table_Size), $ ; The current R color vector.
G: BytArr(!D.Table_Size), $ ; The current G color vector.
B: BytArr(!D.Table_Size), $ ; The current B color vector.
NAME: "", $ ; The name of the current color table.
INDEX: 0, $ ; The index number of the current color table.
TYPE: "", $ ; The type of color table (e.g, BREWER or IDL).
BREWER: 0, $ ; Set to 1 if using BREWER color tables, else to 0.
REVERSED: 0B } ; Set to 1 if the color table is reversed.
If a pointer to the structure is obtained, you will be responsible
for freeing it to prevent memory leakage:
XColors, ColorInfo=colorInfoPtr
Print, "Color Table Name: ", (*colorInfoPtr).Name
Ptr_Free, colorInfoPtr
Note that that Name field will be "Unknown" and the Index field will
be -1 until a color table is actually selected by the user. You are
responsible for checking this value before you use it.
When called in modal or blocking fashion, you don't have to worry about freeing
the pointer, since no pointer is involved:
XColors, /Block, ColorInfo=colorInfoData
Help, colorInfoData, /Structure
Print, "Color Table Name: ", colorInfoData.Name
DATA: This keyword can be set to any valid IDL variable. If
the variable is defined, the specified object method or notify
procedure will be passed this variable via a DATA keyword. This
keyword is defined primarily so that Notify Procedures are compatible
with the XLOADCT way of passing data. It is not strictly required,
since the _EXTRA keyword inheritance mechanism will allow passing
of *any* keyword parameter defined for the object or procedure that is
to be notified.
DRAG: Set this keyword if you want colors loaded as you drag
the sliders. Default is to update colors only when you release
the sliders. Use of this keyword is greatly discouraged.
_EXTRA: This keyword inheritance mechanism will pick up and
pass along to any method or procedure to be notified and keywords
that are defined for that procedure. Note that you should be sure
that keywords are spelled correctly. Any mis-spelled keyword will
be ignored.
FILE: A string variable pointing to a file that holds the
color tables to load. The normal colors1.tbl file is used by default.
GROUP_LEADER: The group leader for this program. When the group
leader is destroyed, this program will be destroyed.
INDEX: The index of the color table to start up. If provided, a color
table of this index number is loaded prior to display. Otherwise,
the current color table is used. Set this keyword if you wish
to have the index number of the event structure correct when
the user CANCELs out of the progam.
MODAL: Set this keyword (along with the GROUP_LEADER keyword) to
make the XCOLORS dialog a modal widget dialog. Note that NO
other events can occur until the XCOLORS program is destroyed
when in modal mode.
NCOLORS: This is the number of colors to load when a color table
is selected.
NOSLIDERS: If this keyword is set, the color stretch and color gamma
sliders are not displayed. This would be appropriate, for example,
for programs that just load pre-defined color tables.
NOTIFYID: A 2-column by n-row array that contains the IDs of widgets
that should be notified when XCOLORS loads a color table. The first
column of the array is the widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarchy 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 XCOLORS_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {XCOLORS_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
R:BytArr(!D.TABLE_SIZE < 256), G:BytArr(!D.TABLE_SIZE < 256), $
B:BytArr(!D.TABLE_SIZE < 256), INDEX:0, NAME:"", $
TYPE:"", BREWER:0, REVERSED:0}
The ID field will be filled out with NOTIFYID[0, n] and the TOP
field will be filled out with NOTIFYID[1, n]. The R, G, and B
fields will have the current color table vectors, obtained by
exectuing the command TVLCT, r, g, b, /Get. The INDEX field will
have the index number of the just-loaded color table. The name
field will have the name of the currently loaded color table.
The TYPE field with be "BREWER" if a Brewer color table was loaded,
or "IDL" otherwise. The BREWER field will be set to 1 if a Brewer
color table was loaded, or to 0 otherwise. The REVERSED field will
be set to 1 if the color table is reversed, or to 0 otherwise.
Note that XCOLORS can't initially tell *which* color table is
loaded, since it just uses whatever colors are available when it
is called. Thus, it stores a -1 in the INDEX field to indicate
this "default" value. Programs that rely on the INDEX field of
the event structure should normally do nothing if the value is
set to -1. This value is also set to -1 if the user hits the
CANCEL button. (Note the NAME field will initially be "Unknown").
Typically the XCOLORS button will be defined like this:
xcolorsID = Widget_Button(parentID, Value='Load New Color Table...', $
Event_Pro='Program_Change_Colors_Event')
The event handler will be written something like this:
PRO Program_Change_Colors_Event, event
; Handles color table loading events. Allows colors be to changed.
Widget_Control, event.top, Get_UValue=info, /No_Copy
thisEvent = Tag_Names(event, /Structure_Name)
CASE thisEvent OF
'WIDGET_BUTTON': BEGIN
; Color table tool.
XColors, NColors=info.ncolors, Bottom=info.bottom, $
Group_Leader=event.top, NotifyID=[event.id, event.top]
ENDCASE
'XCOLORS_LOAD': BEGIN
; Update the display for 24-bit displays.
Device, Get_Visual_Depth=thisDepth
IF thisDepth GT 8 THEN BEGIN
WSet, info.wid
...Whatever display commands are required go here. For example...
TV, info.image
ENDIF
ENDCASE
ENDCASE
Widget_Control, event.top, Set_UValue=info, /No_Copy
END
NOTIFYOBJ: A vector of structures (or a single structure), with
each element of the vector defined as follows:
struct = {XCOLORS_NOTIFYOBJ, object:Obj_New(), method:''}
where the Object field is an object reference, and the Method field
is the name of the object method that should be called when XCOLORS
loads its color tables.
ainfo = {XCOLORS_NOTIFYOBJ, a, 'Draw'}
binfo = {XCOLORS_NOTIFYOBJ, b, 'Display'}
XColors, NotifyObj=[ainfo, binfo]
Note that the XColors program must be compiled before these structures
are used. Alternatively, you can put this program, named
"xcolors_notifyobj__define.pro" (*three* underscore characters in this
name!) in your PATH:
PRO XCOLORS_NOTIFYOBJ__DEFINE
struct = {XCOLORS_NOTIFYOBJ, OBJECT:Obj_New(), METHOD:''}
END
Or, you can simply define this structure as it is shown here in your code.
"Extra" keywords added to the XCOLORS call are passed along to
the object method, which makes this an alternative way to get information
to your methods. If you expect such keywords, your methods should be defined
with an _Extra keyword.
If you set the /OBJECT_DATA keyword, the same structure defined for the
COLORINFO keyword above will be passed to your object method via an
XCOLORS_DATA keyword that you will have to define for the method.
NOTIFYPRO: The name of a procedure to notify or call when the color
tables are loaded. If the DATA keyword is also defined with a valid
IDL variable, it will be passed to this program via an DATA keyword.
But note that *any* keyword appropriate for the procedure can be used
in the call to XCOLORS. For example, here is a procedure that re-displays
an image in the current graphics window:
PRO REFRESH_IMAGE, Image=image, _Extra=extra, WID=wid
IF N_Elements(wid) NE 0 THEN WSet, wid
cgImage, image, _Extra=extra
END
This program can be invoked with this series of commands:
IDL> Window, /Free
IDL> cgImage, image, Position=[0.2, 0.2, 0.8, 0.8]
IDL> XColors, NotifyPro='Refresh_Image', Image=image, WID=!D.Window
Note that "extra" keywords added to the XCOLORS call are passed along to
your procedure, which makes this an alternative way to get information
to your procedure. If you expect such keywords, your procedure should
be defined with an _Extra keyword as illustrated above.
OBJECT_DATA: Set this keyword if you wish color information to be
supplied to your object notification method via an XCOLORS_DATA
keyword. This keyword is ignored unless the NOTIFYOBJ keyword is
also used. The color information is supplied as a structure and is
defined in the COLORINFO keyword definition above.
REVERSE: If this keyword is set, the color table is reversed and the
Reverse Color Table button is set on.
TITLE: This is the window title. It is "Load Color Tables" by
default. The program is registered with the name 'XCOLORS:' plus
the TITLE string. The "register name" is checked before the widgets
are defined. If a program with that name has already been registered
you cannot register another with that name. This means that you can
have several versions of XCOLORS open simultaneously as long as each
has a unique title or name. For example, like this:
IDL> XColors, NColors=100, Bottom=0, Title='First 100 Colors'
IDL> XColors, NColors=100, Bottom=100, Title='Second 100 Colors'
WINDOW: Set this keyword to send the colors to an FSC_Window program.
WINID: The window index number of an FSC_Window to receive the color vectors.
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:
Colors are changed. Events are sent to widgets if the NOTIFYID
keyword is used. Object methods are called if the NOTIFYOBJ keyword
is used. This program is a non-blocking widget.
RESTRICTIONS:
None.
EXAMPLE:
To load a color table into 100 colors, starting at color index
50 and send an event to the widget identified at info.drawID
in the widget heirarchy of the top-level base event.top, type:
XCOLORS, NCOLORS=100, BOTTOM=50, NOTIFYID=[info.drawID, event.top]
MODIFICATION HISTORY:
Written by: David W. Fanning, 15 April 97. Extensive modification
of an older XCOLORS program with excellent suggestions for
improvement by Liam Gumley. Now works on 8-bit and 24-bit
systems. Subroutines renamed to avoid ambiguity. Cancel
button restores original color table.
23 April 1997, added color protection for the program. DWF
24 April 1997, fixed a window initialization bug. DWF
18 June 1997, fixed a bug with the color protection handler. DWF
18 June 1997, Turned tracking on for draw widget to fix a bug
in TLB Tracking Events for WindowsNT machines in IDL 5.0. DWF
20 Oct 1997, Changed GROUP keyword to GROUP_LEADER. DWF
19 Dec 1997, Fixed bug with TOP/BOTTOM reversals and CANCEL. DWF.
9 Jun 1998, Fixed bug when using BOTTOM keyword on 24-bit devices. DWF
9 Jun 1998, Added Device, Decomposed=0 for TrueColor visual classes. DWF
9 Jun 1998, Removed all IDL 4 compatibility.
21 Oct 1998, Fixed problem with gamma not being reset on CANCEL. DWF
5 Nov 1998. Added the NotifyObj keyword, so that XCOLORS would work
interactively with objects. DWF.
9 Nov 1998. Made slider reporting only at the end of the drag. If you
want continuous updating, set the DRAG keyword. DWF.
9 Nov 1998. Fixed problem with TOP and BOTTOM sliders not being reset
on CANCEL. DWF.
10 Nov 1998. Fixed fixes. Sigh... DWF.
5 Dec 1998. Added INDEX field to the XCOLORS_LOAD event structure. This
field holds the current color table index number. DWF.
5 Dec 1998. Modified the way the colorbar image was created. Results in
greatly improved display for low number of colors. DWF.
6 Dec 1998. Added the ability to notify an unlimited number of objects. DWF.
12 Dec 1998. Removed obsolete Just_Reg keyword and improved documetation. DWF.
30 Dec 1998. Fixed the way the color table index was working. DWF.
4 Jan 1999. Added slightly modified CONGRID program to fix floating divide
by zero problem. DWF
2 May 1999. Added code to work around a Macintosh bug in IDL through version
5.2 that tries to redraw the graphics window after a TVLCT command. DWF.
5 May 1999. Restore the current window index number after drawing graphics.
Not supported on Macs. DWF.
9 Jul 1999. Fixed a couple of bugs I introduced with the 5 May changes. Sigh... DWF.
13 Jul 1999. Scheesh! That May 5th change was a BAD idea! Fixed more bugs. DWF.
31 Jul 1999. Substituted !D.Table_Size for !D.N_Colors. DWF.
1 Sep 1999. Got rid of the May 5th fixes and replaced with something MUCH simpler. DWF.
14 Feb 2000. Removed the window index field from the object notify structure. DWF.
14 Feb 2000. Added NOTIFYPRO, DATA, and _EXTRA keywords. DWF.
20 Mar 2000. Added MODAL, BLOCK, and COLORINFO keywords. DWF
20 Mar 2000. Fixed a slight problem with color protection events triggering
notification events. DWF.
31 Mar 2000. Fixed a problem with pointer leakage on Cancel events, and improved
program documentation. DWF.
17 Aug 2000. Fixed a problem with CANCEL that occurred only if you first
changed the gamma settings before loading a color table. DWF.
10 Sep 2000. Removed the requirement that procedures and object methods must
be written with an _Extra keyword. DWF.
5 Oct 2000. Added the File keyword to LOADCT command, as I was suppose to. DWF.
5 Oct 2000. Now properly freeing program pointers upon early exit from program. DWF.
7 Mar 2001. Fixed a problem with the BLOCK keyword. DWF.
12 Nov 2001. Renamed Congrid to XColors_Congrid. DWF.
14 Aug 2002. Moved the calculation of NCOLORS to after the draw widget creation
to fix a problem with !D.TABLE_SIZE having a correct value when no windows had
been opened in the current IDL session. DWF.
14 Aug 2002. Fixed a documentation problem in the NOTIFYID keyword documentation
that still referred to !D.N_COLORS instead of the current !D.TABLE_SIZE. DWF.
27 Oct 2003. Added INDEX keyword. DWF.
29 July 2004. Fixed a problem with freeing colorInfoPtr if it didn't exist. DWF.
5 December 2005. Added NOSLIDERS keyword and performed some small cosmetic changes. DWF.
27 Sep 2006. Fixed a problem in which XCOLORS set device to indexed color mode. DWF.
14 May 2008. Added ability to read the Brewer Color Table file, if available. DWF
8 July 2008. Small change in how the program looks for the Brewer file. DWF.
1 October 2008. Added a button to switch from either BREWER color tables to IDL
color tables, depending upon which is showing currently. The button ONLY appears
if the file fsc_brewer.tbl can be found somewhere in the IDL distribution. DWF.
7 October 2008. Whoops! The 1 Oct change wasn't as simple as that. Fixed problems with
destroy and restarting the program with respect to keywords that are set, etc. DWF.
12 October 2008. Changed license to BSD Open Software License. DWF.
21 October 2008. Found a problem with MODAL operations that I fixed. However, that
led to problems with how I was switching from IDL to Brewer colors and visa versa,
so I changed that mechanism, too.
21 October 2008. Added OBJECT_DATA keyword so that I can get additional information
about the state of the color table tool into object methods. DWF.
12 April 2009. Add REVERSE keyword and Reverse Color Table button. DWF.
28 April 2009. In looking for a Brewer color table file, I replaced all FILE_WHICH
commands with FIND_RESOURCE_FILE commands. DWF.
(See xcolors.pro)
NAME:
XMOVIE
PURPOSE:
This program is a simplified version of XINTERANIMATE. It is written
to illustrate the proper way to write an animation loop in a widget
program using the WIDGET_TIMER functionality and pixmaps.
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.
CALLING SEQUENCE:
XMOVIE, image3d
INPUTS:
image3d: A three-dimensional image array. The animation occurs over
the third dimension.
KEYWORD PARAMETERS:
GROUP: The group leader of the program. When the group leader dies,
this program dies as well.
TITLE: The window title of the program. The default is "Animation
Example...".
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
EXAMPLE:
To open the abnormal heart data and animate it, type:
filename = FILEPATH(SUBDIR=['examples', 'data'], 'abnorm.dat')
OPENR, lun, filename, /GET_LUN
data = BYTARR(64, 64, 15)
READU, lun, data
FREE_LUN, lun
data = REBIN(data, 256, 256, 15)
XMOVIE, data
MODIFICATION HISTORY:
Written by: David W. Fanning, June 96.
Added slider for controlling animation speed. 30 June 99. DWF
Added pixmap operations. 15 May 2002. DWF
(See xmovie.pro)
NAME:
XSTRETCH
PURPOSE:
The purpose of this program is to allow the user to perform a variety
of image pixel transformations, commonly known as "contrast stretching".
The program supports the following stretches:
LINEAR Linear stretch between end points.
LINEAR 2% Linear, except 2% of pixels are clipped at either end of histogram.
GAMMA An exponential function.
LOG An S-shaped log function.
ASINH An inverse hyperbolic sine function (strong log function).
SQUARE ROOT Another type of log function.
EQUALIZATION Image histogram is equalized before stretching.
ADAPTIVE EQUALIZATION Image histogram is equalized with Adapt_Hist_Equal before stretching.
GAUSSIAN A gaussian normal distribution function.
An image histogram is provided to the user as an aid in manipulating
the stretch parameters.
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:
Image Processing, Widgets
CALLING SEQUENCE:
XSTRETCH, image
INPUT PARAMETERS:
image: The image data to be stretched. It must be 2D array or a
pointer to a 2D array.
KEYWORD PARAMETERS:
BETA: The "softening parameter" associated with the ASINH stretch. (See ASINHSCL for
details.) Set to 3 by default.
BLOCK: Set this keyword if you wish the program to be a blocking widget.
BREWER: Set this keyword if you wish to use the Brewer Colors, as explained
in this reference: http://www.dfanning.com/color_tips/brewer.html. The
Brewer color table file, fsc_brewer.tbl must be found somewhere in your
IDL path for this option to be available. The file can be downloaded here.
http://www.dfanning.com/programs/fsc_brewer.tbl
COLORS: A five element string array, listing the cgColorS colors for drawing the
histogram plot. The colors are used as follows:
colors[0] : Background color. Default: "white".
colors[1] : Axis color. Default: "black".
colors[2] : Min threshold color. Default: "firebrick".
colors[3] : Max threshold color. Default: "steel blue".
colors[4] : ASinh color. Default: "grn6".
colors[5] : Histogram color. Default: "charcoal".
If a particular color is represented as a null string, then the
default for that color is used.
COLORTABLE: The index of a colortable you would like to load.
A gray-scale colortable is used if this parameter is not provided.
EXPONENT: The "exponent" parameter of a LOG stretch. (See LOGSCL for details.)
Set to 4.0 by default.
_EXTRA: This keyword collects any keyword appropriate for the
Plot command, which is used to display the image histogram.
FILENAME: If no image is supplied as a positional parameter, this keyword can be
used to specify the name of an image file. The image must be capable of
being read by IMAGESELECT, so that means these kinds of files with these
file extensions:
TYPE FILE EXTENSION
BMP *.bmp
DICOM *.dcm
FITS *.fits, *.fts (requires NASA ASTRO library on IDL Path)
GIF *.gif (IDL 6.2 and higher)
JPEG *.jpg, *.jpeg, *.jpe
JPEG2000 *.jpf, *.jpx, *.jp2, *.j2c, *.j2k
PICT *.pict
PNG *.png
TIFF *.tif, *tiff
GAMMA: The gamma scale factor. (See GMASCL for details.) Set to 1.5 by default.
GROUP_LEADER: Keyword to assign a group leader (so this program can be
called from within another widget program).
MAX_VALUE: Keyword to assign a maximun value for the normalized Histogram Plot.
Images with lots of pixels of one color (e.g. black) skew
the histogram. This helps make a better looking plot. Set by default
to the maximum value of the histogram data.
MINTHRESH: The initial minimun threshold value for the stretch.
MAXTHRESH: The initial maximum threshold value for the stretch.
MEAN: The "mean" parameter of a LOG stretch. (See LOGSCL for details.)
Set to 0.5 by default.
NEGATIVE: Set this keyword if you prefer to see a negative image, rather
that the normal positive image.
NO_WINDOW: Set this keyword if you do no want the program to display an
image window. This would be the case, for example, if you
are displaying the image in your own window and your program
is being notified of images changes via the NOTIFY_PRO or
NOTIFY_OBJ keywords.
NOTIFY_OBJ: Set this keyword to a structure containing the fields OBJECT
and METHOD. When the image is changed, the object identified in
the OBJECT field will have the method identified in the METHOD
field called. The method should be written to accept one positional
parameter. The parameter passed to the method is a structure as defined
below.
NOTIFY_PRO: Set this keyword to the name of a procedure that should
be notified when the image is changed. The procedure should
be defined with one positional parameter. The parameter passed
to the procedure is a structure defined as below.
SIGMA: The amount of width applied to the Gaussian stretch. Default is 1.
TITLE: The title of the histogram window. By default: 'Drag Vertical Lines to STRETCH Image Contrast'.
TYPE: The type of stretch to be applied. May be either a string (e.g, 'GAMMA') or a number from
the table below:
Number Type of Stretch
0 Linear scaled = BytScl(image, MIN=minThresh, MAX=maxThresh)
1 Gamma scaled = GmaScl(image, MIN=minThresh, MAX=maxThresh, Gamma=gamma)
2 Log scaled = LogScl(image, MIN=minThresh, MAX=maxThresh, Mean=mean, Exponent=exponent)
3 Asinh scaled = AsinhScl(image, MIN=minThresh, MAX=maxThresh, Beta=beta)
4 Linear 2% A linear stretch, with 2 percent of pixels clipped at both the top and bottom
5 Square Root A linear stretch of the square root histogram of the image values.
6 Equalization A linear stretch of the histogram equalized image histogram.
7 Gaussian A Gaussian normal function is applied to the image histogram.
UVALUE: Simply a holder for any IDL variable. If this is defined, then the structure
passed via NOTIFY_OBJ or NOTIFY_PRO will contain an extra field named UVALUE.
XPOS: The X position of the histogram window in pixels from upper-left
of display. By default, 100.
YPOS: The Y position of the histogram window in pixels from upper-left
of display. By default, 100.
OUTPUTS:
The image and histogram windows can be save as BMP, JPEG, PNG, PICT, TIFF, GIF, and PostScript output
files from the Control pull-down menu.
The stretched image, the stretched image histogram (in 256-element format, suitable for
input into HISTOMATCH), and the current stretch parameters can be saved as main-level IDL
variables from the Control pull-down menu. If you choose to save "parameters", a structure
of this form is saved:
struct = { minThresh: info.minThresh, $
maxThresh: info.maxThresh, $
gamma: info.gamma, $
beta: info.beta, $
mean: info.mean, $
exponent: info.exponent, $
type: info.type }
The TYPE field is a string that reflects the current stretch type at the time the
parameters were saved. This should be used to tell you which other fields in the structure
are pertinent for a stretch operation.
If you choose to save "everything", the saved variable is a structure similar to the one above,
except there are two additional fields: (1) IMAGE contains the stretched image, and HISTOGRAM
contains the stretch image histogram.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
NOTIFICATION STRUCTURE:
If you choose to be notified of changes in the image (NOTIFY_PRO or NOTIFY_OBJ),
the following structure will be sent as the first positional parameter:
struct = { image: stretchedImage, $ ; The stretched image.
r: info.r, $ ; The R color vector associated with the image
g: info.g, $ ; The G color vector associated with the image
b: info.b, $ ; The B color vector associated with the image
type: info.type, $ ; The TYPE of stretch applied to the image.
minThresh: info.minThresh, $ ; The minimum threshold value.
maxThresh: info.maxThresh, $ ; The maximum threshold value.
beta: info.beta, $ ; The current BETA value.
gamma: info.gamma, $ ; The current GAMMA value.
mean: info.mean, $ ; The current MEAN value.
exponent: info.exponent, $ ; The current EXPONENT value.
sigma: info.sigma } ; The current SIGMA value.
A "uvalue" field might also be in this structure if something was passed with the UVALUE keyword.
DEPENDENCIES:
Requires a number of files from the Coyote Library:
http://www.idlcoyote.com/programs/coyoteprograms.zip
EXAMPLE:
If you have a 2D image in the variable "image", you can run this
program like this:
XSTRETCH, image
XSTRETCH, image, TYPE='GAMMA'
XSTRETCH, image, TYPE='LOG', EXPONENT=5.5
XSTRETCH, image, TYPE='ASINH', BETA=0.1
For a good ASINH image, try the FITS files located here:
http://cosmo.nyu.edu/hogg/visualization/rgb/
MODIFICATION HISTORY:
Written by: David W. Fanning, April 1996.
October, 1996 Fixed a problem with not restoring the color
table when the program exited. Substituted a call to XCOLORS
instead of XLOADCT.
October, 1998. Added NO_BLOCK keyword and modified to work with
24-bit color devices.
April, 1999. Made lines thicker. Offered default image. DWF.
April, 1999. Replaced TV command with cgImage. DWF.
April, 1999. Made both windows resizeable. DWF.
April, 2000. Made several modifications to histogram plot and to
the way colors were handled. Added ability to pass pointer to
the image as well as image itself. DWF.
February 2001. Removed GIF file support for IDL 5.4 and fixed
a problem with cleaning up the pixmap. DWF.
October 29, 2002. Added ability to load an image file with GETIMAGE. DWF.
Added ability to store stretched image as main-level variable. Oct 30, 2002. DWF.
Fixed a problem with the image window aspect ratio being calculated
incorrectly. 2 Nov 2002. DWF.
Added ability to open formatted images as well as raw data files. 2 Nov 2002. DWF.
Fixed a couple of minor problems with resizing the histogram window. 4 Nov 2002. DWF.
Added NO_WINDOW and NOTIFY_PRO keywords. 4 Nov 2002. DWF.
Fixed a problem with the histogram plot when the minimum image value
is greater than 0. 8 Nov 2002. DWF.
Added NOTIFY_OBJ and BLOCK keywords. 16 Nov 2002. DWF.
Fixed some problems in which images that are NOT byte valued could not be
displayed property. 29 Dec 2005. DWF.
Added GIF images back in. 29 Dec 2005. DWF.
EXTENSIVE modifications, primarily so it would work perfectly with perverse
FITS images. 20 Feb. 2006. DWF.
Added NEGATIVE keyword. 20 Feb. 2006. DWF.
Added GAMMA stretch. 20 Feb. 2006. DWF.
Added LOG and ASINH stretches. 25 Feb. 2006. DWF.
Added ability to save the stretched image, the stretched image histogram, and
image stretch parameters as main-level IDL variables. 1 March 2006. DWF.
Removed restrictions for 2D images. Now allows 24-bit images (MxNx3) to
be loaded. 3 March 2006.
Modified the histogram plot xrange to use the output min and max from
the histogram. 3 March 2006.
Renamed IMGSCL to GMASCL to avoid name space conflicts. 8 March 2006. DWF.
Modifications to GUI for updated ASINHSCL function. Removed ALPHA keyword
and changed the definition of BETA. 25 April 2006. DWF.
Added LINEAR 2%, SQUARE ROOT, GAUSSIAN and EQUALIZATION stretches. 4 Sept 2007. DWF
Added MINTHRESH and MAXTHRESH keywords. 25 June 2008. DWF.
Fixed a problem with the plot coordinate system not being re-established correctly
under certain circumstances. 9 July 2008. DWF.
Fixed several small errors in using the TYPE keyword, and added the ability to
restore the original stretch to the image from the Controls menu. Bug here
is identified as bug in FSC_INPUTFIELD, so be sure to get this program, too. 1 October 2008. DWF.
Fixed a problem with the Linear 2% stretch giving incorrect results. 14 October 2008. DWF.
Added a NAN keyword to every HISTOGRAM call. 6 November 2008. DWF.
Modifed the way the histogram was drawn. 14 March 2009. DWF.
Add BREWER and UVALUE keywords to the program. 15 April 2009. DWF.
Improvements made to histogram plotting functionality to better handle bin size and
problems caused by NANs in the input image. 9 June 2009. DWF.
Whoops! Left a NAN keyword out of a STDDEV call, and this caused havoic with binsize. 25 Aug 2009 DWF.
Modifications for EQUALIZATION stretch and for working with large images. 26 Aug 2009. DWF.
Fixed a problem with too strict interpretation of PLOT keywords passed to it from legacy code. Changed
_STRICT_EXTRA on Plot command to _EXTRA. 26 Aug 2009. DWF.
Fixed a problem when choosing binsize for integer data types GE 12. 25 Jan 2010. DWF.
Fixed a small typo that caused the histogram to be taken of the square-root of the
image, rather than the image itself. 31 March 2010, DWF.
Byte type data is causing me heartburn. Internally, use INT data when byte type data
is passed in. 10 April 2010. DWF.
Fixed a general problem when working with unsigned integer images. I now make sure
threshold values stay within the data range appropriate for the data type. 21 April 2010. DWF.
Fixed another problem with integer data types and bin size. 23 April 2010. DWF.
Fixed a problem with the display image when starting with a Square Root stretch. 23 April 2010. DWF.
Added ADAPTIVE EQUALIZATION stretch and changed default colors. 24 Nov 2010. DWF.
Changed SELECTIMAGE references to Coyote Library routine IMAGESELECT. 6 Jan 2011. DWF.
Fixed misplaced parenthesis with SQRT function and NAN keyword. 7 March 2011. DWF.
(See xstretch.pro)
NAME:
ZOOMBOX
PURPOSE:
The purpose of this program is to display an image which
can be zoomed by drawing a rubberband box on top of it. The
"zoomed" image appears in its own window. The program is written
in object graphics. Either 8-bit or 24-bit images may be used.
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:
Image Processing, Widgets.
CALLING SEQUENCE:
ZOOMBOX, image
INPUTS:
image: An 8-bit or 24-bit image.
GROUP_LEADER: This keyword is used to assign a group leader to this
program. This program will be destroyed when the group
leader is destroyed. Use this keyword if you are calling
ZOOMBOX from another widget program.
HARDWARE_RENDERING: Set this keyword if you want to render the scene using
the hardware renderer. This is NOT recommended, since this makes
rendering exceedingly slow on most machines.
INSTANCE: Set this keyword to use instancing to draw the rubberband zoom box.
The default is not to use instancing.
INTERPOLATE: Set this keyword to use bilinear interpolation on the sub-image
defined by the box when zooming. The default is to use nearest neighbor
interpolation.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
DEPENDENCIES:
Uses XCOLORS and PICKCOLOR from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
http://www.dfanning.com/programs/pickcolor.pro
PROCEDURE:
Clicking the left mouse button allows you to drag a rubberband box
over the portion of the window you want to zoom into.
EXAMPLE:
IDL> ZOOMBOX
RESTRICTIONS:
Object graphics programs are really meant to be used on 24-bit displays.
Colors are decidedly ugly in 256 color environments.
Requires FSC_NORMALIZE from the Coyote Library.
http://www.dfanning.com/programs/fsc_normalize.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 24 April 2000.
Modified draw widget event handling. 22 October 2001. DWF.
Added INSTANCE keyword to demonstrate instancing in object. 14 February 2002. Mark Hadfield.
Removed NORMALIZE from source code. 29 Nov 2005. DWF.
Renamed NORMALIZE to FSC_NORMALIZE to avoid numerous naming conflicts. 17 October 2008. DWF.
(See zoombox.pro)