This page was created by the IDL library routine
mk_html_help.
NAME:
IDL Commands
This reference is a complete listing of
all built-in IDL functions, procedures,
statements, executive commands, and
objects, collectively referred to as
"commands." Every IDL language element
that can be used either at the command
line or in a program is listed alphabetically.
A description of each routine follows its
name.
Note
Descriptions of Scientific Data Formats
routines (CDF_*, EOS_*, HDF_*, and
NCDF_* routines) can be found in
the Scientific Data Formats book.
Routines written in the IDL language are
noted as such, and the location of the .pro
file within the IDL distribution is specified.
You may wish to inspect the IDL source
code for some of these routines to gain
further insight into their inner workings.
Conventions used in this reference
guide are described below.
NAME:
IDL Syntax
The following table lists the
elements used in IDL syntax listings:
Element Description
[ ] (Square brackets) Indicates that the contents are optional. Do not include the
brackets in your call.
[ ] (Italicized square Indicates that the
square brackets are part of the statement
brackets) (used to define an array).
Argument Arguments are shown in italics, and must be specified in
the order listed.
KEYWORD Keywords are all caps, and can be specified in any order.
For functions, all arguments
and keywords must be
contained within parentheses.
/KEYWORD Indicates a boolean keyword.
Italics Indicates arguments, expressions, or statements for which
you must provide values.
{ } (Braces) * Indicates that you must choose one of the values they
contain
* Encloses a list of possible
values, separated by vertical
lines ( | )
* Encloses useful
information about a keyword
* Defines an IDL structure
(this is the only case in which
the braces are included in the call).
| (Vertical lines) Separates multiple values or keywords.
[, Value1, ... , Valuen] Indicates that
any number of values can be specified.
[, Value1, ... , Value8] Indicates the
maximum number of values that can be
specified.
Table 1: Elements of IDL Syntax
Elements of Syntax
Square Brackets ( [ ] )
* Content between square brackets is
optional. Pay close attention to the
grouping of square brackets.
Consider the following examples:
ROUTINE_NAME, Value1 [, Value2] [,
Value3]: You must include Value1.
You do not have to include Value2
or Value3. Value2 and Value3 can be
specified independently.
ROUTINE_NAME, Value1 [, Value2,
Value3]: You must include Value1. You
do not have to include Value2 or Value3,
but you must include both Value2 and
Value3, or neither.
ROUTINE_NAME [, Value1 [, Value2]]:
You can specify Value1 without
specifying Value2, but if you specify
Value2, you must also specify Value1.
* Do not include square brackets in
your statement unless the brackets are
italicized. Consider the following syntax:
Result = KRIG2D( Z [, X, Y] [,
BOUNDS=[xmin, ymin, xmax, ymax]] )
An example of a valid statement is:
R = KRIG2D( Z, X, Y, BOUNDS=[0,0,1,1] )
* Note that when [, Value1, ... , Valuen]
is listed, you can specify any number of
arguments. When an explicit number is
listed, as in [, Value1, ... , Value8], you
can specify only as many arguments as are listed.
Braces ( { } )
* For certain keywords, a list of the
possible values is provided. This list is
enclosed in braces, and the choices are
separated by a vertical line ( | ). Do not
include the braces in your statement.
For example, consider the following
syntax:
LIVE_EXPORT [, QUALITY={0 | 1 | 2}]
In this example, you must choose either
0, 1, or 2. An example of a valid
statement is:
LIVE_EXPORT, QUALITY=1
* Braces are used to enclose the allowable
range for a keyword value. Unless
otherwise noted, ranges provided are
inclusive. Consider the following syntax:
Result = CVTTOBM( Array [, THRESHOLD=value{0 to 255}] )
An example of a valid statement is:
Result = CVTTOBM( A, THRESHOLD=150 )
* Braces are also used to provide
useful information about a keyword. For
example:
[, LABEL=n{label every nth gridline}]
Do not include the braces or
their content in your statement.
* Certain keywords are prefaced by
X, Y, or Z. Braces are used for these
keywords to indicate that you must
choose one of the values it contains. For
example, [{X | Y}RANGE=array]
indicates that you can specify either
XRANGE=array or YRANGE=array.
* Note that in IDL, braces are used
to define structures. When defining a
structure, you do want to include
the braces in your statement.
Italics
* Italicized words are arguments,
expressions, or statements for which you must
provide values. The value you provide
can be a numerical value, such as 10, an
expression, such as DIST(100), or a
named variable. For keywords that expect
a string value, the syntax is listed
as KEYWORD=string. The value you
provide can be a string, such as 'Hello'
(enclosed in single quotation marks), or
a variable that holds a string value.
* The italicized values that must be
provided for keywords are listed in the most
helpful terms possible. For example, [,
XSIZE=pixels] indicates that the XSIZE
keyword expects a value in pixels, while
[, ORIENTATION=ccw_degrees_from_horiz]
indicates that you must provide
a value in degrees, measured
counter-clockwise from horizontal.
Procedures
IDL procedures use the following general syntax:
PROCEDURE_NAME, Argument [, Optional_Argument]
where PROCEDURE_NAME is the name of
the procedure, Argument is a required
parameter, and Optional_Argument is an
optional parameter to the procedure.
Functions
IDL functions use the following general syntax:
Result = FUNCTION_NAME( Argument [, Optional_Argument] )
where Result is the returned value of
the function, FUNCTION_NAME is the name
of the function, Argument is a required
parameter, and Optional_Argument is an
optional parameter. Note that all arguments
and keyword arguments to functions
should be supplied within the parentheses
that follow the function's name.
Functions do not always have to be
used in assignment statements (i.e.,
A=SIN(10.2)), they can be used just like
any other IDL expression. For example,
you could print the result of
SIN(10.2) by entering the command:
PRINT, SIN(10.2)
Arguments
The "Arguments" section describes each
valid argument to the routine. Note that
these arguments are positional parameters
that must be supplied in the order indicated
by the routine's syntax.
Named Variables
Often, arguments that contain values upon
return from the function or procedure
("output arguments") are described as
accepting "named variables". A named
variable is simply a valid IDL variable
name. This variable does not need to be
defined before being used as an output
argument. Note, however that when an
argument calls for a named variable, only
a named variable can be used-sending an
expression causes an error.
Keywords
The "Keywords" section describes each
valid keyword argument to the routine. Note
that keyword arguments are formal parameters
that can be supplied in any order.
Keyword arguments are supplied to IDL
routines by including the keyword name
followed by an equal sign ("=") and the
value to which the keyword should be set.
The value can be a value, an expression,
or a named variable (a named variable is
simply a valid IDL variable name).
Note
If you set a keyword equal to an undefined
named variable, IDL will quietly ignore
the value.
For example, to produce a plot with
diamond-shaped plotting symbols, the PSYM
keyword should be set to 4 as follows:
PLOT, FINDGEN(10), PSYM=4
Note the following when specifying keywords:
* Certain keywords are boolean, meaning
they can be set to either 0 or 1. These
keywords are switches used to turn an
option on and off. Usually, setting such
keywords equal to 1 causes the option
to be turned on. Explicitly setting the
keyword to 0 (or not including the keyword)
turns the option off. In the syntax
listings in this reference, all keywords
that are preceded by a slash can be set
by prefacing them by the slash. For
example, SURFACE, DIST(10), /SKIRT is
a shortcut for SURFACE, DIST(10),
SKIRT=1. To turn the option back off,
you must set the keyword equal to
0, as in SURFACE, DIST(10), SKIRT=0.
In rare cases, a keyword's default value
is 1. In these cases, the syntax is listed
as KEYWORD=0, as in SLIDE_IMAGE
[, Image] [, CONGRID=0]. In this
example, CONGRID is set to 1 by
default. If you specify CONGRID=0, you
can turn it back on by specifying
either /CONGRID or CONGRID=1.
* Some keywords are used to obtain values
that can be used upon return from the
function or procedure. These keywords
are listed as KEYWORD=variable.
Any valid variable name can be used for
these keywords, and the variable does
not need to be defined first. Note,
however, that when a keyword calls for a
named variable, only a named variable
can be used-sending an expression
causes an error.
For example, the WIDGET_CONTROL
procedure can return the user values
of widgets in a named variable using
the GET_UVALUE keyword. To return
the user value for a widget ID (contained
in the variable mywidget) in the
variable userval, you would use the command:
WIDGET_CONTROL, mywidget, GET_UVALUE = userval
Upon return from the procedure, userval
contains the user value. Note that
userval did not have to be defined
before the call to WIDGET_CONTROL.
* Some routines have keywords that are
mutually exclusive, meaning only one
of the keywords can be present in a
given statement. These keywords are
grouped together, and separated by a
vertical line. For example, consider the
following syntax:
PLOT, [X,] Y [, /DATA | , /DEVICE | , /NORMAL]
In this example, you can choose either
DATA, DEVICE, or NORMAL, but not
more than one. An example of a valid statement is:
PLOT, SIN(A), /DEVICE
* Keywords can be abbreviated to their
shortest unique length. For example, the
XSTYLE keyword can be abbreviated
to XST because there are no other
keywords in IDL that begin with XST.
You cannot shorten XSTYLE to XS,
however, because there are other
keywords that begin with XS, such as
XSIZE.
NAME:
.COMPILE
The .COMPILE command compiles and saves
procedures and programs in the same
manner as .RUN. If one or more filenames
are specified, the procedures and
functions contained therein are compiled
but not executed. If you enter this command
at the Command Input Line of the IDLDE
and the files are not yet open, IDL opens
the files within Editor windows and compiles
the procedures and functions contained
therein.
See RESOLVE_ROUTINE for a way to invoke
the same operation from within an
IDL routine, and RESOLVE_ALL for a way
to automatically compile all user-written
or library functions called by
all currently-compiled routines.
If the -f flag is specified, File is compiled
from the source stored temporarily in
TempFile rather than on disk in File itself.
This allows you to make changes to File
(in an IDLDE editor window, for example),
store the modified source into the
temporary file (IDLDE does it automatically),
compile, and test the changes without
overwriting the original code stored in File.
Note
.COMPILE is an executive command.
Executive commands can only be used at the
IDL command prompt, not in programs.
Syntax
.COMPILE [File1, ..., Filen]
.COMPILE -f File TempFile
NAME:
.CONTINUE
The .CONTINUE command continues
execution of a program that has stopped
because of an error, a stop statement, or a
keyboard interrupt. IDL saves the location
of the beginning of the last statement
executed before an error. If it is possible to
correct the error condition in the interactive
mode, the offending statement can be re-
executed by entering .CONTINUE. After
STOP statements, .CONTINUE continues
execution at the next statement. The
.CONTINUE command can be abbreviated; for
example, .C. Execution of a program
interrupted by typing Ctrl+C also can be
resumed at the point of interruption
with the .CONTINUE command.
Note
.CONTINUE is an executive command.
Executive commands can only be used at
the IDL command prompt, not in programs.
Syntax
.CONTINUE
NAME:
.EDIT
The .EDIT command opens files in IDL
Editor windows when called from the
Command Input Line of the IDLDE. This
functionality is only available on the
Windows and Motif platforms. Note that
filenames are separated by spaces, not
commas.
Note
.EDIT is an executive command. Executive
commands can only be used at the IDL
command prompt, not in programs.
Syntax
.EDIT File1 [File2 ... Filen]
NAME:
.FULL_RESET_SESSION
The .FULL_RESET_SESSION command
does everything .RESET_SESSION does,
plus the following:
* Removes all system routines
installed via LINKIMAGE or a DLM.
* Removes all structure definitions installed via a DLM.
* Removes all message blocks added by DLMs.
* Unloads all sharable libraries
loaded into IDL via CALL_EXTERNAL,
LINKIMAGE, or a DLM.
* Re-initializes all DLMs to their unloaded initial state.
Note
The VMS operating system does not
support unloading sharable libraries.
Therefore, .FULL_RESET_SESSION is
identical to .RESET_SESSION under
VMS, and these extra steps are not performed.
Note
.FULL_RESET_SESSION is an executive
command. Executive commands can
only be used at the IDL command prompt, not in programs.
Syntax
.FULL_RESET_SESSION
NAME:
.GO
The .GO command starts execution at the
beginning of a previously-compiled main
program.
Note
.GO is an executive command. Executive
commands can only be used at the IDL
command prompt, not in programs.
Syntax
.GO
NAME:
.OUT
The .OUT command continues executing
statements in the current program until it
returns.
Note
.OUT is an executive command. Executive
commands can only be used at the IDL
command prompt, not in programs.
Syntax
.OUT
NAME:
.RESET_SESSION
The .RESET_SESSION command resets much
of the state of an IDL session without
requiring the user to exit and restart the IDL session.
.RESET_SESSION does the following:
* Returns current execution point to $MAIN$ (RETALL).
* Removes all breakpoints.
* Closes all files except the standard 3
units, the JOURNAL file (if any), and any
files in use by graphics drivers.
* Destroys/Removes the following:
* All local variables in $MAIN$.
* All widgets. Exit handlers are not called.
* All windows and pixmaps for the
current window system graphics device
are closed. No other graphics state is reset.
* All common blocks.
* All handles
* All user defined system variables
* All pointer and object reference heap variables.
* Object destructors are not called.
* All user defined structure definitions.
* All user defined object definitions.
* All compiled user functions and
procedures, including the main program
($MAIN$), if any.
The following are not reset:
* The current values of intrinsic
system variables are retained.
* The saved commands and output log are preserved.
* Graphics drivers are not reset to their
full uninitialized state. However, all
windows and pixmaps for the current
window system device are closed.
* The following files are not closed:
* Stdin (LUN 0)
* Stdout (LUN -1)
* Stderr (LUN -2)
* The journal file (!JOURNAL) if one is open.
* Any files in use by graphics
drivers (e.g. PostScript).
* Dynamically loaded graphics drivers
(LINKIMAGE) are not removed, nor are
any dynamic sharable libraries
containing such drivers, even if the same
library was also used for another
purpose such as CALL_EXTERNAL,
LINKIMAGE system routines, or
DLMs. See the .FULL_RESET_SESSION
executive command to unload dynamic libraries.
Note
.RESET_SESSION is an executive
command. Executive commands can only be
used at the IDL command prompt, not in programs.
Syntax
.RESET_SESSION
NAME:
.RETURN
The .RETURN command continues execution
of a program until encountering a
RETURN statement. This is convenient for
debugging programs since it allows the
whole program to run, stopping before
returning to the next-higher program level so
you can examine local variables.
Also see the RETURN command.
Note
.RETURN is an executive command.
Executive commands can only be used at the
IDL command prompt, not in programs.
Syntax
.RETURN
NAME:
.RNEW
The .RNEW command compiles and saves
procedures and functions in the same
manner as .RUN. In addition, all variables
in the main program unit, except those in
common blocks, are erased. The -T and -L
filename switches have the same effect as
with .RUN.
Note
.RNEW is an executive command. Executive
commands can only be used at the
IDL command prompt, not in programs.
Syntax
.RNEW [File1, ..., Filen]
To save listing in a file: .RNEW -L
ListFile.lis File1 [, File2, ..., Filen]
To display listing on screen: .RNEW
-T File1 [, File2, ..., Filen]
Example
Some statements using the .RUN and
.RNEW commands are shown below.
Statement Description
.RUN Accept a program from the
keyboard. Retain the present
variables.
.RUN myfile Compile the file myfile.pro. If
it is not found in the current
directory, try
to find it in the
directory search path.
.RUN -T A, B, C Compile the files a.pro, b.pro
and c.pro. List
the files on the
terminal.
Table 2: Examples using .RUN and .RNEW
Statement Description
.RNEW -L myfile.lis myfile, yourfile
Erase all variables and compile
the files myfile.pro and
yourfile.pro. Produce a listing
on myfile.lis.
Table 2: Examples using .RUN and .RNEW
NAME:
.RUN
The .RUN command compiles procedures,
functions, and/or main programs in
memory. Main programs are executed
immediately. The command can be followed
by a list of files to be compiled. Filenames
are separated by blanks, tabs, or commas.
If a file specification is included in the
command, IDL searches for the file first in the
current directory, then in the directories
specified by the system variable !PATH. See
"Executing Program Files" in Chapter 2 of
Using IDL for more information on IDL's
search strategy.
If a main program unit is encountered,
execution of the program will begin after all
files have been read if there were no errors.
The values of all of the variables are
retained. If the file isn't found, input is
accepted from the keyboard until a complete
program unit is entered.
Files containing IDL procedures, programs,
and functions are assumed to have the
file extension (suffix) .pro. Files created
with the SAVE procedure are assumed to
have the extension .sav. See "Preparing
and Running Programs" in Chapter 2 of
Using IDL for further information.
Note
.RUN is an executive command. Executive
commands can only be used at the IDL
command prompt, not in programs.
Syntax
.RUN [File1, ..., Filen]
To save listing in a file: .RUN -L
ListFile.lis File1 [, File2, ..., Filen]
To display listing on screen: .RUN
-T File1 [, File2, ..., Filen]
Note
Subsequent calls to .RUN compile the procedure again.
Using .RUN to Make Program Listings
The command arguments -T for terminal
listing or -L filename for listing to a named
file can appear after the command name and
before the program filenames to produce
a numbered program listing directed
to the terminal or to a file.
For instance, to see a listing on the
screen as a result of compiling a procedure
contained in a file named analyze.pro,
use the following command:
.RUN -T analyze
To compile the same procedure and save
the listing in a file named analyze.lis,
use the following command:
.RUN -L analyze.lis analyze
In listings produced by IDL, the line number
of each statement is printed at the left
margin. This number is the same as that
printed in IDL error statements, simplifying
location of the statement causing the error.
Note
If the compiled file contains more than one
procedure or function, line numbering is
reset to "1" each time the end
of a program segment is detected.
Each level of block nesting is indented four
spaces to the right of the preceding block
level to improve the legibility of the program's structure.
NAME:
.SKIP
The .SKIP command skips one or more
statements and then executes a single step. It
is useful for continuing over a program
statement that caused an error. If the optional
argument n is present, it gives the number
of statements to skip; otherwise, a single
statement is skipped. Note that .SKIP
does not skip into a called routine.
For example, consider the following program segment:
...... ... ...
OPENR, 1, 'missing'
READF, 1, xxx, ..., ...
... ... ...
If the OPENR statement fails because the
specified file does not exist, program
execution will halt with the OPENR statement
as the current statement. Execution
can not be resumed with the executive
command .CONTINUE because it attempts to
re-execute the offending OPENR statement,
causing the same error. The remainder of
the program can be executed by entering
.SKIP, which skips over the incorrect OPEN
statement.
Note
.SKIP is an executive command. Executive
commands can only be used at the IDL
command prompt, not in programs.
Syntax
.SKIP [n]
NAME:
.STEP
The .STEP command executes one or more
statements in the current program starting
at the current position, stops, and returns
control to the interactive mode. This
command is useful in debugging programs.
The optional argument n indicates the
number of statements to execute. If n is
omitted, a single statement is executed.
Note
.STEP is an executive command. Executive
commands can only be used at the IDL
command prompt, not in programs.
Syntax
.STEP [n] or .S [n]
NAME:
.STEPOVER
The .STEPOVER command executes one or
more statements in the current program
starting at the current position, stops,
and returns control to the interactive mode.
Unlike .STEP, if .STEPOVER executes a
statement that calls another routine, the
called routine runs until it ends before
control returns to interactive mode. That is, a
statement calling another routine
is treated as a single statement.
The optional argument n indicates the
number of statements to execute. If n is
omitted, a single statement (or
called routine) is executed.
Note
.STEPOVER is an executive command.
Executive commands can only be used at
the IDL command prompt, not in programs.
Syntax
.STEPOVER [n] or .SO [n]
NAME:
.TRACE
The .TRACE command continues execution
of a program that has stopped because of
an error, a stop statement, or a keyboard interrupt.
Note
.TRACE is an executive command. Executive
commands can only be used at the
IDL command prompt, not in programs.
Syntax
.TRACE
NAME:
A_CORRELATE
The A_CORRELATE function computes the
autocorrelation Px(L) or autocovariance
Rx(L) of a sample population X as a function of the lag L.
N L 1
(x
k x)(xk+L x)
P k = 0
x(L) = Px(L) =
------------------------
N 1
(x
k x)2
k = 0
N L 1
Rx(L) = Rx(L) 1
= ----
N (x
k x)(xk+L x)
k = 0
where x is the mean of the sample
population x = (x0, x1, x2, ... , xN-1).
Note
This routine is primarily designed for use
in 1-D time-series analysis. The mean is
subtracted before correlating. For image
processing, methods based on FFT should
be used instead if more than a few
tens of points exist. For example:
Function AutoCorrelate, X
Temp = FFT(X,-1)
RETURN, FFT(Temp * CONJ(Temp), 1)
END
This routine is written in the IDL language.
Its source code can be found in the file
a_correlate.pro in the lib
subdirectory of the IDL distribution.
Syntax
Result = A_CORRELATE(X, Lag [, /COVARIANCE] [, /DOUBLE] )
Arguments
X
An n-element integer, single-, or
double-precision floating-point vector.
Lag
An n-element integer vector in the interval
[-(n-2), (n-2)], specifying the signed
distances between indexed elements of X.
Keywords
COVARIANCE
Set this keyword to compute the sample
autocovariance rather than the sample
autocorrelation.
DOUBLE
Set this keyword to force the computation
to be done in double-precision arithmetic.
Example
; Define an n-element sample population:
X = [3.73, 3.67, 3.77, 3.83, 4.67,
5.87, 6.70, 6.97, 6.40, 5.57]
; Compute the autocorrelation of
X for LAG = -3, 0, 1, 3, 4, 8:
lag = [-3, 0, 1, 3, 4, 8]
result = A_CORRELATE(X, lag)
PRINT, result
IDL prints:
0.0146185 1.00000 0.810879 0.0146185 -0.325279 -0.151684
See Also
CORRELATE, C_CORRELATE, M_CORRELATE, P_CORRELATE,
R_CORRELATE
NAME:
ABS
The ABS function returns the
absolute value of its argument.
Syntax
Result = ABS(X)
Arguments
X
The value for which the absolute value
is desired. If X is of complex type, ABS
returns the magnitude of the complex number:
Real2 Imaginary2
+
If X is of complex type, the result is returned
as the corresponding floating point type.
For all other types, the result has the same
type as X. If X is an array, the result has the
same structure, with each element containing
the absolute value of the corresponding
element of X.
ABS applied to any of the unsigned integer
types results in the unaltered value of X
being returned.
Example
To print the absolute value of -25, enter:
PRINT, ABS(-25)
IDL prints:
25
NAME:
ACOS
The ACOS function returns the angle,
expressed in radians, whose cosine is X (i.e.,
the arc-cosine). The range of ACOS is between 0 and .
<NEW>ACOS now supports complex input.</NEW>
Syntax
Result = ACOS(X)
Arguments
X
The cosine of the desired angle in the
range (-1 X 1). If X is double-precision
floating, the result of ACOS is also
double-precision. X cannot be complex. All other
types are converted to single-precision
floating-point and yield floating-point results.
If X is an array, the result has the same
structure, with each element containing the
arc-cosine of the corresponding element of X.
Example
To find the arc-cosine of 0.707 and store
the result in the variable B, enter:
B = ACOS(0.707)
See Also
COS
NAME:
ADAPT_HIST_EQUAL
The ADAPT_HIST_EQUAL function performs
adaptive histogram equalization, a
form of automatic image contrast enhancement.
The algorithm is described in Pizer
et. al., "Adaptive Histogram Equalization
and its Variations.", Computer Vision,
Graphics and Image Processing, 39:355-368.
Adaptive histogram equalization
involves applying contrast enhancement
based on the local region surrounding each
pixel. Each pixel is mapped to an intensity
proportional to its rank within the
surrounding neighborhood. This method
of automatic contrast enhancement has
proven to be broadly applicable to a wide
range of images and to have demonstrated
effectiveness.
Syntax
Result = ADAPT_HIST_EQUAL (Image [, FCN]
[, CLIP=value] [, NREGIONS=nregions]
[, TOP=value] )
Return Value
The result of the function is a byte image
with the same dimensions as the input
image parameter.
Arguments
Image
A two-dimensional array representing
the image for which adaptive histogram
equalization is to be performed. This parameter
is interpreted as unsigned 8-bit data,
so be sure that the input values are
properly scaled into the range of 0 to 255.
Keywords
FCN
<NEW>Set this keyword to the desired cumulative
probability distribution function in the form of a
256 element vector. If omitted, a linear ramp,
which yields equal probability bins results.
This function is later normalized, so magnitude
is inconsequential, though it should increase
monotonically.</NEW>
CLIP
Set this keyword to a nonzero value to clip
the histogram by limiting its slope to the
given CLIP value, thereby limiting contrast.
For example, if CLIP is set to 3, the
slope of the histogram is limited to 3. By
default, the slope and/or contrast is not
limited. Noise over-enhancement in
nearly homogeneous regions is reduced by
setting this parameter to values larger than 1.0.
NREGIONS
Set this keyword to the size of the
overlapped tiles, as a fraction of the largest
dimensions of the image size. The default
is 12, which makes each tile 1/12 the size
of the largest image dimension.
TOP
Set this keyword to the maximum value of
the scaled output array. The default is 255.
Example
The following code snippet reads a data
file in the examples/data subdirectory of
the IDL distribution containing a cerebral
angiogram, and then displays both the
original image and the adaptive histogram equalized image:
OPENR, 1, FILEPATH('cereb.dat', $
SUBDIRECTORY=['examples','data'])
;Image size = 512 x 512
a = BYTARR(512,512, /NOZERO)
;Read it
READU, 1, a
CLOSE, 1
; Reduce size of image for comparison
a = CONGRID(a, 256,256)
;Show original
TVSCL, a, 0
;Show processed
TV, ADAPT_HIST_EQUAL(a, TOP=!D.TABLE_SIZE-1), 1
See Also
H_EQ_CT, H_EQ_INT, HIST_2D, HIST_EQUAL, HISTOGRAM
NAME:
ALOG
The ALOG function returns the natural
logarithm of X. The result has the same
structure as X.
Syntax
Result = ALOG(X)
Arguments
X
The value for which the natural log is
desired. The result of ALOG is double-
precision floating if X is double-precision,
and complex if X is complex. All other
types are converted to single-precision
floating-point and yield floating-point results.
When applied to complex numbers, the
definition of the ALOG function is:
ALOG(x) = COMPLEX(log |x|, atan x)
Example
To print the natural logarithm of 5, enter:
PRINT, ALOG(5)
IDL prints:
1.60944
See Also
ALOG10
NAME:
ALOG10
The ALOG10 function returns the logarithm
to the base 10 of X. This function
operates in the same manner as the ALOG function.
Syntax
Result = ALOG10(X)
Arguments
X
The value for which the base 10 log is desired.
Example
To find the base 10 logarithm of 5 and
store the result in the variable L, enter:
L = ALOG10(5)
See Also
ALOG
NAME:
AMOEBA
The AMOEBA function performs
multidimensional minimization of a function
Func(x), where x is an n-dimensional
vector, using the downhill simplex method of
Nelder and Mead, 1965, Computer Journal, Vol 7, pp 308-313.
The downhill simplex method is not as
efficient as Powell's method, and usually
requires more function evaluations.
However, the simplex method requires only
function evaluations-not derivatives-and
may be more reliable than Powell's
method.
If the minimum is found, AMOEBA returns
an n-element vector corresponding to the
function's minimum value. If a minimum
within the given tolerance is not found
within the specified number of iterations,
AMOEBA returns a scalar value of -1.
Results are returned with the same precision
(single- or double-precision floating-
point) as is returned by the
user-supplied function to be minimized.
This routine is written in the IDL language.
Its source code can be found in the file
amoeba.pro in the lib subdirectory of
the IDL distribution. AMOEBA is based on
the routine amoeba described in section
10.4 of Numerical Recipes in C: The Art of
Scientific Computing (Second Edition),
published by Cambridge University Press,
and is used by permission.
Syntax
Result = AMOEBA( Ftol [, FUNCTION_NAME=string]
[, FUNCTION_VALUE=variable] [, NCALLS=value] [, NMAX=value]
[, P0=vector, SCALE=vector | , SIMPLEX=array] )
Arguments
Ftol
The fractional tolerance to be achieved in
the function value-that is, the fractional
decrease in the function value in the
terminating step. If the function you supply
returns a single-precision result, Ftol
should never be less than your machine's
floating-point precision-the value
contained in the EPS field of the structure
returned by the MACHAR function. If the
function you supply returns a double-
precision floating-point value, Ftol should
not be less than your machine' double-
precision floating-point precision. See MACHAR for details.
Keywords
FUNCTION_NAME
Set this keyword equal to a string
containing the name of the function to be
minimized. If this keyword is omitted,
AMOEBA assumes that an IDL function
named "FUNC" is to be used.
The function to be minimized must be written
as an IDL function and compiled prior
to calling AMOEBA. This function must
accept an n-element vector as its only
parameter and return a scalar single- or
double precision floating-point value as its
result.
See the Example section below for an example function.
FUNCTION_VALUE
Set this keyword equal to a named variable
that will contain an (n+1)-element vector
of the function values at the simplex points.
The first element contains the function
minimum.
NCALLS
Set this keyword equal to a named variable
that will contain a count of the number of
times the function was evaluated.
NMAX
Set this keyword equal to a scalar value
specifying the maximum number of function
evaluations allowed before terminating. The default is 5000.
P0
Set this keyword equal to an n-element
single- or double-precision floating-point
vector specifying the initial starting point.
Note that if you specify P0, you must also
specify SCALE.
For example, in a 3-dimensional problem, if
the initial guess is the point [0,0,0], and
you know that the function's minimum
value occurs in the interval:
-10 < X[0] < 10, -100 < X[1] < 100, -200 < X[(2] < 200,
specify: P0=[0,0,0] and SCALE=[10, 100, 200].
Alternately, you can omit P0 and SCALE and specify SIMPLEX.
SCALE
Set this keyword equal to a scalar or
n-element vector containing the problem's
characteristic length scale for each
dimension. SCALE is used with P0 to form an
initial (n+1) point simplex. If all dimensions
have the same scale, set SCALE equal to
a scalar.
If SCALE is specified as a scalar, the
function's minimum lies within a distance of
SCALE from P0. If SCALE is an N-dimensional
vector, the function's minimum lies
within the Ndim+1 simplex with the
vertices P0, P0 + [1,0,...,0] * SCALE, P0 +
[0,1,0,...,0] * SCALE, ..., and P0+[0,0,...,1] * SCALE.
SIMPLEX
Set this keyword equal to an n by n+1 single-
or double-precision floating-point array
containing the starting simplex. After
AMOEBA has returned, the SIMPLEX array
contains the simplex enclosing the function
minimum. The first point in the array,
SIMPLEX[*,0], corresponds to the function's
minimum. This keyword is ignored if
the P0 and SCALE keywords are set.
Example
Use AMOEBA to find the slope and intercept
of a straight line that fits a given set of
points, minimizing the maximum error. The
function to be minimized (FUNC, in this
case) returns the maximum error, given
p[0] = intercept, and p[1] = slope.
; First define the function FUNC:
FUNCTION FUNC, P
COMMON FUNC_XY, X, Y
RETURN, MAX(ABS(Y - (P[0] + P[1] * X)))
END
; Put the data points into a common
block so they are accessible to
; the function:
COMMON FUNC_XY, X, Y
; Define the data points:
X = FINDGEN(17)*5
Y = [ 12.0, 24.3, 39.6, 51.0,
66.5, 78.4, 92.7, 107.8, $
120.0, 135.5, 147.5, 161.0,
175.4, 187.4, 202.5, 215.4, 229.9]
; Call the function. Set the
fractional tolerance to 1 part in
; 10^5, the initial guess to
[0,0], and specify that the minimum
; should be found within a distance of 100 of that point:
R = AMOEBA(1.0e-5, SCALE=1.0e2,
P0 = [0, 0], FUNCTION_VALUE=fval)
; Check for convergence:
IF N_ELEMENTS(R) EQ 1 THEN MESSAGE,
'AMOEBA failed to converge'
; Print results:
PRINT, 'Intercept, Slope:', r, $
'Function value (max error): ', fval[0]
IDL prints:
Intercept, Slope: 11.4100 2.72800
Function value: 1.33000
See Also
POWELL
NAME:
ANNOTATE
The ANNOTATE procedure starts an IDL
widget program that allows you to
interactively annotate images and plots
with text and drawings. Drawing objects
include lines, arrows, polygons, rectangles,
circles, and ellipses. Annotation files can
be saved and restored, and annotated
displays can be written to TIFF or PostScript
files. The