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: Wed Jun 13 14:08:03 2007.
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:
ANNOTATEWINDOW
PURPOSE:
The purpose of this routine is to allow the user to annotate or make
measurements on a graphics window. A copy of the graphics window is
created and placed into an annotation window. The user can create
various kinds of file output from within the annotation window.
Select the annotation tool from the tool bar at the top of the annotate
window. Click and drag in the window to draw the annotation. (The text
tool requires you to click in the window to start typing. Be sure to
hit a carriage return at the end of typing to "set" the text in the
window.) Click anywhere inside the tool to "select" it. Most tools
allow you to move and edit the shape of the annotation after selection.
Right click inside a selected annotation to access properties of that
annotation, such as grouping, moving an annotation forward to backward,
deleting the object, etc. Click the "Other Properties" button to access
individual properties for the annotations. For example, if you mis-spelled
some text, you would click on the text to select it. Right click to access
it's select menu, select the Other Properties button, and find the text
field in this pop-up dialog to change the spelling of the text.
AUTHORS:
FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
1645 Sheely Drive 18 The Green South
Fort Collins Warborough, Oxon
CO 80526 USA OX10 7DN, ENGLAND
Phone: 970-221-0438 Phone: +44 (0)1865 858279
E-mail: davidf@dfanning.com E-mail: davidb@burridgecomputing.co.uk
CATEGORY:
Catalyst Applications.
SYNTAX:
AnnotateWindow, theBackground
ARGUMENTS:
theBackground: This can either be the window index number of a graphics window,
or it can be an 8-bit or 24-bit image variable. If this argument
is undefined, the program tries to obtain a background image
from the current graphics window. Note that if the graphics window
contains a black background (the normal situation for many IDL
graphics windows), this will be reproduced *exactly* in PostScript
output. This is NOT the same as most PostScript output. If you
intend to create PostScript output of your annotated window, it
may be better to create graphics windows with white backgrounds.
Device, Decomposed=0, Get_Decomposed=currentState
TVLCT, [0, 255], [0,255], [0, 255], !D.Table_Size-3
Plot, findgen(11), Color=!D.Table_Size-3, Background=!D.Table_Size-2
Device, Decomposed=currentState
AnnotateWindow
KEYWORDS:
BG_COLOR: The name of a background color. This is used only if there is a margin
around the background image. By default, "white". The background color
will always be "white" if the output is sent to a PostScript file. (See list
of color names below.)
COLOR: The name of the foreground color for the annotations. By default "Light Coral"
as something that might contrast enough with any background. (See list
of color names below.)
NOMARGIN: There is a 10% margin added to the background image, unless this keyword
is set, in which case the background image will fill the annotation window.
XRANGE: The TapeMeasure tool will report the distance in normalized coordinate space
by default. Use this keyword to specify a two-element array that represents
the minimum and maximum X range of the background image.
YRANGE: The TapeMeasure tool will report the distance in normalized coordinate space
by default. Use this keyword to specify a two-element array that represents
the minimum and maximum Y range of the background image.
RESTRICTIONS:
Requires the Catalyst Library from Fanning Software Consulting, Inc., or a catalyst.sav file
to be restored prior to use. A Catalyst save file may be download from Coyote's Guide to IDL
Programming. Be sure to download a version compatible with your IDL license.
http://www.dfanning.com/programs/catalyst.sav (for IDL 6.1 or higher)
The following color names can be used for the BG_COLOR and COLOR keywords:
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
EXAMPLE:
To annotate a medical image:
filename = Filepath(Subdirectory=['examples','data'], 'mr_knee.dcm')
image = Read_DICOM(filename)
AnnotateWindow, Rebin(image, 512, 512), XRange=[0,5], YRange=[0,5]
Remember to right-click on any annotation object to access that objects properties.
This is the way you would change a mis-spelled text label, add units to a measurement,
change the color of an annotation object, etc.
Also remember that you MUST type a carriage return when using the Text Tool to
"set" the text into the annotation window.
MODIFICATION_HISTORY:
Written by: David W. Fanning, 25 July 2005.
Improved documentation header. 11 August 2005. DWF.
(See annotatewindow.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:
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:
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:
CHGCOLOR
PURPOSE:
The purpose of this routine is to allow the user to change
the color at a particular color index. The user is able to
mix their own color by manipulating red, green, and blue
sliders. This routine is ideal for changing axes or background
colors of a plot, for example. The routine works on 8-bit,
16-bit, and 24-bit displays.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Widgets, Colors.
CALLING SEQUENCE:
CHGCOLOR, index
REQUIRED INPUTS:
INDEX: The color index to be changed. It must be a value
between 0 and 255.
KEYWORD PARAMETERS:
LABEL: Text that goes next to the color window. The default is
"Resulting Color".
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
NOTIFYID: A a 2 column by n row array that contains the IDs of widgets
that should be notified when CHGCOLOR changes a color. The first
column of the array contains widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarch in which the corresponding widgets in the first column
are located. (The purpose of the top widget IDs is to make it
possible for the widget in the first column to get the "info"
structure of the widget program.) An CHGCOLOR_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {CHGCOLOR_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
r:(!D.N_COLORS < 256), g:(!D.N_COLORS < 256), b:(!D.N_COLORS < 256)}
The ID field will be filled out with NOTIFYID(0, n) and the TOP
field will be filled out with NOTIFYID(1, n).
TITLE: This is the window title. It is "Modify Drawing Color" by
default. The program is registered with the name "chgcolor " plus
the TITLE string. The register name is checked before the widgets
are defined. This gives you the opportunity to have multiple copies
of CHGCOLOR operating simultaneously. (For example, one will change
the background color and one will change the plotting color.)
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color at the specified index is changed. Events are sent to widgets
if the NOTIFYID keyword is used.
RESTRICTIONS:
None.
EXAMPLE:
To change the background color of a plot, type:
CHGCOLOR, !P.Background
To see a more complete example, look at the program SLICE
in the Coyote Software Library:
ftp://ftp.frii.com/pub/dfanning/outgoing/idl_examples
MODIFICATION HISTORY:
Written by David Fanning, 23 April 97.
12 May 97, Fixed a bug in the way colors were loaded when
a tracking event occurred. DWF
13 May 97, Added a JUST_REGISTER keyword and set it up for
running in IDL 5.0 as a non-blocking widget.
27 Sept 98. Fixed problems caused by IDL 5.1 color changes.
27 Sept 98. Removed JUST_REGISTER keyword. Made widget non-blocking.
03 Nov 98. Modified layout and added slider ganging. DWF.
(See chgcolor.pro)
NAME:
CIndex
PURPOSE:
This is a program for viewing the current colors in the
colortable with their index numbers overlayed on each color.
On 24-bit systems you must click the cursor in the graphics window
to see the colors in the current color table.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY: Graphics
CALLING SEQUENCE: CIndex
INPUTS: None.
Optional Inputs: None
OUTPUTS: None
OPTIONAL OUTPUTS: None
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 TVIMAGE from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
http://www.dfanning.com/programs/tvimage.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.
(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:
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:
COLORBAR
PURPOSE:
The purpose of this routine is to add a color bar to the current
graphics window.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics, Widgets.
CALLING SEQUENCE:
COLORBAR
INPUTS:
None.
KEYWORD PARAMETERS:
ANNOTATECOLOR: The name of the "annotation color" to use. The names are those for
FSC_COLOR, and using the keyword implies that FSC_COLOR 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 = FSC_COLOR(ANNOTATECOLOR, COLOR). This keyword is provide
to maintain backward compatibility, but also to solve the problem of
and 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
TVImage, image
Colorbar, Color=FSC_Color('firebrick')
The proper syntax for device-independent color is like this:
LoadCT, 33
TVImage, image
Colorbar, AnnotateColor='firebrick', Color=255
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARSIZE: The character size of the color bar annotations. Default is 1.0.
COLOR: The color index of the bar outline and characters. Default
is !P.Color..
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(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.
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.
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 FSC_COLOR program from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.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
COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]
MODIFICATION HISTORY:
Written by: David W. Fanning, 10 JUNE 96.
10/27/96: Added the ability to send output to PostScript. DWF
11/4/96: Substantially rewritten to go to screen or PostScript
file without having to know much about the PostScript device
or even what the current graphics device is. DWF
1/27/97: Added the RIGHT and TOP keywords. Also modified the
way the TITLE keyword works. DWF
7/15/97: Fixed a problem some machines have with plots that have
no valid data range in them. DWF
12/5/98: Fixed a problem in how the colorbar image is created that
seemed to tickle a bug in some versions of IDL. DWF.
1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
3/30/99: Modified a few of the defaults. DWF.
3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
3/30/99: Added the RANGE keyword. DWF.
3/30/99: Added FONT keyword. DWF
5/6/99: Many modifications to defaults. DWF.
5/6/99: Removed PSCOLOR keyword. DWF.
5/6/99: Improved error handling on position coordinates. DWF.
5/6/99. Added MINOR keyword. DWF.
5/6/99: Set Device, Decomposed=0 if necessary. DWF.
2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
10/10/99. Modified the program so that current plot and map coordinates are
saved and restored after the colorbar is drawn. DWF.
3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
4/28/00. Made !P.Font default value for FONT keyword. DWF.
9/26/00. Made the code more general for scalable pixel devices. DWF.
1/16/01. Added INVERTCOLORS keyword. DWF.
5/11/04. Added TICKNAME keyword. DWF.
9/29/05. Added REVERSE keywords, which does the *exact* same thing as
INVERTCOLORS, but I can never remember the latter keyword name. DWF.
1/2/07. Added ANNOTATECOLOR keyword. DWF.
4/14/07. Changed the default FORMAT to I0. DWF.
5/1/07. Unexpected consequence of default format change is colorbar annotations
no longer match contour plot levels. Changed to explicit formating of
colorbar axis labels before PLOT command. DWF.
5/25/07. Previous change has unanticipated effect on color bars using
logarithmic scaling, which is not really supported, but I have an
article on my web page describing how to do it: http://www.dfanning.com/graphics_tips/logcb.html.
Thus, I've fixed the program to accommodate log scaling, while still not OFFICIALLY
supporting it. DWF.
(See colorbar.pro)
NAME:
COLORBAR__DEFINE
PURPOSE:
The purpose of this routine is to implement a COLORBAR object
class. The ColorBar is rendered in the direct graphics system.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics.
CALLING SEQUENCE:
colorbar = Obj_New("COLORBAR")
INPUTS:
All inputs to the program are via keyword parameters.
KEYWORD PARAMETERS:
Background: Background color. This is the color with which the colorbar is
erased. The default color is !P.Background.
Bottom: Bottom color index of colors allocated to colorbar.
Charsize: Character size of annotation. Default is 1.0.
Color: Color of annotation and outline. Default is !P.Color.
Font: Font to use for annotation. Default is -1, Hershey fonts.
Format: Format of annotation. Default is "(F8.2)".
Major: The number of major tick intervals. Default is 5.
Minor: The number of minor tick intervals. Default is 2.
MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command
that resizes the colorbar into the window.
NColors: The number of colors allocated to colorbar. Default is (256 <
!D.N_Colors).
Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is
0 (Bilinear).
Position: The position of colorbar in normalized coordinates. Default for a
horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a
vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are
designed for a 400 by 400 window.
Range: The data range on colorbar. Default is [0, 255].
TickLen: The length of tick marks. Default is -0.1
TickV: Locations for the tick marks in data units. This is the same as
the [XY]TickV keyword. Default is to do what IDL would do
normally.
Vertical: Set this keyword if you want a vertical colorbar. Default is
horizontal.
XEraseBox: A five-element vector of X points (normalized) for erasing the
colorbar plot. Normally this keyword will not have to be used.
The program uses the plot REGION for erasing. But larger
character sizes can result in annotation going outside the
region enclosed by the plot. If that is the case, then use this
keyword along with YEraseBox to specify a larger-than-normal
erasure area. The points are sent to the POLYFILL command for
erasing.
POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background
YEraseBox: A five-element vector of Y points (normalized) for erasing the
colorbar plot.
OBJECT METHODS:
Clamp: This procedure method allows the color bar range to be "clamped"
to a particular data range.
Draw: This procedure method draws the colorbar in the display window. The
ERASE keyword to this method will erase the current colorbar (by
calling the ERASE method) before drawing the colorbar in the display
window.
colorbar->Draw
Erase: This procedure method erases the colorbar object in the window. It
accomplishes this by performing a POLYFILL in the background color.
This method is primarily useful for interactive graphics display
devices.
colorbar->Erase
GetProperty: This procedure method allows one to obtain the current state
of the object via the keyword parameters listed above.
colorbar->GetProperty, Range=currentRange, Title=currentTitle
Print, currentRange, currentTitle
SetProperty: This procedure method allows one to set the properties of the
colorbar object via the keywords described above. In addition,
a DRAW and ERASE keyword are provided so that the colorbar can
be immediately drawn when the new property is set.
colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw
COMMON BLOCKS:
None.
SIDE EFFECTS:
The display window is not erased first.
RESTRICTIONS:
None.
EXAMPLE:
To create a colorbar, use it, then destroy it, type:
colorbar = Obj_New("COLORBAR", Title='Colorbar Values', Range=[0,1000],$
Format='(I4)')
Window
LoadCT, 5
colorbar->Draw
colorbar->SetProperty, Range=[0,500], /Erase, /Draw
Obj_Destroy, colorbar
MODIFICATION HISTORY:
Written by: David Fanning, Fanning Software Consulting,
26 November 1998.
Added Horizontal keyword to SetProperty method and fixed problem in
going from Vertical to Horizontal color bars. 29 Nov 1998. DWF.
Added LoadCT method and current color table index to object.
6 December 1998.
Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF.
Fixed a bug with how NCOLORS and BOTTOM keywords interacted.
29 Aug 1999. DWF.
10 Oct 99. Modified the program so that current plot and map coordinates
are saved and restored after the colorbar is drawn. DWF.
26 May 2000 Added {XY}TICKV capability to the draw method. This
required adding TickV to the object data structure, and to the
INIT, GetProperty and SetProperty methods.
Changed default tick length to -0.1. DWF (and Jack Saba)
18 Nov 2001. Added Clamp method. DWF.
(See colorbar__define.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 FSC_COLOR.
FGCOLOR - The name of the foreground color. For example, 'Navy', 'Black', etc.
The name must be compatible with names appropriate for FSC_COLOR.
DEPENDENCIES:
Reqires FSC_COLOR from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.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.
(See colorbuttonbitmap.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:
CW_DRAWCOLOR
PURPOSE:
This compound widget is used to place a label or color name next
to a color patch. Clicking on the color patch allows the user
to select another color
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics
CALLING SEQUENCE:
colorpatchID = CW_DrawColor(parent)
REQUIRED INPUTS:
parent - The identifier of a parent base widget.
OUTPUTS:
colorpatchID - The widget identifier of the top-level base of this compound widget
INPUT KEYWORDS:
COLOR - The name of the color to be displayed. Color names come from PickColorName.
COLUMN - Set this keyword to stack widgets in a column. Default is in a row.
EVENT_FUNC - The name of an event handler function for this compound widget.
EVENT_PRO -The name of an event handler procedure for this compound widget.
INDEX - An index number where the color should be loaded. !D.Table_Size-2, by default.
LABEL_LEFT - Set this keyword to have the label text aligned on the left of the label. Default is to center.
LABEL_RIGHT - Set this keyword to have the label text aligned on the right of the label. Default is to center.
LABELSIZE - This is the X size of the label widget (containing the label) in device coordinates. Default is natural size.
LABELTEXT - This is the text on the label. Example, "Background Color", etc.
TITLE - This is the title on the PickColorName program that allows the user to select another color.
UVALUE - A user value for the widget.
XSIZE - The xsize (in pixel units) of the color patch. By default, 20.
YSIZE - The xsize (in pixel units) of the color patch. By default, 20.
OUTPUT KEYWORDS:
OBJECT - The object reference. Use this to call methods, etc.
DEPENDENCIES:
Reqires FSC_COLOR and PICKCOLORNAME from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.pro
http://www.dfanning.com/programs/pickcolorname.pro
MODIFICATION HISTORY:
Written by David W. Fanning, March 2001.
Fixed a problem with self object cleanup. 7 March 2006. DWF.
(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:
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 FSC_COLOR. 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
FSC_Color
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=FSC_Color('ivory')
Map_Grid, LatDel = 2.0, LonDel = 2.0, /Box_Axes, Color=FSC_Color('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:
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 FSC_COLOR. 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
FSC_Color
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=FSC_Color('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=FSC_Color('charcoal')
MODIFICATION HISTORY:
Written by David W. Fanning, 2 April 2005.
(See drawstates.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=FSC_Color('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.
(See find_boundary.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.
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.
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, Fit_Ellipse(indices, XSize=400, YSize=300), /Device, Color=FSC_Color('red')
MODIFICATION HISTORY:
Written by David W. Fanning, April 2002. Based on algorithms provided by Craig Markwardt
and Wayne Landsman in his TVEllipse program.
(See fit_ellipse.pro)
NAME:
FSC_COLOR
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 104 color
names and values are supplied with the program. These colors were
obtained from the file rgb.txt, found on most X-Window distributions.
Representative colors were chosen from across the color spectrum. To
see a list of colors available, type:
Print, FSC_Color(/Names), Format='(6A18)'.
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 = FSC_Color(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 = FSC_Color("Green", !D.Table_Size-2)
backColor = FSC_Color("Charcoal", !D.Table_Size-3)
dataColor = FSC_Color("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 WHITE 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:
Print, FSC_Color(/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.
RETURN VALUE:
The value that is returned by FSC_Color 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, FSC_Color('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=FSC_Color('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=FSC_Color('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 either a color name or the color
table index number. The program will figure out what you want.
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.
RESTRICTIONS:
Required programs from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/pickcolorname.pro
EXAMPLE:
To get drawing colors in a device-decomposed independent way:
axisColor = FSC_Color("Green", !D.Table_Size-2)
backColor = FSC_Color("Charcoal", !D.Table_Size-3)
dataColor = FSC_Color("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=FSC_Color('Charcoal', /Triple))
To change the viewport color later:
theView->SetProperty, Color=FSC_Color('Antique White', /Triple)
To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this:
IDL> TVLCT, FSC_Color(["red", "green", and "yellow"], /Triple), 100
MODIFICATION HISTORY:
Written by: David W. Fanning, 19 October 2000. Based on previous
GetColor program.
Fixed a problem with loading colors with TVLCT on a PRINTER device. 13 Mar 2001. DWF.
Added the ROW keyword. 30 March 2001. DWF.
Added the PICKCOLORNAME code to the file, since I keep forgetting to
give it to people. 15 August 2001. DWF.
Added ability to specify color names and indices as vectors. 5 Nov 2002. DWF.
Fixed a problem with the TRIPLE keyword when specifying a vector of color names. 14 Feb 2003. DWF.
Fixed a small problem with the starting index when specifying ALLCOLORS. 24 March 2003. DWF.
Added system color names. 23 Jan 2004. DWF
Added work-around for WHERE function "feature" when theColor is a one-element array. 22 July 2004. DWF.
Added support for 8-bit graphics devices when color index is not specified. 25 August 2004. DWF.
Fixed a small problem with creating color structure when ALLCOLORS keyword is set. 26 August 2004. DWF.
Extended the color index fix for 8-bit graphics devices on 25 August 2004 to
24-bit devices running with color decomposition OFF. I've concluded most of
the people using IDL don't have any idea how color works, so I am trying to
make it VERY simple, and yet still maintain the power of this program. So now,
in general, for most simple plots, you don't have to use the colorindex parameter
and you still have a very good chance of getting what you expect in a device-independent
manner. Of course, it would be *nice* if you could use that 24-bit display you paid
all that money for, but I understand your reluctance. :-) 11 October 2004. DWF.
Have renamed the first positional parameter so that this variable doesn't change
while the program is running. 7 December 2004. DWF.
Fixed an error I introduced on 7 December 2004. Sigh... 7 January 2005. DWF.
Added eight new colors. Total now of 104 colors. 11 August 2005. DWF.
Modified GUI to display system colors and removed PickColorName code. 13 Dec 2005. DWF.
Fixed a problem with colorIndex when SELECTCOLOR keyword was used. 13 Dec 2005. DWF.
Fixed a problem with color name synonyms. 19 May 2006. DWF.
The previous fix broke the ability to specify several colors at once. Fixed. 24 July 2006. DWF.
Updated program to work with 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF
(See fsc_color.pro)
NAME:
FSC_SURFACE
PURPOSE:
The purpose of this program is to demonstrate how to
create a rotating surface using 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:
FSC_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:
BLOCK: Set this keyword to 1 to create a blocking widget program. This is
useful if you want to call this program from within a stopped program, for
example. Remember only the first blocking program actually blocks.
COLORTABLE: Set this keyword to a number between 0 and 40 to select one
of the pre-selected IDL color tables for elevation shading.
ELEVATION_SHADING: Set this keyword to put elevation shading into effect.
EXACT: Set this keyword to a one-, two-,or three-element array to set exact axis
scaling for the X, Y, and Z axes, respectively. If Exact is a one-element array,
all three axes are set to the same value. For example, to set the X axis to
exact scaling and the Y and Z axes to normal scaling, type:
IDL> FSC_Surface, Exact=[1,0,0]
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the IDLgrSURFACE initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
HIDDEN_LINES: Set this keyword to draw the surface with hidden lines removed.
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 two-, four- or six-element array of normalized (0 to 1) coordinates
used to position the X, Y, and Z axis in the coordinate space. Uses the form
[x0, x1, y0, y1, z0, z1]. In the absence of POSITION information, the Z position
is always [0,1] and the X and Y positions are calculated in a manner that
preserves the aspect ratio of the surface data.
SHADED: Set this keyword to set up a shaded surface plot rather than a wire
mesh surface, which is the default.
TITLE: A string used as the title of the plot.
XRANGE: A two-element array specifying the range of the X axis.
XTITLE: A string used as the X title of the plot.
YRANGE: A two-element array specifying the range of the Y axis.
ZRANGE: A two-element array specifying the range of the Z axis.
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.
SIDE EFFECTS:
None.
DEPENDENCIES:
This program requires the following additional files from the Coyote Library:
error_message.pro
fsc_droplist.pro
fsc_color.pro
normalize.pro
loaddata.pro
pickcolor.pro
xcolors.pro
EXAMPLE:
To use this program with your data, type:
IDL> FSC_Surface, data
Use your LEFT mouse button to rotate the surface plot in the window.
Use your RIGHT mouse button to zoom into a closer view of the plot.
Use your MIDDLE mouse button to zoom away from the plot.
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97.
Made axis scaling more robust. 17 Sept 97. DWF.
Minor modifications to incorporate better understanding
of how objects work. 4 Oct 97. DWF.
Fixed error cleaning up all of my created objects. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Fixed mis-spelling of HELVETICA14. 29 June 98. DWF.
Added the EXACT keyword to the X and Y axes to force axis ranging. 27 July 98. DWF
Added the ability to select rendering "drag" quality for faster operation. 22 Aug 98. DWF.
Added ability to get non-exact axis scaling. 12 May 99. DWF.
Improved documentation and readability of code. 12 May 99. DWF.
Added VECTOR and LANDSCAPE keywords and improved printing capability. 16 Feb 2000. DWF.
Added different lights and a Light Controller option. 28 April 2000. DWF.
Added elevation shading. 8 May 2000. DWF.
Removed VECTOR keyword. Replaced with VECTOR/BITMAP/COLOR Print buttons. 8 May 2000. DWF.
Added HIDDEN_LINE keyword. 8 May 2000. DWF.
Added EXACT keyword extensions and changed name from XSURFACE to FSC_SURFACE. 11 May 2000. DWF.
Made change to Light Control code to accomodate FSC_DROPLIST changes. 6 Jan 2001. DWF.
Removed unused color table vector code from a LONG time ago. 17 Jan 2001. DWF.
Added TIFF file output and removed GIF output for IDL 5.4. 11 Feb 2001. DWF.
Added short wait before taking image snapshot for JPEG and TIFF files to avoid
extraneous text in output files. 22 October 2001. DWF.
Added the POSITION keyword. 16 April 2002. DWF.
Added the ability to zoom into and out of plot with RIGHT and MIDDLE mouse buttons. 16 April 2002. DWF.
Fixed a problem with leaving lights on when switching to elevation shading. 16 April 2002. DWF.
Fixed a problem in not restoring viewport parameters after printing. 20 April 2002. DWF.
Added BMP, EPS, and PGN file output. 20 April 2002.DWF.
Added a BLOCK keyword. 11 May 2002. DWF.
Added a check for NAN in elevation colors part of the code. 14 August 2002. DWF.
Removed extra Save As TIFF File button. 24 August 2002. DWF.
Removed NORMALIZE from the source code. 29 November 2005. DWF.
Added [XYZ]Range keywords. 15 February 2006. DWF.
Fixed a problem with colors. Elevation shading now corresponds to Z Axis range, not data range.
15 February 2006. DWF.
Added ENABLE_FORMATTING keywords to axis and plot title creation functions. 15 February 2006. DWF.
Fixed a problem with EXPOSE events not blocking when blocking widgets are running. This is apparently
due to undocumented changes in XMANAGER behaviour. 5 July 2006. DWF.
(See fsc_surface.pro)
NAME:
FSC_WINDOW
PURPOSE:
This routine implements a "smart" resizeable graphics window.
It is used as a wrapper for built-in IDL graphics procedures
such as SURFACE, CONTOUR, PLOT, SHADE_SURF, etc. In additon,
it can be used to display any user-written graphics procedure
so long as that procedure follows three simple rules: (1) It
does not open it's own graphics windows, (2) It is defined with
no more than three positional arguments (an unlimited number
of keyword arguments are allowed), and (3) It uses no device-
specific commands, such as "WSet", "Device, Decomposed=1", etc.
Keyword arguments permit the window to have its own portion
of a color table and to be able to change the colors loaded in
that portion of the color table. Colors are updated
automatically on both 8-bit and 24-bit color displays. In
addition, the window colors will "protect" themselves. I mean
by this that the window will re-load its own colors into the
color table when the window gains keyboard focus. This
prevents other applications from changing the colors used to
display data in this window. (This is an issue mainly in
IDL 5 applications where widget applications can run
concurrently with commands from the IDL command line.)
Keyword arguments also permit the window to create output
files of its contents. These files can be color and
gray-scale PostScript, and color BMP, GIF, JPEG, PICT, PNG,
TIFF, or JPEG files. Output can also be sent directly to
the default printer.
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, Graphics.
CALLING SEQUENCE:
FSC_WINDOW, command, P1, P2, P3
REQUIRED INPUTS:
COMMAND: 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', etc.
OPTIONAL INPUTS:
P1: The first positional parameter appropriate for the graphics
command.
P2: The second positional parameter appropriate for the graphics
command.
P3: The third positional parameter appropriate for the graphics
command.
INPUT KEYWORD PARAMETERS:
WBACKGROUND: The background color index for the window. Setting this color
along with the WERASEIT keyword causes the window to be erased with
this color. Set to !P.Background by default.
WERASEIT: Setting this keyword "erases" the contents of the current
graphics window before re-executing the graphics command. For example,
this keyword might need to be set if the graphics "command" is TVSCL.
The default is to NOT erase the display before reissuing the graphics
command.
_EXTRA: This keyword forms an anonymous structure of any unrecognized
keywords passed to the program. The keywords must be appropriate
for the graphics command being executed.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
METHOD: Set this keyword to indicate that the method of an object
should be called, instead of a graphics procedure command. If this
keyword is set, the COMMAND parameter should be the name of an object
procedure method, and the P1 parameter MUST be an object reference.
TVORDER: This keyword corresponds the the !Order system variable. It
is not used in this program, but is carried along for the call to
TVREAD when windows are saved as ouput files. It will affect the
transfer of window contents into the output data file. It should be
used if the output file contents appear upside down.
WTITLE: This is the window title. It is the string "COMMAND Window (1)"
by default, where COMMAND is the input parameter. And the number
(1 in this case) is the window index number of the draw widget.
WXPOS: This is the initial X offset of the window. Default is to
position the window in the approximate middle of the display.
WYPOS: This is the initial Y offset of the window. Default is to
position the window in the approximate middle of the display.
WPOSTSCRIPT: Set this keyword to 1 to include a PostScript File button under
the Save As button. This keyword is set automatically on 24-bit display
devices. To turn the button OFF on 24-bit devices, set the keyword value to 0.
There is no guaranteed way to create perfect PostScript output when the program
is run on 8-bit displays. This will depend entirely on how the "graphics command"
is written. Hence the button is turned off automatically on 8-bit devices.
WPRINT: Set this keyword to 1 to include a Print button under the File button.
This keyword is set automatically on 24-bit display devices. To turn the
button OFF on 24-bit devices, set the keyword value to 0. There is no
guaranteed way to print output correctly when the program is run on
8-bit displays. This will depend entirely on how the "graphics command"
is written. Hence the button is turned off automatically on 8-bit devices.
WXSIZE: This is the initial X size of the window. Default is 400
pixels.
WYSIZE: This is the initial Y size of the window. Default is 400
pixels.
WCOLORS: Using this keyword adds a "Colors..." button to the
"File" menu. Set this keyword to the number of colors available
in the window and the starting index of the first color. For example,
to allow the window access to 100 colors, starting at color index 50
(i.e., color indices 50 to 149), use WColors=[100, 50]. If you use the
keyword syntax "/WColors", all the colors available will be used, not just
one color. If the keyword is set to a scalar value greater than 1, the
starting color index is set to 0. The default value for this keyword
is [(!D.Table_Size, 0].
OUTPUT KEYWORDS:
TLB: The top-level base widget identifier. This can be used for a number
of purposes. For example, it could be used to destroy the window programmatically:
FSC_Window, 'Surface', dist(40), TLB=tlb
Widget_Control, tlb, /DESTROY
COMMON BLOCKS:
None.
RESTRICTIONS:
This program requires additional programs from the Fanning
Software Consulting library:
CENTERTLB.PRO
ERROR_MESSAGE.PRO
FSC_PSCONFIG__DEFINE.PRO
FSC_DROPLIST.PRO
FSC_FIELD.PRO
FSC_FILESELECT.PRO
FSC_INPUTFIELD.PRO
FSC_PLOTWINDOW.PRO
PSCONFIG.PRO
PSWINDOW.PRO
TVREAD.PRO
XCOLORS.PRO
If the "command" program requires keywords that are also keywords
to FSC_WINDOW, then you must use the keyword twice on the command line.
EXAMPLE:
If the program is called with no parameters whatsoever, it will load
example data.
IDL> FSC_WINDOW
To use the program with an IDL PLOT command, for example:
IDL> FSC_WINDOW, 'PLOT', Findgen(11), Charsize=1.5, Title='Example Plot'
To build your own graphics display command, you can do something like this.
Here is a command program that takes an image, a column number, and a row number,
and plots a column and row profile next to one another:
PRO COL_ROW_PLOT, image, column, row, _Extra=extra
; Check parameters.
IF N_Elements(image) EQ 0 THEN image = DIST(200)
IF N_ELements(column) EQ 0 THEN column = 100
IF N_Elements(row) EQ 0 THEN row = 100
; Set up plots.;
!P.Multi = [0, 2, 1]
Plot, image[column, *], Title='Row Profile', YRange=[Min(image), Max(image)], $
XStyle=1, XTitle='At Column No: ' + StrTrim(column,2), _Extra=extra
Plot, image[*, row], Title='Column Profile', YRange=[Min(image), Max(image)], $
XStyle=1, XTitle='At Row No: ' + StrTrim(row,2), _Extra=extra
!P.Multi = 0
END
This command program is used with FSC_WINDOW, like this:
IDL> Demo_GetData, image, Filename='ctscan.dat'
IDL> FSC_WINDOW, 'COL_ROW_PLOT', image, 30, 185, YTitle='Image Value'
TIPS FOR WRITING GRAPHICS DISPLAY PROGRAMS TO USE WITH FSC_WINDOW:
It is *exceedingly* difficult to write a graphics display routine that uses
color and get it to display properly on your display, in a PostScript file, and
when printed. This is because: (1) your display is a 24-bit device and the PostScript
and PRINTER devices are both 8-bit devices, and (2) the printer is different from your
display and PostScript device in not being able to load colors on the fly. (A single
color table can only be loaded when you SET_PLOT to a PRINTER, and then the colors
cannot be changed.)
Since FSC_Window knows *nothing* about your graphics display routine, the chances of
it doing all three of these things correctly are just about zero, unless you follow
the recommendations below. (In which case, your changes improve to about 50/50.)
RECOMMENDATIONS
1. Use FSC_COLOR to specify your colors. If you don't do this, please don't call
me for help. This is the FIRST thing I will recommend you try. :-) FSC_COLOR *exists* to
solve these particular problems! And _get the latest version_! Things may have changed
since you last downloaded it.
2. Consider using a white background color for your graphics display. This is what
you are going to get with PostScript whether you like it or not. It will make things
a LOT simpler for you to do it this way. Otherwise, it is up to you to write your
graphics display program in such a way that if you are in the PostScript device, you
will fill the page with the background color *before* you draw your graphics. Something
like this:
IF !D.Name EQ 'PS' THEN Polyfill, [0,0,1,1, 0], [0,1,1,0,0], /Normal, $
Color=FSC_Color(backgroundColor)
Plot, data, Color=FSC_Color(plotColor), Background=FSC_Color(backgroundColor)
3. If you plan to print the contents of your FSC_WINDOW, you *must* load your
colors *immediately* before you call the FSC_WINDOW program. This will ensure
that the program will load *these* colors before it calls the PRINTER device.
Unless you have specific requirements, I would load the colors like this:
TVLCT, FSC_Color(/AllColors, /Triple, NColors=ncolors), !D.table_Size - ncolors - 2
FSC_Window, 'yourprogram', ...
4. In your graphics display program, use FSC_Color to specify *all* colors and DO *NOT*
use a color index parameter in the call. (The colorIndex parameter is the second
positional parameter to FSC_COLOR.) You code might look something like this:
Plot, mydata, Color=FSC_Color('Dodger Blue'), Background=FSC_Color('White')
Good luck! If you have any problems (and you have followed recommendation 1 already),
then please contact me for help.
MODIFICATION HISTORY:
Written by: David Fanning, Sept 2000. Based on previous XWINDOW program.
Whoops! Left out the line to resize draw widgets on UNIX machines. Fixed. 12 Oct 2000, DWF.
Removed support for GIF files for IDL 5.4. 18 Jan 2001. DWF.
Beefed up documentation. 27 March 2001. DWF.
Added TVORDER keyword. 25 March 2002. DWF.
Added METHOD keyword so that an object method could used as the graphics
display routine name. 6 July 2003 KaRo
Added tips for writing graphics display programs. 26 Aug 2004. DWF.
(See fsc_window.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.
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 = LoadData(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.
(See gmascl.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 NORMALIZE from Coyote Library:
http://www.dfanning.com/programs/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.
(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 TVIMAGE
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:
HIST_ND
PURPOSE:
Perform an N-dimensional histogram, also known as the joint
density function of N variables, ala HIST_2D.
CALLING SEQUENCE:
hist=HIST_ND(V,BINSIZE,MIN=,MAX=,NBINS=,REVERSE_INDICES=)
INPUTS:
V: A NxP array representing P data points in N dimensions.
BINSIZE: The size of the bin to use. Either an N point vector
specifying a separate size for each dimension, or a scalar,
which will be used for all dimensions. If BINSIZE is not
passed, NBINS must be.
OPTIONAL INPUTS:
MIN: The minimum value for the histogram. Either a P point
vector specifying a separate minimum for each dimension, or
a scalar, which will be used for all dimensions. If
omitted, the natural minimum within the dataset will be
used.
MAX: The maximum value for the histogram. Either a P point
vector specifying a separate maximmum for each dimension, or
a scalar, which will be used for all dimensions. If omitted,
the natural maximum within the dataset will be used.
NBINS: Rather than specifying the binsize, you can pass NBINS,
the number of bins in each dimension, which can be a P point
vector, or a scalar. If BINSIZE it also passed, NBINS will
be ignored, otherwise BINSIZE will then be calculated as
binsize=(max-min)/nbins. Note that *unlike* RSI's version
of histogram as of IDL 5.4, this keyword actually works as
advertised, giving you NBINS bins over the range min to max.
KEYWORD PARAMETERS:
MIN,MAX,NBINS: See above
REVERSE_INDICES: Set to a named variable to receive the
reverse indices, for mapping which points occurred in a
given bin. Note that this is a 1-dimensional reverse index
vector (see HISTOGRAM). E.g., to find the indices of points
which fell in a histogram bin [i,j,k], look up:
ind=[i+nx*(j+ny*k)]
ri[ri[ind]:ri[ind+1]-1]
See also ARRAY_INDICES for converting in the other
direction.
OUTPUTS:
hist: The N-Dimensional histogram, of size N1xN2xN3x...xND
where the Ni's are the number of bins implied by the data,
and/or optional inputs min, max and binsize.
OPTIONAL OUTPUTS:
The reverse indices.
EXAMPLE:
v=randomu(sd,3,100)
h=hist_nd(v,.25,MIN=0,MAX=1,REVERSE_INDICES=ri)
SEE ALSO:
HISTOGRAM, HIST_2D
MODIFICATION HISTORY:
Mon Mar 5 09:45:53 2007, J.D. Smith
Correctly trim out of range elements from the
histogram, when MIN/MAX are specified. Requires IDL
v6.1 or later.
Tue Aug 19 09:13:43 2003, J.D. Smith
Slight update to BINSIZE logic to provide consistency
with HIST_2D.
Fri Oct 11 10:10:01 2002, J.D. Smith
Updated to use new DIMENSION keyword to MAX/MIN.
Fri Apr 20 12:57:34 2001, JD Smith
Slight update to NBINS logic. More aggressive keyword
checking.
Wed Mar 28 19:41:10 2001, JD Smith
Written, based on HIST_2D, and suggestions of CM.
(See hist_nd.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:
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:
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
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.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::DELETE, index, ALL=all, DESTROY=destroy
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 it deleted.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
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
The GET_ITEM_PTR method returns a pointer to the specified data
item from the list.
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: Set this keyword to return the thing the pointer
points to (i.e., the item itself.)
ALL: Set this keyword to return an n-element array containing all the list
elements. This requires that all list elements be of the same type, and
if they are arrays, they have 7 dimensions or fewer.
If index is passed, it is ignored.
Added by HBT 14-Jul-2004.
Return Value: A pointer to the specified data item stored
in the list. IF DEREFERENCE is set, the data item itself
is returned. If ALL is set, then an array containing
all the elements is returned.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_NODE, index
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.
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
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.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::REPLACE_ITEM, Index, NewItem
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.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
EXAMPLE:
mylist = Obj_New("LINKEDLIST", 5)
mylist->Add, 10
mylist->Add, 7, 1, /Before
mylist->Add, 12
print, mylist->Get_Item(/All, /Deref)
mylist->Replace_Item, 1, 'Bob'
mylist->Help
mylist->Delete
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.
(See linkedlist__define.pro)
NAME:
LOADDATA
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 17 data sets are
available in all categories of data. The user selects one of the
possible data sets with the mouse.
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 = LoadData()
If calling from within a widget program:
data = LoadData(Cancel=cancelled, Group_Leader=event.top)
If you know which data set you want, you can load it directly:
data = LoadData(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 17).
KEYWORD PARAMETERS:
CANCEL : An output keyword that is 1 of the use clicked the CANCEL
button and 0 otherwise.
data = Loaddata(Cancel=cancelled)
IF cancelled THEN RETURN
GROUP_LEADER: The group leader of the widget. This keyword
is required if you wish LOADDATA 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 = LoadData(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 loaddata.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:
LoadCT, 0 ; Gray-scale colors.
image = LoadData(22) ; Load image.
TV, image ; No contrast.
TV, LogScl(image) ; Improved contrast.
TV, LogScl(image, Exponent=10, Mean=0.65) ; Even more contrast.
TV, 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.
(See logscl.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
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 two programs from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/fsc_color.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=FSC_Color('Almond')
Map_GSHHS_Shoreline, datafile, /Fill, Level=3, /Outline
XYOutS, 0.5, 0.85, 'Australia', Font=0, Color=FSC_Color('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=FSC_Color('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=FSC_Color('CHARCOAL'), Map_Structure=map
Map_Continents, /USA, Map_Structure=map
XYOutS, 0.5, 0.85, 'Great Lakes Region', Font=0, Color=FSC_Color('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/.
(See map_gshhs_shoreline.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/fsc_color.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/tvread.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.
(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 FSC_Color 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/fsc_color.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/tvread.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.
(See mpi_plotconfig__define.pro)
NAME:
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 = 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 = 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.
(See normalize.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:
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 FSC_COLOR.
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 FSC_COLOR 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:
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 = FSC_Color(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 FSC_COLOR 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.
(See pickcolor.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.
(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:
READ_TOMS_AEROSOL
PURPOSE:
This is a demonstration program, used in the TOMS Tutorial
(http://www.dfanning.com/graphics_tips/toms_tutorial.html),
to show how to write a program that looks the same on the
display and in a PostScript file. TOMS satellite data is
overlaid on a map projection.
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:
Read_TOMS_Aerosol, filename
ARGUMENTS:
filename: The name of the TOMS data file. If not provided, the user
will be prompted for the name of the file.
KEYWORDS:
DATA: Set this keyword to a named variable that on return will
contain a 288 by 180 array of floating point values. Missing
data is indicated by !Values.F_NAN.
HEADER: Set this keyword to a named variable that on return will
contain the first three lines of the TOMS data set.
LIMIT: A four-element input vector that limits the extent of the map
projection. Identical to the LIMIT keyword for MAP_SET.
The form of the keyword is:
LIMIT = [latmin, lonmin, latmax, lonmax]
PS: Set this keyword to 1 if you wish to create PostScript output
instead of sending graphics output to the display.
COMMON BLOCKS:
None
RESTRICTIONS:
TOMS data can be freely obtained from NASA at http://toms.gsfc.nasa.gov/.
Requires numerious files from the Coyote Library:
http://www.dfanning.com/programs/coyoteprograms.zip
MODIFICATION HISTORY:
Written by David W. Fanning, 18 January 2006
(See read_toms_aerosol.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:
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)
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.
KEYWORDS:
None.
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
MODIFICATION HISTORY:
Written by David W. Fanning, 21 October 2006.
(See shapeinfo.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 NORMALIZE from the Coyote Library.
http://www.dfanning.com/programs/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 FSC_COLOR.
RADIUS: The radius of the station plot circle in normalized coordinates.
RESTRICTIONS:
Requires FSC_COLOR from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.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=FSC_Color('Ivory', !P.Background)
Map_Set, /Cylindrical,Position=[0.1, 0.1, 0.9, 0.9], Color=FSC_Color('Steel Blue'), /NoErase
Map_Grid, Color=FSC_Color('Charcoal', !D.Table_Size-2)
Map_Continents, Color=FSC_Color('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.
(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:
None.
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 are forgot to change limits to allow for them. 4 May 2007. DWF.
(See symcat.pro)
NAME:
Terminator_Map
PURPOSE:
This is a program for viewing a map of the Earth with a day/night terminator.
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:
Terminator_Map, center_lon, center_lat, Map_Projection='Aitoff'
INPUT ARGUMENTS:
center_lon: The longitude, in degrees, of the center of the map, (-180 to 180). Defaults to 0.0.
center_lat: The latitude, in degrees, of the center of the map, (-90 to 90). Defaults to 0.0.
Latitudes other than zero can cause program problems. See the NOTES section for details.
INPUT KEYWORDS:
FLIPDAY: The program suffers from an inability to always correctly distinguish the
"day" side of the day/night terminator (see NOTES section). If the program
gets it wrong, you can use this keyword to "flip" the day/night area. For
example, here is a call that gets it wrong:
Terminator_Map, 0, 90.0, MAP_PROJECTION=4, time="Thu Apr 13 08:49:34 2006"
Unfortunately, you can only know if it is "wrong" by visual inspection. The sun
is always placed correctly. I realize this limits the usefulness of the program,
generally, but it is a limitation I am not motivated enough to fix. That is to
say, the program meets my limited needs perfectly. :-)
KEEP_ASPECT: If set, the aspect ratio of the map is more or less preserved.
MAP_PROJECTION: Either the number or the name of one of the following map projection types. Defaults to "CYLINDRICAL".
0 CYLINDRICAL
1 GOODESHOMOLOSINE
2 HAMMER
3 LAMBERT
4 MERCATOR
5 MILLER_CYLINDRICAL
6 MOLLWEIDE
7 ROBINSON
TIME: A date/time string of nearly any format. The month, however, should be represented
as a three-letter string. The time is written as hh:mm:ss. Examples of date/time strings
are these:
'Wed Apr 12 22:39:52 2006'
'12 APR 2006 04:16:00'
'Apr 12, 2006 04:16:00'
'Nov 12, 2006'
If undefined, the current day and time (from SYSTIME) is used.
OUTPUT KEYWORDS:
IMAGE: If passed a named variable, will return a 24-bit image of the result in the display window.
DEPENDENCIES:
Requires both the Coyote Library and the JHUAPL Library to be on the !PATH, since many programs
from both are used.
http://www.dfanning.com/programs/coyotefiles.zip
http://fermi.jhuapl.edu/s1r/idl/s1rlib/local_idl.html
EXAMPLE:
Window, XSize=800, YSize=400
Terminator_Map
NOTES:
The spherical geometry problems inherent with working the map projections are not
completely solved in this program. The main problem seems to be that if the
terminator polygon (represented in the program by the variables lon_terminus
and lat_terminus) overlaps the pole regions, then stardard methods for determining
if a point is inside or outside a polygon are not reliable. (*All* longitudes are
inside the polygon if the polygon overlaps a pole!) In the program, this manifests
itself as the sun side of the terminator appearing dark and the night side appearing
light. Hence, the FLIPDAY keyword.
To some extent, this problem can be eliminated by setting the CENTER_LAT parameter
to zero, at least with some map projections. I've thought about forcing it to be
zero and forcing you to use well-behaved map projections, but have decided to leave
the program the way it is so you can discover the limitations yourself.
MODIFICATION HISTORY:
Written by David W. Fanning, April 12, 2006.
(See terminator_map.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.
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.
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.
(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 = Loaddata(2)
IDL> image = Loaddata(7)
IDL> Texture_Surface, data, Image=image, Colortable=33
RESTRICTIONS:
Requires the ASPECT program from the Coyote Library:
http://www.dfanning.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:
TVIMAGE
PURPOSE:
This purpose of TVIMAGE is to enable the TV command in IDL
to be a completely device-independent and color-decomposition-
state independent command. On 24-bit displays color decomposition
is always turned off for 8-bit images and on for 24-bit images.
The color decomposition state is restored for those versions of
IDL that support it (> 5.2). Moreover, TVIMAGE adds features
that TV lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVIMAGE also supports the !P.MULTI system variable, unlike the
TV command. TVIMAGE was written to work especially well in
resizeable graphics windows. Note that if you wish to preserve
the aspect ratio of images in resizeable windows, you should set
the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works
equally well on the display, in the PostScript device, and in
the Printer and Z-Graphics Buffer devices. The TRUE keyword is
set automatically to the correct value for 24-bit images, so you
don't need to specify it when using TVIMAGE.
AUTHOR:
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics display.
CALLING SEQUENCE:
TVIMAGE, image
INPUTS:
image: A 2D or 3D image array. It should be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
KEYWORD PARAMETERS:
BACKGROUND: This keyword specifies the background color. Note that
the keyword ONLY has effect if the ERASE keyword is also
set or !P.MULTI is set to multiple plots and TVIMAGE is
used to place the *first* plot.
ERASE: If this keyword is set an ERASE command is issued
before the image is displayed. Note that the ERASE
command puts the image on a new page in PostScript
output.
_EXTRA: This keyword picks up any TV keywords you wish to use.
HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
specified position in the window. If you prefer, you can
force the image to maintain its aspect ratio in the window
(although not its natural size) by setting this keyword.
The image width is fitted first. If, after setting the
image width, the image height is too big for the window,
then the image height is fitted into the window. The
appropriate values of the POSITION keyword are honored
during this fitting process. Once a fit is made, the
POSITION coordiates are re-calculated to center the image
in the window. You can recover these new position coordinates
as the output from the POSITION keyword.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignored when TVImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics.
MINUS_ONE: The value of this keyword is passed along to the CONGRID
command. It prevents CONGRID from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays.
NOINTERPOLATION: Setting this keyword disables the default bilinear
interpolation done to the image when it is resized. Nearest
neighbor interpolation is done instead. This is preferred
when you do not wish to change the pixel values of the image.
This keyword must be set, for example, when you are displaying
GIF files that come with their own non-IDL color table vectors.
NORMAL: Setting this keyword means image position coordinates x and y
are interpreted as being in normalized coordinates. This keyword
is only valid if the TV keyword is set.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
TVImage, image, /Overplot
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this can
be an output parameter if the KEEP_ASPECT_RATIO keyword is
used.
TV: Setting this keyword makes the TVIMAGE command work much
like the TV command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
If a 24-bit image is displayed on an 8-bit display, the
24-bit image must be converted to an 8-bit image and the
appropriate color table vectors. This is done with the COLOR_QUAN
function. The TVIMAGE command will load the color table vectors
and set the NOINTERPOLATION keyword if this is done. Note that the
resulting color table vectors are normally incompatible with other
IDL-supplied color tables. Hence, other graphics windows open at
the time the image is display are likely to look strange.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2]
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
!P.Multi = 0
MODIFICATION HISTORY:
Written by: David Fanning, 20 NOV 1996.
Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
that this program should act more like TV and less like a "color
aware" application. I leave "color awareness" to the program
using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
Fixed a small bug that prevented this program from working in the
Z-buffer. 17 April 1997. DWF.
Fixed a subtle bug that caused me to think I was going crazy!
Lession learned: Be sure you know the *current* graphics
window! 17 April 1997. DWF.
Added support for the PRINTER device. 25 June 1997. DWF.
Extensive modifications. 27 Oct 1997. DWF
1) Removed PRINTER support, which didn't work as expected.
2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
3) Added check for window-able devices (!D.Flags AND 256).
4) Modified PostScript color handling.
Craig Markwart points out that Congrid adds an extra row and column
onto an array. When viewing small images (e.g., 20x20) this can be
a problem. Added a Minus_One keyword whose value can be passed
along to the Congrid keyword of the same name. 28 Oct 1997. DWF
Changed default POSITION to fill entire window. 30 July 1998. DWF.
Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
Added limited PRINTER portrait mode support. The correct aspect ratio
of the image is always maintained when outputting to the
PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
Added a MARGIN keyword. 18 Oct 1998. DWF.
Re-established Device, Decomposed=0 keyword for devices that
support it. 18 Oct 1998. DWF.
Added support for the !P.Multi system variable. 3 March 99. DWF
Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added automatic recognition of !P.Multi. Setting MULTI keyword is no
longer required. 18 Nov 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
Added BACKGROUND keyword. 20 April 2000. DWF.
Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.
Rearranged the PLOT part of code to occur before decomposition state
is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF.
Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF.
Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF.
Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to
display images. 8 June 2001. DWF.
Fixed small problem with multiple plots and map projections. 29 June 2003. DWF.
Converted all array subscripts to square brackets. 29 June 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Small modification at suggestion of Karsten Rodenacker to increase size of
images in !P.MULTI mode. 8 December 2004. DWF.
Minor modifications on Karsten Rodenacker's own account concerning margination
and TV behaviour. 8 December 2004. KaRo
There was a small inconsistency in how the image was resized for PostScript as
opposed to the display, which could occasionally result in a small black line
to the right of the image. This is now handled consistently. 3 January 2007. DWF.
Made a small change to CMCONGRID to permit nearest-neighbor interpolation for 3D arrays.
Previously, any 24-bit image was interpolated, no matter the setting of the NOINTERP
keyword. 22 April 2007. DWF.
Updated the program for the 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF.
(See tvimage.pro)
NAME:
TVREAD
PURPOSE:
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics
CALLING SEQUENCE:
image = TVREAD(xstart, ystart, ncols, nrows)
The returned image will be a 2D image on 8-bit systems and
a 24-bit pixel interleaved true-color image on 24-bit systems.
A -1 will be returned if a file output keyword is used (e.g., JPEG, TIFF, etc.).
OPTIONAL INPUTS:
XSTART -- The starting column index. By default, 0.
YSTART -- The starting row index. By default, 0.
NCOLS -- The number of columns to read. By default, !D.X_Size - XSTART
NROWS -- The number of rows to read. By default, !D.Y_Size - YSTART.
KEYWORD PARAMETERS:
BMP -- Set this keyword to write the screen dump as a color BMP file.
CANCEL -- An output keyword set to 1 if the user cancels out of a
filename dialog. Set to 0 otherwise.
COLORS -- If a 24-bit image has to be quantized, this will set the number
of colors in the output image. Set to 256 by default. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
CUBE -- If this keyword is set to a value between 2 and 6 the color
quantization will use a cubic method of quantization. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
DITHER -- If this keyword is set the quantized image will be dithered.
Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.
(See the COLOR_QUAN documentation for details.)
FILENAME -- The base name of the output file. (No file extensions;
they will be added automatically.) This name may be changed by the user.
image = TVREAD(Filename='myfile', /JPEG)
No file will be written unless a file output keyword is used
(e.g., JPEG, TIFF, etc.) in the call. By default the FILENAME is
set to "idl". The file extension will be set automatically to match
the type of file created.
GIF -- Set this keyword to write the screen dump as a color GIF file.
JPEG -- Set this keyword to write the screen dump as a color JPEG file.
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.
PICT -- Set this keyword to write the screen dump as a color PICT file.
PNG -- Set this keyword to write the screen dump as a color PNG file.
TIFF -- Set this keyword to write the screen dump as a color TIFF file.
TRUE -- Set this keyword to the type of interleaving you want. 1 = Pixel
interleaved, 2 = row interleaved, 3 = band interleaved.
TYPE -- Can be set to the type of file to write. Use this instead of
setting BMP, GIF, JPEG, PICT, PNG, or TIFF keywords: TYPE='JPEG'. The
primary purpose of this is to make event handlers easier to write.
QUALITY -- This keyword sets the amount of compression for JPEG images.
It should be set to a value between 0 and 100. It is set to 75 by default.
(See the WRITE_JPEG documentation for details.)
WID -- The index number of the window to read from. The current graphics window
(!D.Window) is selected by default. An error is issued if no windows are
currently open on a device that supports windows.
_EXTRA -- Any keywords that are appropriate for the WRITE_*** routines are
also accepted via keyword inheritance.
COMMON BLOCKS:
None
RESTRICTIONS: Requires IDL 5.2 and higher.
MODIFICATION HISTORY:
Written by David W. Fanning, 9 AUG 2000.
Added changes to make the program more device independent. 16 SEP 2000. DWF.
Removed GIF file support for IDL 5.4 and above. 18 JAN 2001. DWF.
Added NODIALOG keyword. 28 MAR 2001. DWF.
Added an output CANCEL keyword. 29 AUG 2001. DWF.
Added ERROR_MESSAGE code to file. 17 DEC 2001. DWF.
Added ORDER keyword. 25 March 2002. DWF.
Now create 24-bit PNG files if reading from a 24-bit display. 11 May 2002. DWF.
Now create 24-bit BMP files if reading from a 24-bit display. 23 May 2002. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Unleashed the GIF code for IDL 6.2 and above. 10 Nov 2005. DWF.
Rolled back previous change to IDL 6.1. 24 Jan 2006. DWF.
Fixed a problem in which 16-bit displays were treated as 24-bit displays,
and as a result could not produce WHITE colors. Now all 16-bit displays
are treated as 8-bit displays. It is an ugly trade-off. 24 Jan 2006. DWF.
Added TYPE keyword 27 Sep 2006. DWF.
Updated program to work with 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF.
(See tvread.pro)
NAME:
TVSCALE
PURPOSE:
This purpose of TVSCALE is to enable the TVSCL command in IDL
to be a completely device-independent and color-decomposition-
state independent command. On 24-bit displays color decomposition
is always turned off for 8-bit images and on for 24-bit images.
The color decomposition state is restored for those versions of
IDL that support it (> 5.2). Moreover, TVSCALE adds features
that TVSCL lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVSCALE also supports the !P.MULTI system variable, unlike the
TVSCL command. TVSCALE was written to work especially well in
resizeable graphics windows. Note that if you wish to preserve
the aspect ratio of images in resizeable windows, you should set
the KEEP_ASPECT_RATIO keyword, described below. TVSCALE works
equally well on the display, in the PostScript device, and in
the Printer and Z-Graphics Buffer devices. The TRUE keyword is
set automatically to the correct value for 24-bit images, so you
don't need to specify it when using TVSCALE. In addition, you can
use the TOP and BOTTOM keywords to define a particular set of
number to scale the data to. The algorithm used is this:
TV. BytScl(image, TOP=top-bottom) + bottom
Note that if you scale the image between 100 and 200, that
there are 101 possible pixel values. So the proper way to
load colors would be like this:
LoadCT, NColors=101, Bottom=100
TVSCALE, image, Top=200, Bottom=100
Alternatively, you could use the NCOLORS keyword:
LoadCT, NColors=100, Bottom=100
TVSCALE, image, NColors=100, Bottom=100
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 display.
CALLING SEQUENCE:
TVSCALE, image
INPUTS:
image: A 2D or 3D image array. It does not have to be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TVSCL keyword is set.
KEYWORD PARAMETERS:
BACKGROUND: This keyword specifies the background color. Note that
the keyword ONLY has effect if the ERASE keyword is also
set or !P.MULTI is set to multiple plots and TVSCALE is
used to place the *first* plot.
BOTTOM: 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.
ERASE: If this keyword is set an ERASE command is issued
before the image is displayed. Note that the ERASE
command puts the image on a new page in PostScript
output.
_EXTRA: This keyword picks up any TV keywords you wish to use.
HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
specified position in the window. If you prefer, you can
force the image to maintain its aspect ratio in the window
(although not its natural size) by setting this keyword.
The image width is fitted first. If, after setting the
image width, the image height is too big for the window,
then the image height is fitted into the window. The
appropriate values of the POSITION keyword are honored
during this fitting process. Once a fit is made, the
POSITION coordiates are re-calculated to center the image
in the window. You can recover these new position coordinates
as the output from the POSITION keyword.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignormed when TVImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics.
MAXVALUE: The data is linearly scaled between the MIN and MAX values,
if they are provided. MAX is set to MAX(image) by default.
MINVALUE: The data is linearly scaled between the MIN and MAX values,
if they are provided. MIN is set to MIN(image) by default.
MINUS_ONE: The value of this keyword is passed along to the CONGRID
command. It prevents CONGRID from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays.
NCOLORS: If this keyword is supplied, the TOP keyword is ignored and
the TOP keyword is set equal to BOTTOM + NCOLORS - 1. This
keyword is provided to make TVSCALE easier to use with the
color-loading programs such as LOADCT:
LoadCT, 5, NColors=100, Bottom=100
TVScale, image, NColors=100, Bottom=100
NOINTERPOLATION: Setting this keyword disables the default bilinear
interpolation done to the image when it is resized. Nearest
neighbor interpolation is done instead. This is preferred
when you do not wish to change the pixel values of the image.
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 TVSCL keyword is set.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
TVScale, image, /Overplot
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this can
be an output parameter if the KEEP_ASPECT_RATIO keyword is
used.
TOP: 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.
TVSCL: Setting this keyword makes the TVIMAGE command work much
like the TVSCL command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
If a 24-bit image is displayed on an 8-bit display, the
24-bit image must be converted to an 8-bit image and the
appropriate color table vectors. This is done with the COLOR_QUAN
function. The TVSCALE command will load the color table vectors
and set the NOINTERPOLATION keyword if this is done. Note that the
resulting color table vectors are normally incompatible with other
IDL-supplied color tables. Hence, other graphics windows open at
the time the image is display are likely to look strange.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
thisPosition = [0.1, 0.1, 0.9, 0.9]
TVSCALE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
MODIFICATION HISTORY:
Written by: David Fanning, 27 May 1999 from TVIMAGE code.
Added MIN, MAX, and NCOLORS keywords 28 May 1999. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Brought the TVSCALE code up to date with TVIMAGE code. 3 April 2000. DWF.
Brought the TVSCALE code up to date with TVIMAGE code. 6 May 2000. DWF.
Change MIN and MAX keywords to MINVALUE and MAXVALUE to prevent
ambiguous keyword errors. 27 July 2000. DWF.
Brought up to date with changes in TVImage. 23 Sept 2000. DWF.
Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to display images. 8 June 2001. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Brought up to date with changes to TVImage as of 22 April 2007. DWF.
Updated the program for the 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF.
(See tvscale.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.
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.
SIDE EFFECTS:
The variable no longer exists.
EXAMPLE:
To delete the variable "info", type:
IDL> Undefine, info
MODIFICATION HISTORY:
Written by David 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.
(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 NORMALIZE from Coyote Library:
http://www.dfanning.com/programs/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.
(See vcolorbar__define.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, direction, speed
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 FSC_COLOR and STATIONPLOT from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.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=FSC_Color('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=FSC_Color('light gray')
Map_Set, /Cylindrical, Position=[0.1, 0.1, 0.9, 0.9], Color=FSC_Color('Steel Blue'), /NoErase
Map_Grid, Color=FSC_Color('Charcoal', !D.Table_Size-2)
Map_Continents, Color=FSC_Color('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.
MODIFICATION HISTORY:
Written by David W. Fanning, June 2005.
(See windowavailable.pro)
NAME:
WINDOWIMAGE
PURPOSE:
The purpose of this routine is to demonstrate how to interactively
adjust the contrast and brightness (also called the window and level)
of an 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:
Graphics, Widgets.
CALLING SEQUENCE:
WINDOWIMAGE, image
INPUTS:
image: A 2D image array. Typically, the image will be a 16-bit medical
image of some type. If this parameter is not present, a 16-bit
dicom image from the examples/data directory will be selected.
KEYWORD PARAMETERS:
COLORTABLE: The index of an IDL-supplied color table to load. Gray-scale by default.
LEVEL: The window level.
WIDTH: The half-width of the window. This value will be subtracted from the
the window LEVEL to form the lower window value, and added to the window
LEVEL to form the upper window value.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The TVIMAGE, COLORBAR__DEFINE, and ERROR_MESSAGE programs from the Coyote Library are
required to run this program:
http://www.dfanning.com/programs/tvimage.pro
http://www.dfanning.com/programs/colorbar__define.pro
http://www.dfanning.com/programs/error_message.pro
EXAMPLE:
To display a 16-bit medical image, type:
IDL> WINDOWIMAGE
MODIFICATION HISTORY:
Written by: David W. Fanning, 7 November 2001.
Modified the windowing algorithm to keep the window within
the data range. Added colorbar and pixmap for smoother
updating. 18 Nov 2001. DWF.
Fixed a small problem with object cleanup. Added window and
level readouts, window resizing. 23 Nov 2001. DWF.
Added LEVEL and WIDTH keywords. Changed output formatting to
accommodate floating integer values. 28 Nov 2005. DWF.
(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. The
event handler, object method, or IDL procedure is then responsibe
for updating the program's display on 16- or 24-bit display systems.
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.
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.
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.
_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:""}
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.
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.
NOTIFYPRO: The name of a procedure to notify or call when the color
tables are loaded. If the DATA keyword is also defined, 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 and image
in the current graphics window:
PRO REFRESH_IMAGE, Image=image, _Extra=extra, WID=wid
IF N_Elements(wid) NE 0 THEN WSet, wid
TVIMAGE, image, _Extra=extra
END
This program can be invoked with this series of commands:
IDL> Window, /Free
IDL> TVImage, 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.
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'
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.
(See xcolors.pro)
NAME:
XCONTOUR
PURPOSE:
The purpose of this program is to demonstrate how to
create a contour plot with axes and a title in the
new IDL 5 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, IDL 5 Object Graphics.
CALLING SEQUENCE:
XCONTOUR, 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:
CBARTITLE: A string used as the title of the colorbar.
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the old IDL contour command. Most of the keywords will
have absolutely no effect.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
NLEVELS: The number of equally spaced contour intervals to draw.
Default is 10. Note that contour levels are acutally calculated,
since the NLEVELS keyword to the contour object does not always
result in the correct number of contour levels.
TITLE: A string used as the title of the plot.
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Requires NORMALIZE from the Coyote library.
http://www.dfanning.com/programs/normalize.pro
EXAMPLE:
To use this program with your 2D data, type:
IDL> XContour, data
MODIFICATION HISTORY:
Written by David Fanning, 9 June 97.
Added a colorbar to the plot. 19 June 97, DWF.
Modified the way VCOLORBAR was called. 14 July 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 to use the IDLgrColorbar object. 20 Sept 98. DWF.
Added the ability to do a filled contour. 27 Sept 98. DWF.
Fixed a bug in the way the data was scaled into the view. 9 May 99. DWF.
Fixed a bug in the filled contours. 11 May 99. DWF.
Added a line to make sure 256 colors are available in Z buffer. 19 Dec 99. DWF.
Fixed a small bug where the X and Y vectors weren't sent to IDLgrContour. 19 Sept 2000. DWF.
Added CBARTITLE keyword and fixed a small memory leak. Updated VCOLORBAR code. 8 Dec 2000. DWF.
Fixed a minor problem with the Colorbar. Removed GIF support for IDL 5.4 and higher. 27 Mar 2001. DWF.
Removed NORMALIZE from the source code. 29 November 2005. DWF.
(See xcontour.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:
XPLOT
PURPOSE:
The purpose of this program is to demonstrate how to
create a line plot with axes and a title in the
new IDL 5 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, IDL 5 Object Graphics.
CALLING SEQUENCE:
XPlot, x, y
REQUIRED INPUTS:
x: A vector of input values used as the dependent data.
OPTIONAL INPUTS
y: A vector of input values used as the dependent data.
If both x and y parameters are present, x is the independent data.
OPTIONAL KEYWORD PARAMETERS:
COLORPRINT: This keyword is allowed for historical reasons, but does
nothing. Color printing is now available from the Print menu at all
times.
EXACT: Set this keyword to a one- or two-element array to set exact axis
scaling for the axes. If Exact is a one-element array, both axes are
set to the same value. If Exact is a two-element array, the first
elements sets the X axis property and the second element sets the Y
axis property. For example, to set the X axis to exact scaling and
the Y axis to normal scaling, type:
IDL> x = Findgen(10)
IDL> XPlot, x, Sin(x), Exact=[1,0], XRange=[0,8.5]
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to new Plot command. To some extent these are similar to the
old IDL Plot command. For example: Linestyle=2, Thick=3,
XRange=[-100,100], etc.
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.
POSITION: A four-element array of the form [x0, y0, x1, y1] for locating
the axes of the plot in the display window. The coordinates are in
"normalized" units, which means the extent of the window is from 0.0 to 1.0.
The default value of POSITION is [0.15, 0.15, 0.925, 0.925].
PSYM: The index of a plotting symbol to use on the plot. Integers 0-7
are valid values.
SYMSIZE: Sets the size of the symbols. By default, symbols are sized
so that they are 0.015 percent of the axis range.
VECTOR: Set this keyword if you want the printed output to be in
vector (as opposed to bitmap) form. This is faster, but not as accurate.
TITLE: A string used as the title of the plot.
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Requires NORMALIZE from the Coyote Library.
http://www.dfanning.com/programs/normalize.pro
EXAMPLE:
To use this program, pass a 1D vector or vectors, like this:
IDL> XPlot, RandomU(seed, 11) * 9, YRange=[0, 10]
MODIFICATION HISTORY:
Written by David W. Fanning, 13 June 97.
Modified axis font handling. 17 Sept 97. DWF.
Was not destroying all objects on exit. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Fixed a bug in the way symbols were (NOT!) sized. 11 May 99. DWF.
Added non-exact axis scaling. 12 May 99. DWF.
Fixed bug that changed data when calling with single parameter. 13 May DWF.
Added VECTOR, LANDSCAPE and COLORPRINT keywords and improved printing
capabilities. 16 Feb 2000. DWF.
Modified the EXACT keyword to accept values for X and Y axes
independently. 10 May 2000. DWF.
Updated for IDL 5.4. 13 June 2001. DWF.
Added EPS output via Clipboard object. 19 May 2002. DWF.
Added additional color schemes. 22 May 2002. DWF.
Added the ability to do color printing from the PRINT menu. 22 May 2002.
Removed COLORPRINT keyword. Keyword is allowed, but does nothing. 22 May 2002.
Added POSITION keyword so you can position plot in window. 1 August 2002. DWF.
Removed NORMALIZE from source code. 29 Nov 2005. DWF.
Fixed a problem with the plot title not appearing. 2 Dec 2005. DWF.
(See xplot.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 linear (LINEAR), power-law (GAMMA), log (LOG), and
inverse hyperbolic sine (ASINH) contrast stretching. 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.
COLORS: A five element string array, listing the FSC_COLORS colors for drawing the
histogram plot. The colors are used as follows:
colors[0] : Background color. Default: "ivory".
colors[1] : Axis color. Default: "charcoal".
colors[2] : Min threshold color. Default: "firebrick".
colors[3] : Max threshold color. Default: "steel blue".
colors[4] : ASinh color. Default: "sea green".
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 SELECTIMAGE, 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.
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.
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)
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: bytarr(256), $ ; The R color vector associated with the image
g: bytarr(256), $ ; The G color vector associated with the image
b: bytarr(256), $ ; The B color vector associated with the image
type: "", $ ; The TYPE of stretch applied to the image.
minThresh: 0.0, $ ; The minimum threshold value.
maxThresh: 0.0, $ ; The maximum threshold value.
gamma: 0.0, $ ; The current GAMMA value.
beta: 0.0, $ ; The current BETA value.
mean: 0.0, $ ; The current MEAN value.
exponent: 0.0 } ; The current EXPONENT value.
DEPENDENCIES:
Requires a number of files from the Coyote Library:
http://www.dfanning.com/programs/xstretch.zip
or
http://www.dfanning.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 TVIMAGE. 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.
Mofications to GUI for updated ASINHSCL function. Removed ALPHA keyword
and changed the definition of BETA. 25 April 2006. DWF.
(See xstretch.pro)
NAME:
ZIMAGE
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.
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:
ZIMAGE, image
INPUTS:
image: A 2D array of image data.
KEYWORD PARAMETERS:
BOTTOM: The lowest color index of the colors to be used (see
NCOLORS). The default is 0.
COLORINDEX: The color index for the rubberband box. This index will
be loaded with a green color. Whatever color is there will
be restored when the ZIMAGE program exits. The default is
NCOLORS + BOTTOM.
NCOLORS: This is the number of colors to use when displaying the
image. The default is !D.N_COLORS-2.
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
ZIMAGE from another widget program.
NOINTERPOLATION: Setting this keyword causes nearest neighbor resampling of
of the zoomed image instead of the default bilinear interpolation
of resampled pixels.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
The COLORINDEX color is turned to green while the rubberband box
is being drawn. The color is restored after the box is drawn.
RESTRICTIONS:
Uses XCOLORS from the Coyote Library:
http://www.dfanning.com/programs/xcolors.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.
Clicking the right mouse button calls up hidden controls that allow
you to load different color tables and set the zoom factor.
The rubberband box is drawn with pixmaps and the "device copy"
technique.
This is an excellent example of how you can take advantage of the
widget program *as* the loop do to something (i.e., draw the box)
that in a regular IDL program would have to be done in a loop. Motion
events are only turned on for the draw widget when the box has to be
drawn.
EXAMPLE:
To display an image you can zoom into, type:
ZIMAGE, image
MODIFICATION HISTORY:
Written by: David Fanning, 15 August 96.
Fixed a !D.N_Colors problem. 17 June 98.
Made modifications so program works in 24-bit environment. 28 July 98. DWF.
Fixed a problem with the pop-up controls under certain circumstances.
13 Oct 98. DWF.
Added 24-bit color response. 13 Oct 98. DWF.
Added ability for each window to have its own color changing tool. 9 Oct 99. DWF.
Small changes, error checking. 24 April 2000. DWF.
Modified draw widget error handling to be consistent with current programming
practices. 26 April 2001. DWF.
(See zimage.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 NORMALIZE from the Coyote Library.
http://www.dfanning.com/programs/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.
(See zoombox.pro)
NAME:
ZPLOT
PURPOSE:
The purpose of this program is to display a line plot in a resizeable
graphics window which can be zoomed by drawing an "arrow box" on top
of it. To return to the un-zoomed plot, click and release anywhere in the 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:
Widgets.
CALLING SEQUENCE:
ZPlot, x, y
OPTIONAL INPUTS:
x: If only one positional parameter, this is assumed to be the
dependent data. If there are two positional parameters, this
is assumed to be the independent data in accordance with the
PLOT command.
y: The dependent data, if the X parameter is present.
KEYWORD PARAMETERS:
Any valid PLOT keyword can be used with this program. In additon,
the following keywords are defined specifically.
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
ZIMAGE from another widget program.
XLOG: Set this keyword if you wish the X axis to be logarthmic style.
YLOG: Set this keyword if you wish the Y axis to be logarthmic style.
ZOOM_XSIZE: The initial X size of the plot window. Default is 400 pixels.
ZOOM_YSIZE: The initial Y size of the plot window. Default is 400 pixels.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Drawing colors are loaded into the color table.
RESTRICTIONS:
Zooms only along the X axis.
Requires FSC_Color from the Coyote Library.
PROCEDURE:
Click and drag the cursor to create an "arrow box". The plot
is zoomed into the X coordinates of the box, when released.
To restore unzoomed plot, click and release anywhere in the
window.
EXAMPLE:
To display an plot you can zoom into, type:
ZPLOT
MODIFICATION HISTORY:
Written by: David Fanning, 15 February 2000.
Modified the original rubberband box to be an "arrow box". 1 April 2000. DWF.
Added the ability to produce log style plots. 20 November 2001. DWF.
Replaced all references to GETCOLOR with FSC_COLOR. 1 March 2006. DWF.
(See zplot.pro)