Varosi vlib AstroContrib Library
This page is a listing of the entire contents of this library for IDL.
This listing is the long version. Viewing the
much more compact listing may be handier.
Last modified: Thu Dec 21 21:18:21 2000.
List of Routines
Routine Descriptions
ACCUMULATE
[Next Routine]
[List of Routines]
NAME:
accumulate
PURPOSE:
Perform running accumulation of one of the dimension in 2D array,
for example, a matrix of histograms.
CALLING:
haccum = accumulate( histogs )
INPUTS:
histogs = matrix ( Nbins, Nhistog ) of histograms to accumulate,
or any 2D array to be accumulated in first dimension.
KEYWORDS:
/NO_TRANSPOSE : assume input matrix of histograms is already transposed,
accumulation is performed on second dimension of input matrix.
HISTORY:
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/accumulate.pro)
ADD_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
add_struct
PURPOSE:
Add the tag values of two structures in nice column format.
Tags are chosen by wildcard matching.
CALLING:
add_struct, struct_in_out, struct_add, TAG_MATCH=tag_match
INPUTS:
struct_in_out = structure to which values are added.
struct_add = tag values of this structure are added to struct_in_out.
KEYWORDS:
OUTPUTS:
EXTERNAL CALLS:
function N_struct
function unique
PROCEDURE:
HISTORY:
Written: Frank Varosi NASA/GSFC 1999.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/add_struct.pro)
ADJCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
adjct
PURPOSE:
My interface to replace standard adjct with adjctmap (my version)
CALLING:
adjct
HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/adjct.pro)
ADJCTMAP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
adjctmap
PURPOSE:
Interactively adjusts color tables using mouse input.
This version is designed (by F.V.) to work with procedures:
color_map_Load,
color_struct,
color_st_Load,
hist_equal_ct,
by saving the color table mapping and parameters in common.
Also, the color bar is put on horizontal axis (more intuitive).
CALLING:
adjctmap
KEYWORDS:
XPOSITION = x position of interaction window on screen
YPOSITION = y position of interaction window on screen
SIDE EFFECTS:
Color tables are modified (rgb_orig is mapped into rgb_curr).
COMMON BLOCKS:
adjct_map, color_map : keeps pixel value to color table mapping.
adjct_ramp, oldx, oldy : keeps RAMP mapping parameters.
NOTE: common colors - color table common block (rgb_orig , rgb_curr),
is modified by pro color_map_Load.
EXTERNAL CALLS:
pro menus - to handle selection of operation types.
pro color_map_Load - apply pixel value to color table mapping,
and load color tables (tvlct).
function select_number - called for steps option only.
PROCEDURE:
A new window is created and a graph of the color output value
versus pixel value is created. User can adjust this transfer function
a number of ways using the mouse (explained in help option).
HISTORY:
DMS, March, 1988, written.
DMS, April, 1989, modified cursor handling to use less CPU
Frank Varosi Oct.1989, added the STEPS option #3 (not all finished).
FV Nov.89, put color bar on horizontal axis (more intuitive).
FV Jan.90, saved color_map (=p) in common
and call color_map_Load instead of tvlct (map is remembered).
FV Feb.90, saved oldx & oldy in common adjct_ramp (ramp is remembered).
FV Nov.90, use modified version of pro menus for initial choice setup.
FV Dec.91, apply smoothing to reduce jitter in draw curve option.
FV 1992, added keywords XPOS and YPOS.
FV 1993, changed name from adjct to adjctmap (so as not to confuse).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/adjctmap.pro)
ALIGN_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ALIGN_STRUCT
PURPOSE:
Check an IDL structure for standard memory alignment of fields,
insert any byte padding required to align fields on size boundaries,
write out new code to define the aligned version of structure.
CATEGORY:
Structures
CALLING SEQUENCE:
align_struct, structure_name
examples:
align_struct, "fdq_sdf"
INPUTS:
structure_name = string giving the structure name
as known by IDL (help,/struct,variable).
inputs/outputs used recursively:
struct = the structure variable currently analyzed.
Max_Field_Size = size of the largest field found in structure.
struct_size = total size of all fields in structure.
Lun_out = Logical unit number for writing .PRO code.
SIDE EFFECTS:
"structure_name"_ST_AL.PRO is created (IDL function code).
PROCEDURE:
Strategy is to call align_struct recursively.
otherwise the field type and size is used to construct IDL definition,
which is then concatenated with the other IDL definitions,
MODIFICATION HISTORY:
written 1990 Frank Varosi STX @ NASA/GSFC
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/align_struct.pro)
ASTRO_TICKS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
astro_ticks
PURPOSE:
Create nice Labels for R.A. or DEC given range of degrees.
CALLING:
astro_ticks, degrees, nticin, ticvals, ticLabs, mtics
INPUTS:
degrees = array of degrees.
nticin = suggested # of ticks.
KEYWORDS:
/RA : to indicate that Labels are for R.A. axis. (hours,..etc.)
OUTPUTS:
ticvals = float array, location of major ticks.
ticLabs = string array, Labels for major ticks.
mtics = # of minor tick marks.
EXTERNAL CALLS:
function Ten
function sixty
PROCEDURE:
Very many "if" statements.
HISTORY:
Written: Frank Varosi NASA/GSFC 1989, based on
"tics.pro" and "ticlabels.pro" from IDL-astron-Library.
F.V. 1991, make seconds start on multiple of 5 or 2 if inc = 5 or 2 .
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/astro_ticks.pro)
ASTRO_TICKS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
astro_ticks
PURPOSE:
Read R.A. and DEC from user, convert and return as degrees.
User input can be delimeted with commas, spaces or ":".
CALLING:
read_radec, asc,dec
INPUTS:
asc = default value of Right Ascension.
dec = default value of Declination.
OUTPUTS:
asc = degrees Right Ascension.
dec = degrees Declination.
EXTERNAL CALLS:
function Ten
function sixty
HISTORY:
Written: Frank Varosi NASA/GSFC 1989, based "radec.pro" in astro-Lib.
F.V. 1991, added option to use default values.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/read_radec.pro)
BACKGROUND
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/background.pro)
BANDPASS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
bandpass
PURPOSE:
Compute flux thru bandpass filter of given transmission at wavelengths.
Optionally, flux and/or transmission is integrated in Log-Log space
(see keyword POWER_LAW), default is integration in Linear-Linear space.
CALLING:
Fobs = bandpass( Lambda, Flux, W=waveT, T=Trans )
INPUTS:
Lambda = wavelengths in microns.
Flux = radiation spectrum at wavelengths of Lambda array.
Units are assumed to be energy/Hertz.
KEYWORDS:
WAVELENGTH = wavelengths (microns) of bandpass filter transmission.
TRANSMISSION = transmission coefficients at wavelengths.
/MICRON : then assumes Flux is in units of energy/micron.
/POWER_LAW_INT : use power law interp for flux, linear interp for
transmission, and power law integral for flux * transmission.
POWER_LAW_INT=2 : use power law interp/integral for flux & transmission.
OUTPUTS:
Returns the integral of the product of Flux times Transmission.
EXTERNAL CALLS:
function unique
function finterpol
function Trapow
function Trapez
PROCEDURE:
Apply reform to inputs just in case they were passed as Flux(i,*) etc.
Interpolate both flux and transmission to single merged wavelength grid
and integrate the product. Optionally, flux and/or transmission
is interpolated/integrated in Log-Log space (see keyword POWER_LAW),
whereas default is interpolation/integration in Linear-Linear space.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
FV, 1998, mod to skip interp if wavelength grids match.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/bandpass.pro)
BIN2D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Bin2D
PURPOSE:
Create a density image (2D histogram) from arrays of (x,y) points,
or create an image of a function from arrays of ( x, y, f(x,y) ) data.
In first case each pixel counts # of (x,y) points falling into
a 2D bin (box), thus forming an image of counters. In optional case,
each pixel is the average of all f(x,y) data falling into the box.
Boxes are determined by dividing the (x,y) range into a uniform grid.
CALLING EXAMPLES:
imh = Bin2D( x, y, NPIX=64, XRAN=[0,20], YRAN=[-5,5] )
imz = Bin2D( x, y, FXY=z, NPIX=[200,100] )
INPUTS:
X = array (any dimension) of x values.
Y = array of y values, should correspond to x array.
optionally, x can be of the form [[x],[y]]
containing both x and y coordinates as rows of matrix,
and then argument y should not be specified.
KEYWORDS:
XRAN and YRAN : specify the x,y range to be mapped into the image.
Common Bin2D, xminc,xmaxc, yminc,ymaxc
can also specify the x,y range if keywords are not used,
otherwise the defaults = min-max ranges of x and y.
NPIXELS = 1 or 2 element integer array specifying size of result,
(single value means square image), default = [64,64].
/NOCLIP means do not bother checking if (x,y) are within range (faster).
TYPE_VAR = type code specifying the IDL variable type of result,
(1=byte, 2=short, 3=Long, 4=float,... default=2, short integer).
KEYWORDS (optional):
IMAGE_DENSITY = an existing image of counters (2D histogram)
to which the result is added (overrides NPIX=).
FXY = array giving z = f(x,y) for the purpose of binning into an image
however, bins with no (x,y) data points are left = zero.
(NOTE: must specify XRAN and YRAN, or set /NOCLIP).
if /BOTH is set and FXY=z is given, then the binned image of z=f(x,y) is
returned by function, and an image of (x,y) density is
returned via the keyword IMAGE_DENSITY.
OUTPUTS:
Result of function is an image of the density of (x,y) points, or an
image of scalar field function if z values are given at (x,y) points.
PROCEDURE:
Binning is performed by finding number of (x,y) duplicates
at each pixel, using the IDL sort and where functions.
HISTORY:
written Frank Varosi, U.of MD., 1988.
F.V. 1990, modif. for IDL-V2.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/bin2d.pro)
BIN3D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Bin3D
PURPOSE:
Create a volume density (3D histogram) from arrays of (x,y,z) points,
or create a voxel matrix from arrays of ( x,y,z, f(x,y,z) ) data.
In first case each voxel counts # of (x,y,z) points falling into
a 3D bin (box), thus forming an image of counters. In optional case,
each voxel value is the average of f(x,y,z) data falling in box.
Boxes are determined by dividing the (x,y,z) range into a uniform grid.
CALLING:
imh = Bin3D( x, y, z, NVOX=64, XRAN=[0,20], YRAN=[-5,5] )
imz = Bin3D( x, y, z, FXYZ=z, NVOX=[200,100,50] )
INPUTS:
x = array (any dimension) of x values.
y = array of y values, should correspond to x array.
z = array of z values, corresponding to x array.
Optionally, x can be of the form [[x],[y],[z]]
containing all x, y and z coordinates as rows of matrix,
and then arguments y and z should not be specified.
KEYWORDS:
XRAN, YRAN, ZRAN : specify the x,y,z range to be mapped into the image.
otherwise the defaults = min-max ranges of x and y.
NVOXELS = 1 or 3 element integer array specifying size of result,
(single value means square image), default = [64,64,64].
/NOCLIP : do not bother checking if (x,y,z) are within range (faster).
TYPE_VAR = type code specifying the IDL variable type of result,
(1=byte, 2=short, 3=Long, 4=float,... default=2, short integer).
KEYWORDS (optional):
VOXEL_DENSITY = an existing image of counters (3D histogram)
to which the result is added (overrides NVOX=).
FXYZ = array giving f(x,y,z) for the purpose of binning into voxels,
however, bins with no (x,y,z) data points are left = zero.
(NOTE: must specify XRAN, YRAN, ZRAN, or set /NOCLIP).
if /BOTH is set and FXYZ=f is given, then the binned image of z=f(x,y,z) is
returned by function, and voxel density of (x,y,z) is
returned via the keyword VOXEL_DENSITY.
OUTPUTS:
Result of function is voxel density of (x,y,z) points, or an
scalar field of voxels if f(x,y,z) values are given.
PROCEDURE:
Binning is performed by finding number of (x,y,z) duplicates
at each voxel, using the IDL histogram, sort and where functions.
HISTORY:
written Frank Varosi, U.of MD., 1988.
F.V. 1990, modif. for IDL-V2.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/bin3d.pro)
BIN_SCAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Bin_Scat
PURPOSE:
Given two arrays of data that are in one-to-one correspondence
(such as a functional relationship), calculate averages and
standard devations of the second array within bins that
are determined by the histogram of the first array.
Using this technique, a scatter plot of y versus x can be
displayed instead as a graph of bin averages with error bars.
Results are returned via keywords.
CALLING:
Bin_Scat, x, y
INPUTS:
x = this array is binned using histogram
y = usually a function of x, this array is averaged over bins
corresponing to the x array.
KEYWORD INPUTS:
NBIN = # of bins desired, default=100.
BINSIZE = the desired binsize, overrides NBIN,
but NBIN will still limit the maximum # of bins.
MIN = minimum data value to include in histogram.
MAX = maximum data value to include in histogram
(defaults are actual min or max of data).
/SUM : setting this keyword causes total of y-values in each bin
to be computed (instead of the default mean, st.dev., median).
KEYWORD OUTPUTS:
XBINS = array of histogram bins between min & max.
XHISTOGRAM = number of x values in each bin.
MEAN = array of means of y values corresponding to x values in each bin.
STDEV = array of standard deviations of y values corresponding to means.
MEDIAN = array of medians of y values in each x-bin.
TOTAL = array of totals of y values in each x-bin (if /SUM is set).
EXTERNAL CALLS:
function Histo (this sets up and calls IDL histogram function)
function stdev
PROCEDURE:
Use the reverse indices keyword of the IDL histogram function
(called via function Histo for which third argument is reverse indices).
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1997.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/bin_scat.pro)
BLINKDRAG_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
blinkdrag_image
PURPOSE:
Blink an image (alternately displaying image and background),
drag it across window using mouse-cursor until a button is pressed.
New location of image and mouse button value are returned.
In X-windows, the window backing store should be pixmap,
that is, use device,RETAIN=2 or window,RETAIN=2,...
for fastest blinking of image.
CALLING:
button = blinkdrag_image( ioffx, ioffy, image, Locx, Locy )
INPUTS:
ioffx & ioffy = Location of cursor inside the image (in device pixels)
offset relative to lower-left corner.
image = byte image to display, blink and drag.
Locx & Locy = starting Location (pixels) of lower-left corner of image.
KEYWORDS:
WAIT_DISPLAY = seconds to wait after displaying image to equalize blink,
default = 0.003 seconds, seems to work.
OUTPUTS:
Locx & Locy = ending Location of lower-left corner of image
(in device pixels) after a button is pressed.
Result of function is value of !mouse.button.
EXAMPLE:
Locx=100 & Locy=100
button = blinkdrag_image( 0, 0, image, Locx, Locy )
COMMON BLOCKS:
common blinkdrag1, wait_image, wait_back ;wait times in millisec.
common blinkdrag2, aex, aey, cex, cey ;for overlay of ellipse.
PROCEDURE:
Sparcstation running SunView is faster than X-windows,
so use waits to stall the blink times, otherwise too much flicker.
For X-windows use PIXMAP and device,COPY=[...] instead of tv and tvrd.
HISTORY:
written Frank Varosi NASA/GSFC 1989
F.V. 91, mod to keep tvrd in window, since idl-v.2.1.2 demands it.
F.V. 92, split into two loop codes for different display types.
F.V. 96, added option to overlay ellipse (coordinates in common).
F.V. 97, can now set blinking image/background display times in common.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/blinkdrag_image.pro)
BORDER_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
Draw a one pixel width border around an image on screen at
window device coordinates (xmin,ymin,xmax,ymax) (can be negative).
If image is only partially in window, the partial border is drawn.
Default color is !D.table_size-1,
and if arg. number is specified it is printed at left bottom corner of image.
Frank Varosi NASA/GSFC 1989
F.V. 1991, option to pass (xmin,ymin,xmax,ymax) vector in 1st. arg.
and keyword COLOR overrides arg. color.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/border_image.pro)
BOX_CREATE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
box_create
PURPOSE:
Interactively create a box using the cursor/mouse
in a rubber-band fashion. First click LEFT button for corner,
then drag and click MIDDLE or RIGHT for final corner.
Device coordinates of lower left & upper right corners, are output.
Function returns status = -4 if first click is RIGHT button (abort),
else if first click is LEFT button (to start rubber-box) then
return status = 2 or 4 for MIDDLE or RIGHT buttons, respectively.
CALLING:
status = box_create( xLow, yLow, xUp, yUp )
INPUTS:
none
OUTPUTS:
xLow, yLow = device coordinates of lower left corner.
xUp, yUp = device coordinates of upper right corner.
KEYWORDS:
/CENTERED causes box to be centered on point selected
by first mouse click
/DATA_COORDIN causes coordinates of box to be converted to data space,
(default is device coordinates).
/DOUBLE_BOX : box is drawn as 2 rectangles,
outer is dark, (min color index),
inner is bright (max color index),
to help assure visibility against any background.
EXTERNAL CALLS:
pro box_draw
pro box_erase
pro box_draw2
pro box_erase2
COMMON BLOCKS:
common box_draw
PROCEDURE:
Loop on box_draw and box_erase while reading cursor coordinates.
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1991 added option to center rubber box around first point selected.
F.V. 1993 added option to convert to data coordinates.
F.V. 1997 added /DOUBLE_BOX option.
F.V. 1998, wait until mouse button is RELEASED (/UP) before returning.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_create.pro)
BOX_CURSOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Box_Cursor
PURPOSE:
Emulate the operation of a variable sized box cursor.
The box is constrained to lie entirely within the window.
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
Box_Cursor, x0, y0, nx, ny [, /INIT, /FIXED_SIZE, /ADJACENT, /CONTIN ]
INPUTS:
No required input parameters.
OPTIONAL INPUT PARAMETERS:
x0, y0, nx, & ny : initial location and size of the box,
required if the keyword INIT is set.
Otherwise, the box is initially in the center of the screen.
KEYWORD PARAMETERS:
/INIT : x0,y0, nx,ny are used as the initial parameters for the box.
/FIXED_SIZE : nx and ny contain the initial size of the box,
and this size cannot be changed by the user.
/ADJACENT : cursor is kept adjacent to box (one pixel lower than box).
/CENTERED : cursor is kept centered in box.
/CONTINUOUS : cursor movement is read continuously,
any mouse button pressing will exit. Default is to click
left button to move, middle to change size, right to exit.
/KEEP_BOX : box is left drawn in window, otherwise it is erased on exit.
OUTPUTS:
x0 = X value of lower left corner of box.
y0 = Y value of lower left corner of box.
nx = width of box in pixels.
ny = height of box in pixels.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased on exit.
RESTRICTIONS:
Works only with window system drivers.
EXTERNAL CALLS:
pro box_draw (if /KEEP_BOX)
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This allows the
box to be drawn and erased without disturbing the contents of window.
Operation is as follows:
Left Mouse button: Move the box by dragging or clicking.
Middle Mouse button: Resize the box by dragging or clicking.
Right mouse button: Exit procedure, returning current box parameters.
MODIFICATION HISTORY:
DMS, April, 1990.
FV, 1992, rearranged and added more options: /ADJACENT, /CONTINUOUS
FV, 1994, added more options: /KEEP_BOX, /CENTERED
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_cursor.pro)
BOX_DRAW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
box_draw
PURPOSE:
Draw a Box (rectangle) in the current window, with specified color,
first saving the data in common,
so it can be later restored with pro box_erase.
CALLING:
box_draw, x1,y1, x2,y2, color
INPUTS:
x1, y1 = device coordinates of lower left corner.
x2, y2 = device coordinates of upper right corner.
color = index to color table, default = !D.table_size-1
KEYWORDS:
Alternate (overrides args.) method of specifying box:
RADIUS_XY = radius of box, 1 or 2 integers, default=1.
SIZE_XY = diameter of box, 1 or 2 integers (overrides radius).
POS_XY = 2 integers, specifying position of box center if RADIUS given,
or specifying position of box lower-left corner if SIZE given.
COLOR = index to color table, default = !D.table_size-1
OUTPUTS:
none
COMMON BLOCKS:
common box_draw
PROCEDURE:
If size of box > 16 :
read pixels at sides of desired box using TVRD, store into common,
display the four sides of box using TV.
If size of box < 16 :
read all pixels in desired box using TVRD, store into common,
set the border to desired color, redisplay using TV.
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1990, if Box < 16x16 then save and redisplay with interior also.
F.V. 1992, added keywords POS=[x,y] and RADIUS=(radius or [radx,rady]).
F.V. 1993, option to pass all 4 coordinates in first argument.
F.V. 1995, option to pass [x,y] coordinates in first 2 arguments.
F.V. 1997, added full argument presence checking.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_draw.pro)
BOX_DRAW2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
box_draw2
PURPOSE:
Draw two boxes (rectangles) in the current window,
the first with specified color at specified location,
the second just around the first with minimum color index (black)
so that the double box can be seen against any background image.
The window image data is saved in common
so that the double box can be erased with box_erase2.
CALLING:
box_draw2, POS_XY=, RADIUS_XY=, SIZE_XY=, COLOR=
KEYWORD INPUTS:
RADIUS_XY = radius of box, 1 or 2 integers.
SIZE_XY = diameter of box, 1 or 2 integers (overrides radius).
POS_XY = 2 integers, specifying position of box center if RADIUS given,
or specifying position of box lower-left corner if SIZE given.
COLOR = index to color table, default = !D.table_size-1
OUTPUTS:
none
EXTERNAL CALLS
pro box_draw
pro box_save
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1997.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_draw2.pro)
BOX_ERASE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
box_erase
PURPOSE:
Erase the box (restore what was there)
drawn by previous call to box_draw,
only if current window is the one in which box was drawn.
CALLING:
box_erase
KEYWORDS:
/RESET : just clear common block, no changes to window.
OUTPUTS:
none
COMMON BLOCKS:
common box_draw
PROCEDURE:
HISTORY:
Frank Varosi NASA/GSFC 1989
F.V.1992 added /RESET option to just forget box (clear out common).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_erase.pro)
BOX_ERASE2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
box_erase2
PURPOSE:
Erase the double box (restore what was there)
drawn by previous call to box_draw2,
only if current window is the one in which box was drawn.
CALLING:
box_erase2
KEYWORDS:
OUTPUTS:
none
COMMON BLOCKS:
common box_draw
EXTERNAL CALLS
pro box_erase
pro box_save
PROCEDURE:
HISTORY:
Frank Varosi NASA/GSFC 1997.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_erase2.pro)
BOX_SAVE
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1989
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/box_save.pro)
BREAK_FILE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
break_file
PURPOSE:
Given a file name, break the filename into the parts
of disk/logical, the directory, the filename, the
extension, and the file version (for VMS)
INPUT:
file - The file name
OUTPUT:
disk_log- The disk or logical (looks for a ":")
This is generally only valid on VMS machines
dir - The directory
filnam - The filename (excluding the ".")
ext - The filename extension (including the ".")
fversion- The file version (only VMS)
node - The Node name (only VMS)
RESTRICTIONS:
VMS:
Assumes that : always precedes []
ULTRIX:
Right now it has trouble with the ultrix option of use
of "." or ".."
HISTORY:
Written 1988 by M.Morrison
Aug-91 (MDM) Changed to handle Unix filename convensions
28-Feb-92 (MDM) * Adjusted to handle arrays
11-Mar-92 (MDM) - Perform a STRTRIM(x,2) on input string before
doing the "break-up"
1-Dec-92 (MDM) - Moved code to do filename, extension and version
number for both VMS and Unix (previously it
did not do version number code for Unix)
29-Jan-93 (DMZ/MDM) - checked for node in file name
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/break_file.pro)
CALL_FUNCTION
[Previous Routine]
[Next Routine]
[List of Routines]
For compatibility of Sun386i version of IDL with newer versions.
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/call_function.pro)
CENTROID
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
centroid
PURPOSE:
Compute centroid coordinates of a stellar image as in DAOPHOT FIND.
CALLING SEQUENCE:
centroid, image, XCEN, YCEN, XY_PEAK=[x,y], [FWHM=fwhm], [/PEAK_LOC]
INPUTS:
image - Two dimensional image array
KEYWORDS:
XY_PEAK = [x,y] vector of 2 integers giving approximate stellar center.
Pixel at maximum in subimage will then be used to start.
If not specified then max pixel of whole image is used.
FWHM - floating scalar or 2 elements (for x & y), default FWHM = 3 pixels.
Centroid computed in box of half width = 1.5*sigma = 0.637*FWHM
/PEAK_LOCATE - causes the peak (maximum pixel) of image to be used
as approximate stellar center (overrides XY_PEAK).
OUTPUTS:
XCEN - floating scalar, giving the computed X centroid position
YCEN - floating scalar, giving the computed Y centroid position
Values for XCEN and YCEN will not be computed if the
centroid falls outside of the box, or if the computed derivatives
are non-decreasing. If the centroid cannot be computed, then a
message is displayed and XCEN and YCEN are set to -1.
RESTRICTIONS:
Program does not check if the input X and Y position falls within image.
SYSTEM VARIABLES:
!DEBUG - If set, the subarray used to compute the centroid is printed
EXTERNAL CALLS:
pro Locate_Peak, image, xmax, ymax
PROCEDURE:
Maximum pixel within distance from input pixel X, Y determined
by FHWM is found and used as the center of a square, within
which the centroid is computed as the value (XCEN,YCEN) at which
the derivatives of the partial sums of the input image over (y,x),
with respect to (x,y), equal zero.
MODIFICATION HISTORY:
Written 2/25/86, by J. K. Hill, S.A.S.C., following
algorithm used by P. Stetson in DAOPHOT.
Added vector subscripting, W. Landsman 5/21/87
Mod: F.Varosi 1991-92, changed name from CNTRD to CENTROID, optimized,
changed SUM calls to SUM_ARRAY, added keyword XY_PEAK=[x,y],
option /PEAK_LOC to locate and use maximum,
add 0.5 to centroid x & y values so it is in center of pixel.
Edit: FV 1999, added more comments explaining keywords in header info.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/centroid.pro)
CHECK_DIR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
check_dir
PURPOSE:
Check if a directory actually exists on a UNIX system,
for VMS this function checks whether a sub-directory exits.
CALLING:
dir_existing = check_dir( directory )
INPUT:
directory = string, full name of directory (sub-directory on VMS).
OUTPUT:
Function returns the directory name if it exists,
else if directory does not exist it returns null string.
On UNIX: directory name is appended with / ,
on VMS if is string of form: [.sub-dir] .
RESTRICTIONS:
Have not tested on MacOS or Win32, probably does not work.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/check_dir.pro)
CHISQ_FIT
[Previous Routine]
[Next Routine]
[List of Routines]
chisq_fit
Example to show how to find the parameters of a nonlinear function
which minimizes the chi-sq of fit to some (x,y) data, using minf_conj_grad.
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/chisq_fit.pro)
CHKARG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
chkarg
PURPOSE:
determine calling arguments of procedure or function
CATEGORY:
utility
CALLING SEQUENCE:
chkarg
INPUTS:
name = string containing the name of the procedure.
KEYWORDS:
PATH = optional directory/library search path. Same format
and semantics as !PATH. If omitted, !PATH is used.
OUTPUTS:
name = name of routine
proc = string array with lines of procedure
lname = libr/direc location of procedure
PROCEDURE:
Based on DOC_LIBRARY
RESTRICTIONS:
Cannot access built-in IDL procedures
MODIFICATION HISTORY:
Written DMZ (ARC) Oct 1990
Converted to version 2 (DMZ Jul'92)
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/chkarg.pro)
CHOOSE_N_COLORS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
choose_N_colors
PURPOSE:
Allow user to choose number of colors to use for color table,
or else take whatever number is available.
CALLING:
choose_N_colors
INPUTS:
None.
KEYWORDS:
DEFAULT_NCOL = (default = 100).
/YES_CHOOSE : assume yes answer to first question, so as to skip
ahead to choosing # of colors.
OUTPUTS:
None.
EXTERNAL CALLS:
function yes_no_menu
function get_text_input
pro print_struct
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1997.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/choose_n_colors.pro)
CIRCINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
CIRCINT
PURPOSE:
Integrate flux in circular apertures. User responsible for
subtracting sky first. See notes (1) and (2) below.
CALLING SEQUENCE:
circint, image, x0, y0, radii, totdif, npixdif, t8, n8
INPUT PARAMETERS:
image 2-D image array
x0, y0 center of circular apertures (need not be integral)
radii vector of aperture radii
OUTPUT PARAMETERS (see note 2):
totdif total raw flux for each annulus (difference of successive
apertures)
npixdif number of pixels in each annulus
t8 like totdif, but each annulus is divided into eight sections
(X dimension = 8, Y dimension = number of annuli). Allows
assessment of error due to lumpiness of distribution, by
method of Djorgovski & King
n8 number of pixels in each octant of annulus.
OPTIONAL INPUT KEYWORDS:
MASK Must be same size as image. If a pixel in
the mask is 1, the corresponding pixel in the image is
counted. If 0, the corresponding pixel in the image is
ignored (in all results). See note (3).
/VERBOSE causes routine to tell you what stage it's at. See note (1).
COMMON BLOCKS:
none
NOTES:
(1) If you aren't sure you've set up right, use the /verbose keyword,
because the routine is fairly slow.
(2) For a surface brightness profile, plot totdif/npixdif vs. radii.
For an aperture growth curve, plot tot vs. radii.
(3) Mask is intended to mask out stars or garbage. Depending on your
application, you might be better off modifying the input image.
SIDE EFFECTS: none
PROCEDURE: Similar to IDL/UIT/DAOPHOT aperture routine.
MODIFICATION HISTORY:
Integrate in circular aperture.
RSH - STX - 20 Aug 1990
Modified to ignore some pixels according to mask image.
RSH - STX - 19 Sept 90
Totals done for annuli rather than discs.
RSH - STX - 20 Sept 90
Use of mask corrected. RSH - STX - 27 Sept 90
Small change to conserve array space. RSH - STX - 5 Nov 90
Fractional-pixel approximation adopted from Wayne Landsman's version
of DAOPHOT APER. Annuli computed from discs. RSH - STX - 17 July 91
Annuli divided into octants for subsequent error estimate due to random
distribution of sources. RSH - STX - 22 July 91
Several bugs fixed. RSH - STX - 3 Oct 91
Spiffed up for UIT IDL library. RSH - Hughes STX - 11 June 92
Speeded up initializaion. RSH - HSTX - 5 August 1993
Minor change to allow a scalar radius. JWmP - HSTX - 1995 May 12
Speeded up by computing totals for annuli rather than discs. F.V. - 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/circint.pro)
COLOR_MAP_LOAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_map_Load
PURPOSE:
Apply pixel value to color index mapping, and load color tables.
Pixel value zero is always mapped to color # zero,
and max value mapped to color # Lastcolor,
Mapping is saved in common adjct_map, cmap.
CALLING:
color_map_Load, color_map, Lastcolor, /RELOAD
INPUTS:
color_map = array of indices, mapping pixel values to color numbers.
Lastcolor = optional, specifies last color index to use.
(default Lastcolor = !D.table_size-1)
KEYWORDS:
/RELOAD just uses previous mapping from common adjct_map, cmap
so that input color_map is ignored.
EFFECTS:
R_orig, G_orig, B_orig is mapped to R_curr, G_curr, B_curr,
the common adjct_map, cmap, is updated,
the new color table and mapping is applied to window system (tvlct).
COMMON BLOCKS:
common colors, R_orig, G_orig, B_orig, R_curr, G_curr, B_curr
common adjct_map, cmap
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_map_load.pro)
COLOR_RESTORE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_restore
PURPOSE:
Restore RGB_MAP structure variable from an IDL save file
and then load the color table and mapping.
If variable not in file then assume old type with .
CALLING:
color_restore, file_name
INPUTS:
file_name = string, name of IDL save file containing variable: colors.
EFFECTS:
Color table of frame buffer is modified (using TVLCT).
EXTERNAL CALLS:
pro color_st_Load
COMMON BLOCKS:
common colors, ro,go,bo, rc,gc,bc
common adjct_map, color_map
common adjct_ramp, rampx, rampy
common color_options, ct_map_reset, ct_feedback
common color_table1, table_name
HISTORY:
Written, Frank Varosi NASA/GSFC 1991
(code from pro color_tables, first written 1989).
F.V.1997, interpolate the old rc,gc,bc color arrays if needed.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_restore.pro)
COLOR_SAVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_save
PURPOSE:
Save RGB table and mapping as an IDL save file,
into subdirectory called "colors", or current directory.
CALLING:
color_save, filsav
INPUTS:
filsav = string, the name of file in which to save RGB table-mapping,
(default = "current"), and ".rgb" is added at end of name.
EFFECTS:
File containing color-table-structure is created as "filename.rgb",
in subdirectory "colors" if it exists, else in current directory.
EXTERNAL CALLS:
pro find_dir
pro color_struct
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1990, save as structure given by function color_struct.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_save.pro)
COLOR_SCALE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_scale
PURPOSE:
Display a color bar with numerical scale in its own window,
or optionally in some other window (see tvs.pro for example).
CALLING:
color_scale, minvalue, maxvalue, topval, scale_type, title
INPUTS:
minvalue = min value (bottom) of scale.
maxvalue = max value (top) of scale.
topval = # of colors used in table, default is !D.table_size-2 .
scale_type = string: LINEAR or LOG10, default is do nothing.
title = string.
KEYWORDS:
LOGMIN = number greater than zero.
POSITION = default is [440,100]
/LARGE
WINDOW = optional window # to display color bar (at POSITION=).
OUTPUTS:
No explicit outputs.
A new window is created in which color bar with scale is displayed,
or if keyword WINDOW=win then color bar and scale are display in win.
COMMON BLOCKS:
common color_scale, xpos, ypos, scale_window, colorbar, region
SIDE EFFECTS:
A window is created and then kept for next display of color scale.
PROCEDURE:
Straightforward.
HISTORY:
written, Frank Varosi NASA/GSFC 1989.
F.V. 1996, fixed bugs, improved, added WINDOW keyword (used by pro tvs).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_scale.pro)
COLOR_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_struct
PURPOSE:
Save current info about color Lookup tables and ADJCT mapping
into structure {RGB_MAP} and return it.
Info in structure {RGB_MAP} can then be saved with pro color_save,
or used to Load color Lookup tables by calling pro color_St_Load.
CALLING:
colors = color_struct( name )
INPUTS:
name = optional string to name the color table (default is null).
RESULT:
Returns structure {RGB_MAP}, containing all color table and
mapping information. Saves a max of 256 colors.
COMMON BLOCKS:
common colors, Rorig,Gorig,Borig, Rcur,Gcur,Bcur
common adjct_map, color_map
common adjct_ramp, rampx, rampy
common color_struct, defined
PROCEDURE:
Define the structure and insert current color table mapping.
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_struct.pro)
COLOR_ST_LOAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_St_Load
PURPOSE:
Use info in structure {RGB_MAP} to Load color Lookup tables.
Intended to work with result of function color_struct.
CALLING:
color_St_Load, color_st
INPUTS:
color_st = scalar structure variable having structure {RGB_MAP},
containing all color table and mapping information.
(as returned by function color_struct).
KEYWORDS:
/RESET : the ADJCT mapping is reset to be one-to-one.
EFFECTS:
The common colors, Rorig,Gorig,Borig, loaded with table from color_st,
the common adjct_map, color_map, is loaded with mapping from color_st,
the common adjct_ramp, rampx, rampy, is set with saved ramp-map,
the new color table and mapping is applied to window system.
EXTERNAL CALLS:
pro color_map_Load
COMMON BLOCKS:
common colors, Rorig,Gorig,Borig, Rcur,Gcur,Bcur
common adjct_map, color_map
common adjct_ramp, rampx, rampy
PROCEDURE:
Interpolate if color_st.Ncolor is different from !D.table_size.
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_st_load.pro)
COLOR_TABLES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_tables
PURPOSE:
Provide interactive menu choice access to all IDL color table options.
CALLING:
color_tables, caller
INPUTS:
caller = string (optional), to indicate in menu what to return to.
KEYWORDS (all optional):
IMAGE_WINDOW = window number in which data or image is displayed.
INFO_WINDOW = window number in which to write information & instructs.
INIT_SEL = initial menu selection desired.
MENU_WINDOW = for SunView only, window number associated with menu.
EFFECTS:
New color tables and/or mappings are applied to window system.
EXTERNAL CALLS:
pros: adjCTmap color_edit palette
color_map_Load color_save color_restore Hist_Equal_CT
function VarType
function wmenux
COMMON BLOCKS:
common adjCT_map, color_map
common adjCT_ramp, rampx, rampy
common color_options, CT_map_reset, CT_feedback
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V.1990, work with adjCTmap and Hist_Equal_CT using common blocks.
F.V.1991, use RGB_Map structure given by function color_struct.
F.V.1995, mod for IDLv4 change of colors1.tbl location.
F.V.1996, use Varosi's wmenux instead of old IDL instrinsic wmenu.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_tables.pro)
COLOR_TRANS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
color_trans
PURPOSE:
Apply linear transform (matrix) to current RGB color table
and Load result (with tvlct).
CALLING:
color_trans, transform
INPUTS:
transform = square matrix, size N_colors-1 by N_colors-1 elements.
EFFECTS:
Color tables are updated.
COMMON BLOCKS:
common colors, ro,go,bo, rc,gc,bc
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/color_trans.pro)
COMPARE_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
compare_struct
PURPOSE:
Compare all matching Tags names (except for "except_Tags")
between two structure arrays (may be different struct.defs.),
and return a structured List of tags found different.
CATEGORY:
Structures
CALLING:
diff_List = compare_struct( struct_A, struct_B )
INPUTS:
struct_A, struct_B : the two structure arrays to compare.
Struct_Name : for internal recursion use only.
KEYWORDS:
EXCEPT = string array of Tag names to ignore (NOT to compare).
/BRIEF = number of differences found for each matching tag
of two structures is printed while executing.
/FULL = option to print even if zero differences found.
/RECUR_A = option to search for Tag names in sub-structures of struct_A,
then call compare_struct recursively for those sub-structures.
/RECUR_B = search for sub-structures of struct_B, and then
call compare_struct recursively for those nested sub-structures.
Note:
compare_struct is automatically called recursively
for those sub-structures that are in both struct_A and struct_B
and have matching names (otherwise cannot take difference).
OUTPUT:
Returns a structure array describing differences found,
which can be examined by the following examples:
help,/st, diff_List.
print, diff_List
print_struct, diff_List
print_struct, compare_struct( struct_A, struct_B )
PROCEDURE:
Match Tag names and then use where function on tags.
HISTORY:
written: 1990 Frank Varosi STX @ NASA/GSFC (based on copy_struct)
modif Aug.90 by F.V. to check and compare same # of elements only.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/compare_struct.pro)
CONVOL3D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
CONVOL3D
PURPOSE:
Convolution or correlation of two 3D arrays (volumetric data),
or autocorrelation of a single 3D array.
Default is to compute using product of Fourier transforms.
CALLING SEQUENCE:
imconv = convol3d( voldata, psf, FT_PSF = psf_FT )
or:
correl = convol3d( voldata1, voldata2, /CORREL )
or:
correl = convol3d( voldata, /AUTO )
INPUTS:
voldata = 3-D array to be convolved with PSF.
psf = the 3-D array Point Spread Function,
with size < or = to size of voldata.
KEYWORDS:
FT_PSF = passes out/in the Fourier transform of the PSF,
(so that it can be re-used the next time function is called).
FT_VOLDATA = passes out/in the Fourier transform of voldata.
/CORRELATE uses the conjugate of the Fourier transform of PSF,
to compute the cross-correlation of voldata and PSF,
(equivalent to IDL function convol() with NO rotation of PSF).
/AUTO_CORR computes the auto-correlation function of voldata using FFT.
/NO_FT overrides the use of FFT, using IDL function convol() instead.
(then PSF is rotated by 180 degrees to give same result)
METHOD:
When using FFT, PSF is centered & expanded to size of voldata.
Basically a copy of function convolve modified from 2D to 3D.
HISTORY:
written, Frank Varosi, NASA/GSFC 1997,
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/convol3d.pro)
CONVOLVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
CONVOLVE
PURPOSE:
Convolution of an image with a Point Spread Function (PSF),
or correlation two images, or autocorrelation of an image.
Default is to compute using product of Fourier transforms.
CALLING SEQUENCE:
imconv = convolve( image, psf, FT_PSF = psf_FT )
or:
correl = convolve( image1, image2, /CORREL )
or:
correl = convolve( image, /AUTO )
INPUTS:
image = 2-D array (matrix) to be convolved with PSF.
psf = the Point Spread Function, with size < or = to size of image.
KEYWORDS:
FT_PSF = passes out/in the Fourier transform of the PSF,
(so that it can be re-used the next time function is called).
FT_IMAGE = passes out/in the Fourier transform of image.
/CORRELATE uses the conjugate of the Fourier transform of PSF,
to compute the cross-correlation of image and PSF,
(equivalent to IDL function convol() with NO rotation of PSF).
/AUTO_CORR computes the auto-correlation function of image using FFT.
/NO_FT overrides the use of FFT, using IDL function convol() instead.
(then PSF is rotated by 180 degrees to give same result)
METHOD:
When using FFT, PSF is centered & expanded to size of image.
HISTORY:
written, Frank Varosi, NASA/GSFC 1992.
F.V.1993, added one to shift for case of odd size of image.
F.V.1997, change in 93 was not exactly correct, instead:
when PSF size is less than image size, fixed placement
of PSF relative to image, for case of odd size of image.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/convolve.pro)
CONV_ASCII_TIME
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
conv_ascii_time
PURPOSE:
Convert time strings of form 'hh:mm:ss' into seconds (32-bit).
CALLING:
seconds = conv_ascii_time( times, dates )
INPUTS:
time_strings = string array in form "hh:mm:ss".
date_strings = string array in form "mm/dd/yy" or "dd-mmm-yy"
LIMITATIONS:
If dates have different month or year the relative times will be wrong.
OUTPUTS:
Function results is seconds relative to begining of month.
HISTORY:
Written, Frank Varosi NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/conv_ascii_time.pro)
CONV_VARTYPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
conv_vartype
PURPOSE:
Convert input variable to specified other type.
CALLING:
cvar = conv_vartype( variable, TYPE_CODE_OUT=type_out )
INPUTS:
variable = array, the variable to be converted.
KEYWORDS:
TYPE_CODE_OUT = the desired type code of returned array.
OUTPUTS:
Returns array of converted data.
HISTORY:
Written, Frank Varosi NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/conv_vartype.pro)
CONV_VAX_UNIX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
CONV_VAX_UNIX
PURPOSE:
To convert VAX IDL data types to UNIX (Sun,MIPS,etc.) IDL data types.
The architecture is obtained from IDL sys.var. !VERSION.ARCH.
(Derived from the IUE procedure VAX2SUN)
CALLING SEQUENCE:
var_unix = conv_vax_unix( var_vax )
PARAMETERS:
variable (REQ) (IO) (BIFDC) (012)
The data variable to be converted. This may be a scalar
or an array. All IDL datatypes are valid (including structures).
The result of the conversion is returned by the function.
KEYWORD:
TARGET_ARCH = name (string) of desired target architecture
if using this function on a VAX.
otherwise !VERSION.ARCH is used to determine the conversion.
EXAMPLE:
Read a 100 by 100 matrix of floating point numbers from a data
file created on a VAX. Then convert the matrix values into Sun format.
IDL> openr,1,'vax_float.dat'
IDL> data = fltarr(100,100)
IDL> readu,1,data
IDL> data = conv_vax_unix( data )
MODIFICATION HISTORY:
Written F. Varosi August 1990
Modified P. Keegstra April 1992
Implemented MIPSEL architecture
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/conv_vax_unix.pro)
COPY_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
copy_struct
PURPOSE:
Copy all fields with matching tag names (except for "except_Tags")
from one structure array to another structure array of different type.
This allows copying of tag values when equating the structures of
different types is not allowed, or when not all tags are to be copied.
Can also recursively copy from/to structures nested within structures.
Note that the number of elements in the output structure array
is automatically adjusted to equal the length of input structure array.
If this not desired then use pro copy_struct_inx which allows
specifying via subscripts which elements are copied where in the arrays.
CATEGORY:
Structures
CALLING EXAMPLES:
copy_struct, struct_From, struct_To, NT_copied
copy_struct, struct_From, struct_To, EXCEPT=["image","misc"]
copy_struct, struct_From, struct_To, /RECUR_TANDEM
INPUTS:
struct_From = structure array to copy from.
struct_To = structure array to copy values to.
KEYWORDS:
EXCEPT_TAGS = string array of tag names to ignore (to NOT copy).
Used at all levels of recursion.
SELECT_TAGS = tag names to copy (takes priority over EXCEPT).
This keyword is not passed to recursive calls in order
to avoid the confusion of not copying tags in sub-structures.
/RECUR_FROM = search for sub-structures in struct_From, and then
call copy_struct recursively for those nested structures.
/RECUR_TO = search for sub-structures of struct_To, and then
call copy_struct recursively for those nested structures.
/RECUR_TANDEM = call copy_struct recursively for the sub-structures
with matching Tag names in struct_From and struct_To
(for use when Tag names match but sub-structure types differ).
OUTPUTS:
struct_To = structure array to which new tag values are copied.
NT_copied = incremented by total # of tags copied (optional)
INTERNAL:
Recur_Level = # of times copy_struct calls itself.
This argument is for internal recursive execution only.
The user call is 1, subsequent recursive calls increment it,
and the counter is decremented before returning.
The counter is used just to find out if argument checking
should be performed, and to set NT_copied = 0 first call.
EXTERNAL CALLS:
pro match (when keyword SELECT_TAGS is specified)
PROCEDURE:
Match Tag names and then use corresponding Tag numbers.
HISTORY:
written 1989 Frank Varosi STX @ NASA/GSFC
mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY.
mod Aug.90 by F.V. adjust # elements in TO (output) to equal
# elements in FROM (input) & count # of fields copied.
mod Jan.91 by F.V. added Recur_Level as internal argument so that
argument checking done just once, to avoid confusion.
Checked against Except_Tags in RECUR_FROM option.
mod Oct.91 by F.V. added option SELECT_TAGS= selected field names.
mod Aug.95 by W. Landsman to fix match of a single selected tag.
mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion.
F.V.1999, correctly handle copying tag arrays of different # elements.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/copy_struct.pro)
COPY_STRUCT_INX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
copy_struct_inx
PURPOSE:
Copy all fields with matching tag names (except for "except_Tags")
from one structure array to another structure array of different type.
This allows copying of tag values when equating the structures of
different types is not allowed, or when not all tags are to be copied.
Can also recursively copy from/to structures nested within structures.
This procedure is same as copy_struct with option to
specify indices (subscripts) of which array elements to copy from/to.
CATEGORY:
Structures
CALLING EXAMPLES:
copy_struct_inx, struct_From, struct_To, NT_copied, INDEX_FROM=subf
copy_struct_inx, struct_From, struct_To, INDEX_FROM=subf, INDEX_TO=subto
INPUTS:
struct_From = structure array to copy from.
struct_To = structure array to copy values to.
KEYWORDS:
INDEX_FROM = indices (subscripts) of which elements of array to copy.
(default is all elements of input structure array)
INDEX_TO = indices (subscripts) of which elements to copy to.
(default is all elements of output structure array)
EXCEPT_TAGS = string array of Tag names to ignore (to NOT copy).
Used at all levels of recursion.
SELECT_TAGS = Tag names to copy (takes priority over EXCEPT).
This keyword is not passed to recursive calls in order
to avoid the confusion of not copying tags in sub-structures.
/RECUR_FROM = search for sub-structures in struct_From, and then
call copy_struct recursively for those nested structures.
/RECUR_TO = search for sub-structures of struct_To, and then
call copy_struct recursively for those nested structures.
/RECUR_TANDEM = call copy_struct recursively for the sub-structures
with matching Tag names in struct_From and struct_To
(for use when Tag names match but sub-structure types differ).
OUTPUTS:
struct_To = structure array to which new tag values are copied.
NT_copied = incremented by total # of tags copied (optional)
INTERNAL:
Recur_Level = # of times copy_struct_inx calls itself.
This argument is for internal recursive execution only.
The user call is 1, subsequent recursive calls increment it,
and the counter is decremented before returning.
The counter is used just to find out if argument checking
should be performed, and to set NT_copied = 0 first call.
EXTERNAL CALLS:
pro match (when keyword SELECT_TAGS is specified)
PROCEDURE:
Match Tag names and then use corresponding Tag numbers,
apply the sub-indices during = and recursion.
HISTORY:
adapted from copy_struct: 1991 Frank Varosi STX @ NASA/GSFC
mod Aug.95 by F.V. to fix match of a single selected tag.
mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion,
and check validity of INDEX_FROM and INDEX_TO in more detail.
F.V.1999, correctly handle copying tag arrays of different # elements.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/copy_struct_inx.pro)
CORREL_IMAGES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
correl_images
PURPOSE:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting of one image relative to the other.
Optimal (x,y)-offsets can then be found using pro CorrMat_Analyze.
CALLING:
corrmat = correl_images( image_A, image_B )
INPUTS:
image_A, image_B = the two images to be cross-correlated,
image_B is shifted relative to image_A.
KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with pro CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution
correlation of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using pro CorrMat_Analyze.
/NUMPIX causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, then function result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, returned as a matrix.
EXTERNAL CALLS:
function round_off( number ) to round off fractions.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
HISTORY:
Written: Frank Varosi, NASA/GSFC, 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/correl_images.pro)
CORREL_OPTIMIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
correl_optimize
PURPOSE:
Assuming the images are two detections of the same scene,
find the optimal (x,y) pixel offset of image_B relative to image_A,
by means of maximizing the cross-correlation function.
Note that bad pixels or extremely noisy data will bias the
cross-correlation function and give possibly erroneous results.
Small amount of noise is no problem, pre-filtering is recommended,
returned variable max_correl can be used to decide validity.
Cross-correlation is computed directly by default, but if
keyword /FFT is set it will be computed using FFTs of images.
CALLING:
correl_optimize, image_A, image_B, xoffset_optimum, yoffset_optimum
INPUTS:
image_A, image_B = the two images to be analyzed, the offset of
image_B relative to image_A is determined.
KEYWORDS:
XOFF_INIT = initial X pixel offset of image_B relative to image_A,
YOFF_INIT = Y pixel offset, (default offsets are 0 and 0).
MAX_REDUCTION = maximum reduction factor allowed, otherwise
the first reduction rebins image into about 8 x 8 pixels.
MAGNIFICATION = option to determine offsets up to fractional pixels,
(example: MAG=2 means 1/2 pixel accuracy, default=1).
/NUMPIX : (# overlap pixels)^(1/4) used as correlation weighting factor.
/MONITOR causes the progress of computation to be briefly printed.
/PRINT causes the results of analysis to be printed to standard output.
/FFT : use FFT to compute correlation of images, usually faster,
but may not be always accurate because periodic nature of FT
may cause confusion (in this case /NUMPIX has no effect).
But if data is well inside image boundaries it is accurate.
OUTPUTS:
xoffset_optimum = optimal X pixel offset of image_B relative to image_A.
yoffset_optimum = optimal Y pixel offset.
max_correl = the maximal correlation corresponding to optimal offset.
edge = 1 if maximum is at edge of correlation domain, otherwise=0.
plateau = 1 if maximum is in a plateau of correlation function, else=0.
EXTERNAL CALLS:
function correl_images( image_A, image_B )
function convolve( image_A, image_B,/CORREL ) if /FFT is set.
pro corrmat_analyze
IDL system variable !DEBUG should be defined.
PROCEDURE:
The combination of function correl_images( image_A, image_B ) and
pro corrmat_analyze is used to obtain the (x,y) offset
yielding maximal correlation. The combination is first executed at
large REDUCTION factor (to speed up computation) and with
all possible shifts to find the approximate optimal (x,y) offsets.
The reduction factor is then decreased by factors of 2 and
the x & y shifts are kept small, thus zooming into the optimal offsets.
Finally, the MAGNIFICATION option (if specified)
is executed to determine the (x,y) offset up to fractional pixels.
If /FFT is set then just use function convolve( image_A,image_B,/CORR )
and pro corrmat_analyze to obtain the optimal (x,y) offset,
rebinning the images first if magnification is greater than one.
NOTES:
Recommend that the images be normalized so that maximim=1,
and thresholded at some uniform percent of max=1.
See for example function modify_image.
HISTORY:
Written: Frank Varosi, NASA/GSFC, 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/correl_optimize.pro)
CORRMAT_ANALYZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
corrmat_analyze
PURPOSE:
Analyze the 2-D cross-correlation function of two images
and find the optimal (x,y) pixel offsets.
Intended to analyze to result of function CORREL_IMAGES,
and called by pro CORREL_OPTIMIZE.
CALLING:
corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, [...]
INPUTS:
correl_mat = cross-correlation matrix of 2 images.
(as computed by function CORREL_IMAGES( imA, imB ) or
function CONVOLVE( imA, imB, /CORREL ) ).
NOTE:
If correl_mat(*,*,1) is the number of pixels for each correlation,
(the case when /NUMPIX was specified in call to CORREL_IMAGES)
then (# overlap pixels)^(1/4) is used as correlation weighting factor.
KEYWORDS:
XOFF_INIT = initial X pixel offset of image_B relative to image_A.
YOFF_INIT = Y pixel offset, (both as specified to correl_images).
REDUCTION = reduction factor used in call to CORREL_IMAGES.
MAGNIFICATION = magnification factor used in call to CORREL_IMAGES,
this allows determination of offsets up to fractions of a pixel.
PLATEAU_THRESH = threshold used for detecting plateaus in
the cross-correlation matrix near maximum, (default=0.01),
used only if MAGNIFICATION > 1
/PRINT causes the result of analysis to be printed.
OUTPUTS:
xoffset_optimum = optimal X pixel offset of image_B relative to image_A.
yoffset_optimum = optimal Y pixel offset.
max_correl = the maximal correlation corresponding to optimal offset.
edge = 1 if maximum is at edge of correlation domain, otherwise=0.
plateau = 1 if maximum is in a plateua of correlation function, else=0.
EXTERNAL CALLS:
function round_off( number ) to round off fractions.
IDL system variable !DEBUG should be defined.
PROCEDURE:
Find point of maximum cross-correlation and calc. corresponding offsets.
If MAGNIFICATION > 1:
the correl_mat is checked for plateau near maximum, and if found,
the center of plateau is taken as point of maximum cross-correlation.
HISTORY:
Written: Frank Varosi, NASA/GSFC, 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/corrmat_analyze.pro)
CUBIC_ZEROS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
cubic_zeros
PURPOSE:
Attempt to implement Cardano's formula for the zero solutions
of a cubic equation. Presently written to solve reduced form,
with parameters input by keywords: x^3 + px + q
CALLING:
INPUTS:
KEYWORDS:
OUTPUTS:
PROCEDURE:
Not yet finished. Must handle more special cases.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1998.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/cubic_zeros.pro)
CURSOR_SCALE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
cursor_scale
PURPOSE:
Interactively select min-max on a color bar using mouse-cursor,
or input range/levels by typing.
CALLING:
range = cursor_scale( minval, maxval, scaling )
INPUTS:
minval, maxval, scaling
KEYWORDS:
MAXLIM=
MINLIM=
INITIAL_MARKS=
LOGMIN=
/INCREMENT
OUTPUTS:
mosaic_spec, NLev, Levels
EXTERNAL CALLS:
pro color_scale
pro window_set_show
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
F.V. 1991, added keyword /INCREM to enter Min & Increment.
F.V. 1993, modified /INCREM option to get & return sequece of Levels.
F.V. 1997, added 0.3 sec wait before cursor query.
F.V. 1997, added option to read contours from a file (*.levels).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/cursor_scale.pro)
CW_DRAW_AXES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
CW_Draw_Axes
PURPOSE:
This compound widget merges a central scrolling draw widget,
for displaying an image or some user defined graphics,
with two smaller scrolling draw widgets for the X and Y axes
of the image/graphics. The scroll bars of all the draw widgets
are ganged so that moving any one will move the others, thus
all viewport events are swallowed. Button events in the X & Y axes
draw widgets cause all viewports to scroll and are then swallowed.
All motion/button events occuring in the central draw widget
are reported to the parent or higher level widgets.
CATEGORY:
Compound widgets.
CALLING:
Widget = CW_Draw_Axes( Parent )
INPUTS:
Parent = the ID of the parent widget.
If not specified, a base is created just for this widget.
KEYWORDS:
RETAIN: Controls the setting for backing store for both windows.
If backing store is provided, a window which was obscured
will be redrawn when it becomes exposed. Set RETAIN=0 for
no backing store. Set RETAIN=1 to "request backing store
from server" (this is the default). Set RETAIN=2 for IDL
to provide backing store.
/FRAME: causes frame to be drawn around the widget,default is no frame.
UVALUE = the user value for the widget.
SIZE_XY = two integer array specifying the width and height of
the draw window (in pixels), default = [ 2048, 2048 ].
SCROLL_SIZE_XY = two integer array specifying the width and height of
the visible part of the draw window, default =[512,512].
OUTPUTS:
The ID of the created widget is returned (widget is not realized).
PROCEDURE:
WIDGET_CONTROL, id, SET_VALUE=value
can be used to change the display.
Action depends on the "value" variable type:
string: name of user provided procedure to be called.
The argument passed to procedure is that state of CW,
which has window numbers and other info, so that
graphics can be directed into the draw widgets.
two integers: sets all draw viewports to the (x,y) specified.
single integer equaling zero: erases all 3 draw windows.
image (matrix): it is displayed in central draw window.
structure: tags should be handles pointing to images which are
then displayed in central, x-axis, y-axis windows, resp.
WIDGET_CONTROL, id, GET_VALUE=state
can be used to obtain the state (structure var.) of widget.
HISTORY:
written: Frank Varosi 1994 HSTX @ NASA/GSFC.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/cw_draw_axes.pro)
DATATYPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DATATYPE
PURPOSE:
Returns data type as a string. Makes it easier to do
data type dependent operations.
CALLING SEQUENCE:
TYP = DATATYPE(VAR, [FLAG])
INPUTS:
VAR = a variable.
[FLAG] = Output format flag: 0 (def) gives 3 char type, else
type is spelled out.
OUTPUTS:
TYP = a string indicating the data type of VAR.
TYP is 3 char upper case: UND, STR, BYT, INT, FLO, LON, DOU, COM
unless FLAG = 1 (non-zero).
Procedure:
Uses the SIZE function to determine the datatype.
MODIFICATION HISTORY:
Written by R. Sterner, 29 June, 1988.
Johns Hopkins University Applied Physics Laboratory.
Modified for version 2 IDL B. PFarr, STX, 27 Jan, 1990.
Structures added. M. Greason, STX, 14 August 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/datatype.pro)
DDL_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DDL_struct
PURPOSE:
Convert a DDL record-structure definition file
into IDL structure(s) code, packaged as a function.
CATEGORY:
Structures
CALLING SEQUENCE:
status = DDL_struct( DDL="DDL_name", /ABBREV,/TRUNC,VARIANT=# )
examples:
print, ddl_struct( ddl="FDQ_SDF", /ABBREV, /TRUNC )
print, ddl_struct( ddl="BET_LT_ET", VARIANT=2 )
INPUTS/OUTPUTS:
keywords:
DDL_NAME = string giving DDL file name (type .DDL is assumed )
optional:
/ABBREV performs Field name abbreviations as defined
by DDL_abbrev.pro
VARIANT = variant number to choose for structure definition,
(default variant = 1)
/TRUNC causes the output file name (not including .PRO)
to be truncated to 15 characters,
so IDL will compile it automatically when invoked.
inputs used recursively:
DDL_Lun = Logical unit number for reading DDL file.
Lun_out = Logical unit number for writing .PRO code.
ABBREV = keyword to indicate use of abbreviations.
VARIANT = variant number to choose for structure definition.
function returns a string which is not important to user
(it is just the final return from chain of recursion).
SIDE EFFECTS:
"DDL_name".DDL file is read,
"DDL_name"_struct.PRO is created (IDL function code).
PROCEDURE:
The DDL file (given by "DDL_name".DDL) is read one line at a time,
if declaration STRUCTURE is encountered,
then DDL_struct is called recursively,
obtaining the complete IDL structure definition,
which is then printed to file "DDL_name"_struct.pro ,
otherwise the field type and size is used to construct IDL definition,
(calling DDL_abbrev,Tag_Name for name abbreviations if /ABBREV),
which is then concatenated with the other IDL definitions,
and returned when declaration END STRUCTURE is encountered in DDL file.
EXTERNAL CALLS:
pro DDL_ABBREV (should be in same directory)
function GET_WORDS (from [varosi.idl.lib]VAROSI.TLB)
MODIFICATION HISTORY:
written June,1990 Frank Varosi STX @ NASA/GSFC
modif. Aug.1990 by F.V. to process field variants in DDL.
modif. Sep.1990 by F.V. to handle multi-dimensional array declarations,
and option to truncate filename to 15 chars.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/ddl_struct.pro)
DDL_TO_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
create IDL function code which defines record structure for DATASET.
check for DDL file (describing DATASET) and invoke DDL_STRUCT function.
Frank Varosi Sep.1990
check if IDL structure definition code exists?
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/ddl_to_struct.pro)
DIR_GENERIC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
dir_generic
PURPOSE:
Convert string specifying a subdirectory into a string array
of sub-directories which determine a path in generic fashion.
(result is thus independent of operating systems).
CALLING:
direct_array = dir_generic( directory )
INPUT:
directory = string, full name of directory.
OUTPUT:
Function returns string array giving a path of sub-directories,
which do not include the OS specific syntax for directories,
that is, leaving out the "/" or ".".
EXTERNAL CALLS
function get_words
HISTORY:
Written, Frank Varosi NASA/GSFC 1994.
F.V. 1995, handle case for MacOS and Win32.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/dir_generic.pro)
DIR_PATH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
dir_path
PURPOSE:
Construct and return a string specifying a directory (with OS syntax)
from a string array of sub-directories (with no OS syntax)
which determine a path in generic fashion, thus independent of OS.
CALLING:
directory = dir_path( direct_array, dir_delim )
INPUT:
direct_array = string array giving a path of sub-directories, which
upon concatenation specifies the subdirectory.
(default is current directory).
Do not include the operating system specific syntax for
directories, that is, leave out the "/" or ".",
they are automatically added depending on op.sys.
Leading & trailing blanks are trimmed, default ="".
OUTPUT:
dir_delim = optional, string used to delimit (end) the directory name.
(this is "]" on VMS, otherwise uses "/" on UNIX, etc.).
Function returns string specifying the directory on current OS.
EXTERNAL CALLS:
function strconcat
HISTORY:
Written: Frank Varosi NASA/GSFC 1989.
F.V. 1994, simplified by using function strconcat.
F.V. 1995, handle case for MacOS and Win32.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/dir_path.pro)
DISK_REGION
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Disk_Region
PURPOSE:
Function returns a matrix of 0 and 1, 1 indicating the inside of circle.
CALLING:
disk_mask = Disk_Region( center, SIZE=sz, RADIUS=radius, COUNT=npix )
INPUTS:
center =
KEYWORDS:
SIZE =
RADIUS =
COUNT =
OUTPUTS:
PROCEDURE:
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1997.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/disk_region.pro)
DISPLAY_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
display_image
PURPOSE:
Display the visible portion of an image in window.
CALLING:
display_image, image, x,y
INPUTS:
image =
x,y =
HISTORY:
Written: Frank Varosi NASA/GSFC 1989.
F.V. 1991, added option (xmax,ymax) to display just central subset
of image, (so that edge regions of image are not displayed).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/display_image.pro)
DL_VMS2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DL_VMS2
PURPOSE:
Extract the documentation template of one or more procedures.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
DL_VMS2 ;For prompting.
DL_VMS2, Name ;Extract documentation for procedure Name using
the current !PATH.
INPUTS:
Name: A string containing the name of the procedure.
KEYWORDS:
FILE: If this keyword is set, the output is sent to the file
"userlib.doc", in the current directory.
PRINT: If set, this keyword sends the output of DL_VMS2 to lpr.
PATH: An optional directory/library search path. This keyword uses
the same format and semantics as !PATH. If omitted, !PATH is
used.
OUTPUTS:
Documentation is output to terminal or printer.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Output is produced on terminal or printer.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward.
MODIFICATION HISTORY:
Written, DMS, Sept, 1982.
Added library param, Jul 1987.
Unix version, Feb, 1988.
Revised for VMS Version 2, 15 December 1989
Modified by Jim Pendleton, GRO/OSSE NU, July 30, 1992 to handle
!PATH's gt 255 characters.
AB, 21 September 1992, renamed from DOC_LIB_VMS to DL_VMS2 to
avoid DOS filename limitations.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/dl_vms2.pro)
DOC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DOC
PURPOSE:
Provides online documentation for IDL procedures found in the IDL
search path.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
DOC ;For prompting.
DOC, NAME ;Extract documentation for procedure NAME.
OPTIONAL INPUT PARAMETERS:
NAME = String containing the name of the procedure.
RESTRICTIONS:
None.
PROCEDURE:
Decides whether the graphics device supports X-windows widgets, in
which case it calls SCANPATH, else it calls DOC_LIBRARY.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/doc.pro)
DOC_LIB_UNIX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DOC_LIB_UNIX
PURPOSE:
Extract the documentation template of one or more procedures.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
doc_lib_unix ;For prompting.
doc_lib_unix, Name ;Extract documentation for procedure Name using
the current !PATH.
INPUTS:
Name = string containing the name of the procedure or "*" for all.
OPTIONAL INPUT PARAMETERS:
PRINT = keyword parameter which, if set to 1, sends output
of doc_lib_unix to lpr. If PRINT is a string, it is a shell
command used for output with its standard input the
documentation. I.e. PRINT="cat > junk"
DIRECTORY = directory to search. If omitted, use current directory
and !PATH.
MULTI = flag to allow printing of more than one file if the module
exists in more than one directory in the path + the current
directory.
OUTPUTS:
No explicit outputs. Documentation is piped through more unless
/PRINT is specified.
KEYWORDS:
OUT = redirected output of spawn command
COMMON BLOCKS:
None.
SIDE EFFECTS:
output is produced on terminal or printer.
RESTRICTIONS:
??
PROCEDURE:
Straightforward.
MODIFICATION HISTORY:
DMS, Feb, 1988.
DMZ, Oct 1992 -- added keyword to capture output
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/dl_unix2.pro)
DOC_MENU
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Doc_menu
PURPOSE:
Extract the documentation template of one or more procedures.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
Doc_menu ;For prompting.
Doc_menu, Name ;Extract documentation for procedure Name using
the current !PATH.
OPTIONAL INPUT PARAMETERS:
Name = string containing the name of the procedure.
Under Unix, Name may be "*" for all modules.
If Name is not passed, then Doc_menu will go into an interactive
mode to prompt the user for the directory or library to search, and
then for the routine to get information on.
KEYWORDS:
PRINT = keyword parameter which, if set to 1, sends output
of doc_menu to the default printer. Under Unix, if PRINT
is a string, it is a shell command used for output with
its standard input set to the documentation
(i.e. PRINT="cat > junk")
Unix KEYWORDS:
DIRECTORY = directory to search. If omitted, use current directory
and !PATH.
MULTI = flag to allow printing of more than one file if the module
exists in more than one directory in the path + the current
directory.
VMS KEYWORDS:
FILE - If present and non-zero, the output is left in the file
userlib.doc, in the current directory.
PATH = optional directory/library search path. Same format
and semantics as !PATH. If omitted, !PATH is used.
OUTPUTS:
Documentation is sent to the standard output unless /PRINT
is specified.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Output is produced on terminal or printer.
RESTRICTIONS:
The DIRECTORY and MULTI keywords are ignored under VMS. The
FILE and PATH keywords are ignored under Unix.
PROCEDURE:
If NAME is not passed, then this procedure will first display a list of
the directories in !PATH, and ask for the user to select one. Then a
list of procedures in the selected directory are displayed, and the
user is again asked to select one of them. Finally, the routine
DOC_LIB_xxx, where xxx represents the operating system, is called to
display the documentation in the file between the lines containing the
characters ";+" and ";-".
VMS text libraries can also be searched by this routine.
If a file named "aaareadme.txt" is also found in the selected
directory, then this can be selected as the topic "*INFO*".
MODIFICATION HISTORY:
Written, DMS, Sept, 1982.
Added library param, Jul 1987.
Unix version, DMS, Feb, 1988.
New VMS version, DMS, Dec. 1989
Wrapper procedure to call the correct version
under Unix and VMS, AB, Jan 1990
Added support for DOS, SNG, Dec, 1990
Added interactive capabilities, William Thompson, July 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/doc_menu.pro)
DOUBLE_TICKS
[Previous Routine]
[Next Routine]
[List of Routines]
Double the number of tick marks on an axis,
but Label only the current (assumed equally spaced, increasing).
Use to specify ![XYZ].TICKV
and to specify ![XYZ].TICKS
and to specify ![XYZ].TICKNAME
(thus every other major tick will be labeled, in between will be blank).
/NEG will reverse order of labels, so values will be descending.
Frank Varosi STX @ NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/double_ticks.pro)
DRAW_MARK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
draw_mark
PURPOSE:
Draw a mark of requested symbol and diameter on graphics device.
Default symbol is cross, which for X or SUN device
is composed of foreground cross over background (darker) cross.
By default the image data from marked area is first read
(unless /NOSAVE or area is not in a window)
and this saved image data is returned, and then symbol is drawn.
Diameter is in DEVICE coordinates (max diam of mark is 256 pixels).
CALLING:
imsav = draw_mark( xcur, ycur, diameter, xsave, ysave )
INPUTS:
xcur, ycur = desired location of mark, in device coordinates.
diameter = diameter of mark in DEVICE units (max diam is 256 pixels).
KEYWORDS:
SYMBOL = "circle", "box", "diamond", "cross", or "asterisk".
Default is "cross" with black around white center lines.
FORE_COLOR = center color of cross, default is white.
BACK_COLOR = border color of cross, default is black.
THICKNESS = thickness of lines drawing the mark,
this is always 1 (one) for window displays,
and default is 4 when drawing on PostScript (non windows).
/NOSAVE : default is save pixels in display that the mark overwrites.
Setting /NOSAVE skips this part, thus faster.
OUTPUTS:
xsave, ysave = the location of saved window region (if NOSAVE=0).
Funtion returns window pixel values from marked region, as read by TVRD,
or returns integer 1 if /NOSAVE.
EXTERNAL CALLS:
function rot2d
COMMON BLOCKS:
common draw_mark, Hmark, Vmark, Fcol, Bcol
common draw_marks, circle, box, diamond, cross, asterisk
PROCEDURE:
Call TV if windows and symbol = cross, else call PLOT.
HISTORY:
Written: Frank Varosi NASA/GSFC 1991.
F.V. 1991, added keyword /NOSAVE to skip the tvrd.
F.V. 1991, adapted for PostScript, added keywords SYMBOL & THICKNESS.
F.V. 1999, added print of help with syntax and MAGF keyword.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/draw_mark.pro)
EXPAND_PATH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EXPAND_PATH
PURPOSE:
Expands any logical names in an IDL search PATH (e.g. !PATH) into the
directories defined by that logical name. *** VMS only. ***
CALLING SEQUENCE:
Result = EXPAND_PATH(PATH)
INPUTS:
PATH = Valid IDL search path, e.g. !PATH.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The variable PATH must be in the proper format for !PATH.
PROCEDURE:
TRNLOG is called with the /FULL_TRANSLATION switch to translate the
logical names.
MODIFICATION HISTORY:
William Thompson
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/expand_path.pro)
EXPECT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
expect
PURPOSE:
Compute expectation (mean, first moment) of a probability distribution.
CALLING:
mean = expect( x, Px )
INPUTS:
x = array of independent variable values, strictly increasing.
Px = array of probability distribution values (positive) at points x.
KEYWORDS:
/EXP : integrate in Linear-Log space,
increases accuracy for exponentially varying functions.
/POW : integrate in Log-Log space,
increases accuracy for functions with power-law variation.
OUTPUTS:
Function returns scalar mean value of probability distribution.
EXTERNAL CALLS:
function Trap_Int
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1998.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/expect.pro)
EXTRACT_REGION
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
extract_region
PURPOSE:
Interactively extract a sub-region of image array, using mouse.
Optionally, sub-region can be specified by entering position & size.
To active this option, press the MIDDLE mouse button first, then
widget will appear into which region position & size can be typed.
CALLING:
imsub = extract_region( image )
INPUTS:
image = 2D array.
KEYWORDS:
VALUE_FILL = value to use in filling empty pixels of result, default=0.
SIZE_REGION = 2 integers, desired size of extracted region,
default is variable (interactive).
MAGNIFICATION = magification factor of displayed image.
WINDOW = IDL window number for displayed image.
WPOS_XY = 2 integers, position of displayed image in window coordinates.
/LIMIT_REGION : selection of region is limited to actual image size.
/ERASE_BOX : erase the region selection box upon completion (def=no).
/DISPLAY : automatically create a window and display the image.
/LOG10 : display ( image > 1 ) in Log base 10 scaling.
LOG10 = ( image > LOG10 ) is displayed in Log base 10 scaling.
KEYWORD OUTPUTS:
SIZE_REGION = 2 integers, actual size of extracted region.
START_XY = 2 integers, begining Location of extracted region.
LAST_XY = 2 integers, ending Location of extracted region.
OUTPUT:
Function returns the extracted image array,
which is a subset, or possibly an extension, of input image.
EXTERNAL CALLS:
pro get_window
pro box_cursor
function box_create
pro box_erase
COMMON BLOCKS:
common extract_region, xy_region ;saved position & size.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
F.V. 1994: options to fix sub-region and edit position & size.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/extract_region.pro)
EXT_FRAC_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
Extract a part of image specified up to fractional pixels
by resampling image on fractionally shifted grid, using REBIN twice.
( xbot:xtop , ybot:ytop ) is sub-image location in MAGNIFIED image
(virtual magnified grid coordinates),
thus performing fractional pixel extraction when MAGF=Magf > 1.
Sub-image is returned at normal magnification (=1).
Frank Varosi NASA/GSFC 1990
F.V. 1991, fixed bugs, use /SAMPLE for Magnify and averaging for De-Magnify.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/ext_frac_image.pro)
EXT_MOD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EXT_MOD
PURPOSE:
to extract modules from VMS libraries
CALLING SEQUENCE:
ext_mod,lib_nam,targ_dir
INPUTS:
lib_nam = name of source library
targ_dir = target directory of modules
HISTORY:
written Jan'93 by DMZ (ARC)
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/ext_mod.pro)
FACTOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FACTOR
PURPOSE:
Find prime factors of a given number.
CATEGORY:
CALLING SEQUENCE:
factor, x, p, n
INPUTS:
x = Number to factor. in
KEYWORD PARAMETERS:
OUTPUTS:
p = Array of prime numbers. out
n = Number of each element of p. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 4 Oct, 1988.
RES 25 Oct, 1990 --- converted to IDL V2.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/factor.pro)
FILTER_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
filter_image
PURPOSE:
Computes the average and/or median of pixels in moving box,
replacing center pixel with the computed average and/or median,
(using the IDL smooth or median functions).
The main reason for using this function is the options to
also process the pixels at edges and corners of image, and,
to apply iterative smoothing simulating convolution with Gaussian,
and/or to convolve image with a Gaussian kernel.
CALLING:
Result = filter_image( image, SMOOTH=box_width, /MEDIAN, /ALL )
INPUT:
image = 2-D array (matrix)
KEYWORDS:
SMOOTH = width of square box for moving average, in # pixels.
/SMOOTH means use box width = 3 pixels for smoothing.
MEDIAN = width of square moving box for median filter, in # pixels.
/MEDIAN means use box width = 3 pixels for median filter.
/ALL_PIXELS causes the edges of image to be filtered as well,
accomplished by reflecting pixels adjacent to edges outward.
/ITERATE : apply smooth(image,3) iteratively for a count of
[ (box_width-1)/2 = radius ] times, when box_width >= 5.
This is equivalent to convolution with a Gaussian PSF
of FWHM = 2 * sqrt( radius ) as radius gets large.
Note that /ALL_PIXELS is automatically applied,
giving better results in the iteration limit.
(also, MEDIAN keyword is ignored when /ITER is specified).
Can also specify FWHM = # pixels when using /ITER.
FWHM_GAUSSIAN = Full-width half-max of Gaussian to convolve with image.
FWHM can be a single number (circular beam),
or 2 numbers giving axes of elliptical beam.
However, if /ITERATE is set then convolution with a Gaussian
is approximated by iteration of smooth( image, 3 ).
/NO_FT_CONVOL causes the convolution to be computed directly,
with IDL function convol.
The default is to use FFT when factors of size are all LE 13.
(note that external function convolve handles both cases)
RESULT:
Function returns the smoothed, median filtered, or convolved image.
If both SMOOTH and MEDIAN are specified, median filter is applied first.
EXAMPLES:
To apply 3x3 moving median filter and
then 3x3 moving average, both applied to all pixels:
Result = filter_image( image, /SMOOTH, /MEDIAN, /ALL )
To iteratively apply 3x3 moving average filter for 4 = (9-1)/2 times,
thus approximating convolution with Gaussian of FWHM = 2*sqrt(4) = 4 :
Result = filter_image( image, SMOOTH=9, /ITER )
To convolve all pixels with Gaussian of FWHM = 3.7 x 5.2 pixels:
Result = filter_image( image, FWHM=[3.7,5.2], /ALL )
EXTERNAL CALLS:
function psf_gaussian
function convolve
pro factor
function prime ;all these called only if FWHM is specified.
PROCEDURE:
If /ALL_PIXELS or /ITERATE keywords are set then
create a larger image by reflecting the edges outward,
then call the IDL median and/or smooth function on the larger image,
and just return the central part (the orginal size image).
HISTORY:
Written, 1991, Frank Varosi, NASA/GSFC.
FV, 1992, added /ITERATE option.
FV, 1993, added FWHM_GAUSSIAN= option.
FV, 1999, option FWHM_GAUSSIAN=#pixels can be used with /ITER approx.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/filter_image.pro)
FIND_DIR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
find_dir
PURPOSE:
Check for existence of a sub-directory (independent of op.sys.)
and return the name with correct op.sys. syntax.
CALLING:
dirspec = find_dir( dir )
INPUT:
dir = string, the directory name to look for
do not specify wildcards (*) or op.sys. syntax.
KEYWORD:
/LINKS = assume all Links (UNIX only) are actually directories
and include them in the search.
OUTPUT:
Returns the directory name with appropriate op.sys. syntax ([] or /).
EXTERNAL CALLS:
function find_dirs
PROCEDURE:
Use function findfile in VMS, but otherwise use function find_dirs,
and then see if requested directory is in list.
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
F.V. 1994, handle case for MacOS and Win32.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/find_dir.pro)
FIND_DIRS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
find_dirs
PURPOSE:
Return a list of sub-directories (and links) in specified directory.
Can also wildcard search with specific characters in directory names.
CALLING EXAMPLE:
subdirs = find_dirs( dirspec, DIR=["data","images"], NDIR=Ndir )
INPUT:
dirspec = characters to look for in directory name (default = *),
do not specify wildcards (*) because
they are added automatically, ( search is on "*dirspec*" ).
KEYWORDS:
DIRECTORY_PATH = string array giving a path of directories, which
upon concatenation specifies the subdirectory to search.
(default is current directory).
Do not include the operating system specific syntax for
directories, that is, leave out the "/" and ".",
they are automatically added depending on op.sys.
NDIR = returned number of directories found (not including # Links)
/LINKS = assume all Links (UNIX only) are actually directories
and include them at the end of the List.
NLINK = number of Links found, if /LINKS was set.
OUTPUT:
Returns array of directory names (minus directory delimeters ] or /).
RESTRICTIONS:
Have not tested on Win32, probably does not work.
EXTERNAL CALLS:
function dir_path
function VarType
PROCEDURE:
Use function findfile in VMS, but otherwise use "spawn ls -F" on UNIX.
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
F.V. 1994, handle case for MacOS.
F.V. 1995, fixed for case of no dirs but found Links.
F.V. 1999, handle case for OS = Win32.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/find_dirs.pro)
FIND_FILES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
find_files
PURPOSE:
Search for files with specified file-extension in specified directory.
CALLING EXAMPLE:
find_files, files, filnams, FILEXT=".fits", DIR=["data","images"]
KEYWORDS:
FILEXT = the file-extension (name ending) to look for (e.g. ".dat"),
do not use wildcard, because * is automatically placed in front.
DIRECTORY_PATH = string array giving a path of directories, which
upon concatenation specifies the subdirectory to search.
(default is current directory).
Do not include the operating system specific syntax for
directories, that is, leave out the "/" and ".",
they are automatically added depending on op.sys.
OUTPUT:
files = array of complete file names found (nothing if none found)
filnams = array file names (without the directory spec in name).
EXTERNAL CALLS:
function dir_path
PROCEDURE:
Use function findfile and then manipulate the strings.
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/find_files.pro)
FIND_OUTLIERS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
find_outliers
PURPOSE:
Find outlier (bad) pixels in an image and return array of subscripts.
Outliers are flagged if value exceeds N_SIGMA times local standard
deviation (assuming that good data pixels do not deviate that much).
This procedure uses the histogram of image with reverse indices
to home in on pixels that have values outside the distribution
of most pixel values, and so is faster and usually better than
function sigma_filter, except when bad pixel values are within the
distribution of good pixels.
CALLING:
subscripts = find_outliers( image, box_width, N_SIGMA=# )
INPUTS:
image = 2-D array (this input will be modified).
box_width = width of square box in which to test statistics of
outlier candidate pixels, units in # pixels (default=3).
KEYWORDS:
N_SIGMA = number of standard deviations flagging outliers (float),
minimum = 1, default = 5.
STOP = integer, the checking for outliers will stop after this
number of candidates are found to be NOT outliers (default=9).
RADIUS = specify test box size with radius, so box_width = 2*radius+1.
/MEDIAN : causes the median of values in test box to be used as
the replacement value, and in estimation of standard deviation.
/NO_MIN_OUT : outlier pixels related to minimum extremes of image
are NOT checked or replaced. This takes precedence over /NO_MAX.
/NO_MAX_OUT : outlier pixels related to maximum extremes of image
are NOT checked or replaced.
/MONITOR : prints information about % of pixels replaced.
OUTPUT:
image = the input array is modified by replacing outliers as found.
KEYWORD OUTPUT:
N_FOUND = total # of pixels found to be outliers, optional output.
NOTES:
For a flat gaussian noise image:
N_sigma = 2 finds about 5% of pixels to be outliers,
N_sigma = 3 finds about 1% of pixels to be outliers,
N_sigma = 4 finds 0.5% of pixels to be outliers, and so on.
Setting /MEDIAN causes less pixels to be replaced and at same time
is then more successful at replacing adjacent pairs of outlier pixels.
The algorithm is semi-iterative since the image is modified during
the processing, thus changing the local deviations in test boxes,
and this feature actually helps to remove adjacent outliers.
Increasing box_width (or RADIUS) will usually replace more pixels.
Setting STOP= larger values causes more pixels to be checked and so
takes longer time, and results in more pixels being replaced,
whereas STOP=0 will replace only the maximum and/or minimum pixels
(if they are outliers, and if they occur first in reverse indices).
PROCEDURE:
Possible outliers are found using the reverse indices from the
histogram of image. Starting from the maximum bin and working down,
each outlier candidate is checked by finding the mean (or median) and
standard deviation of pixels in box centered at candidate pixel
of the image (excluding that pixel), and if the center value exceeds
specified number of standard deviations from the mean (or median),
the subscript is added to array of subscripts. The process is repeated
starting at the minimum bin and working to more positive values.
This method of using histograms is faster than function sigma_filter
for large images, and is more successful at finding outliers.
HISTORY:
Written, 1997, Frank Varosi, HSTX @ NASA/GSFC
FV, 8/97, for case of int/Long image, histogram binsize must be >= 1.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/find_outliers.pro)
FINTERPOL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FINTERPOL
PURPOSE:
Linear interpolation of a table of function values onto a new grid.
Finterpol is faster than the old IDL lib routine interpol
when the arrays (xold & xnew) have more than about 10 elements,
and speedup factor increases to > 15 when number of elements > 100.
This is acheived by first calling function InterLeave( xold, xnew ),
which then allows subsequent computations to be vectorized.
Intermediate computations are stored in a common block so that
after the first call, further interpolations of different functions
evaluated on the same grids can be performed even faster (10 X)
by omitting the xold & xnew arguments in further calls. The array
of points at which function is known must be strictly increasing,
but the new interpolation points can be in any order. If the new
grid points are beyond the range of old points extrapolation is
performed, and a message is printed (unless /QUIET is set).
See keywords for options to interpolate exponential or power-law
functional behaviours.
CALLING:
fxnew = finterpol( fxold, xold, xnew )
INPUTS:
fxold = array of function values at the points xold.
xold = array of points (strictly increasing) where func is evaluated.
xnew = array of new points at which linear interpolations are desired.
KEYWORDS:
/QUIET : do not check or print any messages if extrapolation is done.
Default is to give warning messages about # points extrapolated.
/INITIALIZE : use only the xold & xnew arrays to compute arrays
that are kept in the common block for use in fast repetitive
interpolations of different functions from/to same grids.
No interpolation is performed and just status (0/1) is returned.
/EXPONENTIAL_INTERP: perform interpolation/extrapolation in Log-Linear
space, thereby giving correct result for exponential function.
(Function values are then assumed > 1e-37).
/POWER_LAW_INTERP: perform interpolation/extrapolation in Log-Log space,
thereby giving correct result for power-law function.
(Function and X coordinate values are then assumed > 1e-37).
OUTPUTS:
Function returns array of linear interpolates at new grid points,
or it returns just the number 1 if /INIT is set, or 0 if calling error.
COMMON BLOCKS:
common finterpol
common finterpol2
EXTERNAL CALLS:
function InterLeave
function scalar
PROCEDURE:
Call function InterLeave to find old grid points which bracket
the new grid points, and then interpolate in vectorized form.
Take natural log of function values for exponential interpolation,
then exponentiating on return, take log of grid points and function
for interpolation of power-law behaviour.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1997.
F.V. 1998, added /EXPONENTIAL_INTERP and /POWER_LAW_INTERP options.
F.V. 1999, /EXP and /POWER options are remebered for repeat calls,
and scalar value is returned if result has just one element.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/finterpol.pro)
FITEXY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
fitexy
PURPOSE:
Linear Least-squares approximation in one-dimension (y = a + b*x),
when both x and y data have errors (e.g. Gaussian noise).
CALLING EXAMPLE:
fitexy, x, y, A, B, X_SIG=sigx, Y_SIG=sigy, [sigmas, covar, chi_sq]
INPUTS:
x = array of values for independent variable.
y = array of data values assumed to be linearly dependent on x.
KEYWORDS:
X_SIGMA = scalar or array specifying the standard deviation of x data.
Y_SIGMA = scalar or array specifying the standard deviation of y data.
TOLERANCE = desired accuracy of minimum & zero location, default=1.e-3.
OUTPUTS:
A_intercept = constant parameter result of linear fit,
B_slope = slope parameter, so that:
( A_intercept + B_slope * x ) approximates the y data.
OPTIONAL OUTPUT:
sigma_A_B = two element array giving standard deviation of
A_intercept and B_slope parameters, respectively.
chi_sq = resulting minimum Chi-Square of Linear fit.
COMMON:
common fitexy, communicates the data for computation of chi-square.
CALLS:
function chisq_fitexy
pro minf_bracket
pro minf_parabolic
function zbrent
PROCEDURE:
From "Numerical Recipes" column: Computer in Physics Vol.6 No.3
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/fitexy.pro)
FITSBYTE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITSBYTE
CALLING SEQUENCE:
fitsbyte, im [, host=conversion_flag]
PURPOSE:
To convert an image array from FITS byte ordering to the ordering
used by the computer.
INPUT/OUTPUT:
im The image array (both input and output).
OPTIONAL KEYWORDS:
HOST If present and non-zero, the image is converted to "host"
form. Otherwise, it is converted to "network", or FITS,
form.
COMMON BLOCKS:
None
PROCEDURE:
The byteorder procedure is used to perform the conversion. The
form of this conversion depends upon the datatype of the array.
If it is of I*2 format, a short integer swap is performed. If it
is of I*4 format, a long integer swap is performed. Otherwise,
nothing is done.
MODIFICATION HISTORY:
Written by Michael R. Greason, STX, 21 August 1990.
Mod F.Varosi Oct.1991, do short integer byte swap for floating point.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/fitsbyte.pro)
FLAT_BY_SORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
flat_by_sort
PURPOSE:
Estimate sky or row/column pattern background in an image by
sorting rows (or columns) and then subtract the background
to return flat fielded image.
CALLING EXAMPLE:
image_flat = flat_by_sort( image, imback, /TRANSPOSE, MIN_SORT=9 )
INPUTS:
image = 2D array of data
KEYWORDS:
/TRANSPOSE : work on transpose so columns are sorted to get background.
MIN_SORT = index of which element of sorted row to use at background,
MIN=1 causes 1st value above minimum to be the background,
MIN = #pixels_per_row/2 causes median to be used,
MIN=0 (default) causes the first statistically favorable value
above minimum to be selected as the row background.
OUTPUTS:
imback = the estimated sky or row/column pattern background.
RESULT:
Function returns the flat fielded image (background subtracted).
PROCEDURE:
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/flat_by_sort.pro)
FORCE_EVENTS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Force_Events
PURPOSE:
To set timers on widgets that match the requested values,
causing them to generate events in sequence.
CALLING:
Force_Events, widget_map, event_values
INPUTS:
widget_map = array of structures with at least the following tags:
{ id:0L, value:"" } for each widget of interest.
This can be obtained from function widget_Tree_Map.
event_values = array of strings, corresponding to widget values.
The matches need not be exact but must be unique.
KEYWORD:
TIMER_INCREMENT = seconds between each sequential event, default = 0.1.
OUTPUT: none.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/force_events.pro)
FRAC_PIX_SHIFT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
frac_pix_shift
PURPOSE:
Extract a part of image specified up to fractional pixels
by calling function frac_pix_shift( image ) with x & y shifts,
which resamples image onto fractionally shifted grid
using the bilinear interp feature of intrinsic IDL function poly_2d.
CALLING:
imex = frac_pix_extrac( image, xBegin, yBegin, xSize, ySize )
INPUTS:
image =
xBegin, yBegin =
xSize, ySize =
KEYWORDS:
BEGIN_PIXEL =
SIZE_EXTRACT =
OUTPUTS:
The extracted image is returned.
EXTERNAL CALLS:
function frac_pix_shift( image )
PROCEDURE:
Setup and call function frac_pix_shift, return subimage.
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/frac_pix_extrac.pro)
FRAC_PIX_SHIFT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
frac_pix_shift
PURPOSE:
Shift the image by fraction of a pixel in x and/or y directions
using the bilinear interp feature of intrinsic IDL routine poly_2d.
Minimum shift is one tenth of pixel, anything less is ignored.
Best to keep abs( x & y shifts ) < 0.5, otherwise poly_2d extrapolates.
CALLING:
imshift = frac_pix_shift( image, x_shift, y_shift )
INPUTS:
image, x_shift, y_shift
KEYWORDS:
SHIFT_XY =
/RENORMALIZE : shifted image is renormalized to conserve positive flux.
OUTPUTS:
The image shifted is returned.
PROCEDURE:
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/frac_pix_shift.pro)
FSORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FSORT
PURPOSE:
Function to sort data into ascending order,
original subscript order is maintained when values are equal (FIFO).
(unlike IDL sort routine alone,
which may rearrange the order of equal values)
CALLING SEQUENCE:
result = fsort( array, [asort] )
INPUT:
Array - array to be sorted
KEYWORDS:
/INFO = optional keyword to cause brief message about # equal values.
/DESCENDING = descending order instead of the default ascending order.
OUTPUT:
Subscripts which give sorted order are returned as function value.
OPTIONAL OUTPUT:
Asort - sorted array
METHOD:
uses WHERE to find equal clumps, instead of looping with IF ( EQ ).
HISTORY:
written by F. Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/fsort.pro)
FULLWID_HALFMAX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FullWid_HalfMax
PURPOSE:
Return the full-width-half-max (FWHM) around the peak (maximum)
in a 1D profile, 2D image (e.g. star), or 3D volumetric-data.
FWHM is determined for each dimension independently by:
Linear interpolations (default), or fitting Gaussian functions,
or by fitting modified Lorentzian functions, to each profiles.
CALLING:
fwhm_xy = FullWid_HalfMax( data, CENTROID=cxy, /GAUSSIAN_FIT )
INPUTS:
data = 1D, 2D, or 3D array (e.g. spectrum, image, or data cube).
KEYWORDS (in):
/GAUSSIAN_FIT : nonlinear Least-squares fit of Gaussian function to
profile in each dimension to get FWHM,
(default is to estimate FWHM by Linear interpolation).
/LORENTZIAN_FIT : non-Lin-Lsq fit modified Lorentzian (Cauchy) function
to profile in each dimension to estimate FWHM, and
other parameters, giving more freedom than Gaussian.
/SKY_FIT : include a constant param (sky offset) in non-Lin-Lsq fits.
/AVERAGE : return the average FWHM, instead of one for each dimension.
/INNER_MAX : find maximum value within inner 80% of data (ignore edges).
MAX_ITER_FIT = maximum # of iterations to use in Lsq fits, default=10.
KEYWORDS (out):
FIT_PARAMETERS = an array containing the parameters determined by the
Lsq fits to profiles, thus a matrix if data is > 1 dimensional.
SIGMA_PARAMS = array containing standard deviation of the parameters.
CENTROID = array, the centroid coordinate of profile in each dim,
if either /GAUSSIAN_FIT or /LORENTZIAN_FIT requested.
Convention is that center of pixel is at 0.5 + pixel#.
PEAK_INDEX = array, the pixel # at maximum of profile in each dim.
RANGE_MINMAX = array containing the minimum, maximum value of data.
RESULT:
Function returns an array giving FWHM for each dimension,
or if /AVER set, a scalar giving the average FWHM around the peak.
EXTERNAL CALLS:
function gaussian
function Lorentzian
pro non_Lin_Lsq
PROCEDURE:
Simply find maximum point of data and
call function FullWid_HalfMax recursively for profile in each dimension.
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
F.V. 1994, /SKY_FIT option for Non-Lin-Lsq fitting to model sky offset.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/fullwid_halfmax.pro)
FW_HM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FW_HM
PURPOSE:
Directly call the function FullWid_HalfMax to
return the full-width-half-max (FWHM) around the peak (maximum)
in a 1D profile, 2D image (e.g. star), or 3D volumetric-data.
FWHM is determined for each dimension independently by:
Linear interpolations (default), or fitting Gaussian functions,
or by fitting modified Lorentzian functions, to each profiles.
CALLING EXAMPLE:
fwhm_xy = fw_hm( data, CENTROID=cxy, /GAUSSIAN_FIT )
INPUTS:
data = 1D, 2D, or 3D array (e.g. spectrum, image, or data cube).
KEYWORDS (in):
/GAUSSIAN_FIT : nonlinear Least-squares fit of Gaussian function to
profile in each dimension to get FWHM,
(default is to estimate FWHM by Linear interpolation).
/LORENTZIAN_FIT : non-Lin-Lsq fit modified Lorentzian (Cauchy) function
to profile in each dimension to estimate FWHM, and
other parameters, giving more freedom than Gaussian.
/SKY_FIT : include a constant param (sky offset) in non-Lin-Lsq fits.
MAX_ITER_FIT = maximum # of iterations to use in Lsq fits, default=10.
/AVERAGE : return the average FWHM, instead of for each dimension.
KEYWORDS (out):
FIT_PARAMETERS = an array containing the parameters determined by the
Lsq fits to profiles, thus a matrix if data is > 1 dimensional.
CENTROID = array, the centroid coordinate of profile in each dim,
if either /GAUSSIAN_FIT or /LORENTZIAN_FIT requested.
Convention is that center of pixel is at 0.5 + pixel#.
PEAK_INDEX = array, the pixel # at maximum of profile in each dim.
RANGE_MINMAX = array containing the minimum, maximum value of data.
RESULT:
Function returns an array giving FWHM for each dimension,
or if /AVER set, a scalar giving the average FWHM around the peak.
EXTERNAL CALLS:
function FullWid_HalfMax
HISTORY:
Written: Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/fw_hm.pro)
GAMMLN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME
GAMMLN
PURPOSE:
Return the natural log of the gamma function. Adapted from the
algorithm GAMMLN in Section 6.1 in "Numerical Recipes " (Second
Edition) by Press et al. 1992. This function became obsolete
in IDL 2.4.0 when the equivalent LNGAMMA intrinsic function was
introduced.
CALLING SEQUENCE:
result = gammln ( xx )
INPUTS:
xx - numeric scalar or vector for which the log of the gamma function
will be evaluated. Must be > 0
OUTPUT:
result = alog ( gamma(xx) ). The result will double precision if xx
is double, otherwise the result is floating point.
NOTES:
IDL has an intrinsic gamma function, GAMMA, but overflow occurs in
GAMMA for X > 34.5. By computing the log of the gamma function, one
can deal with much larger input values. GAMMLN also allows double
precision computation, not available with GAMMA.
EXAMPLE:
Compare the output of GAMMA with GAMMLN
IDL> x = findgen(15)+0.5
IDL> print, alog(gamma(x))
IDL> print,gammln(x)
METHOD:
Uses the expansion of Lanczos as described in Press et al. (1986)
REVISION HISTORY:
Written, W. Landsman July, 1992
Double Precision update October, 1992
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gammln.pro)
GAUSSIAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
gaussian
PURPOSE:
Compute the 1-D Gaussian function at an array of points.
CALLING:
y = gaussian( xi, parms, pderiv )
INPUTS:
xi = array, independent variable of Gaussian function.
parms = parameters of Gaussian, 2 or 3 element array:
parms(0) = maximum value (factor) of Gaussian,
parms(1) = mean value (center) of Gaussian,
parms(2) = standard deviation (sigma) of Gaussian.
parms(3) = optional, constant offset added to Gaussian.
(if parms has only 2 elements then sigma taken from common).
OUTPUT:
pderiv = optional output of partial derivatives,
computed only if parameter is present in call.
pderiv(*,i) = partial derivative at all xi absisca values
with respect to parms(i), i=0,1,2.
Function returns array of Gaussian evaluated at xi.
COMMON BLOCKS:
common gaussian, sigma
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
F.V. 1994, added optional fourth parameter = constant offset.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gaussian.pro)
GAUSS_LEG_QUADR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Gauss_Leg_Quadr
PURPOSE:
Setup Gaussian-Legendre quadrature for numerical integration.
Get roots of Legendre polynomials and corresponding
weights for Gaussian quadrature of a function:
Approximate integral = total( weights * function( roots ) )
CALLING:
Gauss_Leg_Quadr, Npq, xq, wq
INPUTS:
Npq = integer, number of points desired for quadrature,
forced to be an even number. The quadrature will be
exact for polynomials up to degree 2*Npq-1.
KEYWORDS:
XRANGE = range of integration, default = (-1,1).
Range can be changed later by rescaling points and weights,
(see code at end of this routine).
EPSILON = accuracy of root convergence, default = 3.d-14.
OUTPUTS:
xq = points at which function should be evaluated.
wq = corresponding weights: Integral = total( wq * func( xq ) )
EXAMPLE:
IDL> Gauss_Leg_Quadr, 2, xq, wq, XRANGE=[0,3]
IDL> print, total( wq * xq^2 )
9.0000000 ; = integral of x^2 from 0 to 3.
IDL> print, total( wq * xq^3 )
20.250000 ; = integral of x^3 from 0 to 3.
PROCEDURE:
G. Rybicki algorithm as described in Numerical Recipes section 4.5.
Uses Newton's method to find roots of Legendre polynomials,
since the Leg.Poly. derivatives are needed anyway to compute weights.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
F.V.1995: fixed mistake in using xrange.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gauss_leg_quadr.pro)
GETTOK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETTOK
PURPOSE:
Function to retrieve the first part of the string
until the character char is encountered.
(eg. if st is 'abc=999' then gettok(st,'=') would return
'abc' and st would be left as 999)
gettok(st,char)
INPUT:
st - string to get token from (on output token is removed)
char - character separating tokens
OUTPUT:
taken value is returned
!err is set to size of token
HISTORY
version 1 by D. Lindler APR,86
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gettok.pro)
GET_CURSOR_WIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
get_cursor_win
PURPOSE:
Find out which window the cursor is in and return the window number.
The cursor Location is also returned.
CALLING:
window_number = get_cursor_win( x, y )
INPUTS: none
KEYWORDS: none
OUTPUTS:
x, y = Location of cursor if found in some window.
Function returns the window number if cursor is found in it,
otherwise returns -1.
PROCEDURE:
Get the numbers of currently open windows
and check cursor position in each window (see if positive).
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_cursor_win.pro)
GET_LIB
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GET_LIB
PURPOSE:
Place library and directory elements of !PATH into a string array.
Used by SCLIB.
CALLING SEQUENCE:
LIB = GET_LIB()
INPUTS:
path = path name (default is !path)
OUTPUTS:
Function result is a string array of path elements.
PROCEDURE:
Reads !PATH and keys on commas (VMS) or colons (UNIX).
MODIFICATION HISTORY:
Written DMZ (ARC) April 1991
William Thompson, Dec 1991, modified to be compatible with UNIX, and
with VMS logical names. Also, to be
compatible with changes in SCANPATH
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_lib.pro)
GET_MOD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GET_MOD
PURPOSE:
Extract list of procedure modules from a library or directory. Used by
SCPATH.
CALLING SEQUENCE:
MODS = GET_MOD(LIB)
INPUTS:
LIB = Library or directory name.
OUTPUTS:
Result of function is a string array with each module name.
PROCEDURE:
Spawns a LIBRARY/LIST or uses FINDFILE.
MODIFICATION HISTORY:
Written DMZ (ARC) May 1991
William Thompson, Dec 1991, modified to be compatible with UNIX.
DMZ (DEC'92), fixed bug in FINDFILE with long argument lists.
F.V.1993, fixed up the UNIX part of code (spawn, etc...).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_mod.pro)
GET_PROC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GET_PROC
PURPOSE:
Extract procedure from a library or directory.
CALLING SEQUENCE:
PROC = GET_PROC(LIB,NAME,FNAME,TEXT,
/DOC_ONLY,/EXTRACT,/SEARCH,/LINOS,/BUFFER)
INPUTS:
LIB = Library name.
NAME = Procedure name.
TEXT = Search string.
KEYWORDS:
DOC_ONLY= Logical switch to decide whether only the documentation
(between ";+" and ";-") is to be read in, or the entire file.
EXTRACT = copy extracted library module to user's current directory
SEARCH = Logical switch to decide whether to search for string in
variable TEXT
UNUSABLE KEYWORDS -- code is in place but modifications to DOC.PRO
are needed to pass /LINOS or BUFFER=[n1,n2]
LINOS = added line number option
BUFFER = 2 element vector indicating display n1 lines before search
string and n2 lines after search string. Only valid if
/SEARCH is set
OUTPUTS:
FNAME = File name.
PROC = string array with each element being a line of code.
PROCEDURE:
If necessary, then spawns a LIBRARY/EXTRACT command.
MODIFICATION HISTORY:
Written DMZ (ARC) May 1991.
Modified WTT (ARC) Dec 1991, to support UNIX.
Modified DMZ (ARC) Jul 1992, to speed reading and add extract keyword
Modified EEE (HSTX) Oct 1992, 1) to find all occurrences of ;+/;_
2) to search for input string
3) to allow BUFFER keyword
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_proc.pro)
GET_TEXT_INPUT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
get_text_input
PURPOSE:
Prompt the user for input with a question and
return the text string typed by user.
For X-windows the input is thru a text widget, in middle of screen,
and the text widget waits until carriage return is entered.
Otherwise input is in terminal window, with a beep to alert user.
CALLING:
text = get_text_input( question )
INPUTS:
question = string(s), prompt for input, default is null string.
If an array is passed, each element is shown on its own line.
KEYWORDS:
DEFAULT_INPUT = optional string, setting the default response.
OUTPUTS:
Function returns the text string entered by user,
with leading and trailing blanks removed.
HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
F.V.1997, question can be a string array, shown as multiple lines.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_text_input.pro)
GET_WINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
get_window
PURPOSE:
Get a new window or set focus to existing window (non /FREE windows).
This makes repeated use of windows easier:
first call creates window, subsequent calls just set focus to it.
If window was deleted, then it is just recreated with no errors.
Window size and position values are the defaults of IDL,
unless specified with the usual window routine keywords.
If existing window size is different then specified in keywords
it is recreated with requested size. If new window is requested
and more than 32 windows exist (max # of non /FREE windows)
this routine stops with request that user delete a window,
then continue (IDL> .c), and then new window will be created.
CALLING:
get_window, winum
INPUTS:
winum = 0 <= integer <= 31, window # to get, default is new window.
If window exists the focus is set to it.
If # is negative, creates new window.
KEYWORDS:
XSIZE, YSIZE = size of window (optional),
default for new window: 640 by 512.
/SHOW : de-iconify and/or pop window into view.
/ERASE : erase contents of an existing window.
Standard window keywords such as TITLE, XPOS, and YPOS
are passed to window call via _EXTRA keyword mechanism.
OUTPUTS:
winum = window # actually created or focus set to.
RESTRICTIONS:
Works only with window numbers between 0 and 31 (inclusive),
not the /FREE created windows which have numbers 32 and higher.
PROCEDURE:
Get the numbers of currently open windows
and check if in table or create a new window.
HISTORY:
Written: Frank Varosi NASA/GSFC 1990.
F.V.1992, mod to handle new IDL-X feature that #>31 are for /FREE only.
F.V.1995, mod to return if not windowing system,
and on Macintosh cannot check window states so skip it.
F.V.1998, mod to _EXTRA keyword instead of XPOS and YPOS explicitly.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_window.pro)
GET_WORDS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
get_words
PURPOSE:
Separate text string(s) into array of words and return it.
CALLING:
words = get_words( text )
EXAMPLE:
dirs = get_words( !path, DELIMIT=":" )
INPUTS:
text = string or string array. An array of strings is considered
to have a delimeter at end of each array element.
KEYWORDS:
DELIMITERS = string(s) of single characters to search for in text,
and then use to separate text into words,
default = null, tab, comma and blank characters.
Note that multi-character strings will be just
converted to array of single characters since the
the code is restricted to finding single char. delimeters.
WNUMS = optional integer scalar/array of subscript(s) to select
and return out of the words array.
OUTPUTS:
Function returns arrays of strings: the words in text.
PROCEDURE:
Convert string to byte array and find where delimiters are.
HISTORY:
Written: Frank Varosi NASA/GSFC 1989.
F.V.1990 : generalized and added DELIMITERS keyword.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/get_words.pro)
GRADIENT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
gradient
PURPOSE:
Compute the gradient vector at every pixel of an image using
neighbor pixels. Default is to return the Euclidean norm of gradient
(2-D array), or specify keywords for other options.
CALLING:
gradim = gradient( image )
INPUTS:
image = 2-D array.
KEYWORDS:
XRANGE=, YRANGE= [min,max] range of pixel coordinates (for x,y axes),
allowing scaling of gradient magnitudes.
/VECTOR then 2 images are returned (3-D array) with d/dx and d/dy.
/ONE_SIDED then x & y-partial derivatives computed over adjacent pixels.
/ABSVAL then magnitude of gradient is computed by absolute value norm.
OUTPUTS:
Function returns gradient norm (2-D array) or gradient vector (3-D).
HISTORY:
Frank Varosi U.Md. 1987
F.V. NASA/GSFC 1991, added keyword options.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gradient.pro)
GRIDXY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
gridxy
PURPOSE:
Create a 2-D grid of X & Y coordinates, suitable for computations,
in the form of 2 images, stacked as 3-D array,
or 2 vectors (collapsed images, 2-D array result).
CALLING:
gxy = gridxy( Ngx, Ngy, XRAN=[-1,1], YRAN=[-1,1] )
INPUTS:
Ngx, Ngy = number of X & Y grid points, resp.
KEYWORDS:
XRANGE, YRANGE = 2 element arrays specifying [min,max] of X & Y range.
Note that the ranges are saved in common MapLim, so that if
next call does not specify them, the common values are used.
Default values are [0,Ngx] and [0,Ngy].
DIMENSIONS = 2 elements array, alternative specification of [Ngx,Ngy].
/INCLUDE_MAXRAN causes the last coordinate in output array to be
the maximum of X & Y range (default is max - grid_size).
SHIFT = fraction of grid size to shift points so as to stay within
specified range, default is start at minimum of range.
/VECTOR : collapse 2-D to 1-D and return 2-D array : ( Ngx*Ngy, 2 ).
/TRANSPOSE applies only when /VECTOR, result is fltarr( 2, Ngx*Ngy )
/FLIP transposes the x and y coordinates.
POWER = scalar, optional exponent used to raise elements to a power
before creating matrix, thus faster than afterwards.
Power is not applied to zero values, they are kept zero.
OUTPUTS:
Result is an array of X & Y coordinate points:
3-D array = fltarr( Ngx, Ngy, 2 )
or 2-D array = fltarr( Ngx*Ngy, 2 ) if /VECTOR set.
COMMON BLOCKS:
common MapLim ,xminc,xmaxc ,yminc,ymaxc ;can specify limits.
PROCEDURE:
Use the matrix outer product (#).
HISTORY:
Written: Frank Varosi U.MD. 1987
F.V. 1990, updated for IDL version-2, added keywords.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gridxy.pro)
GRIDXYZ
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
gridxyz
PURPOSE:
Create a 3-D grid of X & Y coordinates, suitable for computations,
in the form of 3 data-cubes, stacked as 4-D array,
or 3 vectors (collapsed cubes, 2-D array result).
CALLING:
gxyz = gridxyz( Ngx, Ngy, Ngz, XRAN=[-1,1], YRAN=[-1,1] )
INPUTS:
Ngx, Ngy, Ngz = number of X, Y, & Z grid points, resp.
KEYWORDS:
XRANGE, YRANGE = 2 element arrays specifying [min,max] of X & Y range.
Note that the ranges are saved in common MapLim, so that if
next call does not specify them, the common values are used.
Default values are [0,Ngx] and [0,Ngy].
DIMENSIONS = 3 elements array, alternate specification of [Ngx,Ngy,Ngz].
/INCLUDE_MAXRAN causes the last coordinate in output array to be
the maximum of X & Y range (default is max - grid_size).
SHIFT = fraction of grid size to shift points so as to stay within
specified range, default is start at minimum of range.
/VECTOR : collapse 3-D to 1-D and return 2-D array : ( Ngx*Ngy*Ngz, 3 ).
POWER = scalar, optional exponent used to raise elements to a power
before creating matrix, thus faster than afterwards.
Power is not applied to zero values, they are kept zero.
OUTPUTS:
Result is an array of X & Y coordinate points:
4-D array = fltarr( Ngx, Ngy, Ngz, 3 )
or 2-D array = fltarr( Ngx*Ngy*Ngz, 3 ) if /VECTOR set.
COMMON BLOCKS:
common MapLim ,xminc,xmaxc ,yminc,ymaxc ;can specify limits.
common MapLim2 ,zminc,zmaxc
EXTERNAL CALLS:
function gridxy
PROCEDURE:
Call func gridxy for 2 coordinates the matrix outer product (#).
HISTORY:
Written: Frank Varosi U.MD. 1988.
F.V. 1990, updated for IDL version-2, added keywords.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gridxyz.pro)
GS_ORTHONORM
[Previous Routine]
[Next Routine]
[List of Routines]
Gram-Schmidt Re-OrthoNormalization of basis vectors.
Frank Varosi U.MD.1988
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gs_orthonorm.pro)
GS_ORTHONORM_V
[Previous Routine]
[Next Routine]
[List of Routines]
Gram-Schmidt Re-OrthoNormalization of many vector-bases.
Frank Varosi U.MD.1988
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/gs_orthonorm_v.pro)
HANDLES_FREE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Handles_Free
PURPOSE:
Free a vector of handles, ignoring any invalid handles.
CALLING:
Handles_Free, handles
INPUTS:
handles = array of IDL handles (pointers to IDL variables).
OUTPUTS:
None.
PROCEDURE:
Loop over valid handles calling IDL instrinsic handle_free.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/handles_free.pro)
HANDLES_POOL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Handles_Pool
PURPOSE:
Copy the handle values from and array of handles and lump them
all together into a single array. This array can then be saved
along with the handle-value sizes matrix and then later restored
and the handles recreated using function Handles_Unpool.
In the case of handle values with different variable types,
the variable type of the pool array is determined by
the first handle value, and all other handle values are
memory mapped to that same type (no conversion, data is unchanged).
CALLING:
pool = Handles_Pool( handles, SIZES=vsizes )
INPUTS:
handles = array of IDL handles (pointers to IDL variables).
KEYWORDS:
SIZES = output, matrix of sizes of the variables stored in handles.
This matrix contains all the information needed to extract the
original variables from the pool using function Handles_Unpool.
NPVEC = output, vector of # elements from each handle actually pooled.
Note that for those handles storing strings & structures
npvec will be zero since those types cannot be pooled.
OUTPUTS:
Function returns an array which is the "pool" containing all
elements stored in the handles lumped together.
EXTERNAL CALLS:
function Handle_Sizes
function Map_Var_Type
function N_bytes_vtype
PROCEDURE:
Get and set each handle value with /NO_COPY in loop of pool insertions.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/handles_pool.pro)
HANDLES_UNPOOL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Handles_Unpool
PURPOSE:
Extract all the handle-values that were lumped in a pool array
by function Handle_Pool and then create a new array of handles
storing the original values (variable types are also original).
Besides the pool array, caller must also provide the value sizes matrix.
CALLING:
handles = Handles_Unpool( pool, SIZES=vsizes )
INPUTS:
pool = an array which is the "pool" containing all elements
that were stored in the handles lumped together.
Obtained as result of function Handles_Pool.
KEYWORDS:
SIZES = required input, matrix of variable sizes to be put in handles.
This matrix is created when using Handles_Pool and contains all
the information needed to extract the variables from the pool.
Matrix can also be obtained using function Handle_Sizes.
NPVEC = optional output, vector of # elements in each returned handle
that is extracted from pool.
OUTPUTS:
Function returns an array of IDL handles (pointers to IDL variables).
EXTERNAL CALLS:
function Map_Var_Type
function N_bytes_vtype
PROCEDURE:
Get and set each handle value with /NO_COPY in loop of pool insertions.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/handles_unpool.pro)
HANDLE_SIZES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Handle_Sizes
PURPOSE:
Get the IDL sizes of the values pointed to by an array of handles.
CALLING:
sizes = Handle_Sizes( handles )
INPUTS:
handles = array of IDL handles (pointers to IDL variables).
OUTPUTS:
Function returns matrix of sizes (results of IDL size function),
each row (i) is the size( value stored in handle (i) ).
If any handle is not valid (undefined) the row is zero.
PROCEDURE:
Get and set each handle value with /NO_COPY in loop of size checks.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/handle_sizes.pro)
HEADFITS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
HEADFITS
CALLING SEQUENCE:
Result = headfits( filename )
PURPOSE:
READ A FITS FILE HEADER RECORD
INPUTS:
FILENAME = String containing the name of the file to be read.
OUTPUTS:
Result of function = header record.
MODIFICATION HISTORY:
adapted by Frank Varosi from READFITS by Jim Wofford, January, 24 1989
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/headfits.pro)
HISTO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Histo
PURPOSE:
Provides a convient interface to IDL histogram function:
return histogram with requested number of bins (or specified binsize),
and also output the vector of bin values (useful for plotting).
If keyword BOX_STDEV is set, this specifies the size of moving box
for which local variances of data are computed and then the
histogram of all local standard deviations is returned.
CALLING EXAMPLES:
hist_data = Histo( data, BinVals, Revix, NBIN=70, MIN=.1, MAX=50 )
hist_stdev = Histo( data, BinVals, BOX_STDEV=3 )
plot, binvals, Histo( data, binvals )
INPUT:
data = array of numbers (vector, image, etc.)
KEYWORDS:
NBIN = # of bins desired, default=100.
BINSIZE = the desired binsize, overrides NBIN,
but NBIN can still limit the maximum # of bins.
MIN = minimum data value to include in histogram.
MAX = maximum data value to include in histogram
(defaults are actual min or max of data).
/NORMALIZE : normalize the histogram so that its integral over bins
is unity, making it a probability density (trapeziodal rule).
BOX_STDEV = the width in pixels of moving box
in which to compute local variances,
and then histogram of standard deviations is returned.
LOCAL_VARIANCE = optional output, the array of local variances
of data (before sqrt), if BOX_STDEV is specified.
OUTPUTS:
BinVals = the data values at center of each bin (x-axis for plotting).
Revix = array of reverse indices from the IDL histogram function
(optional, computed only if argument is present).
Function returns a vector giving the histogram of data.
If BOX_STDEV is specified then
the histogram of local standard deviations of the data is returned.
EXTERNAL CALLS:
function vartype
function trapez (if /NORM)
PROCEDURE:
Determine binsize (and bins) and call the IDL histogram function.
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V.1991: added BINSIZE option and then NBIN limits the Max # bins.
F.V.1992: added option BOX_STDEV = width of moving box in which to
compute Local standard deviations of data and return histogram of it.
F.V.1996: fixed bug where sometimes last bin element is dropped,
because IDL histogram returns one more than requested NBIN.
F.V.1997: added optional output argument "Revix" (reverse indices),
and keyword option /NORMALIZE.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/histo.pro)
HISTOG_CORREL
[Previous Routine]
[Next Routine]
[List of Routines]
Compute simple correlation between histograms (must be all on same scale).
First one is correlated with all of them, /WEIGHT uses values as weighting.
Keyword NORM allows re-using the total( density(*,0)^2 ) computation.
Frank Varosi STX @ NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/histog_correl.pro)
HISTOG_DIFFER
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi STX @ NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/histog_differ.pro)
HIST_EQUAL_CT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Hist_Equal_CT
PURPOSE:
Histogram equalize the color tables of an image or a region of display.
CALLING:
Hist_Equal_CT, Image ... to histogram equalize from an image.
Hist_Equal_CT ... to histogram equalize from a region.
INPUTS:
Image = image whose histogram is to be used in determining
the new color tables. If omitted, the user is prompted
to mark the diagonal corners of a region of the display.
The Image MUST be a byte image, scaled the same way as
the image loaded to the display.
KEYWORDS:
WINDOW = the window number containing image (default = current window),
for interactively selecting region to equalize.
INFO_WINDOW = optional window number in which to
display information & instructions (default is print it).
EFFECTS:
Color tables are updated.
EXTERNAL CALLS:
pro color_map_load
function color_struct
pro color_st_Load
COMMON BLOCKS:
colors -- the color tables are modified by pro color_map_load
adjctmap -- saves the color table mapping for further adjustments.
PROCEDURE:
Either the image parameter or the region of the display marked by
the user is used to obtain a pixel distribution histogram. The
cumulative integral is taken and scaled. This function is applied
to the current color tables.
HISTORY:
DMS, March, 1988, written.
modified by F. Varosi NASA/GSFC 1989 to Loop and use rubber-box
(box_create, box_draw, and box_erase routines required).
F.V.1990 use color_map_load to tvlct and save histogram eq.
for use in adjct, allowing further adjustments.
F.V.1991 use color_struct and color_st_Load to save and reset tables.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/hist_equal_ct.pro)
HPRINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME
HPRINT
PURPOSE:
Print a FITS header (or any other string array) at the the terminal
by printing 1 line at a time.
Needed because IDL will add an extra space to the 80 character
FITS lines, causing a space to appear betweeen lines.
CALLING SEQUENCE:
HPRINT, h, [ firstline ]
INPUTS:
H - FITS header (or any other string array).
OPTIONAL INPUT:
FIRSTLINE - scalar integer specifying the first line to begin
displaying. The default is FIRSTLINE = 1, i.e. display
all the lines. If Firstline is negative, then the first
line to be printed is counted backward from the last line.
NOTES:
HPRINT has the following differences from the intrinsic PRINT procedure
(1) Arrays are printed one line at a time to avoid a space between 80
character lines
(2) Lines are trimmed with STRTRIM before being printed to speed up
display
(3) The /more option is used for output.
EXAMPLE:
Read the header from a FITS file named 'test.fits' and display it at the
terminal beginning with line 50
IDL> h = headfits( 'test.fits') ;Read FITS header
IDL> hprint, h, 50 ;Display starting at line 50
To print the last 25 lines of the header
IDL> hprint, h, -25
REVISION HISTORY:
Written W. Landsman July, 1990
Added test for user quit July, 1991
Added optional FIRSTLINE arguement November, 1992
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/hprint.pro)
ICONIFY_WINDOWS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
iconify_windows
PURPOSE:
Iconify window(s), first checking if window(s) actually exists,
thus avoiding accidental error trap.
CALLING:
iconify_windows, winum
INPUTS:
winum = integer scalar or array, window number(s) to iconify.
KEYWORDS:
/SHOW : show (de-iconify) the windows instead.
OUTPUTS: none.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/iconify_windows.pro)
IMAGE_EXTRACT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
image_extract
PURPOSE:
Extract an image (or array of any dimensions or type)
from pool-array (a 1-D array for storing data) using pointers.
The image (array) must have been inserted using pro image_insert.
In this way, many different sized images can be stored in single array,
and there is no type conversion, just straight memory mapping.
CALLING:
image = image_extract( inum, im_pool, im_sizes )
INPUTS:
inum = integer, the insertion slot # of image in pool-array.
im_pool = 1-D pool-array for storing data using pointers,
im_sizes = 2-D array, each row contains the standard IDL size info
plus pointer into pool-array (beginning and ending Locations).
Variables im_pool & im_sizes are created/modified by pro image_insert
and pro image_remove, and should NOT be altered any other way.
OUTPUTS:
Function returns the image (array) requested.
RELATED ROUTINES:
pro image_insert
pro image_remove
pro image_replace
EXTERNAL CALLS:
function map_var_type
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1990 modified to handle > 2-D image.
F.V. 1994 modified to handle data of any mixed types.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/image_extract.pro)
IMAGE_INSERT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
image_insert
PURPOSE:
Insert an image (or array of any dimensions or type)
into pool-array (a 1-D array for storing data) and update pointers.
The image (array) can be extracted using function image_extract.
In this way, many different sized images can be stored in single array,
and there is no type conversion, just straight memory mapping.
CALLING:
image_insert, image, inum, im_pool, im_sizes
INPUTS:
image = array of any size or type.
inum = integer, the insertion slot # of image in pool-array.
im_pool = 1-D pool-array for storing data using pointers.
im_sizes = 2-D array, each row contains the standard IDL size info
plus pointer into pool-array (beginning and ending Locations).
Variables im_pool & im_sizes are created/modified by pro image_insert
and pro image_remove, and should NOT be altered any other way.
KEYWORDS:
/REPLACE : option to replace an existing image in pool-array.
OUTPUTS:
im_pool : 1-D pool-array contains new data.
im_sizes : updated to contain new info and pointer into pool-array.
RELATED ROUTINES:
pro image_remove
pro image_replace
function image_extract
EXTERNAL CALLS:
pro image_replace
function map_var_type
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1990 modified to handle > 2-D image.
F.V. 1994 modified to handle data of any mixed types.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/image_insert.pro)
IMAGE_REMOVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
image_remove
PURPOSE:
Remove an image (or array of any dimensions or type)
from pool-array (a 1-D array for storing data) and update pointers.
The image (array) must have been inserted using pro image_insert.
CALLING:
image_remove, inum, im_pool, im_sizes
INPUTS:
inum = integer, the insertion slot # of image in pool-array.
im_pool = 1-D pool-array for storing data using pointers.
im_sizes = 2-D array, each row contains the standard IDL size info
plus pointer into pool-array (beginning and ending Locations).
Variables im_pool & im_sizes are created/modified by pro image_insert
and pro image_remove, and should NOT be altered any other way.
OUTPUTS:
im_pool : 1-D pool-array is modified.
im_sizes : info and pointer of inum slot is deleted.
RELATED ROUTINES:
pro image_insert
pro image_replace
function image_extract
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1990 modified to handle > 2-D image.
F.V. 1994 modified to handle data of any mixed types.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/image_remove.pro)
IMAGE_REPLACE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
image_replace
PURPOSE:
Replace an image (or array of any dimensions or type)
in pool-array (a 1-D array for storing data) and update pointers.
The image (array) must have been inserted using pro image_insert.
In this way, many different sized images can be stored in single array.
CALLING:
image_replace, image, inum, im_pool, im_sizes
INPUTS:
image = array of same size & type as already inserted into im_pool.
inum = integer, the insertion slot # of image in pool-array.
im_pool = 1-D pool-array for storing data using pointers.
im_sizes = 2-D array, each row contains the standard IDL size info
plus pointer into pool-array (beginning and ending Locations).
Variables im_pool & im_sizes are created / modified by pro image_insert
and pro image_remove, and should NOT be altered any other way.
OUTPUTS:
im_pool : 1-D pool-array contains new data.
RELATED ROUTINES:
pro image_insert
pro image_remove
function image_extract
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1990 modified to handle > 2-D image.
F.V. 1994 modified to handle data of any mixed types.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/image_replace.pro)
IMAGHEQ
[Previous Routine]
[Next Routine]
[List of Routines]
Imb = imagHeq( IMAGE, Pflag, Nbins, Heq,Hist )
Returns byte histogram equalization of image with weighting IH(x)*(x^Pflag)
where IH(x) is the integrated histrogram.
Pflag = 0 or omitted gives the usual histogram equalization .
IMAGE input can be byte, int, Long, float,
values are temporarily scaled to get # histogram bins = Nbins.
Default for Nbins is 1000 (unless image is allready BYTE, INTEGER, LONG)
Frank Varosi U.Md. 1988.
F.V. 1990, mod for IDL-V2.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/imagheq.pro)
IMAGHEQZ
[Previous Routine]
[Next Routine]
[List of Routines]
Returns byte histogram equalization of image with weighting IH(x)*(x^Pflag)
where IH(x) is the integrated histrogram.
Pflag = 0 or omitted gives the usual histogram equalization .
IMAGE input can be byte, int, Long, float, but values must be greater than 2.
Imb = imagHeq( IMAGE,Pflag,Heq,Hist ) GRZERO,GZIM are NOT computed
Imb = imagHeq( IMAGE,Pflag,Heq,Hist, GRZERO,GZIM ) GRZERO,GZIM are OUTPUT
Imb = imagHeq( SIZE(image),Pflag,Heq,Hist, GRZERO,GZIM ) use previous values
Frank Varosi, U.of MD., 1988.
F.V. 1990, modif. for IDL-V2.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/imagheqz.pro)
IMAGREAD
[Previous Routine]
[Next Routine]
[List of Routines]
Read image # Kimag from file.
result is image data, and header is returned :
[ #X_pixels, #Y_pixels, IDL_data_type, #extra_header_recs, #images-1 ]
Frank Varosi, U.of MD., 1988
F.V. 1990, mod. for IDL-V2,
and added keywork /V1 to read V1 type files.
(reminder: should use make_array instead of case statement).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/imagread.pro)
IMAGUPD
[Previous Routine]
[Next Routine]
[List of Routines]
Add an image to existing file.
Frank Varosi, U.of MD., 1988.
F.V. 1990, mod. for IDL-V2,
and added keywork /V1 to convert to V1 vartype codes (not fully consistent).
(reminder: should use make_array instead of case statement).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/imagupd.pro)
IMAGWRIT
[Previous Routine]
[Next Routine]
[List of Routines]
Create file and write image
First header records is always:
[ #X_pixels, #Y_pixels, IDL_data_type, #extra_header_recs, #images-1 ]
(specify #extra_header_recs = Nheader for later use).
Frank Varosi U.MD.1988
F.V. 1990, mod. for IDL-V2,
and added keywork /V1 to write header so V1 routines can read file.
(reminder: should use make_array instead of case statement).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/imagwrit.pro)
IMAGXY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
imagxy
PURPOSE:
Create a density image (2D histogram) from arrays of (x,y) points,
or create an image of a function from arrays of ( x, y, f(x,y) ) data.
In first case each pixel counts # of (x,y) points falling into
a 2D bin (box), thus forming an image of counters. In optional case,
each pixel is the average of all f(x,y) data falling into the box.
Boxes are determined by dividing the (x,y) range into a uniform grid.
CALLING EXAMPLES:
imh = imagxy( x, y, NPIX=64, XRAN=[0,20], YRAN=[-5,5] )
imz = imagxy( x, y, FXY=z, NPIX=[200,100] )
INPUTS:
X = array (any dimension) of x values.
Y = array of y values, should correspond to x array.
optionally, x can be of the form [[x],[y]]
containing both x and y coordinates as rows of matrix,
and then argument y should not be specified.
KEYWORDS:
XRAN and YRAN : specify the x,y range to be mapped into the image.
Common imagxy, xminc,xmaxc, yminc,ymaxc
can also specify the x,y range if keywords are not used,
otherwise the defaults = min-max ranges of x and y.
NPIXELS = 1 or 2 element integer array specifying size of result,
(single value means square image), default = [64,64].
/NOCLIP means do not bother checking if (x,y) are within range (faster).
TYPE_VAR = type code specifying the IDL variable type of result,
(1=byte, 2=short, 3=Long, 4=float,... default=2, short integer).
KEYWORDS (optional):
IMAGE_DENSITY = an existing image of counters (2D histogram)
to which the result is added (overrides NPIX=).
FXY = array giving z = f(x,y) for the purpose of binning into an image
however, bins with no (x,y) data points are left = zero.
(NOTE: must specify XRAN and YRAN, or set /NOCLIP).
if /BOTH is set and FXY=z is given, then the binned image of z=f(x,y) is
returned by function, and an image of (x,y) density is
returned via the keyword IMAGE_DENSITY.
OUTPUTS:
Result of function is an image of the density of (x,y) points, or an
image of scalar field function if z values are given at (x,y) points.
PROCEDURE:
Binning is performed by finding number of (x,y) duplicates
at each pixel, using the IDL sort and where functions.
HISTORY:
written Frank Varosi, U.of MD., 1988.
F.V. 1990, modif. for IDL-V2.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/imagxy.pro)
IM_STATS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
im_stats
PURPOSE:
Compute and return statistics of an image in structured variable,
including: Gaussian noise st.dev., sky (background) Level,
FWHM, centroid, min, max, rms, average of image.
CALLING:
stat_struct = im_stats( image, /GET_FWHM )
INPUTS:
image = 2D array
KEYWORDS:
BOX_SIZE = width of moving box in which to compute local variances,
then used to estimate most probable standard deviation.
NOISE_MODEL = string: "GAUSSIAN", the default, or "POISSON"
NAME = string, used in returned structure to name the image.
/PRINT_STATS causes results of analysis to be briefly printed.
GET_FWHM = estimated Full Width Half Max by one of 3 methods:
1 : Linear interpolation,
2 : nonlinear Lsq fit of Gaussian function,
3 : nonlinear Lsq fit of generalized Lorentzian function.
(if NAME contains the string "star" then GET_FWHM is set).
N_STRUCT = # of { IMAGE_STATS5 } structure to replicate and return,
overrides all other inputs.
OUTPUT:
Returns a structure containing results of statistical analysis.
EXTERNAL CALLS:
function sky_noise
function N_struct
function filter_image
function FullWid_HalfMax
COMMON BLOCKS:
common im_stats, struct
PROCEDURE:
Call functions sky_noise and FullWid_HalfMax.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
F.V.1994, set keyword /SKY_FIT in function FullWid_HalfMax.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/im_stats.pro)
INDEX_CLUMPS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Index_Clumps
PURPOSE:
Isolate groups of consecutive subscripts.
Procedure returns two arrays: Clump_Beg and Clump_End
which specify all the consecutive runs in the input array SubScripts.
The consecutive subscripts are then given by the Loop:
for j=0,n_elements(Clump_Beg)-1 do begin
SubClump = SubScripts( Clump_Beg(j):Clump_End(j) )
CALLING:
Index_Clumps, SubScripts, Clump_Beg, Clump_End, NOSINGLE= , COUNT=
INPUT:
SubScripts = array of numbers.
KEYWORDS:
COUNT = the number of clumps found (output).
/NOSINGLE : ignore trivial clumps of one subscript.
OUTPUTS:
Clump_Beg = indices of clump beginings.
Clump_End = indices of clump endings.
PROCEDURE:
Apply the where function.
HISTORY:
Written: Frank Varosi NASA/GSFC 1991.
FV 1997, fixed for the case of just one subscript.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/index_clumps.pro)
INTERLEAVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
InterLeave
PURPOSE:
Determine the interleaving of two arrays of numbers,
by returning subscripts of the interleaving elements,
basically binning the array B into bins defined by array A.
Note that the input arrays can be in any order (non-sorted), but
for using result of this function you probably want A sorted first.
CALLING:
Locs = InterLeave( A, B )
INPUTS:
A = the reference grid array of numbers.
B = array of numbers to interleave with A.
OUTPUT:
Function returns an integer array of same length as input B,
containing for each element of B the subscript of the element in A
which is less than (or equal) and closest to that element of B.
If there is no element of A less than or equal to an element of B
that subscript is set to -1.
KEYWORD:
NBINS = optional output, # how many bins of grid A were occupied.
EXTERNAL CALLS:
function Fsort (to sort and keep original order if equal).
PROCEDURE:
Proceed as in the beginning of pro match (by D.Lindler),
but then find interleave locations by observing jumps in flag array.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/interleave.pro)
INTERPOLATE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
interpolate
PURPOSE:
Linearly interpolate vectors with a regular or irregular grid.
CALLING SEQUENCE:
Result = interpolate( V, U )
INPUTS:
V: The input vector can be any type except string.
U: The absicissae values for the result. The result will have
the same number of elements as U, does not need to be monotonic.
KEYWORDS:
X = the grid of V, default is x = findgen( N_elements( V ) ).
OUTPUTS:
Interpolate returns a floating-point vector of N points determined
by linearly interpolating the input vector.
MODIFICATION HISTORY:
Written, DMS, October, 1982.
Modified, Rob at NCAR, February, 1991. Made larger arrays possible
and corrected by using long indexes into the array.
Mod by F.V. 1993 to emulate the interpolate function for sun386i.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/interpolate.pro)
INTERSECTION
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
intersection
PURPOSE:
Function to determine if two intervals, boxes, cubes, etc. intersect.
If so, return 1 = true and the Locations of intersection within each.
CALLING:
intersect_flag = intersection( boxA, boxB, sectionA, sectionB )
INPUTS:
boxA, boxB = vectors or matrices, of form:
[ [ Left-endpoint , Right-endpoint ] X (# dimensions) ]
OUTPUTS:
sectionA, sectionB = optional, vectors or matrices, same form as input,
but endpoints are now the starting & ending Locations
of the intersection within each box, so they can be used
to extract the intersection from each box.
The function returns 1 if intersection exists, otherwise returns 0.
PROCEDURE:
Check the cases for 1-D, then apply recursively for higher dimensions.
HISTORY:
Written: Frank Varosi NASA/GSFC 1993.
F.V. 1996, bug fix: changed one LE to LT and one GE to GT.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/intersection.pro)
IT_GET_COLOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
it_get_color
PURPOSE:
Returns the color index associated with an item,
so that:
plot,x,y,COLOR = it_get_color( "data" )
will make a graph using with cyan lines/symbols.
The first 7 default items are the colors themselves, so that:
plot,x,y,COLOR = it_get_color( "green" )
will make a graph using with green lines/symbols.
Item colors are assigned with pro it_set_color,
and pro Seven_Colors must be called first.
CALLING:
color_index = it_get_color( item, color )
INPUTS:
item = string, users name of item (default = "white")
OUTPUTS:
color = string (optional), the name of primary color.
Function returns the index in lookup color table associated with item.
If item is not found then the index for white is returned.
COMMON BLOCKS:
common seven_color_it, it_color
EXTERNAL CALLS:
function N_struct
PROCEDURE:
Straightforward.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/it_get_color.pro)
IT_SET_COLOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
it_set_color
PURPOSE:
Associate an item with any of the 7 primary colors:
"red","yellow","green","cyan","blue","violet","white".
Examples:
it_set_color, "model", "green"
it_set_color, "data", "cyan"
This info is saved in common block.
Then function it_get_color returns the color index associated with
any item, so that:
plot,x,y,COLOR = it_get_color( "data" )
will make a graph using with cyan lines/symbols.
Note that pro Seven_Colors must be called first.
CALLING:
it_set_color, item, color
INPUTS:
item = string, users name of item.
color = string, one of:
"red","yellow","green","cyan","blue","violet","white".
KEYWORDS:
None.
OUTPUTS:
None.
COMMON BLOCKS:
common seven_colors, colors
common seven_color_it, it_color
EXTERNAL CALLS:
function N_struct
PROCEDURE:
Straightforward.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/it_set_color.pro)
KILL_WINDOWS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
kill_windows
PURPOSE:
Delete window(s), first checking if window(s) actually exists,
thus avoiding accidental error trap.
CALLING:
win_stat = kill_windows( winum )
INPUTS:
winum = integer scalar or array, window number(s) to delete
(if undefined, then nothing happens and (-1) is returned).
OUTPUTS:
Function always returns a scalar or array of (-1), same size as input.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/kill_windows.pro)
LEE_FILT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Lee_filt
PURPOSE:
Performs the Lee filter algorithm on the input
image (or vector) using a box of side 2*radius+1.
CATEGORY:
E3 Smoothing (image)
CALLING SEQUENCE:
Result = Lee_filt( image, radius, sigma )
INPUTS:
image = Input image array or one dimensional vector
radius : Side of filter box = 2*radius+1. Default value = 1.
sigma = Estimate of the standard deviation. Def = average Var of image.
OUTPUTS:
Function returns the result of the filtering,
optional output is variance of image, if requested in arg.list.
PROCEDURE:
The LEE (Computer Graphics 197?) technique smooths additive
image noise by generating statistics in a local neighborhood
and comparing them to the expected values:
Var( image ) * image + Smooth( image ) * sigma
filter = ------------------------------------------------
Var( image ) + sigma
Code reformulates above with adds & subtracts instead of multiplies.
MODIFICATION HISTORY:
Written, 24-Nov-1982, R. A. Howard, Naval Research Lab, Wash.DC 20375
Modified, Jan.1991, Frank Varosi, STX @ NASA/GSFC, cleaned it up.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/lee_filt.pro)
LLSQ1D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
LLsq1D
PURPOSE:
Linear Least-squares approximation in one-dimension (y = a + b*x).
CALLING EXAMPLE:
LLsq1D, x, y, A, B, [ sigmas, covar, chi_sq, Y_SIGMA=sigmay ]
INPUTS:
x = array of values for independent variable.
y = array of data values assumed to be linearly dependent on x.
KEYWORDS:
Y_SIGMA = scalar or array specifying the standard deviation of y data,
if not given, assumed to be unity, and then
sqrt( chi_sq/Ndata ) can be an estimate of Y_SIGMA.
OUTPUTS:
A_intercept = constant parameter result of linear fit,
B_slope = slope parameter, so that:
( A_intercept + B_slope * x ) approximates the y data.
OPTIONAL OUTPUT:
sigma_A_B = two element array giving standard deviation of
A_intercept and B_slope parameters, respectively.
covariance_A_B = co-variance of A_intercept and B_slope parameters.
chi_sq = resulting minimum Chi-Square of Linear fit.
PROCEDURE:
Standard algorithm.
Uses transform to reduce roundoff errors (cf. Numerical Recipes).
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/llsq1d.pro)
LOCAL_VARIANCE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Local_Variance
PURPOSE:
Compute Local variances of data array (spectrum, image) in a moving box,
of width specified by keyword BOX_WIDTH.
CALLING:
Locvar = Local_Variance( data )
INPUT:
data = array of numbers (vector, image, etc.)
KEYWORDS:
BOX_WIDTH = the width in pixels of moving box
in which to compute local variances, default=3.
MEAN_MEDIAN=
/USE_MEDIAN
OUTPUTS:
Function returns the corresponding array of local variances.
PROCEDURE:
Call the IDL smooth function twice.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/local_variance.pro)
LOCATE_PEAK
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi STX @ NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/locate_peak.pro)
LOC_FILE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
loc_file
PURPOSE:
get files from a set of directories
CATEGORY:
help
CALLING SEQUENCE:
fname=loc_file(file,path=path,loc=loc,count=count,all=all)
INPUTS:
file : file name
KEYWORDS:
loc : directory locations of found files
path : array or scalar string with directory name(s)
count : number of found files
all : search all directories
PROCEDURE:
Uses FINDFILE
HISTORY:
Written Dec'92 (DMZ,ARC)
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/loc_file.pro)
LOOK_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Look_image
PURPOSE:
Compute and optionally print mean & standard deviation of pixel values
in a box or circle centered at (xi,yi) of image array.
(Usually called by pro Look_images).
CALLING:
Look_image, image, xi,yi, box_size, mean, stdev, imtot, npix
INPUTS:
image = 2D array
xi, yi = pixel Location of box/circle center.
box_size = width of square box (diameter of circle), in pixels, def=5.
OUTPUTS:
mean = the mean of pixel values in box/circular region.
stdev = the standard deviation of pixel values in box/circular region.
imtot = total of pixel values in box/circular region.
npix = # of pixels in box/circular region.
KEYWORDS:
/CIRCULAR : use circular region instead of box.
/PRINT : causes mean and st.dev. to be printed, default = 0,
if PRINT=2 then pixel values in box are also printed.
/FWHM_PRINT : print the Full-Width-Half-Max of data in box.
/LOG10 : assume input image is in Log10 units, so print 10.^image vals.
BOX_WIDTH = optional way to specify size of box,
1 integer for square box, 2 integers for rectangular box.
RADIUS = optional way to specify box/circle in terms of it radius.
BORDER = # of pixels at edge of image to ignore, default = 0.
XOFF, YOFF = optional offset of image in some bigger image,
used when printing pixel locations only, default=(0,0).
EXTERNAL CALLS:
function FullWid_HalfMax (if /FWHM_PRINT)
function Disk_Region (if /CIRC)
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1989, added keyword BORDER to limit (xi,yi) within image.
F.V. 1990, added keyword CIRCULAR for optional circular region.
F.V. 1991, fixed bug with printing pixvals when box is at top edge.
F.V. 1996, fixed bug with /CIRCULAR option, off by one pixel.
F.V. 1997, use function Disk_Region for /CIRCULAR option.
F.V. 1999, added /LOG10 option.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/look_image.pro)
LORENTZIAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Lorentzian
PURPOSE:
Evaluate the generalized Lorentzian function.
(also known as Cauchy function).
CALLING EXAMPLES:
y = Lorentzian( xi, parms )
y = Lorentzian( xi, parms, pderiv )
INPUTS:
xi = array, indepented variable
parms = array, generalized Lorentzian (Cauchy) function parameters (5):
OUTPUT (optional):
pderiv = matrix of partial derivatives respect to parameters.
PROCEDURE:
Case of dimension breakdown.
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
F.V.1994, added optional sixth parameter = constant offset.
F.V.1994, generalized to 2-D and 3-D.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/lorentzian.pro)
MAKE_HELP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
make_help
PURPOSE:
Create IDL help files for routines in all sub-directories,
one help file for each sub-directory.
CALLING SEQUENCE:
make_help, DIR_ROOT="main_directory"
KEYWORDS:
DIR_ROOT= string giving name of directory in which sub-directories,
containing IDL routines, reside.
RESULT:
An IDL help file will be created for each sub-directory,
the name of each help file is name of sub-directory + ".help".
EXTERNAL CALLS:
function find_dirs
pro mk_Library_Help
PROCEDURE:
Get sub-directory names and
call mk_Library_Help for each sub-directory.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/make_help.pro)
MAP_VAR_TYPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
map_var_type
PURPOSE:
Map a variable to memory location of different type, but no conversion.
Not for use with strings or structures since
they do not have predetermined size.
CALLING:
vmem = map_var_type( variable, nout, TYPE_CODE_OUT=type_out )
INPUTS:
variable = array, the variable to be memory mapped.
KEYWORDS:
TYPE_CODE_OUT = the desired type code of returned array.
OUTPUTS:
nout = # elements actually returned and valid.
Returns an array of requested type containing the input variable
with no conversion.
EXTERNAL CALLS:
function N_bytes_vtype
HISTORY:
Written, Frank Varosi NASA/GSFC 1994.
F.V.1995, added case for double complex variable type.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/map_var_type.pro)
MATCH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
match
PURPOSE:
Routine to match values in two arrays,
by returning subscripts of the matching values.
The subscripts can be returned in 3 kinds of original orders
(see keyword /ORIGINAL for options).
Duplicates can be ignored in the matching process,
or they can be accounted for completely in the first array,
(see keywords). If desired option is not specified,
duplicates may or may not be matched by the straight algorithm.
CALLING SEQUENCE:
match, a, b, suba, subb
INPUTS:
a, b - two arrays in which to find matching elements
KEYWORDS:
COUNT = number of matches found (optional output).
/UNIQUE_ONLY : match only the unique values (discard duplicates).
/DUPLICATES_IN_A : account for duplicates in first input array (a),
so that duplicates get the same subscripts and each group
gets mapped to a single element of second input array (b).
RESOLUTION = maximum distance defining a match (default=0),
option used to find numbers which are almost equal,
i.e. matching up to the specified resolution.
(default is resolution=0 so only exact equality is a match).
/ORIGINAL causes matching subscripts to give elements in original order
of the first array (a), and a(suba) = b(subb).
If ORIGINAL=2 the order of b(subb) is preserved.
If ORIGINAL>2 or <0 the orders are preserved independently.
However, if /DUP then ORIGINAL>1 or <0 means just /ORIGINAL.
/INFO causes informational messages on how many matches were found.
OUTPUTS:
suba = subscripts of elements in vector a with a match in vector b.
subb = subscripts of the elements in vector b with matches in vector a.
suba and subb are ordered such that a(suba) = b(subb)
with increasing values (unless /ORIGINAL_ORDER options are invoked).
EXTERNAL CALLS:
function unique (if keywords /UNIQUE or /DUPLICATES are set)
function remix (if keyword /DUPLICATES is set)
PROCEDURE:
Find matches by finding duplicates in sorted combined list,
keeping track of which element comes from which list.
For the /DUPLICATES_IN_A option, repeatedly match and remove duplicates.
HISTORY:
D. Lindler 1986.
F. Varosi, 1990, optimized storage: flag = byte array, dup is reused.
added option to find matches within RESOLUTION bin size.
F. Varosi, 1992, added /ORIGINAL_ORDER and COUNT= options.
F. Varosi, 1995, added /UNIQUE_ONLY and /DUPLICATES_IN_A options.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/match.pro)
MENUS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Menus
PURPOSE:
Implement a crude menu facility using character strings
at the bottom of a window.
CALLING SEQUENCE:
Choice = Menus( fcn, choices, help_str )
INPUTS:
fcn = 0 to draw choices on bottom of window, fcn is then set = 0.
fcn = 1 to select a choice, and to "unhighlight" previous choice.
Choices = string array containing text for each choice.
Help_str = string array of same # elements as choices. Help text is
displayed on top of the window if the corresponding choice is made.
INITSEL = choice # to have initially pre-selected before user selects.
OUTPUTS:
Function output = choice, from 0 to # of elements in string arrays -1.
If the right button is pressed, -1 is returned to indicate done.
COMMON BLOCKS:
menus_common = our common
SIDE EFFECTS:
Text is written on the current window display.
MODIFICATION HISTORY:
Dms, Dec, 1987.
DMS, April, 1989, added check for button debouncing (see repeat until).
FV, 1990, added INITSEL & Location of choices based on string Lengths.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/menus.pro)
MERGE_SUM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Merge_Sum
PURPOSE:
Compute the sum of two tabulated functions having different grids
for the independent variable. Function values are interpolated
onto a common grid created by merging the two different grids.
CALLING:
Merge_Sum, x1, f1, x2, f2, xm, fm
INPUTS:
x1, x2 = the two different independent variable grids for f1 & f2.
f1, f2 = the arrays of function values to be summed, defined on x1 & x2.
OUTPUTS:
xm = grid created by unique merging the two grids x1 & x2.
fm = f1 + f1 on new grid xm.
KEYWORDS:
/EXPONENTIAL_INTERP: perform interpolation/extrapolation in Log-Linear
space, thereby giving correct result for exponential function.
/POWER_LAW_INTERP: perform interpolation/extrapolation in Log-Log space,
thereby giving correct result for power-law function.
/EXTRAPOLATE: allow extrapolation of function values beyond given range,
default is NO extrapolation, assuming zeros out of range.
EXTERNAL CALLS:
function finterpol
PROCEDURE:
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1998.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/merge_sum.pro)
MINF_BRACKET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
minF_bracket
PURPOSE:
Bracket a local minimum of a 1-D function with 3 points,
thus ensuring that a minimum exists somewhere in the interval.
This routine assumes that the function has a minimum somewhere....
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is bracketed,
This routine is called by minF_conj_grad, to bracket minimum in the
direction of the conjugate gradient of function of many variables
CALLING EXAMPLE:
xa=0 & xb=1
minF_bracket, xa,xb,xc, fa,fb,fc, FUNC_NAME="name" ;for 1-D func.
or:
minF_bracket, xa,xb,xc, fa,fb,fc, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa = scalar, guess for point bracketing location of minimum.
xb = scalar, second guess for point bracketing location of minimum.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa,xb,xc) are then relative distances from POINT_NDIM.
OUTPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
OPTIONAL OUTPUT:
fa,fb,fc = value of function at 3 points which bracket the minimum,
again note that fb < fa and fb < fc if minimum exists.
PROCEDURE:
algorithm from Numerical Recipes (by Press, et al.), sec.10.1 (p.281).
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/minf_bracket.pro)
MINF_CONJ_GRAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
minF_conj_grad
PURPOSE:
Find the local minimum of a scalar function of several variables using
the Conjugate Gradient method (Fletcher-Reeves-Polak-Ribiere algorithm).
Function may be anything with computable partial derivatives.
Each call to minF_conj_grad performs one iteration of algorithm,
and returns an N-dim point closer to the local minimum of function.
CALLING EXAMPLE:
p_min = replicate( 1, N_dim )
minF_conj_grad, p_min, f_min, conv_factor, FUNC_NAME="name",/INITIALIZE
while (conv_factor GT 0) do begin
minF_conj_grad, p_min, f_min, conv_factor, FUNC_NAME="name"
endwhile
INPUTS:
p_min = vector of independent variables, location of minimum point
obtained from previous call to minF_conj_grad, (or first guess).
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px, gradient )
where:
F = scalar value of function at px.
px = vector of independent variables, input.
gradient = vector of partial derivatives of the function
with respect to independent variables, evaluated at px.
This is an optional output parameter:
gradient should not be calculated if parameter is not
supplied in call (Unless you want to waste some time).
/INIT must be specified on first call (whenever p_min is a guess),
to initialize the iteration scheme of algorithm.
/USE_DERIV causes the directional derivative of function to be used
in the 1-D minimization part of algorithm
(default is not to use directional derivative).
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
/QUADRATIC runs simpler version which works only for quadratic function.
OUTPUTS:
p_min = vector giving improved solution for location of minimum point.
f_min = value of function at p_min.
conv_factor = gives the current rate of convergence (change in value),
iteration should be stopped when rate gets near zero.
EXTERNAL CALLS:
pro minF_bracket, to find 3 points which bracket the minimum in 1-D.
pro minF_parabolic, to find minimum point in 1-D.
pro minF_parabol_D, to find minimum point in 1-D, using derivatives.
COMMON BLOCKS:
common minf_conj_grad, grad_conj, grad_save, gs_norm
(to keep conjugate gradient, gradient and norm from previous iteration)
PROCEDURE:
Algorithm adapted from Numerical Recipes, sec.10.6 (p.305).
Conjugate gradient is computed from gradient, which then gives
the best direction (in N-dim space) in which to proceed to find
the minimum point. The function is then minimized along
this direction of conjugate gradient (a 1-D minimization).
The algorithm is repeated starting at the new point by calling again.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/minf_conj_grad.pro)
MINF_PARABOLIC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
minF_parabolic
PURPOSE:
Find a local minimum of a 1-D function up to specified tolerance.
This routine assumes that the function has a minimum nearby.
(recommend first calling minF_bracket, xa,xb,xc, to bracket minimum).
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is found,
This routine is called by minF_conj_grad, to locate minimum in the
direction of the conjugate gradient of function of many variables.
CALLING EXAMPLES:
minF_parabolic, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func.
or:
minF_parabolic, xa,xb,xc, xmin, fmin, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa, xb, xc, x_min are then relative distances from POINT_NDIM)
MAX_ITER = maximum allowed number iterations, default=100.
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
OUTPUTS:
xmin = estimated location of minimum.
When working with function of N variables,
xmin is the relative distance from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION,
so that min. Loc. Pmin = Point_Ndim + xmin * Direction.
fmin = value of function at xmin (or Pmin).
PROCEDURE:
Brent's method to minimize a function by using parabolic interpolation,
from Numerical Recipes (by Press, et al.), sec.10.2 (p.285).
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/minf_parabolic.pro)
MINF_PARABOL_D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
minF_parabol_D
PURPOSE:
Find a local minimum of a 1-D function up to specified tolerance,
using the first derivative of function in the algorithm.
This routine assumes that the function has a minimum nearby.
(recommend first calling minF_bracket, xa,xb,xc, to bracket minimum).
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is found,
This routine is called by minF_conj_grad, to locate minimum in the
direction of the conjugate gradient of function of many variables.
CALLING EXAMPLES:
minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func.
or:
minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px, gradient )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
gradient = derivative of function, a scalar if 1-D,
a gradient vector if N-D,
(should only be computed if arg. is present).
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa, xb, xc, x_min are then relative distances from POINT_NDIM)
MAX_ITER = maximum allowed number iterations, default=100.
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
OUTPUTS:
xmin = estimated location of minimum.
When working with function of N variables,
xmin is the relative distance from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION,
so that min. Loc. Pmin = Point_Ndim + xmin * Direction.
fmin = value of function at xmin (or Pmin).
PROCEDURE:
Brent's method to minimize a function by using parabolic interpolation
and using first derivative of function,
from Numerical Recipes (by Press, et al.), sec.10.3 (p.287),
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/minf_parabol_d.pro)
MINMAX_HISTO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MinMax_Histo
PURPOSE:
Determine suitable min & max range which rejects requested fraction
of data values that are at the low and high extremes.
CALLING:
MinMax_Histo, data, hmin, hmax
INPUTS:
data
KEYWORDS:
REJECT_FRACTION = fraction of extremes to reject, default = 0.001
NBIN = default is 2000.
VALUES = optional returned histogram bin values.
HACCUMULATE = optional returned accumulated histogram
OUTPUTS:
hmin, hmax = min & max range which rejects requested fraction
of data values that are at the low and high extremes.
EXTERNAL CALLS:
function Histo
function accumulate
PROCEDURE:
Accumulate and normalize the histogram and use where function.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/minmax_histo.pro)
MODIFY_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
Smooth all pixels using iteration (approaches gaussian convolution),
apply requested normalizing (max=1), thresholding and/or raising to power.
Frank Varosi 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/modify_image.pro)
MODPOS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
modpos
PURPOSE:
Apply the MOD operator to array, but keep result positive, or
optionally, centered around zero in a periodic interval fashion.
CALLING EXAMPLES:
To MOD into interval [0,1] :
xmod = modpos( xin, WRAP=1 )
To MOD into interval [-1,1] :
xmod = modpos( xin, WRAP=1, /ZERO_CENT )
so that in all cases interval has periodic boundary conditions.
INPUTS:
xin = array to MOD.
KEYWORDS:
WRAP_VALUE = scalar, determines the interval from [0,wrap]
or [-wrap,wrap] if /ZERO set (default: wrap = 2 * !pi ).
/ZERO_CENTERED : keep result in periodic interval centered on zero.
RESULT:
Function returns the array shifted to be in specified interval.
PROCEDURE:
Just check for negative values and shift by the wrap.
The zero-centered case is done by recursive call to modpos and shifting.
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/modpos.pro)
MSORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MSORT
PURPOSE:
Return a matrix of subscripts which will sort into ascending order
the columns of a matrix. Columns are the last index: matrix(i,*).
CALLING:
order_subscripts = msort( matrix )
or:
matrix = msort( matrix, /SORT_NOW ) ;to perform the sort.
INPUT:
matrix = 2-D matrix to be sorted.
KEYWORDS:
/SORT_NOW : result is matrix with sorted columns.
/DESCENDING = descending order instead of the default ascending order.
OUTPUT:
Subscripts which give sorted order are returned as function value,
or the actual sorted matrix if /SORT is specified.
OPTIONAL OUTPUT:
order_column = order indices for each column seperately.
METHOD:
When Nitem per column < 9 applies bubble-sort with gather/scatter
(using WHERE function), otherwise just loop over all columns.
HISTORY:
Frank Varosi U.Md. 1988.
F.V. NASA/GSFC 1991, adapted to IDL-v.2
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/msort.pro)
MULTIPLOT
[Previous Routine]
[Next Routine]
[List of Routines]
Name:
MULTIPLOT
Purpose:
Create multiple plots with shared axes.
Explanation:
This procedure makes a matrix of plots with *SHARED AXES*, either using
parameters passed to multiplot or !p.multi in a non-standard way.
It is good for data with one or two shared axes and retains all the
versatility of the plot commands (e.g. all keywords and log scaling).
The plots are connected with the shared axes, which saves space by
omitting redundant ticklabels and titles. Multiplot does this by
setting !p.position, !x.tickname and !y.tickname automatically.
A call (multiplot,/reset) restores original values.
Note: This method may be superseded by future improvements in !p.multi
by RSI. For now, it's a good way to gang plots together.
CALLING SEQUENCE:
multiplot[pmulti][,/help][,/initialize][,/reset][,/rowmajor]
Examples:
multiplot,/help ; print this header.
; Then copy & paste, from your xterm, the following lines to test:
x = findgen(100) ; MULTIPLOT
t=exp(-(x-50)^2/300) ; -------------------------
erase ; | | |
u=exp(-x/30) ; | | |
y = sin(x) ; | UL plot | UR plot |
r = reverse(y*u) ; | | |
!p.multi=[0,2,2,0,0] ; | | |
multiplot ; y-------------------------
plot,x,y*u,title='MULTIPLOT' ; l| | |
multiplot & plot,x,r ; a| | |
multiplot ; b| LL plot | LR plot |
plot,x,y*t,ytit='ylabels' ; e| | |
multiplot ; l| | |
plot,x,y*t,xtit='xlabels' ; s-------------------------
multiplot,/reset ; xlabels
wait,2 & erase ; TEST
multiplot,[1,3] ; H------------------------
plot,x,y*u,title='TEST' ; E| plot #1 |
multiplot ; I------------------------
plot,x,y*t,ytit='HEIGHT' ; G| plot #2 |
multiplot ; H------------------------
plot,x,r,xtit='PHASE' ; T| plot #3 |
multiplot,/reset ; ------------------------
; PHASE
multiplot,[1,1],/init,/verbose ; one way to return to single plot
% MULTIPLOT: Initialized for 1x1, plotted across then down (column major).
Optional Inputs:
pmulti = 2-element or 5-element vector giving number of plots, e.g.,
multiplot,[1,6] ; 6 plots vertically
multiplot,[0,4,2,0,0] ; 4 plots along x and 2 along y
multiplot,[0,4,2,0,1] ; ditto, except rowmajor (down 1st)
multiplot,[4,2],/rowmajor ; identical to previous line
Optional Keywords:
help = flag to print header
initialize = flag to begin only---no plotting, just setup,
e.g., multiplot,[4,2],/init,/verbose & multiplot & plot,x,y
reset = flag to reset system variables to values prior to /init
default = flag to restore IDL's default value for system variables
rowmajor = flag to number plots down column first (D=columnmajor)
verbose = flag to output informational messages
Outputs:
!p.position = 4-element vector to place a plot
!x.tickname = either '' or else 30 ' ' to suppress ticknames
!y.tickname = either '' or else 30 ' ' to suppress ticknames
!p.noerase = 1
Common blocks:
multiplot---to hold saved variables and plot counter. See code.
Side Effects:
Multiplot sets a number of system variables: !p.position, !p.multi,
!x.tickname, !y.tickname, !P.noerase---but all can be reset with
the call: multiplot,/reset
Restrictions:
1. If you use !p.multi as the method of telling how many plots
are present, you have to set !p.multi at the beginning each time you
use multiplot or call multiplot with the /reset keyword.
2. There's no way to make an xtitle or ytitle span more than one plot,
except by adding spaces to shift it or to add it manually with xyouts.
3. There is no way to make plots of different sizes; each plot
covers the same area on the screen or paper.
Procedure:
This routine makes a matrix of plots with common axes, as opposed to
the method of !p.multi where axes are separated to allow labels.
Here the plots are joined and labels are suppressed, except at the
left edge and the bottom. You tell multiplot how many plots to make
using either !p.multi (which is then reset) or the parameter pmulti.
However, multiplot keeps track of the position by itself because
!p.multi interacts poorly with !p.position.
Modification history:
write, 21-23 Mar 94, Fred Knight (knight@ll.mit.edu)
alter plot command that sets !x.window, etc. per suggestion of
Mark Hadfield (hadfield@storm.greta.cri.nz), 7 Apr 94, FKK
add a /default keyword restore IDL's default values of system vars,
7 Apr 94, FKK
modify two more sys vars !x(y).tickformat to suppress user-formatted
ticknames, per suggestion of Mark Hadfield (qv), 8 Apr 94, FKK
Converted to IDL V5.0 W. Landsman September 1997
Modified to use !P.region when specified. F.Varosi September 1999
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/multiplot.pro)
NEXT_WORD
[Previous Routine]
[Next Routine]
[List of Routines]
extract the first word of text string and return it,
the input string text is also returned without the first word.
text = string with words delimited by blanks.
Frank Varosi NASA/Goddard 1989
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/next_word.pro)
NINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NINT
PURPOSE:
Nearest integer function
CALLING SEQUENCE:
result = nint(x, [ /LONG] )
INPUT:
X - An IDL variable, scalar or vector, usually floating or double
Unless the LONG keyword is set, X must be between -32767.5 and
32767.5 to avoid integer overflow
OUTPUT
RESULT - Nearest integer to X
OPTIONAL KEYWORD INPUT:
LONG - If this keyword is set and non-zero, then the result of NINT
is of type LONG. Otherwise, the result is of type INTEGER
EXAMPLE:
If X = [-0.9,-0.1,0.1,0.9] then NINT(X) = [-1,0,0,1]
REVISION HISTORY:
Written W. Landsman January 1989
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/nint.pro)
NON_LIN_LSQ
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Non_Lin_Lsq
PURPOSE:
Non-linear least squares fit of a function of an
arbitrary number of parameters, to 1-D data set.
Function may be any non-linear function where
the partial derivatives are known or can be approximated.
CALLING:
Non_Lin_Lsq, Xi, Yd, Parms, sigmas, FUNC_NAME="name of function"
INPUTS:
Xi = vector of independent variables.
Yd = vector of dependent variable to be fit with func_name( Xi ),
same length as Xi.
Parms = vector of nterms length containing the initial estimate
for each parameter. If Parms is double precision, calculations
are performed in double precision, otherwise in single prec.
The initial guess of the parameter values should be as close to
the actual values as possible or the solution may not converge.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( Xi, Parms, Pderiv )
where:
F = vector of NPOINT values of function.
Xi = vector of NPOINT independent variables, input.
Parms = vector of NPARM function parameters, input.
Pderiv = array, (NPOINT, NPARM), of partial derivatives.
Pderiv(I,J) = derivative of function at ith point with
respect to jth parameter. Optional output parameter.
Pderiv should not be calculated if parameter is not
supplied in call (Unless you want to waste some time).
WEIGHTS = vector of weights, same length as x and y.
For equal (Gaussian) weighting w(i) = 1. (this is default),
instrumental (Poisson) weighting w(i) = 1./y(i), etc.
/INFO causes Chi-Sq. to be printed each iteration,
INFO > 1 causes current parameter estimates to also print.
MAX_ITER = maximum # of gradient search iterations, default=20.
TOLERANCE = ratio of Chi-Sq. change to previous Chi-Sq. at which
to terminate iterations ( default = 1.e-4 = 0.1% ).
OUTPUTS:
Parms = vector of parameters giving best fit to the data.
OPTIONAL OUTPUT PARAMETERS:
sigmas = Vector of standard deviations for parameters Parms.
chisq = final Chi-Sqr deviation of fit.
Yfit = resulting best fit to data.
CoVariance = covariance matrix for fit params.
PROCEDURE:
Copied from "CURFIT", least squares fit to a non-linear
function, pages 237-239, Bevington, Data Reduction and Error
Analysis for the Physical Sciences.
"This method is the Gradient-expansion algorithm which
compines the best features of the gradient search with
the method of linearizing the fitting function."
HISTORY:
Written, DMS, RSI, September, 1982.
Modified, Frank Varosi, NASA/GSFC, 1992, to use call_function, and
added keywords: WEIGHTS, FUNC_NAME, MAX_ITER, INFO_PRINT, TOLERANCE.
Mod, F.V. 1998, reform Pderiv array to (Ndata,1) if Nparm=1.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/non_lin_lsq.pro)
NORMALIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
normalize
PURPOSE:
Scale the input array so that Mean_Value=1 (default action),
or optionally, so Total=1, or either Max=1.
CALLING:
am1 = normalize( array )
INPUTS:
array = data to be normalized
KEYWORDS:
/TOTAL : just divide by total( array ) so that total of result =1.
/MAX : just divide by max( array ) so that maximum of result =1.
Default is to also divide by # elements so mean value =1.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/normalize.pro)
N_BYTES_VTYPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
N_bytes_vtype
PURPOSE:
Return the number of bytes in a scalar (or vector)
of specified variable type code(s), except for strings or structures
since they do not have predetermined size.
For usage example see map_var_type.pro.
CALLING:
nbytes = N_bytes_vtype( type_code )
INPUTS:
type_code = scalar or vector of IDL variable type codes (0 to 9).
KEYWORDS:
VARIABLE = optionaly give the variable and get the type_code.
OUTPUTS:
Returns the # of bytes in a single element of each given variable type,
unless the code is for strings or structures, then 99 is returned.
HISTORY:
Written, Frank Varosi NASA/GSFC 1994.
F.V.1995, added case for double complex variable type.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/n_bytes_vtype.pro)
N_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
N_struct
PURPOSE:
To determine if variable is a structure and return number of elements.
CALLING:
n = N_struct( var, ntags )
INPUT:
var = any variable.
OUTPUT:
ntags = number of structure tags.
RESULT:
Returns zero if variable is not a structure, otherwise returns # elems.
PROCEDURE:
Determine if argument is a structure by checking for # of tags.
If structure, use size function to get # of elements
(instead of N_elements) so that it works on I/O associated structures.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/n_struct.pro)
OUTLIER_FILTER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
outlier_filter
PURPOSE:
Replace outlier (bad) pixels in an image with the local mean or median.
Outliers are replaced if value exceeds N_SIGMA times local standard
deviation (assuming that good data pixels do not deviate that much).
This procedure uses the histogram of image with reverse indices
to home in on pixels that have values outside the distribution
of most pixel values, and so is faster and usually better than
function sigma_filter, except when bad pixel values are within the
distribution of good pixels.
CALLING:
outlier_filter, image, box_width, N_SIGMA=#
INPUTS:
image = 2-D array (this input will be modified).
box_width = width of square box in which to test statistics of
outlier candidate pixels, units in # pixels (default=3).
KEYWORDS:
N_SIGMA = number of standard deviations flagging outliers (float),
minimum = 1, default = 5.
STOP = integer, the checking/replacing of outliers will stop after this
number of candidates are found to be NOT outliers (default=7).
RADIUS = specify test box size with radius, so box_width = 2*radius+1.
/MEDIAN : causes the median of values in test box to be used as
the replacement value, and in estimation of standard deviation.
/NO_MIN_OUT : outlier pixels related to minimum extremes of image
are NOT checked or replaced. This takes precedence over /NO_MAX.
/NO_MAX_OUT : outlier pixels related to maximum extremes of image
are NOT checked or replaced.
/MONITOR : prints information about % of pixels replaced.
OUTPUT:
image = the input array is modified by replacing outliers as found.
KEYWORD OUTPUT:
N_CHANGE = total # of pixels changed, optional output.
NOTES:
For a flat gaussian noise image:
N_sigma = 2 replaces about 5% of pixels,
N_sigma = 3 replaces about 1% of pixels,
N_sigma = 4 replaces about 0.5% of pixels, and so on.
Setting /MEDIAN causes less pixels to be replaced and at same time
is then more successful at replacing adjacent pairs of outlier pixels.
The algorithm is semi-iterative since the image is modified during
the processing, thus changing the local deviations in test boxes,
and this feature actually helps to remove adjacent outliers.
Increasing box_width (or RADIUS) will usually replace more pixels.
Setting STOP= larger values causes more pixels to be checked and so
takes longer time, and results in more pixels being replaced,
whereas STOP=0 will replace only the maximum and/or minimum pixels
(if they are outliers, and if they occur first in reverse indices).
PROCEDURE:
Possible outliers are found using the reverse indices from the
histogram of image. Starting from the maximum bin and working down,
each outlier candidate is checked by finding the mean (or median) and
standard deviation of pixels in box centered at candidate pixel
of the image (excluding that pixel), and if the center value exceeds
specified number of standard deviations from the mean (or median),
it is replaced by the mean (or median) in box. The process is repeated
starting at the minimum bin and working to more positive values.
This method of using histograms is faster than function sigma_filter
for large images, and is more successful at removing outliers.
HISTORY:
Written, 1997, Frank Varosi, HSTX @ NASA/GSFC
FV, 8/97, for case of int/Long image, histogram binsize must be >= 1.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/outlier_filter.pro)
PATCH_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
patch_image
PURPOSE:
Create a new image by patching a region in an image
using Vertical and/or Horizontal interpolation,
with optional averaging and/or Gaussion noise added.
CALLING:
patched_image = patch_image( image, patch_coordin, direction )
INPUTS:
image = 2D array to patch.
patch_coordin = 4 element integer array specifying region to patch:
[ xcorner, xsize, ycorner, ysize ]
direction = string, H,V, or HV.
KEYWORDS:
AVERAGE = # of pixels to average outside of patch region for values
between which interpolation is computed, default=0.
GAUSSIAN_NOISE = standard deviation of Gaussian noise to add, def=0.
OUTPUTS:
Function returns array of same size as input image, and same values
except changes as requested: horizontal and/or vertical interpolation.
EXTERNAL CALLS:
function vecLinterp
PROCEDURE:
HISTORY:
Written: Frank Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/patch_image.pro)
PATCH_SURF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
patch_surf
PURPOSE:
Interactively select a circular or polygonal region in image and
then patch over the region by minimum curvature surface interpolation,
using the pixel values at edge of region to govern the interpolation.
CALLING:
im_patched = patch_surf( image )
INPUTS:
image = 2-D array of data.
KEYWORDS:
/DISPLAY causes image to be scaled and displayed in a window.
ZOOM = zoom (magnification) factor to display image.
WINDOW = window number in which image is displayed (default=0).
Default is to select arbitrary polygonal region, other options:
BOX_WIDTH = width of fixed size box to patch.
CIRCLE_RADIUS = radius of circular region to patch.
/VARY_BOX_REGION allows choosing corners of an arbitrary rectangle.
EXTRA = minimum number pixels exterior to patch region to use
in computing interpolating surface, default =1, always >1.
RXY = output 2-D array: [[xmin,ymin],[xmax,ymax]] of region used
to compute interpolating surface, containing region patched.
OUTPUTS:
Function returns a new image with region patched by interpolation,
other pixels are same as original image.
EXTERNAL CALLS:
pro tvs
pro box_draw
function box_create
function defroi
function gridxy
function get_window
function min_curve_surf
PROCEDURE:
Call function defroi (or other type) to get region to patch,
then get indices of exterior of patch region, and then by
supplying only the data in a rectangle containing the patch region, use
function min_curve_surf to interpolate throughout interior of region.
HISTORY:
Written: Frank Varosi, NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/patch_surf.pro)
POIDEV
[Previous Routine]
[Next Routine]
[List of Routines]
NAME
POIDEV
PURPOSE:
Return an integer random deviate drawn from a Poisson distribution with
a specified mean. Adapted from procedure of the same name in
"Numerical Recipes" by Press et al. (1986), Section 7.3
CALLING SEQUENCE:
result = POIDEV( xm, [ SEED = ] )
INPUTS:
xm - integer scalar or vector, specifying mean of the Poisson
distribution
OUTPUT:
result - integer scalar or vector, same size as xm
OPTIONAL KEYWORD INPUT-OUTPUT:
SEED - floating point scalar, used as the seed for the random
distribution. This keyword can be used to have POIDEV
give identical results on consecutive runs.
EXAMPLE:
(1) Add Poisson noise to an integral image array, im
IDL> imnoise = POIDEV( im)
(2) Verify the expected mean and sigma for an input value of 81
IDL> p = POIDEV( intarr(10000) + 81) ;Test for 10,000 points
IDL> print,avg(p),sigma(p)
Average and sigma of the 10000 points should be close to 81 and 9
METHOD:
For small values (< 20) independent exponential deviates are generated
until their sum exceeds the specfied mean, the number of events required
is returned as the Poisson deviate. For large (> 20) values, uniform
random variates are compared with a Lorentzian distribution function.
NOTES:
Negative values in the input array will be returned as zeros.
PROCEDURES CALLED:
GAMMLN - returns log of the Gamma function
REVISION HISTORY:
Version 1 Wayne Landsman July 1992
Added SEED keyword September 1992
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/poidev.pro)
POISSON_CURVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Poisson_Curve
PURPOSE:
Return the Poisson density function, evaluated from 0 to MAX_XV.
CALLING:
density = Poisson_Curve( Lambda_mean, xv )
INPUTS:
Lambda_mean = the mean value parameter of Poisson density.
OUTPUTS:
xv = the array of x-values at which Poisson density is evaluated.
Function returns the Poisson density curve evaluated at xv.
KEYWORDS:
MAX_XV = optional, max x-value at which to compute density,
default is about twice the mean value.
MAGNITUDES = optional, # orders of magnitude at which to cutoff the min.
PROCEDURE:
Use Gamma function and Stirlings approximation.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/poisson_curve.pro)
POISSON_NOISE
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/poisson_noise.pro)
POLY_SMOOTH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
poly_smooth
PURPOSE:
Reduce noise in 1-D data (e.g. time-series, spectrum)
but retain dynamic range of variations in the data by
applying a least squares smoothing polynomial filter,
also called the Savitzky-Golay smoothing filter.
The low-pass filter coefficients are computed by effectively
least-squares fitting a polynomial in moving window,
centered on each data point, so the new value will be the
zero-th coefficient of the polynomial. Approximate first derivates
of the data can be computed by using first degree coefficient of
each polynomial, and so on. The filter coefficients for a specified
polynomial degree and window width are computed independent of any
data, and stored in a common block. The filter is then convolved
with the data array to result in smoothed data with reduced noise,
but retaining higher order variations (better than averaging).
CALLING SEQUENCE:
spectrum = poly_smooth( data, width, DEGREE=4 )
INPUTS:
data = 1-D array, such as a spectrum or time-series.
width = total number of data points to use in filter convolution,
(default = 5, using 2 past and 2 future data points),
must be larger than DEGREE of polynomials, and a guideline is
make WIDTH between 1 and 2 times the FWHM of desired features.
KEYWORDS:
DEGREE = degree of polynomials to use in designing the filter
via least squares fits, (default DEGREE = 2), and
the higher degrees will preserve sharper features.
NLEFT = # of past data points to use in filter convolution,
excluding current point, overrides width parameter,
so that width = NLEFT + NRIGHT + 1. (default = NRIGHT)
NRIGHT = # of future data points to use (default = NLEFT).
DERIV_ORDER = order of derivative desired (default = 0, no derivative).
COEFFICIENTS = optional output of the filter coefficients applied,
but they are all stored in common block for reuse, anyway.
RESULTS:
Function returns the data convolved with polynomial filter coefs.
COMMON BLOCKS:
common poly_smooth, degc, nlc, nrc, coefs, ordermax
PROCEDURE:
As described in Numerical Recipies, sec.14.8, Savitsky-Golay filter.
Matrix of normal eqs. is formed by starting with small terms
and then adding progressively larger terms (powers).
The filter coefficients of up to derivative ordermax are stored
in common, until the specifications change, then recompute coefficients.
Coefficients are stored in convolution order, zero lag in the middle.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/poly_smooth.pro)
PRIME
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PRIME
PURPOSE:
Return an array with the specified number of prime numbers.
CATEGORY:
CALLING SEQUENCE:
p = prime(n)
INPUTS:
n = desired number of primes. in
KEYWORD PARAMETERS:
OUTPUTS:
p = resulting array of primes. out
COMMON BLOCKS:
PRIME_COM
NOTES:
Note: Primes that have been found in previous calls are
remembered and are not regenerated.
MODIFICATION HISTORY:
RES 17 Oct, 1985.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/prime.pro)
PRINTW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
printw
PURPOSE:
Use window as a non-scrolling text screen and print one string per line.
CALLING:
printw, strings
INPUT:
strings = string array to be printed in window.
KEYWORDS:
LINE = starting point as # lines from top of window if negative,
# lines from bottom of window if non-negative.
(LINE=-1 is at top and LINE=0 is at bottom, default value is -1)
XOFFSET = horizontal shift by # characters to right each line (deflt=1).
COLOR = color table index to use for graphics.
WINDOW = window number to set and show before output (default=current).
/ERASE : first erase the region to be occupied by text,
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/printw.pro)
PRINT_GRAPHICS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
print_graphics
PURPOSE:
Spawn UNIX lpr command to send file to printer.
CALLING:
print_graphics, fileps, PS_mode
INPUTS:
fileps = string, the file name.
PS_mode = optional string, "color" to indicate color printer queue.
KEYWORDS:
N_COPY = integer, # of copies to print, default = 1.
QUEUE = string, send to a particular printer queue instead of default.
OUTPUTS:
None.
EXTERNAL CALLS:
function next_word
function VarType
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1990.
F.V.1996, added keyword QUEUE.
F.V.1997, use optional environment vars PR_QUE_COLOR and PR_QUE_BW.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/print_graphics.pro)
PRINT_STATS
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/print_stats.pro)
PRINT_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
print_struct
PURPOSE:
Print the tag values of an array of structures in nice column format,
with header line of tag names.
CALLING:
print_struct, structure, Tags_to_print [ , title, string_matrix ]
INPUTS:
structure = array of structured variables
Tags_to_print = string array specifying the names of tags to print.
Default is to print all tags which are not arrays.
KEYWORDS:
FILE = string, optional file name to which output will then be written.
LUN_OUT = Logical unit number for output to an open file,
default is to print to standard output.
TNUMS = tag numbers to print (alternative to specifying tag names).
TRANGE = [beg,end] tag number range to print.
FRANGE = same as TRANGE.
WHICH = optional array of subscripts to select
which structure elements to print.
FORM_FLOAT = string array of three elements specifying
floating point format, ex: FORM=['f','9','2'] means "(F9.2)",
(default float format is G12.4).
MAX_ELEMENTS = positive integer, print only tags that have less than
this number of elements (default is no screening).
/STRINGS : instead of printing, return the array of strings in
fourth argument of procedure: string_matrix.
/TWILD : use the `wildcard' approach to matching tag names,
so that all tag names whose first characters match
the characters in the requested tag are printed.
OUTPUTS:
title = optional string, list of tags printed/processed.
string_matrix = optional output of string matrix of tag values,
instead of printing to terminal or file, if /STRINGS.
EXTERNAL CALLS:
function N_struct
function unique
PROCEDURE:
Check the types and lengths of fields to decide formats,
then loop and form text string from requested fields, then print.
HISTORY:
Written: Frank Varosi NASA/GSFC 1991.
F.V.1993, fixed up the print formats.
F.V.1994, added more keyword options (TNUMS, TRANGE, /STRINGS,...).
F.V.1997, added WHICH and MAX_ELEM keyword options.
F.V.1998, added /COLUMN keyword option (needs more work).
F.V.1999, added /TWILD keyword option and improved /COLUMN.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/print_struct.pro)
PROBE_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
probe_image
PURPOSE:
Interactively select box Location/size with cursor (Left mouse button),
compute and optionally print, mean, st.dev. of image pixels in box.
Options include variable box/rectangle and display of
integrated X & Y profiles as stacked plots. (Quit with right button).
CALLING:
probe_image, image, xi,yi, box_size, mean, stdev, npix
INPUTS:
image = 2D array
OUTPUTS:
xi, yi = Location of box that was analyzed (lower left corner).
box_size = size of box that was analyzed.
mean = the mean of pixel values in box region.
stdev = the standard deviation of pixel values in box region.
npix = # of pixels in image region.
KEYWORDS:
BOX_WIDTH = size of box, 1 or 2 integers.
RADIUS = optional way to specify box in terms of it radius (or radii).
WINDOW = # of window in which image is displayed, default = current.
MAGF = magnification/reduction of displayed image, default = 1.
XPOS, YPOS = position of displayed image in window, default = (0,0).
XOFF, YOFF = optional offset of image in some bigger image,
used when printing pixel locations only, default=(0,0).
/VARIABLE_BOX : allow user to create a rubber-band box with
Left - Middle mouse button combination marking corners.
/DOUBLE_BOX : box is drawn as 2 rectangles,
outer is dark, (min color index),
inner is bright (max color index),
to help assure visibility against any background.
/CONTINUOUS : cursor location is read continuously, no-wait for click.
/FWHM_PRINT : print the Full-Width-Half-Max of data in box.
/PROFILES : average box of data in X & Y projections and make 2 plots.
/SHOWINDOW : make image display window visible.
/DISPLAY_IMAGE : first scale and display the image in a window.
/LOG10 : use Log base 10 scaling.
/PRINT : causes mean and st.dev. to be printed, default = 0,
if PRINT=2 then pixel values in box are also printed.
If /LOOP then results are always printed.
EXTERNAL CALLS:
pro box_draw
pro box_erase
function box_create (if /VARIABLE_BOX)
pro tvs (if /DISPLAY)
pro get_window (if /PROFILES or /DISPLAY)
function VarType
function FullWid_HalfMax (if /FWHM_PRINT or /PROFILES)
function probe_imag_menu
COMMON BLOCKS:
common probe_image(n) where n = blank, 0, ..., 5.
PROCEDURE:
Loop over cursor query code.
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
F.V. 1993, profile plots option.
F.V. 1994, added options for profile plot: see function probe_imag_menu.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/probe_image.pro)
PROBE_IMAG_CURS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
probe_imag_curs
PURPOSE:
Display the values in probe_image profiles at cursor location.
CALLING:
probe_imag_curs
INPUTS:
No explicit inputs, all info in common blocks.
OUTPUTS:
No explicit outputs, info is written to profile plot window.
EXTERNAL CALLS:
function Trp3D
function strconcat
function intersection
COMMON BLOCKS:
common probe_image, winprof
common probe_image3, save_P, save_X, save_Y
PROCEDURE:
Loop over cursor query code.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/probe_imag_curs.pro)
PROBE_IMAG_MENU
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
probe_imag_menu
PURPOSE:
Change the options/state of profile plots for pro probe_image.
CALLING:
return_task = probe_imag_menu( xcrs, ycrs )
INPUTS:
xcrs, ycrs = optional, Location for cursor set at return (device coord.)
All other info taken from common blocks.
OUTPUTS:
Function returns a string telling what to do next in probe_image.
EXTERNAL CALLS:
pro X_Var_Edit
pro probe_imag_curs
pro psport
function next_word
function get_words
function get_text_input
PROCEDURE:
Loop over cursor query code.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/probe_imag_menu.pro)
PROFILE - EXTRACT A PROFILE FROM AN IMAGE.
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Profile - Extract a profile from an image.
PURPOSE:
Allow the operator to mark two points on the image display
with the cursor/mouse/joystick.
The profile Line is defined by
using the marked points as endpoints of a Line, or,
if /CENTER is specified,
the First point defines the center of a Line,
second point defines one endpoint of the Line,
other endpoint automatically taken in equal and opposite direction.
Image values at points along the Line are extracted and returned .
Optionally return the X and Y values of each extracted point.
CATEGORY:
??
CALLING SEQUENCE:
Result = Profile( Image, XX, YY )
INPUTS:
Image = data array. May be any type except complex.
Operator then enters locations of end points of profile.
Optional Input:
xx, yy = each with exactly 2 elements giving
Location of profile end points, then skip interactive choice.
KEYWORD PARAMETERS:
XSTART, YSTART = starting (x,y) location of lower left corner of image.
/NOMARK to inhibit marking the image with the line.
MAGF = magnification of displayed image (default=1).
WINDOW = window number in which image is displayed (default is current)
/CENTER to specify center of Line and one endpoint.
INFO = optional window number to display instructions.
OUTPUTS:
Function result = floating vector containing data points.
xx, yy = Locations of profile cut thru image.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Cursor on image display is enabled.
PROCEDURE:
Straightforward. Calls function DRAW_MARK.
MODIFICATION HISTORY:
Written, DMS, November, 1982.
Modified for Sun, march, 1988.
Mod, FV, 4/1990: options to specify Magnification in display Window,
and to specify profile cut by center and one endpoint.
Mod, FV, 1/1991: call function draw_mark.
Mod, FV, 7/1991: if XX & YY are input with 2 elements, each, then
skip interactive and just extract the profile.
Mod, FV, 1998: added keyword NPIX which return # of pixels extracted,
also can now handle arbitrary (out of image) xx & yy inputs,
in which case only the valid pixels are returned.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/profile.pro)
PROFILES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: PROFILES
PURPOSE:
Interactively draw row (horizontal) or column (vertical) profiles
of an image into a separate window.
CATEGORY:
Image analysis
CALLING SEQUENCE:
PROFILES, Image, sx = sx, sy = sy, WSIZE=wsize, MAGF=magf, WINDOW=windo
INPUTS:
Image = image data of image displayed in current window.
Data need not be scaled into bytes. I.e. it may be
floating. The profile graphs are made from this array.
KEYWORD PARAMETERS:
sx = Starting X of image as displayed in window, default = (0,0).
sy = starting Y of displayed image.
Magf = magnification (integer factor) of displayed image (default=1),
can be 2 element vector for separate x and y magnifications.
Window = window number in which image is displayed (default is current)
Wsize = size of new window as a fraction or multiple of (512, 512).
/BOTH plots both Horizontal and Vertical cuts (when in Horizontal mode).
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A new window is created and used for the profiles. When done,
the new window is deleted.
RESTRICTIONS:
None.
PROCEDURE:
A new window is created and the mouse location in the original window
is used to plot profiles in the new window.
Pressing the left mouse button toggles between
row (horizontal) or column (vertical) profiles.
The right mouse button exits.
MODIFICATION HISTORY:
DMS, Nov, 1988.
Modified, FV, 1990: to specify image Magnification in display Window.
Modified, FV, 1991: to plot BOTH horiz. & vert. profiles.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/profiles.pro)
PSCLOSE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
psclose
PURPOSE:
Close the PostScript device output and reset device and font.
CALLING:
psclose
INPUTS: none
OUTPUTS: none
COMMON BLOCKS:
common psclose, dnamsav, pfont
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/psclose.pro)
PSF_GAUSSIAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
psf_Gaussian
PURPOSE:
Return a point spread function having Gaussian profiles,
as either a 1D vector, a 2D image, or 3D volumetric-data.
CALLING:
psf = psf_Gaussian( NPIXEL=31, FWHM=[4.3,5.2], /NORMALIZE )
or:
psf = psf_Gaussian( parameters )
KEYWORDS:
NDIMEN = dimension of result: 1 (vector), 2 (image), or 3 (volume),
default = 2 (an image result).
NPIXEL = number pixels for each dimension, specify as an array,
or just one number to make all sizes equal.
FWHM = the desired Full-Width Half-Max (pixels) in each dimension,
specify as an array, or single number to make all the same.
CENTROID = pixels numbers of PSF maximum ( 0.5 is center of a pixel ),
default is exact center of requested vector/image/volume.
STDEV = optional way to specify width by standard deviation param.
XY_CORREL = optional, 0 < 1 causes elliptical shape in contours.
/NORMALIZE causes resulting PSF to be normalized so Total( psf ) = 1.
INPUTS (optional):
parameters = an NDIMEN by 3 array giving for each dimension:
[ maxval, center, stdev ], overrides other keywords.
This argument is obtained from the FIT_PARAMS=parameters
keyword result of function FullWid_HalfMax.
EXTERNAL CALLS:
function Gaussian
PROCEDURE:
Straight-forward.
HISTORY:
Written, Frank Varosi NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/psf_gaussian.pro)
PSF_LORENTZIAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
psf_Lorentzian
PURPOSE:
Return a generalized Lorentzian (also called Cauchy function)
point spread function (PSF),
as either a 1D vector, a 2D image, or 3D volume-data.
CALLING EXAMPLES:
psf = psf_Lorentzian( NPIXEL=31, FWHM=4.3, /NORMALIZE )
psf = psf_Lorentzian( parameters )
KEYWORDS:
NDIMEN =
NPIXEL =
FWHM =
CENTROID=
RADII =
POWER =
PSCALE =
XY_CORREL=
/NORMALIZE
INPUTS (optional):
parameters = an Ndim by 5 array giving for each dimension:
[ maxval, center, radius, power, pscale ]
This argument is usually obtained from the FIT_PARAMS=parameters
keyword result of function FullWid_HalfMax.
EXTERNAL CALLS:
function Lorentzian (for 1D case only).
PROCEDURE:
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/psf_lorentzian.pro)
PSF_MODEL
[Previous Routine]
[Next Routine]
[List of Routines]
Generate a model psf (Gaussian or Lorentzian type profiles).
If npix is odd, psf peak is centered in single center pixel.
If npix is even, psf peak is centered between 4 middle pixels.
Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/psf_model.pro)
PSLAND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
psland
PURPOSE:
Set device to PostScript landscape mode
and save previous device and font in common.
CALLING:
psland
KEYWORD INPUT:
FILE = string, name of file to which PostScript should be written.
COMMON BLOCKS:
common psclose, dnamsav, pfont
EXTERNALS:
function VarType
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/psland.pro)
PSPORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
psport
PURPOSE:
Set device to PostScript portrait mode
and save previous device name and font in common.
Call pro psclose to close PS device and reset device name and font.
CALLING EXAMPLE:
psport, FILE="plot.ps"
KEYWORDS:
FILE = PostScript output file, default = "idl.ps"
/SQUARE : make graphics occupy 7 by 7 inch square.
/LONG : make graphics occupy 7 by 9 inch rectangle.
COMMON BLOCKS:
common psclose, dnamsav, pfont
EXTERNALS:
function VarType
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/psport.pro)
PURPOSE:[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PURPOSE:
CALLING:
INPUTS:
KEYWORDS:
OUTPUTS:
EXTERNAL CALLS:
COMMON BLOCKS:
PROCEDURE:
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/dftune.pro)
PURPOSE:[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PURPOSE:
Scale image into bytes and rebin the image for purpose of displaying.
CALLING:
imscaled = scale_image( image, Magf, MIN=, MAX=, ROT=, /LOG )
INPUTS:
image = 2-D array.
Magf = magnification factor, integer if greater than one,
floating point if less than one (reduction), default = 1.
KEYWORDS:
MINIMUM = default is use the miximum of image.
MAXIMUM = default is use the maximum of image.
NSIGMA_RANGE = # of standard deviations around mean of image,
to use as minimum & maximum range for scaling,
used only of non-zero, sets and returns new MIN and MAX values.
TOPVAL = default is !D.table-size-2.
BOTTOM_VAL = default = 0.
LOG10 = display aLog10( image > LOG10 ).
POWER = display image^POWER.
ROTATION = integer, 0 to 7, passed to the IDL rotate function.
SMOOTH = box width of moving average.
/ALL_PIXELS : apply smooth to all pixels by extending image first.
/ITERATE : apply smooth(*,3) for (width-1)/2 times, and this iteration
approaches convolution by Gaussian of FWHM=sqrt( (width-1)/2 ).
OUTPUTS:
Function returns scaled, optionally magnified, rotated, etc. byte image.
EXTERNAL CALLS:
function filter_image
PROCEDURE:
Straightforward.
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V. 1991, added option to de-magnify with binning if Magf < 1.
F.V. 1991, added smoothing option using filter_image.
F.V. 1992, added geometric scaling (image^power) with keyword POWER=
and keyword option BOTTOM= to limit min of bytscl.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/scale_image.pro)
PURPOSE:[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PURPOSE:
CALLING:
magf = set_mag_factor( magf_min, magf_max )
INPUTS:
magf_min = minimum magnification factor, can be < 1, default=1.
magf_max = max mag. factor, def=4.
KEYWORDS:
OLD_MAGF =
OUTPUTS:
Function returns selected mag. factor.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/set_mag_factor.pro)
PURPOSE:[3]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PURPOSE:
CALLING:
INPUTS:
KEYWORDS:
OUTPUTS:
COMMON BLOCKS:
EXTERNAL CALLS:
PROCEDURE:
HISTORY:
Written: Frank Varosi, Raytheon ITSS @ NASA/GSFC, 1999.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/template.pro)
PURPOSE:[4]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PURPOSE:
Returns the angle in degrees for drawing text on a graph,
between two points given by input arrays (xt,yt).
CALLING:
angle = text_angle( xt, yt )
INPUTS:
xt, yt = 2 elements arrays for x and y coordinates resp.
PROCEDURE:
Convert to device coordinates and use inverse tangent function.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1996.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/text_angle.pro)
PXY
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1987.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/pxy.pro)
READFITS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
READFITS
CALLING SEQUENCE:
Result = readfits(filename,[header])
PURPOSE:
Read a FITS file into IDL data and optionally header variables.
INPUTS:
FILENAME = String containing the name of the file to be read.
OPTIONAL KEYWORDS:
UNSIGN - A keyword which, if present, will cause INTEGER*2 data
(BITPIX = 16) to be intepreted as unsigned. Note that
the same effect will occur if the optional FITS keyword
DATATYPE has a a value of UNSIGNED*2, and that a LONG
array will result.
NOSCALE: If present and non-zero, then the ouput data will not be
scaled using the optional BSCALE and BZERO keywords in the
FITS header. Default is to scale.
BLANK_VALUE - The optional BLANK keyword in the FITS header defines
the data value that was assigned to unknown pixel values.
For floating point data, the BLANK_VALUE keyowrd can be used
to assign a different value to these pixels.
SILENT - Normally, READFITS will display the size the array at the
terminal. The SILENT keyword will suppress this
OUTPUTS:
Result of function = array constructed from designated record.
OPTIONAL OUTPUT:
HEADER = String array containing the header from the FITS file.
EXAMPLE:
Read a FITS file TEST.FITS into an IDL image array, IM and FITS
header array, H. Do not scale the data with BSCALE and BZERO.
IM = READFITS('TEST.FITS',H,/NOSCALE)
LIMITATIONS:
Cannot handle FITS extensions (NAXIS = 0)
Cannot handle GROUPS
Cannot handle REAL*8 data on a non-IEEE machine (e.g. VAX)
PROCEDURES USED:
SXPAR (and SXPAR calls STRNUMBER)
MODIFICATION HISTORY:
WRITTEN, Jim Wofford, January, 24 1989
MODIFIED, Kanav Bhagat, July 1990 convert to Version 2
MODIFIED, Frank Varosi, Oct, 1990
added calls to IDL intrinsic ByteOrder for byte swapping,
single call to MAKE_ARRAY using IDL to FITS type mapping,
handle floating point data with optional blank replacement.
MODIFIED, Wayne Landsman December, 1990
corrected ByteOrder call for REAL*4 data
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/readfits.pro)
READ_WINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
read_window
PURPOSE:
Read pixel values from a graphics window and return as array (image).
CALLING:
image = read_window( window )
INPUTS:
window = # of window to read, default is window in which cursor is.
EXTERNAL CALLS:
function get_cursor_win
HISTORY:
Written: Frank Varosi NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/read_window.pro)
REMIX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
RemIx
PURPOSE:
Remove indices (determined previously) from an index array.
CALLING:
sub_indices = RemIx( indices, REMOVE=iremov )
INPUT:
indices = array of numbers.
KEYWORDS:
REMOVE = array of numbers to remove from input indices.
NINDEX = generate index array of length NINDEX, if input not given.
/INFO : print informational messages.
OUTPUTS:
Function returns a subset of input indices, with requested ones removed.
EXTERNAL CALLS
pro match
PROCEDURE:
Apply the match procedure to Locate remove candidates,
and return the others with negated where function.
HISTORY:
Written: Frank Varosi NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/remix.pro)
RFFTINV
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
rfftinv
PURPOSE:
Compute real FFT inverse of 2-D spectrum (coefficients of modes),
where only half of the frequencies (modes, wavenumbers) are required
since the other half is always the rotated and shifted conjugate.
Assumes that the original image (from which spectrum was derived) has
size in each dimension which is an even number (better for FFT anyway).
CALLING:
image = rfftinv( hmodes, [fmodes] )
INPUT:
hmodes = half of the 2-D spectrum:
specifically, if nfx, nfy are the Nyquist frequencies
then hmodes should be an array of size = ( 2*nfx, nfy+1 ).
For example, if size( image ) = (nx,ny) and f = FFT( image, -1 )
then hmodes = f(*,0:ny/2) so nfx = nx/2 and nfy = ny/2.
KEYWORDS:
/CENTERED : assume that the hmodes matrix is shifted in first
dimension (edge to center) so that the coefficient of
frequency (0,0) is at array location (nfx,0).
Default is that frequency (0,0) is at array location (0,0),
the normal result of FFT.
/FORCE_REAL : apply conjugate rules to the input matrix hmodes
in order to insure that the inverse FFT result is real valued.
May change some values of the input spectrum, if necessary,
along the edges of the matrix.
OUTPUTS:
fmodes = optional output of full 2-D spectrum, size = ( 2*nfx, 2*nfy ).
Function returns the inverse FT of spectrum giving a 2-D image
of size = ( 2*nfx, 2*nfy ).
PROCEDURE:
Take the conjugate of input spectrum, shift, rotate and concatenate
with itself to obey conjugate rules for a real function.
HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/rfftinv.pro)
ROT2D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Rot2D
PURPOSE:
Rotate 2D coordinates, single or array of (x,y) coordinates.
CALLING:
xy_rot = Rot2D( xy, angle )
INPUTS:
xy = [x,y] vector or and array of vectors,
in either [[x,y]] form or transposed [[x],[y]] form.
angle = the desired rotation angle in radians, unless /DEGREES.
KEYWORDS:
/DEGREES : indicates that angles are in degrees (default is radians).
ROTMAT = optional output, the 2D rotation matrix (2 by 2).
OUTPUTS:
Function returns rotated (x,y) array with same structure as input.
HISTORY:
Written: Frank Varosi, U.MD.1988.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/rot2d.pro)
ROT3D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Rot3D
PURPOSE:
Rotate 3D coordinates, single or array of (x,y,z) coordinates.
Order of rotations is first around Y-axis, then Z-axis, then X-axis.
CALLING:
xyz_rot = Rot3D( xyz )
INPUTS:
xyz = [x,y,z] vector or and array of vectors,
in either [[x,y,z]] form or transposed [[x],[y],[z]] form.
KEYWORDS:
Xang =
Yang =
Zang =
/DEGREES : indicates that angles are in degrees (default is radians).
ROTMAT = optional output, the 3D rotation matrix (3 by 3).
OUTPUTS:
Function returns rotated (x,y,z) array with same structure as input.
PROCEDURE:
Compute Y-axis, Z-axis, and X-axis rotation matrices and multiply.
HISTORY:
Written: Frank Varosi, U.MD.1988.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/rot3d.pro)
ROTATE_COORDIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
rotate_coordin
PURPOSE:
Apply one of the standard 8 image matrix rotations (0-7) of the
IDL function rotate( image, rotation ) to (x,y) pixel coordinate pair.
This is not the same as planar coordinate rotations,
since all rotations of matrix stay in first quadrant.
CALLING EXAMPLES:
rotate_coordin, xin,yin, xout,yout, rotation, MAX=[64,48]
rotate_coordin, xin,yin, xout,yout, /INVERSE, ROT=rotation, /NORM
rotate_coordin, XY_IN=xyin, XY_OUT=xyout, ROT=rotation, /NORM
INPUTS:
xin, yin = pixel coordinates in an image.
rotation = standard IDL rotation number, but negative means inverse.
KEYWORDS:
ROTATION = another way to specify the rotation number (overrides arg.).
/INVERSE means do inverse of whatever specifies.
/NORM means coordinates are 0 < (x,y) < 1, otherwise must specify MAX=.
MAX_COORDIN = [xmax,ymax], maximums of non-rotatated coordin, def=[1,1]
ZOOM_FACTOR = factor to apply to (xin,yin) -> zfac * ([xin,yin] - zoff)
ZOOM_OFFSET = offset to apply to (xin,yin), default zoff=0.
Alternative Keyword Input/Output:
XY_IN = [xin,yin]
XY_OUT = [xout,yout]
OUTPUTS:
xout, yout = pixel coordinates in rotated image.
HISTORY:
Written, Frank Varosi NASA/GSFC 1990.
F.V.1993, added alternative keywords XY_IN, XY_OUT.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/rotate_coordin.pro)
ROTMAG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
RotMag
PURPOSE:
Rotate, magnify or demagnify, and/or translate an image.
( Combines the effect of ROT and CONGRID ).
CATEGORY:
Z3 - Image processing, geometric transforms.
CALLING:
Result = RotMag( image, ANGLE=Angle, MAG=Mag, /INTERP, MISSING=missval )
INPUTS:
image: The image array to be rotated. This array may be of any type,
but it must have two dimensions.
KEYWORDS:
ANGLE = Angle of rotation in degrees Counter-Clockwise.
MAG = Magnification/demagnification factor. A value of 1.0 = no
change, > 1 is magnification and < 1 is demagnification.
Size of returned (output) image is increased/decrease approp.
XC, YC = X or Y subscripts for the center of rotation. If omitted,
default is the size of the image divided by 2.
INTERP: Set this keyword for bilinear interpolation. If this keyword
is set to 0 or omitted, nearest neighbor sampling is used,
set to 1 then bilinear interpolation is used,
if INTERP = 2 then cubic interpolation (IDL v.3.5) is used.
MISSING = The data value to substitute for pixels in the output image
that map outside the input image.
PIVOT: Setting this keyword causes the image to pivot around the point
XC, YC, so that this point maps into the same point in the
output image. If this keyword is set to 0 or omitted, then the
point XC, YC in the input image is mapped into the center of
the output image.
OUTPUTS:
RotMag returns a rotated, magnified, and/or translated version of the
input image. The dimensions of the output image equal
the magnification factor times dimensions of the input image.
PROCEDURE:
The POLY_2D function is used to translate, scale, and rotate the image.
EXAMPLE:
Create and display an image. Then display a rotated and magnified
version. Create and display the image by entering:
A = BYTSCL(DIST(256))
TV, A
Rotate the image 33 degrees and magnify it 1.5 times. Use bilinear
interpolation to make the image look nice. Enter:
B = RotMag( A, 33, 1.5, /INTERP )
TV, B
MODIFICATION HISTORY:
June, 1982. Written by DMS, RSI.
Feb, 1986. Modified by Mike Snyder, ES&T Labs, 3M Company.
Adjusted things so that rotation is exactly on the
designated center.
October, 1986. Modified by DMS to use the POLY_2D function.
Aug, 1988. Added INTERP keyword.
Dec, 1992. Added PIVOT keyword, William Thompson, NASA/GSFC.
Apr, 1994, F.Varosi, GSFC, copied ROT and mod to magnify size of image.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/rotmag.pro)
ROUND_OFF
[Previous Routine]
[Next Routine]
[List of Routines]
F.V.1991
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/round_off.pro)
RUNKUT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
RunKut
PURPOSE:
Runge-Kutta fixed step solution of ODE system.
CALLING:
RunKut, xsol, TSTART=, TSTOP=, NSTEP=, F_DERIV=
INPUT and OUTPUT:
xsol = array giving initial conditions at time TSTART,
replaced by solution of ODE at TSTOP.
KEYWORDS:
TSTART=
TSTOP=
NSTEP=
F_DERIV = string, name of the function giving derivative array,
the right hand side of ODE system (default is "FdXdT").
Form is:
dXdT = FdXdT( T, X )
The resulting array dXdT must have one-to-one correspondence
with elements of Xsol.
HISTORY:
Written, Frank Varosi U.Md. 1987.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/runkut.pro)
RUNKUT_FIXED
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
RunKut_fixed
PURPOSE:
Runge-Kutta fixed step solution of ODE system.
CALLING:
RunKut_fixed, xsol, TSTART=, TSTOP=, NSTEP=, F_DERIV=
INPUT and OUTPUT:
xsol = array giving initial conditions at time TSTART,
replaced by solution of ODE at TSTOP.
KEYWORDS:
TSTART=
TSTOP=
NSTEP=
F_DERIV =
EXTERNAL CALLS:
function RunKut_step
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/runkut_fixed.pro)
RUNKUT_STEP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
RunKut_step
PURPOSE:
Applies the Runge-Kutta method to solve ODE system,
giving a single step in evolution of the ODE solution trajectory.
CALLING:
RunKut_step, Xsol, Tx, Tstep, F_DERIV=
INPUTS:
Xsol = array of initial conditions for ODE at time Tx.
Tx = scalar, time of initial conditions
Tstep = time step desired.
KEYWORDS:
F_DERIVATIVE = string, name of the function giving derivative array,
the right hand side of ODE system (default is "FdXdT").
Form is:
dXdT = FdXdT( T, X )
or:
dXdT = FdXdT( T, X, Tpast ) if /PAST.
The resulting array dXdT must have one-to-one correspondence
with elements of Xsol.
DXDT_FIRST = optional, the derivative array from a previous call,
(just to save time, default is to compute it).
/PAST option causes the F_DERIVATIVE to be passed a third argument
containing the previous step time.
OUTPUTS:
Xsol = solution of ODE at new time Tx.
Tx = new time of solution ( = Tx + Tstep )
PROCEDURE:
The 4-th order Runge-Kutta method, e.g. Numerical Recipes, sec.15.1.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/runkut_step.pro)
SAVE_PXYZ
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Save_PXYZ
PURPOSE:
Save the values of IDL system structures !P, !X, !Y, and !Z,
for restoring them later.
CALLING:
Save_PXYZ
INPUTS:
None.
KEYWORDS:
/RESTORE
OUTPUTS:
None.
COMMON BLOCKS:
common Save_PXYZ, Psave, Xsave, Ysave, Zsave
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1998.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/save_pxyz.pro)
SAVE_WINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
save_window
PURPOSE:
Read pixel values from a graphics window and store with colors
to a file, in either IDL/XDR format or in GIF format.
Inquires user to choose format and enter file name.
CALLING:
save_window, window
INPUTS:
window = # of window to read, default is window in which cursor is.
KEYWORDS:
FILE = string, file name to which image is written,
default is to inquire user.
/GIF : write in GIF format.
/IDL_XDR : write in IDL/XDR format, default is to inquire user.
EXTERNAL CALLS:
function read_window
function get_text_input
function color_struct
pro write_gif
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/save_window.pro)
SCALAR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
scalar
PURPOSE:
Convert input to a scalar by returning just first element.
CALLING:
s = scalar( x )
INPUTS:
x = any variable.
OUTPUT:
Function returns x(0).
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/scalar.pro)
SCANPATH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SCANPATH
PURPOSE:
Widget-based routine to read in the documentation from IDL procedures
in the search path. Optionally, reads in the entire procedure.
CATEGORY:
Widgets.
CALLING SEQUENCE:
SCANPATH
OPTIONAL INPUTS:
NAME: Name of procedure to search and document
OPTIONAL KEYWORD OUTPUT:
PROC: String array with the text of the latest saved procedure
BUTTONS:
QUIT: Exits SCANPATH.
PRINT: Prints selected procedure. The entire procedure is
printed, even if "DOC ONLY" is selected.
DOC ONLY / ALL: Toggles between showing only the documentation from a
file (the part between the "+" and "-" lines), and
the entire file.
EXTRACT Extract and copy procedure from library and/or directory
to current working directory with ".txt" extension.
ENVIRONMENT VARIABLES:
IDL_PRINT_TEXT: Environment variable (VMS: logical name) which contains
the print command to be used in printing files.
SCANPATH_FONT: Optional font to use in the text widget. Note that the
font is a function of the computer or terminal
providing the X-windows display server, not the host
computer for the IDL application.
RESTRICTIONS:
Needs X-windows and widgets support (MOTIF or OPENLOOK).
SIDE EFFECTS:
If "ALL" is selected to read in the entire file, then memory problems
may arise when reading very large procedure files.
MODIFICATION HISTORY:
Written May'91 by DMZ (ARC).
Modified Dec 91 by WTT (ARC) to support UNIX, and add the following
features:
- Search current directory, as well as !PATH
- Allow for files "aaareadme.txt" containing more
general information to also be searched.
- Only save last five procedures in memory.
- Add "documentation only" button.
- Use environment variable IDL_PRINT_TEXT
- Change extensions ".SCL", ".MOD" to "._SCL", "._MOD".
Modified Jan'92 by DMZ (ARC) to sense screen size and autosize widgets
Modified Feb'92 by WTT (ARC) to use SCANPATH_FONT environment variable.
Modified Feb'92 by DMZ (ARC) to include a message window
Modified Mar'92 by DMZ (ARC) to enable remote printing of files
Modified Jul'92 by DMZ (ARC) to improve DOCONLY switch and add EXTRACT button
Modified Oct'92 by DMZ (ARC) to accept procedure name as input
Modified Dec'92 by EEE (HSTX) to accept search strings
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/scanpath.pro)
SELECT_MIN_LOG
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/select_min_log.pro)
SELECT_NUMBER
[Previous Routine]
[Next Routine]
[List of Routines]
Create menu of integer numbers and return selection.
Frank Varosi NASA/GSFC 1989.
F.V. 1990, added keyword SKIP= interval between numbers.
F.V. 1991, allow first item (minN) in numbers menu to be floating.
F.V. 1991, added keyword /ZERO to include 0 first in menu.
F.V. 1991, added keyword FACTOR= scaling factor for numbers.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/select_number.pro)
SEP_ALPHA_NUM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sep_alpha_num
PURPOSE:
Separate the characters in an array of strings into alpha-strings and
numeric-strings, numeric being the digits 0-9 and alpha is non-numeric.
CALLING:
sep_alpha_num, strings, alpha, numeric
INPUTS:
strings = string or string array.
OUTPUTS:
alpha = array of strings, same number of elements as input,
containing only the non-numeric characters.
numeric = array of strings containing only the numeric characters.
Leading and trailing blanks are trimmed for all output.
PROCEDURE:
Convert string to byte array and find where the digits are & are not.
HISTORY:
Written: Frank Varosi NASA/GSFC 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sep_alpha_num.pro)
SETUP
[Previous Routine]
[Next Routine]
[List of Routines]
; if (!D.name EQ "X") then device,RETAIN=2
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/setup.pro)
SET_ZOOM
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi NASA/GSFC 1989.
F.V. added zoom factor = 0.5 option.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/set_zoom.pro)
SEVEN_COLORS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Seven_Colors
PURPOSE:
Set the top 7 entries in Lookup Color Table (LCT) to be the seven
primary colors: "red","yellow","green","cyan","blue","violet","white".
Creates a structure array in common containing these lookup
color table indices and the names of the colors.
Pro it_set_color can associate an item with any of the 7 colors:
it_set_color, "model", "green"
it_set_color, "data", "cyan"
This info is saved in common block.
Then function it_get_color returns the color index associated with
any item, so that:
plot,x,y,COLOR = it_get_color( "data" )
will make a graph using with cyan lines/symbols.
The first 7 default items are the colors themselves, so that:
plot,x,y,COLOR = it_get_color( "green" )
will make a graph using with green lines/symbols.
CALLING:
Seven_Colors, new_topval
INPUTS:
None.
KEYWORDS:
None.
OUTPUTS:
new_topval = optional, the index just below where 7 colors start in LCT.
COMMON BLOCKS:
common Seven_Colors, colors
common Seven_Color_it, it_color
EXTERNAL CALLS:
function N_struct
PROCEDURE:
Straightforward.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/seven_colors.pro)
SHOW_VOLUME
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Show_Volume
PURPOSE:
Return a shaded image of an iso-surface of 3D volume data (voxels).
Assumes that a window of desired image size is already open.
CALLING EXAMPLES:
image = show_volume( Voxels, THRESH=0.7, XANG=30, ZANG=40 )
tv, show_volume( Voxels, THRESH=0.5, /LOW )
INPUTS:
Voxels = 3D array, data values on equally spaced (x,y,z) grid.
KEYWORD INPUTS:
THRESHOLD = value of iso-surface (default = average of data).
XANGLE = degrees rotation about X-axis.
ZANGLE = degrees rotation about Z-axis.
/LOW : show and shade the Low side of surface (default is high side).
KEYWORD OUTPUTS/INPUTS:
VERTICES = vertices returned by Shade_Volume, for reuse.
POLYGONS = polygon info returned by Shade_Volume, for reuse.
If vertices and polygons are input via the keywords
then the call to Shade_Volume is skipped.
SIZE = [3,nx,ny,nz] : alternate specification of 3D array dimensions
if vertices and polygons are input instead of Voxels.
OUTPUTS:
Function returns a byte image to be displayed using TV.
EXTERNAL CALLS:
pro scale3
PROCEDURE:
Call IDL intrinsic procedure Shade_Volume to get the iso-surface,
call pro scale3 to set the 3D view transformation, then
call IDL intrinsic function PolyShade for projected image.
HISTORY:
Written: Frank Varosi NASA/GSFC 1992.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/show_volume.pro)
SIGMA_FILTER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sigma_filter
PURPOSE:
Replace outlier (bad) pixels in an image with appropriate values,
or do the opposite: keep the outlier pixels and smooth all others.
Computes the mean and standard deviation of pixels in a box centered at
each pixel of the image, but excluding the center pixel. If the center
pixel value exceeds some number of standard deviations from the mean,
it is flagged for replacment by the mean (or median) in box,
or if /KEEP is set they are kept as is and rest of image is smoothed.
Note option to process pixels on the edges (/ALL_PIX).
However, the newer pro outlier_filter is faster on large images.
CALLING:
Result = sigma_filter( image, box_width, N_sigma=(#), /ALL,/MON )
INPUTS:
image = 2-D array (matrix).
box_width = width of square moving box, in # pixels (default = 3)
KEYWORDS:
N_sigma = # standard deviations flagging outliers, floating point,
recommend > 2, default = 4. For gaussian noise:
N_sigma = 2 smooths 5% of pixels, = 3 does 1%.
RADIUS = another way to specify box radius, so box_width = 2*radius+1.
/ALL_PIXELS causes computation to include edges of image,
/MEDIAN_MEAN cause the median filter of image to be used as
the estimator for the mean (instead of smooth).
/ITERATE causes sigma_filter to be applied recursively (max = 20 times)
until no more pixels change (only allowed when N_sigma >= 2).
/KEEP performs opposite task: pixels with values outside of specified
deviation are not changed, pixels within deviation are smoothed.
/MONITOR prints information about % pixels replaced.
KEYWORD OUTPUTS (optional):
N_CHANGE = # of pixels changed (replaced with neighborhood mean).
VARIANCE = image of pixel neighborhood variances * (N_sigma)^2,
DEVIATION = image of pixel deviations from neighborhood means, squared.
EXTERNAL CALLS:
function filter_image
function sigma_filter
PROCEDURE:
Compute mean over moving box-cars using smooth, subtract center values,
compute variance using smooth on deviations from mean,
check where pixel deviation from mean is within variance of box,
replace those pixels in smoothed image (mean) with orignal values,
return the resulting partial mean image.
HISTORY:
Written, 1991, Frank Varosi, HSTX @ NASA/GSFC
F.V.1992, added optional keywords /ITER,/MONITOR,VAR=,DEV=,N_CHANGE=.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sigma_filter.pro)
SIG_FILT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Sig_filt
PURPOSE:
Performs the Sigma filter algorithm on the input
image array using a box of side 2*radius+1.
This filter will remove noisy areas without removing isolated peaks.
The technique smooths additive image noise by checking statistics
in local neighborhoods and averaging only those pixels with values
within 2 * sigma * (central pixel value) range of central pixel.
CATEGORY:
E3 Smoothing (image)
CALLING SEQUENCE:
Result = Sig_filt( image, radius, sigma )
INPUTS:
image = Input image array or one dimensional vector
radius : Side of filter box = 2*radius+1. Default value = 1.
sigma = standard deviation FACTOR applied to each pixel value. Def=0.1
PROCEDURE:
The loops over image pixels and differences are vectorized and
executed within loops of window shifts (which are the shorter loops).
The pixels within range are accumulated as wells as # of pixels used,
then the average is computed after loops.
This order of loops is faster but uses more memory.
MODIFICATION HISTORY:
Written, Jan.1991, Frank Varosi, STX @ NASA/GSFC
based on info from Houra Raiz.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sig_filt.pro)
SIMPLE_TICKS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
simple_ticks
PURPOSE:
Setup simple tick marks for an axis of graph or contour,
(with simple units like pixels).
Assumes that data range is larger than unity.
CALLING:
simple_ticks, data, tickspace, maxticks, tickvals, nticks
INPUTS:
data, tickspace, maxticks
OUTPUTS:
tickspace, tickvals, nticks
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/simple_ticks.pro)
SINCE_VERSION
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SINCE_VERSION
PURPOSE:
Determine if the current release of IDL (as given in the
!VERSION.RELEASE system variable) comes after the user specified
release.
CALLING SEQUENCE:
test = SINCE_VERSION( release )
INPUT:
release - scalar string, must be formatted exactly like the
!VERSION.RELEASE system variable (e.g. '3.0.0')
OUTPUT:
test - 1 if current release is identical or later than the specified
'release' else 0
EXAMPLE:
Use the /FTOXDR keyword to the BYTEORDER procedure if the current
release of IDL is 2.2.2 or later
IDL> if since_version('2.2.2') then byteorder, a, /FTOXDR
REVISION HISTORY:
Written Wayne Landsman Hughes/STX January, 1992
Corrected algorithm W. Landsman April, 1992
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/since_version.pro)
SIXTY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIXTY
PURPOSE:
Converts decimal number to sexigesimal.
Reverse of TEN function.
CALLING SEQUENCE:
X=SIXTY( DECIMAL )
INPUTS:
DECIMAL -- Decimal scalar quantity (usually degrees RA or DEC).
OUTPUTS:
Function value returned = double real vector of three elements,
sexigesimal equivalent of input decimal quantity.
A negative number is signified by making the first non-zero
element of the output vection negative.
PROCEDURE:
Mostly involves checking arguments and setting the sign.
MODIFICATION HISTORY:
Written by R. S. Hill, STX, 19-OCT-87
Output changed to single precision. RSH, STX, 1/26/88
modified for SUN-IDL by FV 1989 (added RA keyword)
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sixty.pro)
SIZE_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIZE_STRUCT
PURPOSE:
Obtain the size in bytes of an IDL structure definition.
CATEGORY:
Structures
CALLING SEQUENCE:
bytes = size_struct( structure )
examples:
print, size_struct( "fdq_sdf" )
INPUTS:
structure = a structure variable or
a string giving the structure name
as known by IDL (help,/struct,variable).
/PRINT = to print all sub structure sizes.
inputs/outputs used recursively:
struct = the structure VARIABLE currently analyzed.
Max_Field_Size = size of the largest field found in structure.
RESULT:
Function returns the total size in bytes of a structure element.
PROCEDURE:
Strategy is to call size_struct recursively if
structure contains sub-structures.
Otherwise just add up the field sizes.
MODIFICATION HISTORY:
written 1990 Frank Varosi STX @ NASA/GSFC (using align_struct).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/size_struct.pro)
SKY_NOISE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sky_noise
PURPOSE:
Estimate the standard deviation of Gaussian noise by finding the
most probable value of standard deviations for moving box of pixels
(where the histogram of local standard deviations attains maximum).
Then the sky level (average background) can be estimated by
fitting a Gaussian of width given by the estimated noise st.dev.
to the histogram of the image values.
CALLING:
sigma = sky_noise( image, sky_Level, BOX_WIDTH= )
INPUTS:
image = 2D array of data.
OUTPUTS:
sky_Level = the average value of the background in image,
optional, computed only if parameter is present.
Function returns the most probable standard deviation of noise in image.
KEYWORDS:
BOX_WIDTH = the width of box around each image pixel
in which to compute local variances, default = 3.
SIGMA_SET = if specficied, this value is used as st.dev. of noise
and routine skips to determine the sky_Level.
/PLOT : create windows with graphs of Histogram of Local Deviations
and Histogram of Data, and overplot with derived results.
KEYWORD OPTIONAL OUTPUTS:
LOCAL_VARIANCE = the image of local variances of data image (no sqrt).
HISTO_VARIANCE = histogram of SQUARE-ROOT of local variance image
VALUE_VARIANCE = values corresponding to local variance histogram
IMAGE_HISTOGRAM = histogram of image
IMAGE_VALUES = values corresponding to image histogram
EXTERNAL CALLS:
function Local_Variance
function histo
pro non_Lin_Lsq
SYSTEM VARIABLES:
if !DEBUG GT 3 then histogram plots are produced in temp. window.
COMMON BLOCKS:
common gaussian, sigma_par ;parameter passed to function gaussian.
common sky_noise, winp, winp2 ;window for debug plots.
PROCEDURE:
Find where the histogram of local standard deviations attains maximum,
and iterate changing binsize until it is satisfactorily representing
the most probable st.dev., then home in on more exact value
by nonlinear Lsq fit to the histogram of local st.devs.
Then estimate the sky level (average background) by fitting (the mean)
a Gaussian with sigma = most probable st.dev. to the histogram of image.
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
F.V. 1995, added !DEBUG and /PLOT options.
F.V. 1997, improved robustness of initial choice of nbin for histogram.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sky_noise.pro)
SMOOTH_ITER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
smooth_iter
PURPOSE:
Approximate convolution with a Gaussian by iteration of
the IDL moving boxcar filter ( smooth( x, 3 ) ).
Gaussian FWHM ~=~ 2 * sqrt( niter ) if niter >> 1.
CALLING:
xs = smooth_iter( x, niter )
INPUTS:
x = data array.
niter = # of smooth( x, 3 ) iterations, default = 3.
OUTPUTS:
Function returns filtered data array of same size.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/smooth_iter.pro)
SORT_STACK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sort_stack
PURPOSE:
Given a stack of images (3-D matrix),
sort each stack of pixels into ascending order.
CALLING:
sort_stack, images
INPUT:
images = stack of images (3-D matrix) to be sorted.
OUTPUT:
images = result with each vertical stack of pixels ordered.
METHOD:
When number of images <= 7 apply bubble-sort with gather/scatter
(using MSORT function), otherwise just loop over all pixel stacks.
HISTORY:
F.Varosi NASA/GSFC 1992
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sort_stack.pro)
STRCONCAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
strconcat
PURPOSE:
Concatenate a string array into single string,
or a matrix of strings into a string array.
CALLING:
string = strconcat( string_array )
INPUTS:
string_array = array of strings or numbers, if numbers they
will be converted to strings before concatenating.
OUTPUT:
Function returns a single string.
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/strconcat.pro)
STRNUMBER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STRNUMBER
PURPOSE:
Function to determine if a string is a valid numeric value.
CALLING SEQUENCE:
result = strnumber(st,val)
INPUTS:
st - string
OUTPUTS:
1 is returned as the function value if the string st has a
valid numeric value, otherwise, 0 is returned.
OPTIONAL OUTPUT:
val - (optional) value of the string. real*8
WARNING:
Note that (as of Version 2.0.10) a blank string (e.g. " ") is not
a valid numeric value, although an empty string ("") is.
HISTORY:
version 1 By D. Lindler Aug. 1987
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/strnumber.pro)
SUBINDGEN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
subindgen
PURPOSE:
Generate indices which map out a subarray in a larger 2D to 4D array.
Limitation is that subarray also starts at subscript zero.
CALLING:
sub_indices = subindgen( array, DIMEN_SUB=dimsub )
INPUTS:
array = 2D, 3D, or 4D array out of which a subarray is to be extracted.
KEYWORDS:
DIMEN_SUB = array, dimensions of the desired subarray to be extracted.
OUTPUTS:
Function returns an array of subscripts which will extract
desired subarray, so that extraction can be repeated.
PROCEDURE:
Generate array of 0s and 1s and then user where function.
HISTORY:
Written: Frank Varosi, RSTX @ NASA/GSFC, 1998.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/subindgen.pro)
SUBSTWID
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
substwid
PURPOSE:
Substitute the actual home directory of user for "~/" (twiddle char.)
in a file name or directory name, on a Unix system.
Note that the form ~username is not altered.
CALLING:
filename_full = substwid( filename )
INPUTS:
filename = string, name of file preceeded with directory
or just a Unix directory specification.
OUTPUTS:
Function returns string with home directory substituted
if "~/" was in file directory specification, else just the input string.
COMMON BLOCKS:
common substwid, home_dir (to save the home directory string)
PROCEDURE:
Spawn a shell and execute the "echo ~" command to get home directory,
and this home-dir is saved in common block for further calls.
HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/substwid.pro)
SUM_ARRAY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SUM_array
PURPOSE:
Total up an array over one of its dimensions.
CALLING SEQUENCE:
RESULT = SUM_array( ARRAY, DIMENSION )
INPUTS:
ARRAY = Input array. May be any type except string.
DIMENSION = Dimension to do total over.
OUTPUTS:
The result is an array with all the dimensions of the input array
except for the dimension specified, each element of which is the total
of the corresponding vector in the input array.
For example, if A is an array with dimensions of (3,4,5), then the
command B = SUM_array(A,1) is equivalent to
B = FLTARR(3,5)
FOR J = 0,4 DO BEGIN
FOR I = 0,2 DO BEGIN
B(I,J) = TOTAL( A(I,*,J) )
ENDFOR
ENDFOR
RESTRICTIONS:
Dimension specified must be valid for the array passed; otherwise the
input array is returned as the output array.
MODIFICATION HISTORY:
William Thompson Applied Research Corporation
July, 1986 8201 Corporate Drive
Landover, MD 20785
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sum_array.pro)
SUN2VAX_V1
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
SUN2VAX
*PURPOSE:
To convert Sun IDL data types to VAX IDL data types.
*CALLING SEQUENCE:
SUN2VAX, variable
*PARAMETERS:
variable (REQ) (IO) (BIFDC) (012)
The data variable to be converted. This may be a scalar
or an array. Valid datatypes are integer, longword,
floating point, and double precision. The result of the
conversion is passed back in the original variable.
*COMMON BLOCKS:
none
*SIDE EFFECTS:
none
*RESTRICTIONS:
Data types passed here must be in the set listed in the "INPUTS"
section.
*EXAMPLE:
Read a 100 by 100 matrix of floating point numbers from a data
file created on a Sun. Then convert the matrix values into
VAX format.
IDL> openr,1,'vax_float.dat
IDL> data = fltarr(100,100)
IDL> forrd,1,data
IDL> SUN2VAX,data
*MODIFICATION HISTORY:
Version 1 By John Hoegy 13-Jun-88
21-Oct-88 - JAH: Fixed problem where it wouldn't convert float
and double scalars.
24-Oct-88 - JAH: Fixed problem with converting integer arrays.
20-Jun-89 - RWT: use SWAP.PRO for byte swapping, remove GOTO's
and modify prolog entries
09-Jan-90 - WTT: Changed name to VAX2SUN. Added checks for undefined
variable, complex, structure, unknown type.
04-May-90 - WTT: Created SUN2VAX from VAX2SUN, reversing floating
point procedure.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sun2vax_v1.pro)
SWAP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SWAP
PURPOSE:
To swap alternating bytes in a byte, integer, longword integer array
or scalar, for conversion from VAX data types to Sun data types.
CALLING SEQUENCE:
SWAP, INT [, TYPE ]
INPUT PARAMETER:
INT = Variable in which bytes will be swapped.
OPTIONAL INPUT PARAMETER:
TYPE = Data type. If not specified, then determined by IDL command
SIZE.
SIDE EFFECTS:
The original vector or scalar is replaced by the swapped data.
RESTRICTIONS:
If INT is a scalar byte, or a byte array with an odd number of bytes,
or any other data type other than byte, integer, or longword integer,
the procedure returns to the main level.
PROCEDURE:
For byte arrays, the odd and even elements are simply reversed. For
integers, ANDs & ORs and the mask 'FF'X (a byte with all bits on) are
used with the intrinsic command ISHFT to interchange bytes.
*MODIFICATION HISTORY:
Apr. 25 1980 D.J. Lindler initial program.
Mar. 21 1988 CAG add VAX RDAF-style prolog, add procedure
call listing, and check for parameters.
Feb. 09 1988 RWT change suggested by D. Lindler to handle
longword integers.
Jun. 14 1989 RWT modify for SUN IDL, add optional parameter,
and allow swapping of bytes in a byte array.
Jan. 08 1989 William Thompson check for odd number of elements.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/swap_v1.pro)
SXADDPAR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SXADDPAR
PURPOSE:
Add or modify a parameter in a FITS header array.
CALLING SEQUENCE:
sxaddpar, Header, Name, Value, Comment, Location, Format=Format
INPUTS:
Header = String array containing FITS header. Max string length must be
equal to 80. If not defined, then SXADDPAR will create an
empty FITS header array.
Name = Name of parameter. If Name is already in the header the value
and possibly comment fields are modified. Otherwise a new record
is added to the header. If name = 'HISTORY' then the value will
be added to the record without replacement. In this case the
comment parameter is ignored.
Value = Value for parameter. The value expression must be of the correct
type, e.g. integer, floating or string. String values of 'T'
or 'F' are considered logical values.
OPTIONAL INPUT PARAMETERS:
Comment = String field. The '/' is added by this routine. Added
starting in position 31. If not supplied, or set equal to '',
then the previous comment field is retained (when found)
Location = Keyword string name. The parameter will be placed
before the location of this keyword. For example, if
Location = 'HISTORY' then the parameter will be placed
before the first history location. This applies only when
adding a new keyword; keywords already in the header are kept
in the same position.
INPUT KEYWORDS:
Format - Optional, can specify format for parameter. A scalar
string should be used.
OUTPUTS:
Header = updated header array.
RESTRICTIONS:
Warning -- Parameters and names are not checked
against valid FITS parameter names, values and types.
MODIFICATION HISTORY:
DMS, RSI, July, 1983.
D. Lindler Oct. 86 Added longer string value capability
Converted to NEWIDL D. Lindler April 90
Added Format keyword, J. Isensee, July, 1990
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sxaddpar.pro)
SXPAR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SXPAR
PURPOSE:
Obtain the value of a parameter in a FITS header
CALLING SEQUENCE:
RESULT = sxpar(HDR,NAME,ABORT,COUNT=COUNT)
INPUTS:
Hdr = FITS header array, (e.g. as returned by SXOPEN)
string array, each element should have a length of 80
characters
Name = String name of the parameter to return. If Name is of
the form 'keyword*' then an array is returned containing
values of keywordN where N is an integer. The value
of keywordN will be placed in RESULT(N-1). The data type
of RESULT will be the type of the first valid match of keywordN
found.
OPTIONAL INPUTS:
ABORT - string specifying that SXPAR should do a RETALL
if a parameter is not found. ABORT should contain
a string to be printed if the keyword parameter is not found.
If not supplied SXPAR will return with a negative
!err if a keyword is not found.
KEYWORDS:
COUNT - Optional keyword to return a value equal to the number of
parameters found by sxpar.
OUTPUTS:
Function value = value of parameter in header.
If parameter is floating, long or string, the
result is of that type. Apostrophes are stripped
from strings. If the parameter is logical, 1 is
returned for T, and 0 is returned for F.
If Name was of form 'keyword*' then a vector of values
are returned.
SIDE EFFECTS:
Keyword COUNT returns the number of parameters found.
!err is set to -1 if parameter not found, 0 for a scalar
value returned. If a vector is returned it is set to the
number of keyword matches found.
If a keyword occurs more than once in a header, a warning is given,
and the first occurence is used.
PROCEDURE:
The first 8 chacters of each element of Hdr are
searched for a match to Name. The value from
the last 20 characters is returned. An error occurs
if there is no parameter with the given name.
MODIFICATION HISTORY:
DMS, May, 1983, Written.
D. Lindler Oct 86 Returns !err=-1 if name not found,
and allows longer string values
D. Lindler Aug, 87 added 'keyword*' capability
D. Lindler Jan 90 added ABORT input parameter
J. Isensee Jul,90 added COUNT keyword
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/sxpar.pro)
TEN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEN
PURPOSE:
Converts sexigesimal number to decimal. Inverse of SIXTY function.
CALLING SEQUENCES:
X=TEN([HOUR_OR_DEG,MIN,SEC])
X=TEN( HOUR_OR_DEG,MIN,SEC )
X=TEN([HOUR_OR_DEG,MIN])
X=TEN( HOUR_OR_DEG,MIN )
X=TEN([HOUR_OR_DEG]) <-- Trivial cases
X=TEN(HOUR_OR_DEG) <--
INPUTS:
VECTOR -- Sexigesimal quantity. Elements represent units
in order from largest to smallest.
OUTPUTS:
Function value returned = double real scalar, decimal equivalent of
input sexigesimal quantity. A minus sign on any element
of the input vector causes all the elements to be taken as < 0.
PROCEDURE:
Mostly involves checking arguments and setting the sign.
MODIFICATION HISTORY:
Written by R. S. Hill, STX, 21 April 87
Modified to allow non-vector arguments. RSH, STX, 19-OCT-87
modified for SUN-IDL by FV 1989 (added RA keyword)
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/ten.pro)
TRAPEX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Trapex
PURPOSE:
Integrate an exponentially varying function given values on
increasing grid of x-points, using trapeziodal rule in Log space.
More accurate than straight trapez. integration for such a case.
CALLING:
fint = Trapex( f, x )
INPUTS:
f = array of function values at points x, must be all positive.
x = array of independent variable values.
KEYWORDS:
/VECTOR : let the upper limit of integral vary over the x-values
and return a vector of definite integrals.
/DELTA : return a vector of definite integrals over
the intervals between the x-values (i.e. do not accumulate).
LRATMIN = floating, default = 0.1.
If the absolute value of the Log of adjacent f(x) ratios
is less than LRATMIN then regular trapeziodal rule is used,
otherwise assume exponential type of variation.
OUTPUTS:
Returns approximate integral(s) (exact or exponential function).
PROCEDURE:
Use Log of function variation to from sum which is exact for exp. func.
HISTORY:
Written: Frank Varosi, U.Md, 1988.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/trapex.pro)
TRAPEZ
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Trapez
PURPOSE:
Integrate real function given values on increasing grid
using the trapeziodal rule.
To integrate rapidly varying functions try using function trapex.
CALLING:
fint = Trapez( f, x )
INPUTS:
f = array of function values at points x.
x = array of independent variable values.
KEYWORDS:
/VECTOR : let the upper limit of integral vary over the x-values
and return a vector of definite integrals.
/DELTA : return a vector of definite integrals over
the intervals between the x-values (i.e. do not accumulate).
OUTPUTS:
Function returns approximate integral(s).
HISTORY:
Written: Frank Varosi, U.Md, 1988.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/trapez.pro)
TRAPOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Trapow
PURPOSE:
Integrate a function having power-law variation, given values on
increasing grid of x-points, using trapeziodal rule in Log-Log space.
More accurate than straight trapez. integration (exact for power-law).
CALLING:
fint = Trapow( f, x )
INPUTS:
f = array of function values at points x, must be all positive.
x = array of independent variable values,
must be all positive and strictly increasing.
KEYWORDS:
/VECTOR : let the upper limit of integral vary over the x-values
and return a vector of definite integrals.
/DELTA : return a vector of definite integrals over
the intervals between the x-values (i.e. do not accumulate).
OUTPUTS:
Returns approximate integral(s) (exact for power-law).
PROCEDURE:
Assume power-law variation and cast in Log-Log space.
If power variation is close to -1, use Log integ. case.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/trapow.pro)
TRAP_INT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Trap_Int
PURPOSE:
Integrate a tabulated function using the trapeziodal rule, with options
to increase accuracy in the case of functions having exponential
or power-law variation by recasting trapeziodal rule in Linear-Log or
Log-Log (x,y) space, respectively. User can also specify the limits
of integration, and the function will be automatically extrapolated
if requested range exceeds the tabulated range of function.
CALLING:
fint = Trap_Int( x, f )
INPUTS:
x = array of independent variable values, strictly increasing.
f = array of function values at points x, must be all positive.
KEYWORDS:
XRANGE = two element vector specifying other Limits of integration.
If just one number it is assumed to be the Lower Limit.
If requested range exceeds tabulated range of function
the values are extrapolated. Default is range of x array.
/EXP : integrate (and interpolate) in Linear-Log space,
increases accuracy for exponentially varying functions.
In this case f array is thresholded > 1.e-37.
/POW : integrate (and interpolate) in Log-Log space,
increases accuracy for functions with power-law variation.
In this case both x and f arrays are thresholded > 1.e-37.
LOG_AXES = alternative indicator of integration method:
0 = Linear-Linear space (default, usualy trapezoidal).
1 = Linear-Log (equiv to /EXP)
2 = Log-Log (equiv to /POW)
/VECTOR : let the upper limit of integral vary over the x-values
and return a vector of cumulative definite integrals.
/DELTA : return a vector of definite integrals over
the intervals between the x-values (i.e. do not accumulate).
OUTPUTS:
Returns approximate integral(s), scalar or vector depending on keywords.
EXAMPLES:
fint = Trap_Int( x, f, XRAN=[.2,.9] ) ;integrate over sub-range.
fint = Trap_Int( x, f, /EXP ) ;exponentially varying function.
fint = Trap_Int( x, f, /POW ) ;power-law varying function.
fintx = Trap_Int( x, f, /VEC ) ;vector of integrals a func(x).
fintd = Trap_Int( x, f, /DELTA ) ;vector of interval integrals.
EXTERNAL CALLS:
function Trapez
function Trapex
function Trapow
PROCEDURE:
Interpolate f-values at XRANGE points if necessary,
using Linear-Linear, Linear-Log, or Log-Log interpolation depending
on users specification of function variation.
If interpolation is performed, then create new xi & fi arrays
and call function Trap_Int recursively.
If /EXP or /POW recast trapeziodal rule into Lin-Log or Log-Log space,
by calling Trapex or Trapow respectively.
HISTORY:
Written: Frank Varosi, HSTX @ NASA/GSFC, 1988-1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/trap_int.pro)
TRP3D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRP3D
PURPOSE:
Transpose a 3D Array (permute order of dimensions)
CATEGORY:
Math.
CALLING:
Arrayout = Trp3D( Arrayin, Transpose_Type )
INPUTS:
Arrayin = Array with up to 3 dimensions (3-D matrix).
Transpose_Type = integer vector of length 3
specifying permutation of dimensions
examples: [1,2,3] is NO tranpositions (identity),
[2,1,3] first two dimensions are transposed,
[3,1,2] last dimension becomes first dimension.
OUTPUTS:
Function returns transposed 3D array (dimensions permuted)
or usual transpose if input is 2D array.
HISTORY:
Frank Varosi, written at U.of Md. 1988.
F.V. at NASA/GSFC 1990, adapted to IDL-v.2.
F.V.1992, simplified code using IDL intrinsic function reform( array ).
F.V.1995, mod to work on structures and 2D arrays (usual transpose).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/trp3d.pro)
TVS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
tvs
PURPOSE:
Scale and display an image, with options to magnify/reduce, rotate,
take Log base 10, etc. (see keywords), and display scale on color bar.
If input image array is actually a stack or matrix of images,
the images are displayed in rows & columns.
If device is PostScript, can specify X & Y SIZE in DEVICE or NORMAL.
CALLING:
tvs, image, xp, yp
INPUTS:
image = 2D, 3D, or 4D array (single image, stack or matrix of images).
xp = horizontal position in window, device units. default = 0.
yp = vertical position in window, device units. default = 0.
KEYWORDS:
MAGF = display magnification of image, integer if greater than one,
floating point if less than one (display reduction),
and default is selected to fill the current window.
MINVAL = default is use the minimum of image.
MAXVAL = default is use the maximum of image.
NSIGMA_RANGE = # of standard deviations around mean of image,
to use as minimum & maximum range for scaling,
used only of non-zero, overrides MINVAL and MAXVAL.
/ERASE : erase window before displaying image(s).
TOPVAL = max color # in lookup table, default = !D.table-size-2.
BOTTOM_VAL = min color # in lookup table for display, default = 0.
LOG10 = display aLog10( image > LOG10 ), default is Linear.
POWER = display image^POWER (default=1).
ROTATION = integer, 0 to 7, passed to the IDL rotate function (def=0).
SMOOTH = box width of moving average, default=0 = no smoothing.
/ALL_PIXELS : apply smooth to all pixels by extending image first.
/ITERATE : apply smooth(*,3) for (width-1)/2 times, and this iteration
approaches convolution by Gaussian of FWHM=sqrt( (width-1)/2 ).
/COLOR_BAR_SCALE : display in separate window a color-bar with scale.
COLOR_BAR_SCALE=2 : display color-bar scale next to image (right side).
NAME_IMAGE = string, optional, name to put in color-bar window.
XSIZE, YSIZE = x & y size of image displayed on PostScript output.
/NORMALIZED : for PostScript, assumes sizes & positions are
in normalized coordinates, this is the default,
so to use is device coordinates set NORMALIZED=0.
EXTERNAL CALLS:
function scale_image
pro color_scale
PROCEDURE:
To display stack of images, call tvs for each, with staggered positions.
HISTORY:
Frank Varosi NASA/GSFC 1992.
F.V. 1996, option COLOR_BAR=2 to display color bar scale next to image.
F.V. 1996, check for PostScript mode & use keywords X-YSIZE, /NORMAL.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/tvs.pro)
TYPIM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
typim
PURPOSE:
Read values of all image pixels from keyboard entries.
CALLING:
image = typim( nx, ny )
INPUTS:
nx, ny = desired size of image, # rows, # columns.
KEYWORDS:
/LONG_ARRAY causes result to be a longword array, default is floating.
EFFECTS:
User is prompted for each pixel by (i,j) = (row,column).
Function returns the entries as a matrix
HISTORY:
Written, Frank Varosi NASA/GSFC 1991.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/typim.pro)
UNIQUE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
unique
PURPOSE:
Return subscripts of unique (first occurence) elements in array,
(thereby eliminating adjacent duplicates),
or optionally sort array before checking for duplicates,
and/or optionally return unique subscripts in original order.
If array is numerical: approximate duplicates (differing by epsilon)
can be found and eliminated by keyword RESOLUTION=epsilon.
CALLING EXAMPLES:
u = unique( array, RESOL=.77, /VERB, /SORT )
x = array( unique( array, /SORT, /ORIGINAL ) )
INPUTS:
array = array of numbers or strings.
KEYWORDS:
RESOLUTION = the accuracy by which to determine equivalence,
if elements differ by RESOLUTION or less they are considered
equal, (array must then be numerical, not strings).
Default is RESOL=0 (duplicates are defined by exact equality).
ASORT = optional output of the sorted array, if /SORT specified.
/VERBOSE to get brief message about # equal values.
/SORT to sort array first, and return sorted unique subscripts.
/ORIGINAL to return the unique subscripts in original order.
OUTPUTS:
Nuniq = # of unique occurences found (optional output).
Function returns subscripts of unique elements in array.
EXTERNAL CALLS:
function Fsort (to sort and maintain original order when duplicates).
PROCEDURE:
Create sorted array first (if requested) then
use the IDL intrinsic function "where" to find differences.
If original order is requested, just sort the unique subscripts at end.
HISTORY:
Written: Frank Varosi NASA/GSFC 1990.
F.V. 1992, added /ORIGINAL_ORDER option.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/unique.pro)
UPGRADE_STRUCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
upgrade_struct
PURPOSE:
Copy tags from a structure to a newer version of structure,
checking first if such an upgrade is really needed.
CALLING:
upgrade_struct, struct_array, REFERENCE_STRUCT=ref_struct
INPUT:
struct_array = array of structures.
KEYWORDS:
REFERENCE_STRUCT = structure to which input should be upgraded.
OUTPUT:
struct_array = array with same structure as the reference structure,
if input structure name does not match the reference structure
name, or if both are anonymous structures (null names).
In such case the tags of original input structure are copied.
If names are the same, the input is not changed at all.
EXTERNAL CALLS:
function N_struct
pro copy_struct
PROCEDURE:
Compare structure names and call copy_struct if upgrade is needed.
HISTORY:
written: 1997 Frank Varosi HSTX @ NASA/GSFC.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/upgrade_struct.pro)
VARTYPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
vartype
PURPOSE:
Check the type of IDL variables.
CALLING:
type_string = vartype( variable )
or:
type_code = vartype( variable, /CODE )
INPUTS:
variable = anything.
KEYWORDS:
/CODE : causes the integer IDL type code to be returned,
instead of a string describing variable type.
/NO_NULL_STRING: consider variable a string only if nonzero length.
OUTPUTS:
sz = (optional) the result of the function size( variable ).
Function returns string describing variable type (see code below),
or if /CODE then the integer IDL type code (0 to 9).
HISTORY:
Written, Frank Varosi NASA/GSFC 1989.
F.V.1994, added keyword /CODE.
F.V.1997, added keyword /NO_NULL_STRING.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/vartype.pro)
VECLINTERP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
vecLinterp
PURPOSE:
Compute a sequence of Linear interpolations between any two arrays.
Arrays can be vectors, images, 3-D matrices, etc., but of same size.
CALLING:
Zinterp = vecLinterp( Z1, Z2, Xp, X1, X2, NPOINT=Np )
INPUTS:
Z1, Z2 = vectors, images, etc. (dependent variable).
X1, X2 = scalars (independent variable)
Xp = vector of interpolation points: X1 <= Xp <= X2
KEYWORDS:
NPOINT = specifies # of equally spaced X values to interpolate,
overrides Xp.
OUTPUTS:
If Npoints>1 then function result is an array of dimension one more than
input arrays (giving a sequence of arrays), else if Npoints=1 result is
same size as input arrays.
PROCEDURE:
HISTORY:
Written: Frank Varosi NASA/GSFC 1984.
F.V.1991 added keyword NPOINT.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/veclinterp.pro)
VEC_DOT_PROD
[Previous Routine]
[Next Routine]
[List of Routines]
return dot (inner) product of vector(s) array( Nvec, Vdim )
(assume 1st index is vector #, 2nd index is vector component #)
(if only one vector, then return its dot procuct).
Frank Varosi U.MD.1988
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/vec_dot_prod.pro)
VEC_NORM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Vec_Norm
PURPOSE:
Return norms of an array of vectors, real or complex.
CALLING:
vnorms = Vec_Norm( vectors )
INPUTS:
vectors = 2-D array : ( Nvec , Vdim )
(1st index is vector #, 2nd index is component # e.g. x,y,z)
OUTPUTS:
Function returns 1-D array of Euclidean norms.
(If only one vector, then returns its norm, a single number).
HISTORY:
Written: Frank Varosi, U.MD.1988.
F.V. 1994, mod to use new feature of total function.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/vec_norm.pro)
VEC_SORT
[Previous Routine]
[Next Routine]
[List of Routines]
Return a matrix of subscripts which Sorts on Last index (columns) of matrix.
For 2-D matrix, columns are matrix(i,*), for 3-D (image stack): matrix(i,j,*).
Sort is increasing order, unless /DECREASING to get decreasing order.
Usual statement: IDL> matrix( vec_sort( matrix ) ) will perform the sort.
is returned (optional) order indices for each column seperately.
Calls external function trp3d() when sorting stack and # images > 9.
Frank Varosi U.Md.1988
F.V. NASA/GSFC 1991, adapted to IDL-v.2, and for stack of images (3-D matrix).
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/vec_sort.pro)
WHERE_TAG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WHERE_TAG
PURPOSE:
Obtain subscripts of elements in structure array for which
a particular Tag has values in a range or matching specified values.
CATEGORY:
Structures
CALLING SEQUENCE:
w = where_tag( struct, TAG_NAME="tag_name", RANGE=[-1,2] )
w = where_tag( struct, TAG_NAME="tag_name", VAL=0 )
w = where_tag( struct, TAG_NAME="tag_name", VAL=[1,2,3,4] )
INPUTS:
Struct = structure array to search.
KeyWords:
TAG_NAME = string specifying Tag Name
TAG_NUMBER = otherwise give the Tag Number,
RANGE = [min,max] range to search for in Struct,
VALUES = one or array of numbers to match for in Struct,
ISELECT= specifies indices to select only part of structure array,
(use it to recycle subscripts from previous searches).
/NOPRINT = suppress informational messages about nothing found.
OUTPUTS:
Nfound = # of occurences found.
RESULT:
Function returns subscripts (indices) to desired elements.
PROCEDURE:
Get tag number and apply the WHERE function appropriately.
HISTORY:
written: 1990 Frank Varosi HSTX @ NASA/GSFC
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/where_tag.pro)
WIDGET_LAB_INFO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Widget_Lab_Info
PURPOSE:
Create 2 Label widgets in a row, one which is just at title
to the Left of a framed Label to which informational text can be set.
CALLING:
wid = Widget_Lab_Info( base )
INPUTS:
base = longword id of the parent base widget.
KEYWORDS:
TITLE = string, label widget on left of row (default = nothing).
VALUE = string to be displayed in framed widget (default = space).
/DYNAMIC: if IDL version > 4.0 then set /DYNAMIC_RESIZE on second Label.
OUTPUTS:
Function returns the id of the framed Label widget.
EXAMPLE:
wid = Widget_Lab_Info( base, L="Status:", VALUE="OK" )
HISTORY:
Written: Frank Varosi NASA/GSFC 1995.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/widget_lab_info.pro)
WIDGET_LAB_TEXT, BASE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Widget_Lab_Text, base
PURPOSE:
Create an editable text widget that has Labels to Left and
right of framed text, all in a row.
CALLING:
wid_text = Widget_Lab_Text( base )
INPUTS:
base = longword id of the parent base widget.
KEYWORDS:
UVALUE = user value of text widget(s) must be specified.
If it is a matrix then an text widget
is created for each row of UVALUE matrix.
LEFT_LABEL = string, first label widget on left of row (default = null).
RIGHT_LABEL = string, last label on right of row (default = null).
FIELD_LABELS = optional, extra label to left of each text widget field.
VALUE = (default = null).
XSIZE = integer, # of chars in text widget(s)
(default = strlen( value ) or 9 if value not spec.).
OUTPUTS:
Function returns the id(s) of text widget(s).
EXAMPLES:
Create single text field:
wid = Widget_Lab_Text( base, L="Time Range =", UVAL="TRAN", R="Hours", $
VALUE=string( Trange, F="(F9.1)" ) )
Create two text fields for min & max of an axis:
wids = Widget_Lab_Text( base, L="Y-axis: ", F=["MIN ="," MAX ="], $
VAL=string( yrange(*,0), F="(I6)" ), $
UVAL=[ ["YRANGE",'0'], ["YRANGE",'1'] ] )
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/widget_lab_text.pro)
WIDGET_LOCATION
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
widget_Location
PURPOSE:
To set the Location of a top-level-base widget on the graphics device.
Calls WIDGET_CONTROL, allows flexibility to specify
either X or Y offsets alone, or both at once.
CALLING:
widget_Location, wid, XPOS=xpos, YPOS=ypos
INPUTS:
wid = Longword integer, the widget ID of the base or a child.
KEYWORDS:
XPOS, YPOS = offset in device pixels from top-left corner of screen,
both x & y or either one alone can be specified.
HISTORY:
Written: Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/widget_location.pro)
WIDGET_TREE_MAP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
widget_Tree_Map
PURPOSE:
To get id's and info of all children of a widget (base),
returned as structure. If a child is a base or has children,
function is called recursively, thus giving a map of the widget tree.
CALLING:
wmap = widget_Tree_Map( base_id )
INPUT:
base_id = integer, id of a widget that has children, usually a base.
If not given,
function returns empty structure for use as template.
OUTPUT:
Function returns an array of structures with tags for widget id's,
parent id's, type flags, values and user values (if they exist and
are strings):
{ id:0L, parent:0L, type:-1, value:"", uvalue:"" }
HISTORY:
Written: Frank Varosi NASA/GSFC 1993.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/widget_tree_map.pro)
WINDOW_SET_SHOW
[Previous Routine]
[Next Routine]
[List of Routines]
Frank Varosi STX @ NASA/GSFC 1990.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/window_set_show.pro)
WMENUX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
wmenux
PURPOSE:
Select from a widget-List type of menu if device supports widgets,
or the old "wmenu" if SUN device, or from numerical list if neither.
CALLING:
sel = wmenux( menu, INIT=init, TIT=0, XPOS=xpos, YPOS=ypos )
INPUTS:
menu = string array of items to select from.
KEYWORDS:
INITIAL_SELECTION = default is 0.
INSTRUCTIONS = string, displayed as window title,
default = "Select item from List:"
TITLE = string, for title of List,
or index in menu of list title, usually 0, default is none.
XPOS, YPOS = x,y Location on device screen, default is top-center.
/NO_SELECT : creates a button widget at top that when pressed
aborts the selection process.
/NO_DEFAULT : implies /NO_SELECT and focusses the pointer on button.
OUTPUTS:
Function returns index of selected item in menu array.
EXTERNAL CALLS:
pro widget_Location
pro hprint
HISTORY:
Written: Frank Varosi NASA/GSFC 1994.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/wmenux.pro)
WRITEFITS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WRITEFITS
CALLING SEQUENCE:
writefits, filename, data [,header]
PURPOSE:
Write an array into a disk FITS file
INPUTS:
FILENAME = String containing the name of the file to be written.
DATA = Image array to be written to FITS file.
OPTIONAL INPUT:
HEADER = String array containing the header for the FITS file.
If variable HEADER is not given, the program will generate
a header array.
OUTPUTS:
None
RESTRICTIONS:
(1) Does not yet support REAL*4 or REAL*8 (BITPIX = -32,-64) in VMS
(2) It is highly recommend to set the FITS keywords BSCALE =1, and
BZERO=0 when writing REAL*4 or REAL*8 data.
MODIFICATION HISTORY:
WRITTEN, Jim Wofford, January, 29 1989
MODIFIED, Kanav Bhagat, July 25, 1990
ability to process multi-dimensional arrays
use of sxpar, sxaddpar, converted to version 2 IDL
MODIFIED, Michael R. Greason, August 1990
Added byte-swapping.
MODIFIED, Wayne Landsman, added BITPIX = -32,-64 support for UNIX
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/writefits.pro)
WRITE_IMAGES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
write_images
PURPOSE:
Write a 3-D array of images to either plain binary file,
F77 binary file, FORMATTED file, or FITS file.
CALLING:
write_images, images, waveLens
INPUTS:
images = 3-D array of data: array( nx, ny, Nimage )
waveLens = vector of wavelenghs corresponding to images
KEYWORDS:
/FITS : write to FITS file, put wavelengths and names in header.
/F77 : write to F77 binary file, put wavelengths in first record.
/FORMAT : write formatted to file, put wavelengths in first record.
NAMES = string array of names corresponding to images
OUTPUTS:
none.
EXTERNAL CALLS:
pro mkhdr
pro sxaddpar
pro writefits
function Trp3D (not used for /FITS)
HISTORY:
Frank Varosi NASA/GSFC 1991.
F.V.1993, added /FITS option.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/write_images.pro)
X_VAR_EDIT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
X_Var_Edit
PURPOSE:
This routine provides an editor for any IDL variable.
CATEGORY:
Widgets
CALLING SEQUENCE:
X_Var_Edit, VAR
INPUTS:
VAR = The variable that is to be edited.
KEYWORD PARAMETERS:
NAME = The NAME of the variable. This keyword is overwritten with the
structure name if the variable is a structure.
GROUP = The widget ID of the widget that calls X_Var_Edit. When this
ID is specified, a death of the caller results in a death of
X_Var_Edit.
OUTPUTS:
VAR = The variable that has been edited, or the original when the user
selects the "Cancel" button in the editor.
COMMON BLOCKS:
X_Var_com - stores the state of the variable that is being edited.
SIDE EFFECTS:
Initiates the XManager if it is not already running.
RESTRICTIONS:
If the variable is exceedingly large such as a giant structure or
huge array, the editor will not fit on the screen and may not be able
to create enough widget components to edit the whole variable.
PROCEDURE:
Create and register the widget and then exit.
If the user selects "accept", the values in the editor are written
to the variable passed in, otherwise, they are ignored.
MODIFICATION HISTORY:
Written by: Steve Richards, February, 1991
Mod by: Frank Varosi, 1994 @ NASA/GSFC, added automatic input focus to
next text widget after CR, changed name: XVarEdit -> X_Var_Edit.
F.V.1999: widget now gets proper scrollbars when too big for screen.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/x_var_edit.pro)
YES_NO_MENU
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
yes_no_menu
PURPOSE:
Provide a simple way to ask the interactive use a Yes/No question.
A yes/no menu is created and widget/menu waits for mouse selection.
CALLING:
answer = yes_no_menu( question )
INPUTS:
question = string, the question to be answer with yes/no,
note that question mark "?" is automatically tacked on the end.
KEYWORDS:
/BINARY : causes result of function to be binary integer, 0=no, 1=yes.
(default is string result).
/NO_DEFAULT : causes mouse to be positioned over the NO selection.
(default is mouse positioned over YES).
OUTPUTS: Function returns string YES or NO, or if /BINARY
it returns an integer 1 or 0, indicating user selection.
HISTORY:
Written: Frank Varosi NASA/GSFC 1990.
F.V. 1993, added X widget menu.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/yes_no_menu.pro)
ZBRENT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZBRENT
PURPOSE:
Find the zero of a 1-D function up to specified tolerance.
This routine assumes that the function is known to have a zero.
CALLING:
x_zero = ZBRENT( x1, x2, FUNC_NAME="name" )
INPUTS:
x1, x2 = scalars, 2 points which bracket location of function zero,
that is, F(x1) < 0 < F(x2).
Note: computations are performed with
same precision (single/double) as the inputs and user supplied function.
REQUIRED INPUT KEYWORD:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px )
where: px = scalar independent variable, input.
F = scalar value of function at px,
should be same precision (single/double) as input.
OPTIONAL INPUT KEYWORD:
MAX_ITER = maximum allowed number iterations, default=100.
TOLERANCE = desired accuracy of minimum location, default = 1.e-3.
OUTPUTS:
Returns the location of zero, with accuracy of specified tolerance.
PROCEDURE:
Brent's method to find zero of a function by using bracketing,
bisection, and inverse quadratic interpolation,
from Numerical Recipes (by Press, et al.), sec.9.3 (p.251).
EXAMPLE:
Find the root of the COSINE function between 1. and 2. radians
IDL> print, zbrent( 1, 2, FUNC = 'COS')
and the result will be !PI/2 within the specified tolerance
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
FV.1994, mod to check for single/double prec. and set zeps accordingly,
as suggested by Mark Hadfield.
FV.1995, if root is not bracketed then return closest endpoint,
and check in detail instead of multiplying to avoid overflows.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/zbrent.pro)
ZOOMW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZOOMW
PURPOSE:
Display part of an image (or graphics) from the current window
expanded in another window.
The cursor is used to mark the center of the zoom.
CALLING:
Zoom, cur_w
INPUTS:
cur_w = window to zoom (optional), < 0 indicates use common ZOOMW3,
or if common is empty, then choose from currently open windows.
KEYWORDS:
FACT = zoom expansion factor, default = 4.
XSIZE = X size of new window, if omitted, 500.
YSIZE = Y size of new window, default = 500.
/CONTINUOUS : keyword param which obviates the need to press the
left mouse button. The zoom window tracks the mouse.
Only works well on fast computers.
OUTPUTS:
No explicit outputs. A new window is created in which zoom is displayed.
COMMON BLOCKS:
The window used for zoom display and zoom parameters are in ZOOMW1,
possible window sizes are in ZOOMW2,
other windows and names are in ZOOMW3 (for case cur_w < 0).
EXTERNAL CALLS:
pros: get_window, box_erase, box_draw, color_tables, printw
SIDE EFFECTS:
A window is created and then kept for next time zoomw is used.
PROCEDURE:
Straightforward.
HISTORY:
This version evolved from zoom.pro in IDL library with modifications to
keep window, added menu items, show zoom box, etc. by
Frank Varosi NASA/GSFC 1989.
F.V. 1991, added select window to zoom, using common zoomw3.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/zoomw.pro)
ZOOMWP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZOOMWP
PURPOSE:
if ZOOMW has been called , then ZOOMWP will Re-Zoom a window
with previous zoom factor and location.
CALLING SEQUENCE:
Zoomwp, windo
INPUTS:
windo = any window to zoom (default is current win, over-riden by /OLD)
KEYWORDS:
/OLD_ZOOM will Re-Zoom the window zoomed in previous ZOOMW call.
/BOX will cause box to be drawn indicating zoomed region.
/ICON will just iconify the zoom window and return.
OUTPUTS:
No explicit outputs. Uses old zoom window if it exists.
COMMON BLOCKS:
The window used for zoom display and zoom parameters are in ZOOMW1.
EXTERNAL CALLS:
pros: box_erase, box_draw
PROCEDURE:
Straightforward.
HISTORY:
written: Frank Varosi NASA/GSFC 1989.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/zoomwp.pro)
ZOOMXY
[Previous Routine]
[List of Routines]
NAME:
zoomxy
PURPOSE:
Interactive zoom of 2-D plotting region by cursor selection,
works for windowing systems and on old graphics terminals.
CALLING EXAMPLES:
zoomxy
zoomxy, window_num
INPUTS:
window_num = IDL window number, default is current window.
RESULTS:
X-Y range for plot is set to user defined box.
EXTERNAL CALLS:
function box_create
HISTORY:
Written, Frank Varosi NASA/GSFC 1987.
F.V.1993 mod to use function box_create for Sunview and X-windows.
(See /host/bluemoon/usr2/idllib/astron/contrib/varosi/vlib/allpro/zoomxy.pro)