[Previous]
[Next]
NAME:
S_TEST
PURPOSE:
This function tests the hypothesis that two sample popultions,
{X[i], Y[i]}, have the same mean of distribution against the
hypothesis that they differ. The result is a two-element vector
containing the maximum number of signed differences between
corresponding pairs of X[i] and Y[i] and the one-tailed level of
significance. This type of test is often refered to as the Sign
Test.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = S_test(X, Y)
INPUTS:
X: An n-element vector of type integer, float or double.
Y: An n-element vector of type integer, float or double.
KEYWORD PARAMETERS:
ZDIFF: Use this keyword to specify a named variable which returns the
number of differences between corresponding pairs of X[i] and
Y[i] resulting in zero. Paired data resulting in a difference
of zero are excluded from the ranking and the sample size is
correspondingly reduced.
CALLS: ***
BINOMIAL
EXAMPLE:
Define the n-element vectors of sample data.
x = [47, 56, 54, 49, 36, 48, 51, 38, 61, 49, 56, 52]
y = [71, 63, 45, 64, 50, 55, 42, 46, 53, 57, 75, 60]
Test the hypothesis that two sample popultions, {X[i], Y[i]}, have
the same mean of distribution against the hypothesis that they differ
at the 0.05 significance level.
result = s_test(x, y, zdiff = zdiff)
The result should be the 2-element vector:
[9.00000, 0.0729981]
The keyword parameter should be returned as:
zdiff = 0
The computed probability (0.0729981) is greater than the 0.05
significance level and therefore we do not reject the hypothesis that
X and Y have the same mean of distribution.
PROCEDURE:
S_TEST computes the nonparametric Sign Test. Differences between
corresponding pairs of X[i] and Y[i] are ranked as either positive or
negative with equal probability of occurance. Differences between
pairs of X[i] and Y[i] that result in zero are excluded from the
ranking and the sample size is correspondingly reduced. The result is
a two-element vector [diff, p] containing the maximum number of signed
differences between corresponding pairs of X[i] and Y[i] and the one-
tailed level of significance. Using the Binomial random variable X,
we can accept of reject the proposed hypothesis. If the sample size
exceeds 25, then the Gaussian distribution is used to approximate the
cumulative Binomial distribution. The one-tailed probability of
obtaining at least (diff) signed differences in an n-element sample is
equal to (p). Prob(X >= diff) = p.
The hypothesis that two sample popultions have the same mean
of distribution is rejected if the number of positive ranks and the
number of negative ranks differ with statistical significance.
REFERENCE:
PROBABILITY and STATISTICS for ENGINEERS and SCIENTISTS (3rd edition)
Ronald E. Walpole & Raymond H. Myers
ISBN 0-02-424170-9
MODIFICATION HISTORY:
Written by: GGS, RSI, August 1994
[Previous]
[Next]
NAME:
SAVGOL
PURPOSE:
Return the coefficients of a Savitzky-Golay smoothing filter,
which may then be used with CONVOL() for smoothing and
optionally for numeric differentiation.
CATEGORY:
Smoothing, differentiation, digital filter, filter
CALLING SEQUENCE:
Kernel = SAVGOL(Nleft, Nright, Order, Degree)
INPUTS:
Nleft = An integer specifying the number of data points
used to the left of each point.
Nright = An integer specifying the number of data points
used to the right of each point.
The total width of the filter is Nleft + Nright + 1.
Order = An integer specifying the order of the derivative desired.
For example, set Order to 0 for the smoothed function,
Order to 1 for the smoothed first derivative, etc.
Order must be less than or equal to degree.
Degree = An integer specifying the degree of smoothing polynomial.
Typical values are 2, 4, or 6.
Degree must be less than the filter width.
KEYWORD PARAMETERS:
DOUBLE = Set this keyword to do the calculation in double precision.
This is suggested for Degree greater than 9.
OUTPUTS:
Result = the desired smoothing kernel.
Use CONVOL to apply this kernel to each dataset.
PROCEDURE:
SAVGOL returns a kernel array that when used
with CONVOL, fits a polynomial of the desired degree to each
local neighborhood of a dataset with equally spaced points.
The coefficients returned by SAVGOL() do not depend on the data
to be fitted, but depend only on the extent of the window, the
degree of the polynomial used for the fit, and the order of the
desired derivative.
SAVGOL is based on the Numerical Recipes routine described in
section 14.8 of Numerical Recipes in C: The Art of Scientific Computing
(Second Edition), published by Cambridge University Press, and is used
by permission. This routine is written in the IDL language.
Its source code can be found in the file savgol.pro in the lib
subdirectory of the IDL distribution.
EXAMPLE:
The code below creates a noisy 800-point vector, with 8 gaussian peaks of
decreasing width. It then plots the vector, the vector smoothed
with a 33-point Boxcar smoother (SMOOTH), and the vector smoothed
with 33-point wide Savitsky-Golay filters of degree 4 and 6.
It may be seen that the Savitsky-Golay filters do a much better job
of preserving the narrower peaks, when compared to SMOOTH.
n = 800 ;# of points
np = 8 ;# of peaks
y = replicate(0.5, n) ;Form baseline
x = findgen(n) ;Index array
for i=0, np-1 do begin ;Add each Gaussian peak
c = (i + 0.5) * float(n)/np ;Center of peak
y = y + exp(-(2 * (x-c) / (75. / 1.5 ^ i))^2) ;Add Gaussian
endfor
!p.multi=[0,1,4] ;Display 4 plots
y1 = y + 0.10 * randomn(-121147, n) ;Add noise, StDev = 0.10
plot, y1, TITLE='Noisy Data' ;Show effects of different filters
plot, y, LINESTYLE=1, TITLE='Smooth of 33'
oplot, smooth(y1, 33, /EDGE_TRUNCATE)
plot, y, LINESTYLE=1, TITLE='S-G of (16,16,4)'
oplot, convol(y1, savgol(16, 16, 0, 4), /EDGE_TRUNCATE)
plot, y, LINESTYLE=1, TITLE='S-G of (16,16,6)'
oplot, convol(y1, savgol(16, 16, 0, 6), /EDGE_TRUNCATE)
MODIFICATION HISTORY:
DMS RSI January, 2000
CT RSI February 2000: added error checking. Changed argument names.
Added /DOUBLE keyword.
[Previous]
[Next]
NAME:
SCALE3
PURPOSE:
Set up transformation and scaling for basic 3D viewing.
This procedure is similar to SURFR and SCALE3D, except that the
data ranges must be specified and the scaling does not vary with
rotation.
CATEGORY:
Graphics, 3D.
CALLING SEQUENCE:
SCALE3, XRANGE = xr, YRANGE = yr, ZRANGE = zr [, AX = ax] [, AZ = az]
INPUTS:
No plain parameters.
KEYWORD PARAMETERS:
XRANGE: Two-element vector containing the minimum and maximum X values.
If omitted, the X-axis scaling remains unchanged.
YRANGE: Two-element vector containing the minimum and maximum Y values.
If omitted, the Y-axis scaling remains unchanged.
ZRANGE: Two-element vector containing the minimum and maximum Z values.
If omitted, the Z-axis scaling remains unchanged.
AX: Angle of rotation about the X axis. The default is 30 degrees.
AZ: Angle of rotation about the Z axis. The default is 30 degrees.
OUTPUTS:
No explicit outputs. Results are stored in the system variables
!P.T, !X.S, !Y.S, and !Z.S.
CALLS: ***
T3D
COMMON BLOCKS:
None.
SIDE EFFECTS:
The 4 by 4 matrix !P.T (the 3D-transformation system variable),
receives the homogeneous transformation matrix generated by this
procedure.
The axis scaling variables, !X.S, !Y.S, and !Z.S are set
from the data ranges.
RESTRICTIONS:
Axonometric projections only.
PROCEDURE:
Set the axis scaling variables from the supplied ranges, then:
1) Translate the unit cube so that the center (.5,.5,.5) is moved
to the origin.
2) Scale by 1/SQRT(3) so that the corners do not protrude.
3) Rotate -90 degrees about the X axis to make the +Z
axis of the data the +Y axis of the display. The +Y data axis
extends from the front of the display to the rear.
4) Rotate about the Y axis AZ degrees. This rotates the
result counterclockwise as seen from above the page.
5) Then it rotates about the X axis AX degrees, tilting the data
towards the viewer.
6) Translate back to the (0,1) cube.
This procedure may be easily modified to affect different rotations
transformations.
EXAMPLE:
Set up a 3D transformation where the data range is 0 to 20 for each
of the 3 axes and the viewing area is rotated 20 degrees about the
X axis and 55 degrees about the Z axis. Enter:
SCALE3, XRANGE=[0, 20], YRANGE=[0, 20], ZRANGE=[0, 20], AX=20, AZ=55
MODIFICATION HISTORY:
DMS, June, 1991.
[Previous]
[Next]
NAME:
SCALE3D
PURPOSE:
Scale the 3D unit cube (a cube with the length of each side equal
to 1) into the viewing area.
CATEGORY:
Graphics, 3D.
CALLING SEQUENCE:
SCALE3D
INPUTS:
No explicit inputs. !P.T is an implicit input.
KEYWORD PARAMETERS:
None.
OUTPUTS:
No explicit outputs. !P.T is an implicit output.
CALLS: ***
T3D
CALLED BY:
SURFR
COMMON BLOCKS:
None.
SIDE EFFECTS:
!P.T is modified.
RESTRICTIONS:
Doesn't work for all forms of perspective transformations.
PROCEDURE:
Eight, 3D data points are created at the vertices of the 3D
unit cube. They are transformed by !P.T. The system
is translated to bring the minimum (x,y,z) point to the origin,
and then scaled to make each coordinates maximum value equal to 1.
MODIFICATION HISTORY:
DMS, May, 1988.
[Previous]
[Next]
NAME:
SEARCH2D
PURPOSE:
This function finds "objects" or regions of similar data
values within a 2-D array of data. Given a starting location
and a range of values to search for, SEARCH2D will find all
the cells within the array that are within the specified range
of values, and have some path of connectivity through these cells
to the starting location. In addition to searching for cells
within a global range of data values, SEARCH2D can also search
for adjacent cells whose values deviate from their neighbors within
specified tolerances. See the procedure "SEARCH3D" for the
three dimensional case.
This function returns a list of the array subscripts that define
the selected object or region.
CATEGORY:
Data subsetting.
Image manipulation.
CALLING SEQUENCE:
Region = SEARCH2D(Array, Xpos, Ypos, Min_val, Max_val)
INPUTS:
Array: The 2-D array of data to search.
Data type : Any 2-D array except string or structure.
Xpos: The X coordinate (first subscript into the 2-D Array)
of the starting cell for the search.
Data type : Long.
Ypos: The Y coordinate (second subscript into the 2-D Array)
of the starting cell for the search.
Data type : Long.
Min_val: The minimum data value to search for. All cells that
are connected to the starting cell, and have a value
greater than or equal to Min_val and less that or equal
to Max_val, will be considered part of the "object".
Max_val: The maximum data value to search for.
KEYWORD PARAMETERS:
DECREASE: If the DECREASE or INCREASE keywords are specified,
then SEARCH2D creates an internal copy of Array.
This internal copy is then processed to enhance the
object edges by using an algorithm similar to the
"SOBEL" edge enhancement process. Any adjacent
cells will be found if their corresponding data value
in the edge enhanced array is greater than DECREASE and
less than INCREASE. In any case, the adjacent cells
will NEVER be selected if their data value is not
between Min_val and Max_val.
The default is 0.0 if INCREASE is specified.
Otherwise, the default is no edge checking.
Data type : Int or Float (usually less than zero).
INCREASE: The maximum value in the edge enhanced array for
a cell to be considered part of the selected object.
Some savings in execution time and memory usage result
when DECREASE and INCREASE are omitted.
See DECREASE above.
The default is 0.0 if DECREASE is specified.
Otherwise, the default is no edge checking.
Data type : Int or Float (usually greater than zero).
LPF_BAND: This keyword indicates what (if any) Low Pass Filtering
is performed on the edge enhanced array before the
search begins. If LPF_BAND is set to 3 or higher
then the edge enhanced array will be smoothed using
LPF_BAND as the width of the smoothing window.
If LPF_BAND is less than 3 then no smoothing is
performed. This keyword only has effect when the
DECREASE or INCREASE keywords are supplied.
See DECREASE above.
The default is zero (no smoothing).
Data type : Int.
DIAGONAL: Normally, cells are considered adjacent only when
squares surrounding the cells share a common edge.
If a non-zero value is passed to DIAGONAL then
SEARCH2D will also locate cells meeting the search
criteria whose surrounding squares share a common
corner. Specifying diagonal search mode requires
more memory and execution time.
The default is no diagonal searching.
Data type : int
OUTPUTS:
This function returns a list of the indices into the 2-D array
that are part of the located object or region. This list is
returned as a LONARR(n) where n is the number of cells found.
If the returned array of indices is called Region, and the
size of the 2-D array of data is size_x by size_y, then the
actual X and Y indices can be obtained by using the following
algorithm :
index_y = Region / size_x
index_x = Region - (index_y * size_x)
The object within the 2-D Array could then be subscripted as :
Array(Region)
OR
Array(index_x, index_y)
CALLS: ***
UNIQ
EXAMPLE:
Find all the indices corresponding to an object contained in a
2-D array of data.
; Create some data.
img = FLTARR(512, 512)
img(3:503, 9:488) = 0.7
img(37:455, 18:438) = 0.5
img(144:388, 90:400) = 0.7
img(200:301, 1:255) = 1.0
img(155:193, 333:387) = 0.3
; Display the image.
TVSCL, img
; Search for an object starting at (175, 300) whose data values
; are between (0.6) and (0.8).
Region = SEARCH2D(img, 175, 300, 0.6, 0.8, /DIAGONAL)
; Scale the background cells into the range 0 to 127.
img = BYTSCL(img, TOP=127B)
; Highlight the object region by setting it to 255.
img(Region) = 255B
; Display the array with the highlighted object in it.
TVSCL, img
MODIFICATION HISTORY:
Written by: Daniel Carr. Thu Sep 3 15:36:17 MDT 1992
[Previous]
[Next]
NAME:
SEARCH3D
PURPOSE:
This function finds "objects" or regions of similar data
values within a 3-D array of data. Given a starting location
and a range of values to search for, SEARCH3D will find all
the cells within the volume that are within the specified range
of values, and have some path of connectivity through these cells
to the starting location. In addition to searching for cells
within a global range of data values, SEARCH3D can also search
for adjacent cells whose values deviate from their neighbors within
specified tolerances. See the procedure "SEARCH2D" for the
two dimensional case.
This function returns a list of the array subscripts that define
the selected object or region.
CATEGORY:
Data subsetting.
Volume manipulation.
CALLING SEQUENCE:
Region = SEARCH3D(Array, Xpos, Ypos, Zpos, Min_val, Max_val)
INPUTS:
Array: The 3-D volume of data to search.
Data type : Any 3-D array except string or structure.
Xpos: The X coordinate (first subscript into the 3-D Array)
of the starting cell for the search.
Data type : Long.
Ypos: The Y coordinate (second subscript into the 3-D Array)
of the starting cell for the search.
Data type : Long.
Zpos: The Z coordinate (third subscript into the 3-D Array)
of the starting cell for the search.
Data type : Long.
Min_val: The minimum data value to search for. All cells that
are connected to the starting cell, and have a value
greater than or equal to Min_val and less that or equal
to Max_val, will be considered part of the "object".
Max_val: The maximum data value to search for.
KEYWORD PARAMETERS:
DECREASE: If the DECREASE or INCREASE keywords are specified,
then SEARCH3D creates an internal copy of Array.
This internal copy is then processed to enhance the
object edges by using an algorithm similar to the
"SOBEL" edge enhancement process (in 3-D). Any
adjacent cells will be found if their corresponding
data value in the edge enhanced array is greater
than DECREASE and less than INCREASE. In any case,
the adjacent cells will NEVER be selected if their
data value is not between Min_val and Max_val.
The default is 0.0 if INCREASE is specified.
Otherwise, the default is no edge checking.
Data type : Int or Float (usually less than zero).
INCREASE: The maximum value in the edge enhanced array for
a cell to be considered part of the selected object.
Some savings in execution time and memory usage result
when DECREASE and INCREASE are omitted.
See DECREASE above.
The default is 0.0 if DECREASE is specified.
Otherwise, the default is no edge checking.
Data type : Int or Float (usually greater than zero).
LPF_BAND: This keyword indicates what (if any) Low Pass Filtering
is performed on the edge enhanced array before the
search begins. If LPF_BAND is set to 3 or higher
then the edge enhanced array will be smoothed using
LPF_BAND as the width of the smoothing window.
If LPF_BAND is less than 3 then no smoothing is
performed. This keyword only has effect when the
DECREASE or INCREASE keywords are supplied.
See DECREASE above.
The default is zero (no smoothing).
Data type : Int.
DIAGONAL: Normally, cells are considered adjacent only when
cubes surrounding the cells share a common face.
If a non-zero value is passed to DIAGONAL then
SEARCH3D will also locate cells meeting the search
criteria whose surrounding cubes share a common
edge or corner. Specifying diagonal search mode
requires more memory and execution time.
The default is no diagonal searching.
Data type : int
OUTPUTS:
This function returns a list of the indices into the 3-D array
that are part of the located object or region. This list is
returned as a LONARR(n) where n is the number of cells found.
If the returned array of indices is called Region, and the
size of the 3-D volume of data is size_x by size_y by size_z,
then the actual X, Y, and Z indices can be obtained by using
the following algorithm :
index_z = Region / (size_x * size_y)
index_y = (Region - (index_z * size_x * size_y)) / size_x
index_x = (Region - (index_z * size_x * size_y)) - (index_y * size_x)
The object within the 3-D Array could then be subscripted as :
Array(Region)
OR
Array(index_x, index_y, index_z)
CALLS: ***
UNIQ
EXAMPLE:
Find all the indices corresponding to an object contained in a
3-D volume of data.
; Create some data.
vol = RANDOMU(s, 40, 40, 40)
vol(3:13, 1:15, 17:33) = 1.3
vol(15:25, 5:25, 15:25) = 0.2
vol(5:30,17:38,7:28) = 1.3
vol(9:23, 16:27, 7:33) = 1.5
; Search for an object starting at (6, 22, 16) whose data values
; are between (1.2) and (1.4)..
Region = SEARCH3D(vol, 6, 22, 16, 1.2, 1.4, /DIAGONAL)
; Scale the background cells into the range 0 to 127.
vol = BYTSCL(vol, TOP=127B)
; Highlight the object region by setting it to 255.
vol(Region) = 255B
; Set up a 3-D view.
Window, 0, Xsize=640, Ysize=512, Retain=2
Create_View, Xmax=39, Ymax=39, Zmax=39, ax=(-30), az=30, zoom=0.8
; Display the volume with the highlighted object in it.
TVSCL, PROJECT_VOL(vol, 64, 64, 40, Depth_Q=0.4)
MODIFICATION HISTORY:
Written by: Daniel Carr. Thu Sep 3 17:36:04 MDT 1992
[Previous]
[Next]
NAME:
SFIT
PURPOSE:
This function determines a polynomial fit to a surface sampled
over a regular or irregular grid.
CATEGORY:
Curve and surface fitting.
CALLING SEQUENCE:
Result = SFIT(Data, Degree) ;Regular input grid
Result = SFIT(Data, Degree, /IRREGULAR) ;Irregular input grid
INPUTS:
Data: The array of data to fit. If IRREGULAR
is not set, the data are assumed to be sampled over a regular 2D
grid, and should be in an Ncolumns by Nrows array. In this case, the
column and row subscripts implicitly contain the X and Y
location of the point. The sizes of the dimensions may be unequal.
If IRREGULAR is set, Data is a [3,n] array containing the X,
Y, and Z location of each point sampled on the surface.
Degree: The maximum degree of fit (in one dimension).
KEYWORDS:
IRREGULAR: If set, Data is [3,n] array, containing the X, Y,
and Z locations of n points sampled on the surface. See
description above.
MAX_DEGREE: If set, the Degree parameter represents the
maximum degree of the fitting polynomial of all dimensions
combined, rather than the maximum degree of the polynomial
in a single variable. For example, if Degree is 2, and
MAX_DEGREE is not set, then the terms returned will be
[[K, y, y^2], [x, xy, xy^2], [x^2, x^2 y, x^2 y^2]].
If MAX_DEGREE is set, the terms returned will be in a
vector, [K, y, y^2, x, xy, x^2], in which no term has a
power higher than two in X and Y combined, and the powers
of Y vary the fastest.
OUTPUT:
This function returns the fitted array. If IRREGULAR is not
set, the dimensions of the result are the same as the
dimensions of the Data input parameter, and contain the
calculated fit at the grid points. If IRREGULAR is set, the
result contains n points, and contains the value of the
fitting polynomial at the sample points.
OUTPUT KEYWORDS:
Kx: The array of coefficients for a polynomial function
of x and y to fit data. If MAX_DEGREE is not set, this
parameter is returned as a (Degree+1) by (Degree+1)
element array. If MAX_DEGREE is set, this parameter
is returned as a (Degree+1) * (Degree+2)/2 element
vector.
PROCEDURE:
Fit a 2D array Z as a polynomial function of x and y.
The function fitted is:
F(x,y) = Sum over i and j of kx[j,i] * x^i * y^j
where kx is returned as a keyword. If the keyword MAX_DEGREE
is set, kx is a vector, and the total of the X and Y powers will
not exceed DEGREE, with the Y powers varying the fastest.
MODIFICATION HISTORY:
July, 1993, DMS Initial creation
July, 2001 Added MAX_DEGREE and IRREGULAR keywords.
[Previous]
[Next]
NAME:
SHADE_SURF_IRR
PURPOSE:
Make a shaded surface representation of an irregulary gridded
elevation dataset.
The data must be representable as an array of quadrilaterals. This
routine should be used when the (X, Y, Z) arrays are too irregular to
be drawn by SHADE_SURF, but are still semi-regular.
CATEGORY:
Graphics, surface plotting.
CALLING SEQUENCE:
SHADE_SURF_IRR, Z, X, Y
INPUTS:
Z: A 2D array of elevations. This array must be dimensioned
as [NX, NY].
X: A 2D array containing the X location of each Z value. This
array must be dimensioned as [NX, NY].
Y: A 2D array containing the Y location of each Z value. This
array must be dimensioned as [NX, NY].
KEYWORD PARAMETERS:
AX: The angle of rotation about the X axis. The default is 30
degrees. This parameter is passed to SURFR. This keyword
value is ignored if the T3D keyword is set to a nonzero
value.
AZ: The angle of rotation about the Z axis. The default is 30
degrees. This parameter is passed to SURFR. This keyword
value is ignored if the T3D keyword is set to a nonzero
value.
IMAGE: Set this keyword to an array that will contain the resulting
shaded surface image. The variable is returned as a byte
array of the same size as the currently selected graphics
device.
PLIST: Set this keyword to an array that will contain the polygon
list on return. This feature is useful when you want to make a
number of images from the same set of vertices and polygons.
T3D: Set this keyword to a nonzero value to indicate that the
generalized transformation matrix in !P.T is to be used
(in which case the keyword values for AX and AZ are ignored).
OUTPUTS:
No explicit outputs.
CALLS: ***
SURFR
COMMON BLOCKS:
None.
SIDE EFFECTS:
The currently selected display is modified.
RESTRICTIONS:
The grid described by X and Y must consist of quadrilaterals,
must be semi-regular, and must be in "CLOCKWISE" order:
i.e., each cell must be defined by the vertices:
v[i,j], v[i+1,j],v[i+1,j+1], and v[i,j+1].
Clockwise ordering:
x[i,j] <= x[i+1, j] ... for all j
and y[i,j] <= y[i, j+1] ... for all i.
WARNING: This restriction is not checked.
PROCEDURE:
First, SURFR is called to establish the 3D to 2D transformation.
Then the vertex and polygon data structures required by the
POLYSHADE function are built and passed that function. POLYSHADE
returns the shaded image which is then displayed by TV.
This simple procedure can be modified to use and/or accept
additional keywords.
MODIFICATION HISTORY:
Oct, 1989, DMS.
DMS, Modified to use SURFR instead of SURFACE. and to return the
polygon list.
Nov, 1996, DLD: Added T3D keyword.
[Previous]
[Next]
NAME:
SHOW3
PURPOSE:
Show a 2D array three ways in a display that combines SURFACE,
CONTOUR, and an image (color/gray scale pixels).
CATEGORY:
Display, graphics.
CALLING SEQUENCE:
SHOW3, Image [, INTERP = Interp, SSCALE = Sscale]
INPUTS:
Image: The 2-dimensional array to display.
OPTIONAL INPUTS:
X = a vector containing the X values of each column of Image.
If omitted, columns have X values 0, 1, ..., Ncolumns-1.
Y = a vector containing the Y values of each row of Image.
If omitted, columns have Y values 0, 1, ..., Nrows-1.
KEYWORD PARAMETERS:
INTERP: Set this keyword to use bilinear interpolation on the pixel
display. This technique is slightly slower, but for small
images, it makes a better display.
SSCALE: Reduction scale for surface. The default is 1. If this
keyword is set to a value other than 1, the array size
is reduced by this factor for the surface display. That is,
the number of points used to draw the wire-mesh surface is
reduced. If the array dimensions are not an integral multiple
of SSCALE, the image is reduced to the next smaller multiple.
E_CONTOUR: a structure containing additional keyword parameters
that are passed to the CONTOUR procedure. See the example
below.
E_SURFACE: a structure containing additional keyword parameters
that are passed to the SURFACE procedure. See the example
below.
OUTPUTS:
No explicit outputs.
CALLS: ***
POLYWARP
CALLED BY:
test_lj [1], test_lj [2], test_lj [3], test_lj [4], test_lj [5], test_lj [6]
test_lj [7], test_lj [8]
COMMON BLOCKS:
None.
SIDE EFFECTS:
A new plot is generated.
RESTRICTIONS:
The display gets too "busy" when displaying larger (say 50 by 50),
images, especially if they are noisy. It can be helpful to use
the SSCALE keyword or the SMOOTH and/or REBIN functions to smooth the
surface plot.
You might want to modify the calls to CONTOUR and SURFACE slightly
to customize the display to your tastes, i.e., with different colors,
skirts, linestyles, contour levels, etc.
PROCEDURE:
First, do a SURFACE with no data to establish the 3D to 2D scaling.
Then convert the coordinates of the corner pixels of the array to
2D. Use POLYWARP to get the warping polynomial to warp the
2D image into the area underneath the SURFACE plot. Output the image,
output the surface (with data) and then output the contour plot at
the top (z=1).
EXAMPLES:
A = BESELJ(SHIFT(DIST(30,20), 15, 10)/2.,0) ;Array for example
SHOW3, A ;Show it with default display.
SHOW3, A, SQRT(FINDGEN(30)) ;Make X axis proportional to sqrt
SHOW3, A, E_CONTOUR={C_CHARSIZE:2, DONW:1} ;Label CONTOUR lines with
double size characters, and include downhill tick marks.
SHOW3, A, E_SURFACE={SKIRT:-1, ZRANGE:[-2,2]} ;Draw a surface with
a skirt and scale Z axis from -2 to 2.
MODIFICATION HISTORY:
DMS. Jan, 1988.
Added fudges for PostScript, April, 1988.
Fixed bug where contour plot was occasionally clipped. Dec, 1990.
Added optional axis variables, and _EXTRA keywords for CONTOUR,
and SURFACE. Jan, 1996.
DD. Added code to ignore !ORDER for the TV of the image. Mar 1997.
SJL Fixed bug from scaling with polywarp. July, 1998.
DD. Add better support for TrueColor devices.
Honor !P.BACKGROUND (rather than assuming black or white
background). Sept, 2000.
[Previous]
[Next]
NAME:
SHOWFONT
PURPOSE:
This procedure displays a vector-drawn font on the current
graphics device.
CATEGORY:
Fonts.
CALLING SEQUENCE:
SHOWFONT, Font, Name
INPUTS:
Font: The index number of the font (may range from 3 to 29)
or, if the TT_FONT keyword is set, a string representing
the name of the TrueType font to display.
Name: Title text to appear at top of display.
KEYWORD PARAMETERS:
ENCAPSULATED: If this keyword is set, and if the current graphics
device is "PS", makes encapsulated PostScript output.
TT_FONT: If this keyword is set, the Font argument is
interpreted as the name of a TrueType font.
OUTPUTS:
No explicit outputs.
CALLS: ***
FILEPATH
SIDE EFFECTS:
A display is made.
RESTRICTIONS:
Not very flexible.
PROCEDURE:
Straightforward.
EXAMPLE:
To create a display of Font 3 for PostScript:
SET_PLOT, 'PS'
SHOWFONT, 3, "Simplex Roman"
To create a display of the Times Roman TrueType font:
SHOWFONT, 'Times', 'Times Roman', /TT_FONT
MODIFICATION HISTORY:
Written by:
DMS, Nov, 1992
WSO, 1/95, Updated for new directory structure
DD, 12/97, Updated to handle TrueType fonts
[Previous]
[Next]
NAME:
SKEWNESS
PURPOSE:
This function computes the statistical skewness of an
N-element vector. If the variance of the vector is zero,
the skewness is not defined, and SKEWNESS returns
!VALUES.F_NAN as the result.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = SKEWNESS(X)
INPUTS:
X: An N-element vector of type integer, float or double.
KEYWORD PARAMETERS:
DOUBLE: IF set to a non-zero value, computations are done in
double precision arithmetic.
NAN: If set, treat NaN data as missing.
CALLS: ***
MOMENT
EXAMPLE:
Define the N-element vector of sample data.
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
Compute the mean.
result = SKEWNESS(x)
The result should be:
-0.0942851
PROCEDURE:
SKEWNESS calls the IDL function MOMENT.
REFERENCE:
APPLIED STATISTICS (third edition)
J. Neter, W. Wasserman, G.A. Whitmore
ISBN 0-205-10328-6
MODIFICATION HISTORY:
Written by: GSL, RSI, August 1997
[Previous]
[Next]
NAME:
SLICER3
PURPOSE:
Widget based application to visualize 3D data.
This program superseeds the "SLICER" program.
CATEGORY:
Volume display / rendering.
CALLING SEQUENCE:
SLICER3 [, hData3D]
INPUTS:
hData3D: A pointer to the 3D data, or an array of pointers
to multiple 3D arrays. If multiple arrays are specified,
they all must have the same X, Y, and Z dimensions.
This parameter is optional. The default is to use a 3D
array created from BYTARR(2,2,2). While running SLICER3,
the user may interactively load data via the file menu
(see example). If data is loaded in this fashion,
any data passed to SLICER3 via a pointer (or pointers) is
deleted, and the pointers become invalid.
KEYWORD PARAMETERS:
DETACH: If set, then the drawing area is placed in a base that is
detached from the control panel. The drawing area can
only be detached if Slicer3 is not run in modal mode.
MODAL: If set, then Slicer3 will block user interaction with all
other widgets (and block the command line) until the user
quits Slicer3. If Slicer3 is started from some other
widget-based application, then it is usually advisable
to run Slicer3 in Modal mode.
GROUP: This keyword specifies a widget ID of the group leader.
If the specified widget is destroyed, Slicer3 is also
destroyed. If Slicer3 is started from a widget
application, then GROUP should ALWAYS be specified.
See example.
DATA_NAMES: A string array of names for the data. The names appear
on the droplist widget for the current data. If the
number of elements of DATA_NAMES is less than the
number of elements in hData3D then default names will
be generated for the unnamed data.
CALLS: ***
CONGRID, CROSSP, FILEPATH, LOADCT, STRETCH, SWAP_ENDIAN, T3D, VERT_T3D
VIZ3D_ADD_GRAPHIC, VIZ3D_BLOCKDRAW, VIZ3D_BLOCKEVENT, VIZ3D_BLOCKSHOW
VIZ3D_CLEANBUFFER, VIZ3D_CLEANVIEW, VIZ3D_DIFFCOLOR, VIZ3D_DIFFSHADEEVENT
VIZ3D_DRAWCUBE, VIZ3D_DRAWDATA, VIZ3D_DRAWSLICEOBLIQUE, VIZ3D_EVENT
VIZ3D_FILLDEPTH, VIZ3D_GETDATA, VIZ3D_KILLDRAW, VIZ3D_KILLMAIN, VIZ3D_LOADCOLOR
VIZ3D_OBLIQPLANEDRAW, VIZ3D_OPTEVENT, VIZ3D_ORTHOPLANEDRAW, VIZ3D_PROBEDRAW
VIZ3D_PROBEEVENT, VIZ3D_PROFDRAW, VIZ3D_PROFILEEVENT, VIZ3D_PROFSHOW
VIZ3D_PROJDRAW, VIZ3D_PROJECTEVENT, VIZ3D_PUTDATA, VIZ3D_REDRAW, VIZ3D_RESET
VIZ3D_SCALEDATA, VIZ3D_SLICEEVENT, VIZ3D_SLICESHOW, VIZ3D_SURFDRAW
VIZ3D_SURFEVENT, VIZ3D_SURFSHOW, VIZ3D_THRESHEVENT, VIZ3D_THRESHSHOW
VIZ3D_TRANSCOLOR, VIZ3D_TRANSPVALU, VIZ3D_VIEW, VIZ3D_VIEWEVENT, VIZ3D_VIEWSHOW
VIZ3D_XYZPOS, XDISPLAYFILE, XLOADCT, XMANAGER
COMMON BLOCKS:
COMMON colors, r, g, b, cur_red, cur_green, cur_blue
These common variables are used by the "STRETCH",
"LOADCT", and "XLOADCT" commands.
SIDE EFFECTS:
Slicer3 modifies the current color table, the device's
decomposed setting (on 24-bit displays), as well as
various elements of the plotting system (ie, the "!X",
"!Y", "!Z", and "!P" system variables).
If the "MODAL" keyword is set (usually a good idea),
then SLICER3 will, upon exit, restore these system
variables, settings, and the color tables to the values
they had when SLICER3 was started.
Slicer3 sets the position for the light source and
enables back-facing polygons to be drawn (see the
IDL "SET_SHADING" command).
Slicer3 overwrites the existing contents of the
Z-buffer. Upon exiting Slicer3, the Z-buffer contents
are the same as what was last displayed by Slicer3.
Slicer3 breaks the color table into 6 "bands", based upon
the number of available colors (max_color=!D.N_COLORS
on 8-bit displays, and max_color=256 on 24-bit displays) :
Band start index: Band end index: Used for:
----------------- --------------- ---------
0 nColor-1 X Slices.
nColor (2*nColor)-1 Y Slices.
2*nColor (3*nColor)-1 Z Slices.
3*nColor (4*nColor)-1 Iso-surfaces.
4*nColor (5*nColor)-1 Projections.
Where:
nColor = (max_color - 9) / 5
Note that the value of !D.N_Colors can vary from
machine to machine, and from run to run, depending
upon available system resources. Also, !D.N_Colors
is usually not set by IDL until the first window has
been created (or realized) in that IDL session.
Annotation colors are the last "band", and they are
set up as :
Color index: Color:
------------- ------
max_color - 1 White.
max_color - 2 Yellow.
max_color - 3 Cyan.
max_color - 4 Purple.
max_color - 5 Red.
max_color - 6 Green.
max_color - 7 Blue.
max_color - 8 Black.
On 24-bit displays, improved performance can often be
gained by running Slicer3 in 8-bit mode. This can be
accomplished (on some platforms) by entering the following
command at the start of the IDL session (before any
windows are created):
Device, Pseudo_Color=8
See the documentation for additional information.
RESTRICTIONS:
The data used by Slicer3 must meet the following conditions:
* The data must have three dimensions.
* The minimum size of the data array must be 2x2x2.
* If multiple volumes are loaded, they all must have the
same dimensions.
PROCEDURE:
"File" menu:
"Load":
Select a file containing a 3D array (or arrays) to load
into Slicer3. The file must have been written in a
certain binary format. For each data array in the file,
the following values are present:
data item data type bytes
-------------------------- ---------- ------
Number of dimensions long 4
in array. Note that
this is always 3 for
valid Slicer3 data.
Size of first dimension. long 4
Size of second dimension. long 4
Size of third dimension. long 4
If multiple arrays are present in the file,
they must all have the same dimensions.
Data type (1 through 5) long 4
(see the IDL "SIZE"
function for types).
Total number of elements. long 4
(dimX*dimY*dimZ).
Note that the all of the above values are the
exact output of the IDL "SIZE" function.
Number of characters long 4
in data name.
Note that the above value is the output from
the IDL "STRLEN" function.
Data name. byte strlen()
3D data. varies varies
Note that the 3D data type and number of bytes
is specified by the "size" information above.
Any number of 3D datasets can be concatenated into
a single file of this type (as long as they all have
the same dimensions).
(See EXAMPLE, below.)
NOTE: Files saved by the "Save Subset" operation
(see below) are suitable for input via the "Load"
operation.
Data files that are moved from one platform to
another may not load as expected, due to differing
byte order. See the "BYTEORDER" and "SWAP_ENDIAN"
IDL commands for details.
"Save / Save Subset":
Slicer3 must be in "Block" mode for this operation to be
available. When selected, a subset of the 3D data
enclosed in the current block is written to the chosen
save file. This subset can then be loaded back into
Slicer3 at any time. If multiple 3D arrays are
currently available in Slicer3, then multiple subsets
are saved to the file.
"Save / Save Tiff Image":
When selected, a tiff image of the current Slicer3
contents is saved to the chosen file. When running in
8-bit mode, a "Class P" palette color Tiff file is created.
In 24-bit mode, a "Class R" (interleaved by image) Tiff
file is created.
"Quit":
Exits Slicer3.
"Tools" menu:
"Erase":
Erases the display window and deletes all the objects
in the display list.
"Delete / ...":
As graphical objects are created, they are added to the
display list. The "Delete" menu allows the user to
delete a specific object from the list. When an object
is deleted, the screen is redrawn with the remaining
objects.
"Colors / Reset Colors":
Selecting this will cause the original color scheme to
be restored.
"Colors / Differential Shading":
This allows the user to change the percentage of
differential shading applied to the X, Y, and Z slices.
"Colors / Slice/Block":
This allows the user to use the "XLOADCT" operation
to modify the colors used for slices and blocks.
In some cases, the new colors will not be visible
until the user selects "Done" in the XLOADCT tool.
"Colors / Surface":
This allows the user to use the "XLOADCT" operation
to modify the colors used for iso-surfaces.
"Colors / Projection":
This allows the user to use the "XLOADCT" operation
to modify the colors used for projections.
Note that on some platforms, the selected colors may not
become visible until after the "XLOADCT" tool is exited.
"Options":
This brings up a panel allowing the user to set:
The axis visibility.
The wire-frame cube visibility.
The display window size
(the X and Y dimensions are always the same).
If the user selects "Ok", then the display is redrawn.
"About" menu:
"About Slicer":
Brings up help information about Slicer3.
"Data:" pull-down menu:
If multiple datasets are currently available in Slicer3,
this menu allows the selection of the current data.
Slices, blocks, iso-surfaces, etc. are created from
the currently selected data. If only one dataset
is currently loaded, then this menu is inactive.
"Mode:" pull-down menu:
This menu is used to select the current mode of operation.
Main Draw Window:
Interaction in the main draw window is dependent upon
the currently selected mode ("Slice", "Block", "Surface",
etc., see below). In general, when coordinate input is
required from the user, it is performed by clicking a
mouse button on the "surface" of the wire-frame cube that
surrounds the data. This 3D location is then used as
the basis for whatever input is needed. In most cases,
the "front" side of the cube is used. In a few cases,
the coordinate input is on the "back" side of the cube.
"Slice" mode:
To display a slice, click and drag the left mouse button
on the wire-frame cube. When the button is released, a
slice through the data will be drawn at that location.
"Draw" mode:
When in Draw mode, new slices will be merged into
the current Z-buffer contents.
"Expose" mode:
When in Expose mode, new slices will be drawn in
front of everything else.
"Orthogonal" mode:
When in Orthogonal mode, use the left mouse button
in the big window to position and draw an orthogonal
slicing plane. Clicking the right mouse button in
the big window (or any mouse button in the small
window) will toggle the slicing plane orientation.
"X":
This sets the orthogonal slicing plane orientation
to be perpendicular to the X axis.
"Y":
This sets the orthogonal slicing plane orientation
to be perpendicular to the Y axis.
"Z":
This sets the orthogonal slicing plane orientation
to be perpendicular to the Z axis.
"Oblique" mode:
Clicking any mouse button in the small window will
reset the oblique slicing plane to its default
orientation.
"Normal" mode:
When in this mode, click and drag the left mouse
button in the big window to set the surface normal
for the oblique slicing plane.
"Center" mode:
When in this mode, click and drag the left mouse
button in the big window to set the center point
for the surface normal.
"Display":
Clicking this button will cause an oblique slicing
plane to be drawn.
"Block" mode:
When in Block mode, use the left mouse button in the
big window to set the location for the "purple" corner
of the block. Use the right mouse button to locate
the opposite "blue" corner of the block.
When in Block mode, the "Save Subset" operation under
the main "File" menu is available.
"Add" mode:
When in this mode, the block will be "added" to the
current Z-buffer contents.
"Subtract" mode:
When in this mode, the block will be "subtracted"
from the current Z-buffer contents. Subtract mode
is only effective when the block intersects some
other object in the display (such as an iso-surface).
"Display":
Clicking this button will cause the block to be drawn.
"Surface" mode:
In iso-surface is like a contour line on a contour
map. On one side of the line, the elevation is higher
than the contour level, and on the other side of the
line, the elevation is lower than the contour level.
An iso-surface, however, is a 3D surface that passes
through the data such that the data values on one side
of the surface are higher than the threshold value,
and on the other side of the surface, the data values
are lower than the threshold value.
When in Surface mode, a logarithmic histogram plot
of the data is displayed in the small draw window.
Click and drag a mouse button on this plot to set
the iso-surface threshold value. This value is
also shown in the text widget below the plot.
The threshold value may also be set by typing a
new value in this text widget. The histogram
plot is affected by the current threshold settings.
(See Threshold mode, below).
"Low":
Selecting this mode will cause the iso-surface polygon
facing to face towards the lower data values.
Usually, this is the mode to use when the iso-surface
is desired to surround high data values.
"High":
Selecting this mode will cause the iso-surface polygon
facing to face towards the higher data values.
Usually, this is the mode to use when the iso-surface
is desired to surround low data values.
"Shading" pull-down menu:
Iso-surfaces are normally rendered with light-source
shading. If multiple datasets are currently loaded,
then this menu allows the selection of a different
3D array for the source of the iso-surface shading
values. If only one dataset is currently loaded,
then this menu is inactive.
"Display":
Clicking this button will cause the iso-surface to
be created and drawn. Iso-surfaces often consist
of tens of thousands of polygons, and can sometimes
take considerable time to create and render.
"Projection" mode:
A "voxel" projection of a 3D array is the projection
of the data values within that array onto a viewing
plane. This is similar to taking an X-ray image of
a 3D object.
"Max" mode:
Select this mode for a Maximum intensity projection.
"Avg" mode:
Select this mode for an Average intensity projection.
"Low" mode:
Select this mode for a Low resolution projection.
"Med" mode:
Select this mode for a Medium resolution projection.
"High" mode:
Select this mode for a High resolution projection.
"Depth Queue %":
Use the slider to set the depth queue percent.
A value of 50, for example, indicates that the
farthest part of the projection will be 50 % as
bright as the closest part of the projection.
"Display":
Clicking this button will cause the projection to
be calculated and drawn. Projections can sometimes
take considerable time to display. Higher resolution
projections take more computation time.
"Threshold" mode:
When in Threshold mode, a logarithmic histogram plot
of the data is displayed in the small draw window.
Click and drag the left mouse button on this plot to
set the minimum and maximum threshold values.
To expand a narrow range of data values into the
full range of available colors, set the threshold
range before displaying slices, blocks, or projections.
The threshold settings also affect the histogram
plot in "Surface" mode. The minimum and maximum
threshold values are also shown in the text widgets
below the histogram plot.
Click and drag the right mouse button on the histogram
plot to set the transparency threshold.
Portions of any slice, block, or projection that are
less than the transparency value are not drawn (clear).
Iso-surfaces are not affected by the transparency
threshold. The transparency threshold value is also
shown in a text widget below the histogram plot.
"Min":
In this text widget, a minimum threshold value can
be entered.
"Max":
In this text widget, a maximum threshold value can
be entered.
"Transp.":
In this text widget, a transparency threshold value
can be entered.
"Profile" mode:
In Profile mode, a plot is displayed showing the
data values along a line. This line is also shown
superimposed on the data in the main draw window.
The bottom of the plot corresponds to the "purple"
end of the line, and the top of the plot corresponds
to the "blue" end of the line.
"Orthogonal" mode:
Click and drag the left mouse button to position the
profile line, based upon a point on the "front"
faces of the wire-frame cube. Click and drag the
right mouse button to position the profile line,
based upon a point on the "back" faces of the
wire-frame cube. As the profile line is moved,
The profile plot is dynamically updated.
"Oblique" mode:
Click and drag the left mouse button to position the
"purple" end of the profile line on one of the "front"
faces of the wire-frame cube. Click and drag the
right mouse button to position the "blue" end of the
profile line on one of the "back" faces of the
wire-frame cube. As the profile line is moved,
The profile plot is dynamically updated.
"Probe" mode:
In Probe mode, click and drag a mouse button over
an object in the main draw window. The actual
X-Y-Z location within the data volume is displayed
in the three text widgets. Also, the data value
at that 3D location is displayed in the status
window, above the main draw window. If the cursor
is inside the wire-frame cube, but not on any object,
then the status window displays "No data value", and
the three text widgets are empty. If the cursor is
outside the wire-frame cube, then the status window
and text widgets are empty.
"X":
Use this text widget to enter the X coordinate for
the probe.
"Y":
Use this text widget to enter the Y coordinate for
the probe.
"Z":
Use this text widget to enter the Z coordinate for
the probe.
"View" mode:
In view mode, a small window shows the orientation
of the data cube in the current view. As view
parameters are changed, this window is dynamically
updated. The main draw window is then updated
when the user clicks on "Display", or exits View
mode.
"Display":
Clicking on this button will cause the objects in
the main view window to be drawn in the new view.
If any view parameters have been changed since
the last time the main view was updated, the main
view will be automatically redrawn when the user
exits View mode.
1st Rotation:
Use this slider to set the angle of the first view
rotation (in degrees). The droplist widget adjacent
to the slider indicates which axis this rotation is
about.
2nd Rotation:
Use this slider to set the angle of the second view
rotation (in degrees). The droplist widget adjacent
to the slider indicates which axis this rotation is
about.
"Zoom %":
Use this slider to set the zoom factor percent.
Depending upon the view rotations, Slicer3 may
override this setting to ensure that all eight
corners of the data cube are within the window.
"Z %":
Use this slider to set a scale factor for the Z
axis (to compensate for the data's aspect ratio).
EXAMPLE:
Example 1:
----------
Create a data save file suitable for dynamic loading into
Slicer3.
; Store some 3D data in a variable called "data_1".
data_1 = INDGEN(20,30,40)
; Store some 3D data in a variable called "data_2".
data_2 = FINDGEN(20,30,40)
; Define the names for the datasets (their names will
; appear in the "Data:" pull-down menu in Slicer3.
data_1_name = 'Test Data 1'
data_2_name = 'Data 2'
; Select a data file name.
dataFile = DIALOG_PICKFILE()
; Write the file.
GET_LUN, lun
OPENW, lun, dataFile
WRITEU, lun, SIZE(data_1)
WRITEU, lun, STRLEN(data_1_name)
WRITEU, lun, BYTE(data_1_name)
WRITEU, lun, data_1
WRITEU, lun, SIZE(data_2)
WRITEU, lun, STRLEN(data_2_name)
WRITEU, lun, BYTE(data_2_name)
WRITEU, lun, data_2
CLOSE, lun
FREE_LUN, lun
Example 2:
----------
Run Slicer3 with data passed to it at startup.
; Create some 3D data.
data = INDGEN(20,30,40)
; Create a pointer to the data, and use the "/NO_COPY"
; keyword to save memory.
h_data = PTR_NEW(data, /NO_COPY)
; Start up Slicer3.
SLICER3, h_data, /MODAL
; If the user did not interactively load any data into
; Slicer3 (via the "File/Load" menu), then the original
; pointer to the data still exists (and the original data
; will still reside in memory). To free it, use:
if PTR_VALID(h_data) then PTR_FREE, h_data
; If the pointer is no longer valid, then that indicates
; that the user interactively loaded data into Slicer3.
; Any data that is loaded interactively is automatically
; deleted when the user exits Slicer3.
; Note that the last contents of the main view window in
; Slicer3 still resides in the Z-buffer. To access this
; image after exiting Slicer3, perform the following actions:
current_device = !D.Name
SET_PLOT, 'Z'
image_buffer = TVRD()
depth_buffer = TVRD(CHANNEL=1, /WORDS)
SET_PLOT, current_device
TV, image_buffer
; Note that the image contained in "image_buffer" will look
; "correct" only if the colors loaded by Slicer3 have not
; been changed since the user exited Slicer3.
MODIFICATION HISTORY:
Daniel Carr - RSI, Fri Nov 22 15:43:36 MST 1996
Daniel Carr - RSI, Fri Jan 10 12:08:01 MST 1997
Fixed bugs and added muti-dataset capability.
Alan Youngblood, Daniel Carr - RSI, Wed Feb 11 10:07:32 MST 1998
Modified routine to use pointers.
CT, RSI, June 2000: Remove /MODAL from XMANAGER, add to WIDGET_BASE.
If modal then use button menus rather than menu bar.
Change TIFF output to use color-interleaving (channel,column,row).
CT, RSI, Sept 2002: Add ORIENTATION=4 to WRITE_TIFF calls.
[Previous]
[Next]
NAME:
SLIDE_IMAGE
PURPOSE:
Create a scrolling graphics window for examining large images.
By default, 2 draw widgets are used. The left draw widget shows
a reduced version of the complete image, while the draw widget on
the right displays the actual image with scrollbars that allow sliding
the visible window.
CALLING SEQUENCE:
SLIDE_IMAGE [, Image]
INPUTS:
Image: The 2-dimensional image array to be displayed. If this
argument is not specified, no image is displayed. The
FULL_WINDOW and SCROLL_WINDOW keywords can be used to obtain
the window numbers of the 2 draw widgets so they can be drawn
into at a later time.
KEYWORDS:
CONGRID: Normally, the image is processed with the CONGRID
procedure before it is written to the fully visible
window on the left. Specifying CONGIRD=0 will force
the image to be drawn as is.
FULL_WINDOW: A named variable in which to store the IDL window number of \
the non-sliding window. This window number can be used with
the WSET procedure to draw to the scrolling window at a later
point.
GROUP: The widget ID of the widget that calls SLIDE_IMAGE. If this
keyword is specified, the death of the caller results in the
death of SLIDE_IMAGE.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
ORDER: This keyword is passed directly to the TV procedure
to control the order in which the images are drawn. Usually,
images are drawn from the bottom up. Set this keyword to a
non-zero value to draw images from the top down.
REGISTER: Set this keyword to create a "Done" button for SLIDE_IMAGE
and register the widgets with the XMANAGER procedure.
The basic widgets used in this procedure do not generate
widget events, so it is not necessary to process events
in an event loop. The default is therefore to simply create
the widgets and return. Hence, when register is not set,
SLIDE_IMAGE can be displayed and the user can still type
commands at the "IDL>" prompt that use the widgets.
RETAIN: This keyword is passed directly to the WIDGET_DRAW
function, and controls the type of backing store
used for the draw windows. If not present, a value of
2 is used to make IDL handle backing store. It is
recommended that if RETAIN is set to zero, then the
REGISTER keyword should be set so that expose and scroll
events are handled.
SLIDE_WINDOW: A named variable in which to store the IDL window number of
the sliding window. This window number can be used with the
WSET procedure to draw to the scrolling window at a later
time.
TITLE: The title to be used for the SLIDE_IMAGE widget. If this
keyword is not specified, "Slide Image" is used.
TOP_ID: A named variable in which to store the top widget ID of the
SLIDE_IMAGE hierarchy. This ID can be used to kill the
hierarchy as shown below:
SLIDE_IMAGE, TOP_ID=base, ...
.
.
.
WIDGET_CONTROL, /DESTROY, base
XSIZE: The maximum width of the image that can be displayed by
the scrolling window. This keyword should not be confused
with the visible size of the image, controlled by the XVISIBLE
keyword. If XSIZE is not specified, the width of Image is
used. If Image is not specified, 256 is used.
XVISIBLE: The width of the viewport on the scrolling window. If this
keyword is not specified, 256 is used.
YSIZE: The maximum height of the image that can be displayed by
the scrolling window. This keyword should not be confused
with the visible size of the image, controlled by the YVISIBLE
keyword. If YSIZE is not present the height of Image is used.
If Image is not specified, 256 is used.
YVISIBLE: The height of the viewport on the scrolling window. If
this keyword is not present, 256 is used.
OUTPUTS:
None.
CALLS: ***
CONGRID, SLIDE_IMG_EVENT, XMANAGER
COMMON BLOCKS:
None.
SIDE EFFECTS:
Widgets for displaying a very large image are created.
The user typically uses the window manager to destroy
the window, although the TOP_ID keyword can also be used to
obtain the widget ID to use in destroying it via WIDGET_CONTROL.
RESTRICTIONS:
Scrolling windows don't work correctly if backing store is not
provided. They work best with window-system-provided backing store
(RETAIN=1), but are also usable with IDL provided backing store
(RETAIN=2).
Various machines place different restrictions on the size of the
actual image that can be handled.
MODIFICATION HISTORY:
7 August, 1991, Written by AB, RSI.
10 March, 1993, ACY, Change default RETAIN=2
23 Sept., 1994 KDB, Fixed Typo in comments. Fixed error in
Congrid call. xvisible was used instead of yvisible.
20 March, 2001 DLD, Add event handling for expose and scroll events
when RETAIN=0.
[Previous]
[Next]
NAME:
SPH_4PNT
PURPOSE:
Given four 3-dimensional points, this procedure returns the
center and radius necessary to define the unique sphere passing
through those points.
CATEGORY:
Analytic Geometry.
CALLING SEQUENCE:
SPH_4PNT, X, Y, Z, Xc, Yc, Zc, R
INPUTS:
X: A 4-element vector containing the X coordinates of the points.
Y: A 4-element vector containing the Y coordinates of the points.
Z: A 4-element vector containing the Z coordinates of the points.
Note: X, Y, and Z should be floating-point or double-precision
vectors.
OUTPUTS:
Xc: The sphere's center x-coordinate.
Yc: The sphere's center y-coordinate.
Zc: The sphere's center z-coordinate.
R: The sphere's radius.
RESTRICTIONS:
Points may not coincide.
EXAMPLE:
Find the center and radius of the unique sphere passing through
the points: (1, 1, 0), (2, 1, 2), (1, 0, 3), (1, 0, 1)
Define the floating-point vectors containing the x, y and z
coordinates of the points.
X = [1, 2, 1, 1] + 0.0
Y = [1, 1, 0, 0] + 0.0
Z = [0, 2, 3, 1] + 0.0
Compute the sphere's center and radius.
SPH_4PNT, X, Y, Z, Xc, Yc, Zc, R
Print the results.
PRINT, Xc, Yc, Zc, R
MODIFICATION HISTORY:
Written by: GGS, RSI, Jan 1993
Modified: GGS, RSI, March 1994
Rewrote documentation header.
Uses the new Numerical Recipes NR_LUDCMP/NR_LUBKSB.
Modified: GGS, RSI, November 1994
Changed internal array from column major to row major.
Changed NR_LUDCMP/NR_LUBKSB to LUDC/LUSOL
Modified: GGS, RSI, June 1995
Added DOUBLE keyword.
Modified: GGS, RSI, April 1996
Modified keyword checking and use of double precision.
[Previous]
[Next]
NAME:
SPH_SCAT
PURPOSE:
Interpolate to a regular grid given scattered samples on the
surface of a sphere.
CATEGORY:
Interpolation.
CALLING SEQUENCE:
Result = SPH_SCAT(lon, lat, f)
INPUTS:
lon = sample longitudes, a vector, in degrees. lon, lat, and
f must have the same number of points.
lat = sample latitudes, a vector, in degreees.
f = data values measured at lon and lat. f(i) = sample value
at lon(i), lat(i).
KEYWORD PARAMETERS:
GS: If present, GS must be a two-element vector [XS, YS],
where XS is the spacing between grid points in longitude,
and YS is the spacing in latitude. The default is based on
the extents of lon and lat. If the grid starts at longitude
Lonmin and ends at Lonmax, then the default horizontal
spacing is (Lonmax - Lonmin)/(NX-1). YS is computed in the
same way. The default grid size, if neither NX or NY
are specified, is 26 by 26.
BOUNDS: If present, BOUNDS must be a four element array containing
the grid limits in longitude and latitude of the output grid:
[Lonmin, Latmin, Lonmax, Latmax]. If not specified, the grid
limits are set to the extent of lon and lat. Warning:
to cover all longitudes, you must directly specify BOUNDS.
NLON: The output grid size in the longitude direction. NLON need not
be specified if the size can be inferred from GS and
BOUNDS. The default value is 26.
NLAT: The output grid size in the latitude direction. See NLON.
NX, NY: Obsolete synonyms for NLON and NLAT, respectively.
BOUT: the actual extent of the regular grid, arranged as in
bounds. An optional output parameter.
GOUT: The actual grid spacing, a two element optional output array.
OUTPUTS:
Result = regularly interpolated result.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Timing. on a Sun SPARCstation LX producing a 36 x 36 output
grid (1296 points), t is ~ .578 + .00368 * N + 2.39e-06 * N^2.
For example:
N 16 64 256 1024 4096
Time .7 .8 1.6 6.6 56
Output points are produced at a rate of approximately 2000
points per second.
PROCEDURE:
This routine is a convenience interface to the Spherical gridding
and interpolation provided by TRIANGULATE and TRIGRID. The
methods are based on the work of Robert Renka, Interpolation of Data
on the Surface of a Sphere, Oak Ridge Natl Lab Technical Paper
CSD-108. The procedure consists of generating a triangulation of the
scattered data points, estimating the gradients with a local method,
and then constructing a triangle based interpolant of the data and
gradient estimates. The interpolant is C(1) continuous.
EXAMPLE:
Create 50 random longitudes and latitudes, make a function value,
and then interpolate, obtaining a 360 x 360 array of
10 degree by 5 degree resolution that covers the sphere:
lon = randomu(seed, 50) * 360. -180. ;Make random scattered points
lat = randomu(seed, 50) * 180. -90.
z = sin(lat*!DTOR) ;Make a function to fit
c = cos(lat*!DTOR)
x = cos(lon*!DTOR) * c
y = sin(lon*!DTOR) * c
f = sin(x+y) * sin(x*z) ;The dependent variable
** Now, given lon, lat, and f, interpolate the data:
result = sph_scat(lon, lat, f, bounds=[0, -90, 350, 85], gs=[10,5])
MODIFICATION HISTORY:
DMS, November, 1994. Written.
[Previous]
[Next]
NAME:
SPHER_HARM
PURPOSE:
This function returns the value of the spherical harmonic
Y(L,M)[theta,phi], |M| <= L, which is a function of two coordinates
(theta, phi) on a spherical surface.
CATEGORY:
Special Math Functions
CALLING SEQUENCE:
Result = SPHER_HARM(Theta, Phi, L, M [, /DOUBLE])
INPUTS:
Theta: The value of the polar (colatitudinal) coordinate at which Y(L,M)
is evaluated. Theta can be either a scalar or an array.
Phi: The value of the azimuthal (longitudinal) coordinate at which Y(L,M)
is evaluated. Phi can be either a scalar or an array.
If Theta and Phi are both arrays then they must have the same number
of elements.
L: An integer specifying the order L of Y(L,M). If L is of type float
then it will be truncated.
M: An integer, -L <= M <= L, specifying the azimuthal order M of Y(L,M).
If M is of type float then it will be truncated.
KEYWORD PARAMETERS:
DOUBLE: Set this keyword to force the computation to be done in
double-precision arithmetic.
OUTPUT:
The result returned by SPHER_HARM is a complex array that has the
same dimensions as the input arrays.
PROCEDURE:
Uses LEGENDRE().
CALLS: ***
FACTORIAL
EXAMPLE:
To visualize the electron probability density for the hydrogen atom
in state 3d0. (Feynman, Leighton, and Sands, 1965:
The Feynman Lectures on Physics, Calif. Inst. Tech, Ch. 19).
;define a data cube (N x N x N)
n = 41L
a = 60*FINDGEN(n)/(n-1) - 29.999 ; [-1,+1]
x = REBIN(a, n, n, n) ; X-coordinates of cube
y = REBIN(REFORM(a,1,n), n, n, n) ; Y-coordinates
z = REBIN(REFORM(a,1,1,n), n, n, n); Z-coordinates
;convert from rectangular (x,y,z) to spherical (phi, theta, r)
spherCoord = CV_COORD(FROM_RECT=TRANSPOSE([[x[*]],[y[*]],[z[*]]]), /TO_SPHERE)
phi = REFORM(spherCoord[0,*], n, n, n)
theta = REFORM(!PI/2 - spherCoord[1,*], n, n, n)
r = REFORM(spherCoord[2,*], n, n, n)
;find electron probability density for hydrogen atom in state 3d0
;Angular component
L = 2 ; state "d" is electron spin L=2
M = 0 ; Z-component of spin is zero
angularState = SPHER_HARM(theta, phi, L, M)
;Radial component for state n=3, L=2
radialFunction = EXP(-r/2)*(r^2)
waveFunction = angularState*radialFunction
probabilityDensity = ABS(waveFunction)^2
SHADE_VOLUME, probabilityDensity, 0.1*MEAN(probabilityDensity), vertex, poly
oPolygon = OBJ_NEW('IDLgrPolygon', vertex, POLYGON=poly, COLOR=[180,180,180])
XOBJVIEW, oPolygon
MODIFICATION HISTORY:
Written by: CT, RSI, March 2000.
[Previous]
[Next]
NAME:
SPLINE
PURPOSE:
This function performs cubic spline interpolation.
CATEGORY:
Interpolation - E1.
CALLING SEQUENCE:
Result = SPLINE(X, Y, T [, Sigma])
INPUTS:
X: The abcissa vector. Values MUST be monotonically increasing.
Y: The vector of ordinate values corresponding to X.
T: The vector of abcissae values for which the ordinate is
desired. The values of T MUST be monotonically increasing.
OPTIONAL INPUT PARAMETERS:
Sigma: The amount of "tension" that is applied to the curve. The
default value is 1.0. If sigma is close to 0, (e.g., .01),
then effectively there is a cubic spline fit. If sigma
is large, (e.g., greater than 10), then the fit will be like
a polynomial interpolation.
KEYWORDS:
DOUBLE: Set this keyword to force computations to be done
using double-precision arithmetic.
OUTPUTS:
SPLINE returns a vector of interpolated ordinates.
Result(i) = value of the function at T(i).
CALLED BY:
WF_DRAW
RESTRICTIONS:
Abcissa values must be monotonically increasing.
EXAMPLE:
The commands below show a typical use of SPLINE:
X = [2.,3.,4.] ;X values of original function
Y = (X-3)^2 ;Make a quadratic
T = FINDGEN(20)/10.+2 ;Values for interpolated points.
;twenty values from 2 to 3.9.
Z = SPLINE(X,Y,T) ;Do the interpolation.
MODIFICATION HISTORY:
Author: Walter W. Jones, Naval Research Laboratory, Sept 26, 1976.
Reviewer: Sidney Prahl, Texas Instruments.
Adapted for IDL: DMS, Research Systems, March, 1983.
CT, RSI, July 2003: Added double precision support and DOUBLE keyword,
use vector math to speed up the loops.
CT, RSI, August 2003: Must have at least 3 points.
[Previous]
[Next]
NAME:
SPLINE_P
PURPOSE:
This procedure performs parameteric cubic spline interpolation.
CATEGORY:
Interpolation - E1.
CALLING SEQUENCE:
SPLINE_P, X, Y, Xr, Yr
INPUTS:
X: The abcissa vector (should be floating or double).
Y: The vector of ordinate values corresponding to X.
Neither X or Y need be monotonic.
KEYWORD PARAMETERS:
DOUBLE: Set this keyword to force computations to be done
using double-precision arithmetic.
INTERVAL: The interval in XY space between interpolants. If
omitted, approximately 8 interpolants per XY segment
will result.
TAN0: The tangent to the spline curve at X[0], Y[0]. If omitted,
the tangent is calculated to make the curvature of the
result zero at the beginning. This is a two element vector,
containing the X and Y components of the tangent.
TAN1: The tangent to the spline curve at X[N-1], Y[N-1].If omitted,
the tangent is calculated to make the curvature of the
result zero at the end. This is a two element vector,
containing the X and Y components of the tangent.
OUTPUTS:
XR: The abcissa values of the interpolated function. This
may NOT be the same variable as either X or Y.
YR: The ordinate values of the interpolated function. This
may NOT be the same variable as either X or Y.
CALLED BY:
ANNOTATE
RESTRICTIONS:
X and Y should be floating or double.
PROCEDURE:
Cubic spline interpolation with relaxed or clamped end conditions
as used in the Numerical Recipes.
This routine is both more general and faster than the
user's library function SPLINE. One call to SPLINE_P is equivalent
to two calls to SPLINE, as both the X and Y are interpolated with
splines. It is suited for interpolating between randomly
placed points, and the abcissae values need not be monotonic.
In addition, the end conditions may be optionally specified via
tangents.
EXAMPLE:
The commands below show a typical use of SPLINE_P:
X = [0.,1,0,-1,0] ;Abcissae for square with a vertical diagonal
Y = [0.,1,2,1,0] ;Ordinates
SPLINE_P, X, Y, XR, YR ;Interpolate with relaxed end conditions
PLOT, XR, YR ;Show it
As above, but with setting both the beginning and end tangents:
SPLINE_P, X, Y, XR, YR, TAN0=[1,0], TAN1=[1,0]
This yields approximately 32 interpolants.
As above, but with setting the interval to 0.05, making more
interpolants, closer together:
SPLINE_P, X, Y, XR, YR, TAN0=[1,0], TAN1=[1,0], INTERVAL=0.05
This yields 116 interpolants and looks close to a circle.
MODIFICATION HISTORY:
DMS, RSI. August, 1993. Written.
DMS, RSI. Jan, 1994. Modified to use NR_ spline routines.
CT, RSI, July 2003: Quietly discard repeated points,
add double-precision support and DOUBLE keyword.
CT, RSI, April 2005: If the first and last points are identical,
don't discard the first point.
[Previous]
[Next]
NAME:
STANDARDIZE
PURPOSE:
This function computes standardized variables from an array
of M variables (columns) and N observations (rows). The result
is an M-column, N-row array where all columns have a mean of
zero and a variance of one.
CATEGORY:
Statistics
CALLING SEQUENCE:
Result = Standardize(A)
INPUTS:
A: An M-column, N-row array of type float or double.
KEYWORD PARAMETERS:
DOUBLE: If set to a non-zero value, computations are done in
double precision arithmetic.
EXAMPLE:
Define an array with 4 variables and 20 observations.
array = $
[[19.5, 43.1, 29.1, 11.9], $
[24.7, 49.8, 28.2, 22.8], $
[30.7, 51.9, 37.0, 18.7], $
[29.8, 54.3, 31.1, 20.1], $
[19.1, 42.2, 30.9, 12.9], $
[25.6, 53.9, 23.7, 21.7], $
[31.4, 58.5, 27.6, 27.1], $
[27.9, 52.1, 30.6, 25.4], $
[22.1, 49.9, 23.2, 21.3], $
[25.5, 53.5, 24.8, 19.3], $
[31.1, 56.6, 30.0, 25.4], $
[30.4, 56.7, 28.3, 27.2], $
[18.7, 46.5, 23.0, 11.7], $
[19.7, 44.2, 28.6, 17.8], $
[14.6, 42.7, 21.3, 12.8], $
[29.5, 54.4, 30.1, 23.9], $
[27.7, 55.3, 25.7, 22.6], $
[30.2, 58.6, 24.6, 25.4], $
[22.7, 48.2, 27.1, 14.8], $
[25.2, 51.0, 27.5, 21.1]]
Compute the mean and variance of each variable using the MOMENT
function. Note: The skewness and kurtosis are also computed.
IDL> for k = 0, 3 do print, MOMENT(array[k,*])
25.3050 25.2331 -0.454763 -1.10028
51.1700 27.4012 -0.356958 -1.19516
27.6200 13.3017 0.420289 0.104912
20.1950 26.0731 -0.363277 -1.24886
Compute the standardized variables.
IDL> result = STANDARDIZE(array)
Compute the mean and variance of each standardized variable using
the MOMENT function. Note: The skewness and kurtosis are also computed.
IDL> for k = 0, 3 do print, MOMENT(result[k,*])
-7.67130e-07 1.00000 -0.454761 -1.10028
-3.65451e-07 1.00000 -0.356958 -1.19516
-1.66707e-07 1.00000 0.420290 0.104913
4.21703e-07 1.00000 -0.363278 -1.24886
MODIFICATION HISTORY:
Written by: GGS, RSI, February 1996
[Previous]
[Next]
NAME:
STDDEV
PURPOSE:
This function computes the stddev of an N-element vector.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = stddev(X)
INPUTS:
X: An N-element vector of type integer, float or double.
KEYWORD PARAMETERS:
DOUBLE: IF set to a non-zero value, computations are done in
double precision arithmetic.
NAN: If set, treat NaN data as missing.
CALLS: ***
MOMENT
CALLED BY:
REGION_GROW
EXAMPLE:
Define the N-element vector of sample data.
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
Compute the standard deviation.
result = stddev(x)
The result should be:
8.16292
PROCEDURE:
STDDEV calls the IDL function MOMENT.
REFERENCE:
APPLIED STATISTICS (third edition)
J. Neter, W. Wasserman, G.A. Whitmore
ISBN 0-205-10328-6
MODIFICATION HISTORY:
Written by: GSL, RSI, August 1997
[Previous]
[Next]
NAME:
STREAMLINE
PURPOSE:
This routine serves to generate the visualization graphics from a
path. The output is a polygonal ribbon which is tangent to a vector
field along its length. The ribbon is generated by placing a line at
each vertex in the direction specified by each normal value multiplied
by the anisotropy factor. The input normal array is not normalized
before use, making it possible to vary the ribbon width as well.
CATEGORY:
3D Toolkit
CALLING SEQUENCE:
STREAMLINE, verts, conn, normals, outverts, outconn
[, ANISOTROPY = vector][, SIZE = vector][, PROFILE = array]
INPUTS:
Verts: Input array of path vertices ([3,N] array).
Conn: Input path connectivity array in IDLgrPolyline POLYLINES
keyword format. There is one set of line segments in this
array for each streamline.
Normals: Normal estimate at each input vertex ([3,N] array).
OUTPUTS:
Outverts: Output vertices ([3,M] float array). Useful if the
routine is to be used with Direct Graphics or the user wants to
manipulate the data directly.
Outconn: Output polygon connectivity array to match the output vertices.
OPTIONAL KEYWORD PARAMETERS:
ANISOTROPY: Set this input keyword to a three element array
describing the distance between grid points in each dimension.
The default value is [1.0, 1.0, 1.0]
SIZE: Set this keyword to a vector of values (one for each path
point). These values are used to specify the width of the
ribbon or the size of profile at each point along its path.
This keyword is generally used to convey additional data
parameters along the streamline.
PROFILE: Set this keyword an array of 2D points which are treated as
the cross section of the ribbon instead of a line segment.
If the first and last points in the array are the same, a
closed profile is generated. The profile is placed at each
path vertex in the plane perpendicular to the line connecting
each path vertex with the vertex normal defining the up
direction.
PROCEDURE/EXAMPLES:
PARTICLE_TRACE, data, seeds, outverts, outconn, outnormals
STREAMLINE, outverts, outconn, outnormals*width, outverts2,
outconn2, PROFILE=[[-1, -1], [-1, 1], [1, 1], [1, -1], [-1,-1]]
oStreamTubes = OBJ_NEW('IDLgrPolygon',outverts2,POLYGONS=outconn2)
CALLS: ***
CROSSP
MODIFICATION HISTORY:
KB, written Feb 1999.
[Previous]
[Next]
NAME:
STRETCH
PURPOSE:
Stretch the image display color tables so the full range
runs from one color index to another.
CATEGORY:
Image processing, point operations.
CALLING SEQUENCE:
STRETCH, Low, High [, /CHOP]
INPUTS:
Low: The lowest pixel value to use. If this parameter is omitted,
0 is assumed. Appropriate values range from 0 to the number
of available colors-1.
High: The highest pixel value to use. If this parameter is omitted,
the number of colors-1 is assumed. Appropriate values range
from 0 to the number of available colors-1.
OPTIONAL INPUTS:
Gamma: Gamma correction factor. If this value is omitted, 1.0 is
assumed. Gamma correction works by raising the color indices
to the Gamma power, assuming they are scaled into the range
0 to 1.
KEYWORD PARAMETERS:
CHOP: If this keyword is set, color values above the upper threshold
are set to color index 0. Normally, values above the upper
threshold are set to the maximum color index.
OUTPUTS:
No explicit outputs.
CALLED BY:
SLICER3
COMMON BLOCKS:
COLORS: The common block that contains R, G, and B color
tables loaded by LOADCT, HSV, HLS and others.
SIDE EFFECTS:
Image display color tables are loaded.
RESTRICTIONS:
Common block COLORS must be loaded before calling STRETCH.
PROCEDURE:
New R, G, and B vectors are created by linearly interpolating
the vectors in the common block from Low to High. Vectors in the
common block are not changed.
If NO parameters are supplied, the original color tables are
restored.
EXAMPLE:
Load the STD GAMMA-II color table by entering:
LOADCT, 5
Create and display and image by entering:
TVSCL, DIST(300)
Now adjust the color table with STRETCH. Make the entire color table
fit in the range 0 to 70 by entering:
STRETCH, 0, 70
Notice that pixel values above 70 are now colored white. Restore the
original color table by entering:
STRETCH
MODIFICATION HISTORY:
DMS, RSI, Dec, 1983.
DMS, April, 1987. Changed common.
DMS, October, 1987. For unix.
DMS, RSI, Nov., 1990. Added GAMMA parameter.
[Previous]
[Next]
NAME:
STRSPLIT
PURPOSE:
Wrapper on the build in system routine STRTOK that implements exactly
the same interface as STRTOK, but with the STRSPLIT name.
The reason for doing this is so that if a user has their own
STRSPLIT in their local user library, their version will superceed
this one. RSI does not recommend this practice, but it is
allowed for backwards compatability reasons. See the
documentation for STRSPLIT in the IDL Reference manual
for details on arguments, keywords, and results.
CALLED BY:
CW_FORM, DEFINE_MSGBLK_FROM_FILE, H5_BROWSER, IDLitwdCurveFitting
IDLitwdImportWizard, IDLitwdTool, ONLINE_HELP_PDF_INDEX
ONLINE_HELP_PDF_ND2FILE, _idlitmanipulator__define, cw_dicomex_query
idlitdatamanagerfolder__define, idlitopstyleapply__define
idlitopstylecreate__define, idlitsrvcreatevisualization__define
idlitstylefolder__define, idlittool__define [1], idlittool__define [2]
idlitviscontour__define [1], idlitviscontour__define [2]
idlitviscontour__define [3], idlitviscontour__define [4]
idlitvisimage__define [10], idlitvisimage__define [11]
idlitvisimage__define [12], idlitvisimage__define [13]
idlitvisimage__define [14], idlitvisimage__define [1]
idlitvisimage__define [2], idlitvisimage__define [3]
idlitvisimage__define [4], idlitvisimage__define [5]
idlitvisimage__define [6], idlitvisimage__define [7]
idlitvisimage__define [8], idlitvisimage__define [9]
idlitvissurface__define [1], idlitvissurface__define [2]
idlitvissurface__define [3]
MODIFICATION HISTORY:
14 October 1999, AB, RSI.
AB, 5/4/2001, Switch from using _EXTRA to _STRICT_EXTRA, so that
incorrect keywords passed to STRTOK will issue proper
error messages instead of being silently ignored.
[Previous]
[Next]
NAME:
SURFR
PURPOSE:
Set up 3D transformations.
This procedure duplicates the rotation, translation, and scaling
features of the SURFACE routine.
CATEGORY:
Graphics, 3D.
CALLING SEQUENCE:
SURFR [, AX = ax] [, AZ = az]
INPUTS:
No plain parameters.
KEYWORD PARAMETERS:
AX: Angle of rotation about the X axis. The default is 30 degrees.
AZ: Angle of rotation about the Z axis. The default is 30 degrees.
OUTPUTS:
No explicit outputs. Results are stored in !P.T.
CALLS: ***
SCALE3D, T3D
CALLED BY:
SHADE_SURF_IRR
COMMON BLOCKS:
None.
SIDE EFFECTS:
The 4 by 4 matrix, !P.T, the 3D transformation system variable,
receives the homogeneous transformation matrix generated by this
procedure.
RESTRICTIONS:
Axonometric projections only.
PROCEDURE:
1. Translate the unit cube so that the center (.5,.5,.5) is moved
to the origin.
2. Rotate -90 degrees about the X axis to make the +Z
axis of the data the +Y axis of the display. The +Y data axis
extends from the front of the display to the rear.
3. Rotate about the Y axis AZ degrees. This rotation is
counterclockwise as seen from above the page.
4. Rotate about the X axis AX degrees, tilting the data
toward the viewer.
5. Translate back to the origin and scale the data so
that the data are still contained within the unit cube after
transformation. This step uses the user procedure SCALE3D.
MODIFICATION HISTORY:
DMS, may, 1988.
[Previous]
[Next]
NAME:
SVDFIT
PURPOSE:
Perform a general least squares fit with optional error estimates.
This version uses the Numerical Recipies (2nd Edition) function
SVDFIT. A user-supplied function or a built-in polynomial or
legendre polynomial is fit to the data.
CATEGORY:
Curve fitting.
CALLING SEQUENCE:
Result = SVDFIT(X, Y, [M])
INPUTS:
X: A vector representing the independent variable.
Y: Dependent variable vector. This vector must be same length
as X.
OPTIONAL INPUTS:
M: The number of coefficients in the fitting function. For
polynomials, M is equal to the degree of the polynomial + 1.
If not specified and the keyword A is set, then
M = N_ELEMENTS(A).
INPUT KEYWORDS:
A: The inital estimates of the desired coefficients. If M
is specified, then A must be a vector of M elements.
If A is specified, then the input M can be omitted and
M=N_ELEMENTS(A). If not specified, the initial value
of each coefficient is taken to be 1.0. If both M and A are
specified, them must agree as to the number of paramaters.
DOUBLE: Set this keyword to force double precision computations. This
is helpful in reducing roundoff errors and improves the chances
of function convergence.
MEASURE_ERRORS: Set this keyword to a vector containing standard
measurement errors for each point Y[i]. This vector must be the same
length as X and Y.
Note - For Gaussian errors (e.g. instrumental uncertainties),
MEASURE_ERRORS should be set to the standard
deviations of each point in Y. For Poisson or statistical weighting
MEASURE_ERRORS should be set to sqrt(Y).
TOL: Set this keyword to the tolerance used when removing singular
values. The default is 1e-5 for single precision, and 2d-12
for double precision (these defaults are approximately 100
and 10000 times the machine precisions for single and
double precision, respectively). Setting TOL to a larger value
may remove coefficients that do not contribute to the solution,
which may reduce the errors on the remaining coefficients.
Note - The WEIGHTS keyword is obsolete. New code should use MEASURE_ERRORS.
WEIGHTS: A vector of weights for Y[i]. This vector must be the same
length as X and Y. If this parameter is ommitted, 1's
(No weighting) are assumed.
The error for each term is weighted by Weight[i] when computing the
fit. Gaussian or instrumental uncertianties should be weighted as
Weight = 1/Sigma where Sigma is the measurement error or standard
deviations of Y. For Poisson or statistical weighting use
Weight=1/sqrt(Y), since Sigma=sqrt(Y).
FUNCTION_NAME:
A string that contains the name of an optional user-supplied
basis function with M coefficients. If omitted, polynomials
are used.
The function is called: R=SVDFUNCT(X,M)
where X and M are scalar values, and the function value is an
M element vector evaluated at X with the M basis functions.
M is the degree of the polynomial +1 if the basis functions are
polynomials. For example, see the function SVDFUNCT or SVDLEG,
in the IDL User Library:
For more examples, see Numerical Recipes in C, second Edition,
page 676-681.
The basis function for polynomials, is R[j] = x)^j.
The function must be able to return R as a FLOAT vector or
a DOUBLE vector depending on the input type of X.
LEGENDRE: Set this keyword to use the IDL function SVDLEG in the lib
directory to fit the data to an M element legendre polynomial.
This keyword overrides the FUNCTION_NAME keyword.
OUTPUTS:
SVDFIT returns a vector of the M coefficients fitted to the
supplied function.
OPTIONAL OUTPUT PARAMETERS:
CHISQ: Sum of squared errors divided by MEASURE_ERRORS if specified.
COVAR: Covariance matrix of the coefficients.
VARIANCE: Sigma squared in estimate of each coeff(M).
That is sqrt(VARIANCE) equals the 1 sigma deviations
of the returned coefficients.
SIGMA: The 1-sigma error estimates of the returned parameters,
SIGMA=SQRT(VARIANCE).
Note: if MEASURE_ERRORS is omitted, then you are assuming that
your model is correct. In this case,
SIGMA is multiplied by SQRT(CHISQ/(N-M)), where N is the
number of points in X. See section 15.2 of Numerical Recipes
in C (Second Edition) for details.
SINGULAR: The number of singular values returned. This value should
be 0. If not, the basis functions do not accurately
characterize the data.
SING_VALUES: Set this keyword to a named variable in which to return the
singular values from the SVD. Singular values which have been removed
will be set to zero.
STATUS: Set this keyword to a named variable that will contain the status
of the computation. Possible values are:
STATUS = 0: The computation was successful.
STATUS > 0: Singular values were found and were removed.
STATUS contains the number of singular values.
Note: If STATUS is not specified, any error messages will be output
to the screen.
YFIT: Vector of calculated Y's.
CALLS: ***
REVERSE
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
MODIFICATION HISTORY:
Adapted from SVDFIT, from the book Numerical Recipes, Press,
et. al., Page 518.
minor error corrected April, 1992 (J.Murthy)
Completely rewritten to use the actual Numerical Recipes routines
of the 2nd Edition (V.2.06). Added the DOUBLE, SIGMA, A, and
LEGENDRE keywords. Also changed Weight to Weights to match the
other fitting routines.
CT, RSI, March 2000: Fixed DOUBLE keyword; fixed SIGMA if
WEIGHTS is omitted.
CT, RSI, August 2000: Added MEASURE_ERRORS.
CT, RSI, September 2002: Add SING_VALUES, STATUS, TOL keywords. Change
default tolerance from 1e-9 to 1e-5 (single) or 2d-12 (double).
Variance values are now removed using the SING_VALUES vector.
[Previous]
[Next]
NAME:
SWAP_ENDIAN
PURPOSE:
This function reverses the byte ordering of arbitrary scalars,
arrays or structures. It may be used, for example, to make little
endian numbers big, or big endian numbers little.
CATEGORY:
Utility.
CALLING SEQUENCE:
Result = SWAP_ENDIAN(A)
INPUTS:
A: The scalar, array, or structure to be swapped.
KEYWORDS:
SWAP_IF_BIG_ENDIAN
If this keyword is set, the swap request will only be
performed if the platform running IDL uses "big endian"
byte ordering. On little endian machines, the SWAP_ENDIAN_INPLACE
request quietly returns without doing anything. Note that this keyword
does not refer to the byte ordering of the input data, but to the
computer hardware.
SWAP_IF_LITTLE_ENDIAN
If this keyword is set, the swap request will only be
performed if the platform running IDL uses "little endian"
byte ordering. On big endian machines, the SWAP_ENDIAN_INPLACE
request quietly returns without doing anything. Note that this keyword
does not refer to the byte ordering of the input data, but to the
computer hardware.
OUTPUTS:
Result: The same type and structure as the input, with the
pertinent bytes reversed.
CALLED BY:
QUERY_BMP, QUERY_WAV, READ_BMP, READ_WAV, SLICER3, WRITE_BMP, WRITE_NRIF, WRITE_WAV
RESTRICTIONS:
Always makes a copy of the input data. If your data is large
enough for this to be a problem, and you don't require a separate
copy, the SWAP_ENDIAN_INPLACE procedure is recommended.
Structures are handled correctly, but are not as efficient as
simple types.
PROCEDURE:
Swap arrays and scalars directly using BYTEORDER.
Swap structures recursively.
EXAMPLE:
A = SWAP_ENDIAN(A) ;Reverses the "endianness" of A
MODIFICATION HISTORY:
DMS, RSI, May, 1993. Written.
DMS, RSI, July, 1993. Added double complex.
AB, RSI, 5 October 1998, Fixed double complex case and updated for
pointer, object reference, unsigned 16, 32, and 64-bit
integers, and 64-bit signed integers.
AB, RSI, 2 October 2001, Added the SWAP_IF_[BIG|LITTLE]_ENDIAN
keywords.
[Previous]
[Next]
NAME:
SWAP_ENDIAN_INPLACE
PURPOSE:
This function reverses the byte ordering of arbitrary scalars,
arrays or structures. It may be used, for example, to make little
endian numbers big, or big endian numbers little. It alters the
input data in place rather than making a copy as the SWAP_ENDIAN
function does.
CATEGORY:
Utility.
CALLING SEQUENCE:
SWAP_ENDIAN_INPLACE, A
INPUTS:
A: The scalar, array, or structure to be swapped.
KEYWORDS:
SWAP_IF_BIG_ENDIAN
If this keyword is set, the swap request will only be
performed if the platform running IDL uses "big endian"
byte ordering. On little endian machines, the SWAP_ENDIAN_INPLACE
request quietly returns without doing anything. Note that this keyword
does not refer to the byte ordering of the input data, but to the
computer hardware.
SWAP_IF_LITTLE_ENDIAN
If this keyword is set, the swap request will only be
performed if the platform running IDL uses "little endian"
byte ordering. On big endian machines, the SWAP_ENDIAN_INPLACE
request quietly returns without doing anything. Note that this keyword
does not refer to the byte ordering of the input data, but to the
computer hardware.
OUTPUTS:
The data in A has its pertinent bytes reversed.
CALLED BY:
BINARY_TEMPLATE, READ_BINARY
RESTRICTIONS:
Structures are handled correctly, but are not as efficient as
simple types.
PROCEDURE:
Swap arrays and scalars directly using BYTEORDER.
Swap structures recursively.
EXAMPLE:
SWAP_ENDIAN_INPLACE, A ;Reverses the "endianness" of A
MODIFICATION HISTORY:
AB, RSI, 2 October 2001, Written. This routine is based on
SWAP_ENDIAN, but performs the swapping on the input
rather than on a copy. Since no copy is involved,
it is efficient to support the SWAP_IF_[BIG|LITTLE]_ENDIAN
keywords, which is not necessarily the case with SWAP_ENDIAN.