Ref Book

Reference
Guide
Volume 1
Routines A - L
IDL Version 4.0
October, 1995 Edition
Copyright Research Systems, Inc.
All Rights Reserved
IDL Version 5.2
November, 1998 Edition
All Rights Reserved
Restricted Rights Notice
The IDL
software program and the accompanying procedures, functions, and

documentation described herein are sold under license agreement. Their use,
duplication, and disclosure are subject to the restrictions stated in the license
agreement.
Limitation of Warranty
Research Systems, Inc. makes no warranties, either express or implied, as to any
matter not expressly set forth in the license agreement, including without
limitation the condition of the software, merchantability, or tness for any
particular purpose.
Research Systems, Inc. shall not be liable for any direct, consequential, or other
damages suffered by the Licensee or any others resulting from use of the IDL
software package or its documentation.
Most Current Documentation
Because changes may be made to IDL after documentation has gone to press,
pleaseconsult IDLshypertext onlinehelp systemfor themost current version of
this document.
Permission to Reproduce this Manual
Purchasersof IDLlicensesaregiven limitedpermission toreproducethismanual
providedsuchcopiesarefor their useonlyandarenot soldor distributedtothird
parties. All such copies must contain the title page and this notice page in their
entirety.
Acknowledgments
IDL
is a trademark of Research Systems Inc., registered in the United States

Patent and Trademark Ofce, for the computer program described herein. All
other brand or product names are trademarks of their respective holders.
Numerical Recipes is a trademark of Numerical Recipes Software. Numerical
Recipes routines are used by permission.
GRG2 is a trademark of Windward Technologies, Inc. The GRG2 software for
nonlinear optimization is used by permission.
Portions of this software are copyrighted by INTERSOLV, Inc., 1991-1998.
IDL documentation is printed on recycled paper. Our paper has a minimum
20% post-consumer waste content and meets all EPA guidelines.
Reference
Guide
Volume 2
Routines M - Z
IDL Version 5.2
November, 1998 Edition
All Rights Reserved
Restricted Rights Notice
The IDL
software program and the accompanying procedures, functions, and

documentation described herein are sold under license agreement. Their use,
duplication, and disclosure are subject to the restrictions stated in the license
agreement.
Limitation of Warranty
Research Systems, Inc. makes no warranties, either express or implied, as to any
matter not expressly set forth in the license agreement, including without
limitation the condition of the software, merchantability, or tness for any
particular purpose.
Research Systems, Inc. shall not be liable for any direct, consequential, or other
damages suffered by the Licensee or any others resulting from use of the IDL
software package or its documentation.
Most Current Documentation
Because changes may be made to IDL after documentation has gone to press,
pleaseconsult IDLshypertext onlinehelp systemfor themost current version of
this document.
Permission to Reproduce this Manual
Purchasersof IDLlicensesaregiven limitedpermission toreproducethismanual
providedsuchcopiesarefor their useonlyandarenot soldor distributedtothird
parties. All such copies must contain the title page and this notice page in their
entirety.
Acknowledgments
IDL
is a trademark of Research Systems Inc., registered in the United States

Patent and Trademark Ofce, for the computer program described herein. All
other brand or product names are trademarks of their respective holders.
Numerical Recipes is a trademark of Numerical Recipes Software. Numerical
Recipes routines are used by permission.
GRG2 is a trademark of Windward Technologies, Inc. The GRG2 software for
nonlinear optimization is used by permission.
Portions of this software are copyrighted by INTERSOLV, Inc., 1991-1998.
IDL documentation is printed on recycled paper. Our paper has a minimum
20% post-consumer waste content and meets all EPA guidelines.
v
Contents
Chapter 1:
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
About IDL .................................................................................................................. 23
IDL Documentation .................................................................................................. 24
Typographical Conventions ...................................................................................... 26
Reporting Problems ................................................................................................... 26
Chapter 2:
Executive Commands . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 3:
System Variables . . . . . . . . . . . . . . . . . . . . . . . . . 37
Constant System Variables ........................................................................................ 37
vi Contents
Contents IDL Reference Guide
Error Handling and Informational System Variables............................................... 38
IDL Environment System Variables .......................................................................... 42
Graphics System Variables ......................................................................................... 46
Chapter 4:
Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . 57
Chapter 5:
Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Chapter 6:
Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Fonts in IDL Direct vs. Object Graphics ................................................................... 66
About the Vector Fonts .............................................................................................. 66
About the TrueType Fonts ........................................................................................ 68
About Device Fonts ................................................................................................... 72
Choosing a Font Type ................................................................................................ 77
Embedded Formatting Commands ........................................................................... 79
Formatting Command Examples .............................................................................. 82
TrueTypeFont Samples ............................................................................................. 86
Vector Font Samples .................................................................................................. 89
Chapter 7:
Graphics Keywords . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 8:
IDL Graphics Devices . . . . . . . . . . . . . . . . . . . . . . 111
Keywords Accepted by the IDL Devices .................................................................. 112
Window Systems....................................................................................................... 143
Printing Graphics Output Files................................................................................ 146
The CGM Device ...................................................................................................... 148
The HP-GL Device ................................................................................................... 150
The LJ Device ............................................................................................................ 151
The Macintosh Display Device ................................................................................ 154
The Null Display Device........................................................................................... 154
The PCL Device ........................................................................................................ 154
The Printer Device.................................................................................................... 156
The PostScript Device .............................................................................................. 156
The Regis Terminal Device ...................................................................................... 168
Contents vii
IDL Reference Guide Contents
The Tektronix Device .............................................................................................. 169
The Microsoft Windows Device.............................................................................. 170
The X Windows Device ........................................................................................... 171
The Z-Buffer Device ................................................................................................ 178
Chapter 9:
IDL Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
How to Use this Chapter ......................................................................................... 183
A_CORRELATE....................................................................................................... 187
ABS............................................................................................................................ 189
ACOS........................................................................................................................ 190
ALOG........................................................................................................................ 191
ALOG10 .................................................................................................................... 192
AMOEBA .................................................................................................................. 193
ANNOTATE............................................................................................................. 196
ARG_PRESENT ....................................................................................................... 198
ARROW .................................................................................................................... 200
ASCII_TEMPLATE.................................................................................................. 202
ASIN ......................................................................................................................... 203
ASSOC ...................................................................................................................... 204
ATAN ........................................................................................................................ 206
AXIS.......................................................................................................................... 207
BAR_PLOT ............................................................................................................... 210
BESELI ...................................................................................................................... 213
BESELJ ...................................................................................................................... 214
BESELY ..................................................................................................................... 215
BETA ......................................................................................................................... 216
BILINEAR................................................................................................................. 217
BIN_DATE ............................................................................................................... 219
BINDGEN ................................................................................................................ 220
BINOMIAL ............................................................................................................... 221
BLAS_AXPY ............................................................................................................. 223
BLK_CON ................................................................................................................ 225
BOX_CURSOR ........................................................................................................ 227
BREAKPOINT ......................................................................................................... 229
BROYDEN ................................................................................................................ 231
BYTARR ................................................................................................................... 233
BYTE ......................................................................................................................... 234
BYTEORDER ........................................................................................................... 235
BYTSCL .................................................................................................................... 238
C_CORRELATE....................................................................................................... 240
CALDAT ................................................................................................................... 242
viii Contents
CALENDAR .............................................................................................................. 244
CALL_EXTERNAL ................................................................................................... 245
CALL_FUNCTION .................................................................................................. 252
CALL_METHOD ..................................................................................................... 253
CALL_PROCEDURE ............................................................................................... 254
CATCH ..................................................................................................................... 255
CD ............................................................................................................................. 257
CEIL ........................................................................................................................... 259
CHEBYSHEV ............................................................................................................ 260
CHECK_MATH ....................................................................................................... 261
CHISQR_CVF .......................................................................................................... 265
CHISQR_PDF........................................................................................................... 266
CHOLDC .................................................................................................................. 267
CHOLSOL ................................................................................................................. 268
CINDGEN ................................................................................................................. 270
CIR_3PNT ................................................................................................................. 271
CLOSE ....................................................................................................................... 273
CLUST_WTS ............................................................................................................ 274
CLUSTER .................................................................................................................. 275
COLOR_CONVERT ................................................................................................ 277
COLOR_QUAN ........................................................................................................ 279
COMFIT .................................................................................................................... 282
COMPLEX ................................................................................................................ 285
COMPLEXARR ........................................................................................................ 287
COMPLEXROUND ................................................................................................. 288
COMPUTE_MESH_NORMALS............................................................................. 289
COND ....................................................................................................................... 290
CONGRID ................................................................................................................ 291
CONJ ......................................................................................................................... 293
CONSTRAINED_MIN ............................................................................................ 294
CONTOUR ............................................................................................................... 300
CONVERT_COORD ............................................................................................... 309
CONVOL .................................................................................................................. 311
COORD2TO3 ........................................................................................................... 314
CORRELATE ............................................................................................................ 315
COS ........................................................................................................................... 317
COSH ........................................................................................................................ 318
CRAMER................................................................................................................... 319
CREATE_STRUCT ................................................................................................... 321
CREATE_VIEW........................................................................................................ 323
CROSSP..................................................................................................................... 326
CRVLENGTH ........................................................................................................... 327
CT_LUMINANCE.................................................................................................... 329
Contents ix
CTI_TEST ................................................................................................................. 330
CURSOR................................................................................................................... 332
CURVEFIT ............................................................................................................... 335
CV_COORD ............................................................................................................ 338
CVTTOBM ............................................................................................................... 340
CW_ANIMATE ....................................................................................................... 341
CW_ANIMATE_GETP ........................................................................................... 345
CW_ANIMATE_LOAD .......................................................................................... 346
CW_ANIMATE_RUN ............................................................................................. 348
CW_ARCBALL ........................................................................................................ 350
CW_BGROUP ......................................................................................................... 354
CW_CLR_INDEX .................................................................................................... 358
CW_COLORSEL ...................................................................................................... 360
CW_DEFROI ........................................................................................................... 362
CW_DICE ................................................................................................................ 366
CW_FIELD ............................................................................................................... 368
CW_FORM .............................................................................................................. 371
CW_FSLIDER .......................................................................................................... 377
CW_ORIENT ........................................................................................................... 380
CW_PDMENU ........................................................................................................ 382
CW_RGBSLIDER .................................................................................................... 387
CW_TMPL ............................................................................................................... 389
CW_ZOOM ............................................................................................................. 390
DBLARR ................................................................................................................... 394
DCINDGEN ............................................................................................................. 395
DCOMPLEX ............................................................................................................ 396
DCOMPLEXARR..................................................................................................... 398
DEFINE_KEY ........................................................................................................... 399
DEFROI .................................................................................................................... 407
DEFSYSV .................................................................................................................. 409
DELETE_SYMBOL (VMS Only) ............................................................................ 411
DELLOG (VMS Only) ............................................................................................. 412
DELVAR ................................................................................................................... 413
DEMO_MODE ........................................................................................................ 414
DERIV ....................................................................................................................... 415
DERIVSIG ................................................................................................................ 416
DETERM .................................................................................................................. 417
DEVICE .................................................................................................................... 419
DFPMIN ................................................................................................................... 420
DIALOG_MESSAGE ............................................................................................... 423
DIALOG_PICKFILE ................................................................................................ 426
DIALOG_PRINTJOB .............................................................................................. 429
DIALOG_PRINTERSETUP .................................................................................... 430
x Contents
DIGITAL_FILTER.................................................................................................... 431
DILATE ..................................................................................................................... 432
DINDGEN ................................................................................................................ 435
DISSOLVE ................................................................................................................ 436
DIST .......................................................................................................................... 437
DO_APPLE_SCRIPT ................................................................................................ 438
DOC_LIBRARY ........................................................................................................ 440
DOUBLE ................................................................................................................... 442
EFONT ...................................................................................................................... 443
EIGENQL .................................................................................................................. 444
EIGENVEC ............................................................................................................... 446
ELMHES.................................................................................................................... 448
EMPTY ...................................................................................................................... 449
EOF ............................................................................................................................ 450
ERASE ....................................................................................................................... 451
ERODE ...................................................................................................................... 452
ERRORF .................................................................................................................... 455
ERRPLOT .................................................................................................................. 456
EXECUTE ................................................................................................................. 458
EXIT .......................................................................................................................... 459
EXP ............................................................................................................................ 460
EXPAND ................................................................................................................... 461
EXPAND_PATH ...................................................................................................... 462
EXPINT ..................................................................................................................... 465
EXTRAC .................................................................................................................... 467
EXTRACT_SLICE .................................................................................................... 469
F_CVF ....................................................................................................................... 471
F_PDF........................................................................................................................ 472
FACTORIAL ............................................................................................................. 473
FFT ............................................................................................................................ 474
FILEPATH ................................................................................................................ 478
FINDFILE.................................................................................................................. 480
FINDGEN ................................................................................................................. 482
FINITE ...................................................................................................................... 483
FIX ............................................................................................................................. 484
FLICK ........................................................................................................................ 485
FLOAT ....................................................................................................................... 486
FLOOR ...................................................................................................................... 487
FLOW3 ...................................................................................................................... 488
FLTARR..................................................................................................................... 490
FLUSH ....................................................................................................................... 491
FORMAT_AXIS_VALUES....................................................................................... 492
FREE_LUN ............................................................................................................... 493
Contents xi
FSTAT ....................................................................................................................... 494
FULSTR .................................................................................................................... 496
FUNCT ..................................................................................................................... 497
FV_TEST .................................................................................................................. 498
FX_ROOT ................................................................................................................ 500
FZ_ROOTS............................................................................................................... 502
GAMMA ................................................................................................................... 504
GAMMA_CT ............................................................................................................ 505
GAUSS_CVF ............................................................................................................ 506
GAUSS_PDF ............................................................................................................ 507
GAUSS2DFIT ........................................................................................................... 508
GAUSSFIT ................................................................................................................ 511
GAUSSINT ............................................................................................................... 513
GET_KBRD .............................................................................................................. 514
GET_LUN ................................................................................................................ 516
GET_SCREEN_SIZE ............................................................................................... 517
GET_SYMBOL (VMS Only) ................................................................................... 518
GETENV ................................................................................................................... 519
GRID3 ....................................................................................................................... 522
GS_ITER................................................................................................................... 525
H_EQ_CT ................................................................................................................. 527
H_EQ_INT ............................................................................................................... 528
HANNING ............................................................................................................... 529
HDF_BROWSER ..................................................................................................... 530
HDF_READ .............................................................................................................. 533
HEAP_GC............................................................................................................... 536
HELP......................................................................................................................... 537
HILBERT .................................................................................................................. 541
HIST_2D .................................................................................................................. 542
HIST_EQUAL .......................................................................................................... 544
HISTOGRAM .......................................................................................................... 546
HLS ........................................................................................................................... 550
HQR.......................................................................................................................... 551
HSV ........................................................................................................................... 553
IBETA ....................................................................................................................... 554
IDENTITY ................................................................................................................ 556
IGAMMA ................................................................................................................. 557
IMAGE_CONT ........................................................................................................ 559
IMAGINARY............................................................................................................ 560
INDGEN ................................................................................................................... 561
INT_2D .................................................................................................................... 563
INT_3D .................................................................................................................... 566
INT_TABULATED .................................................................................................. 568
xii Contents
INTARR .................................................................................................................... 570
INTERPOL ................................................................................................................ 571
INTERPOLATE ........................................................................................................ 573
INVERT ..................................................................................................................... 576
IOCTL ....................................................................................................................... 578
ISHFT ........................................................................................................................ 581
JOURNAL ................................................................................................................. 582
JULDAY .................................................................................................................... 583
KEYWORD_SET ...................................................................................................... 585
KRIG2D ..................................................................................................................... 586
KURTOSIS................................................................................................................ 590
KW_TEST ................................................................................................................. 591
L64INDGEN ............................................................................................................. 593
LABEL_DATE........................................................................................................... 594
LABEL_REGION ...................................................................................................... 596
LADFIT ..................................................................................................................... 598
LEEFILT .................................................................................................................... 600
LINBCG .................................................................................................................... 601
LINDGEN ................................................................................................................. 603
LINFIT ...................................................................................................................... 604
LINKIMAGE............................................................................................................. 606
LIVE_Tools ............................................................................................................... 611
LIVE_CONTOUR .................................................................................................... 612
LIVE_CONTROL ..................................................................................................... 619
LIVE_DESTROY ...................................................................................................... 621
LIVE_EXPORT ......................................................................................................... 623
LIVE_IMAGE ........................................................................................................... 625
LIVE_INFO ............................................................................................................... 630
LIVE_LINE ............................................................................................................... 640
LIVE_LOAD ............................................................................................................. 644
LIVE_OPLOT ........................................................................................................... 645
LIVE_PLOT .............................................................................................................. 649
LIVE_PRINT ............................................................................................................. 655
LIVE_RECT .............................................................................................................. 656
LIVE_STYLE ............................................................................................................. 659
LIVE_SURFACE ....................................................................................................... 665
LIVE_TEXT .............................................................................................................. 671
LJLCT ........................................................................................................................ 674
LL_ARC_DISTANCE ............................................................................................... 675
LMFIT ....................................................................................................................... 677
LMGR........................................................................................................................ 680
LNGAMMA .............................................................................................................. 682
LNP_TEST ................................................................................................................ 683
Contents xiii
LOADCT .................................................................................................................. 685
LON64ARR .............................................................................................................. 686
LONARR .................................................................................................................. 687
LONG ....................................................................................................................... 688
LONG64 ................................................................................................................... 689
LSODE ...................................................................................................................... 690
LU_COMPLEX ........................................................................................................ 694
LUDC........................................................................................................................ 696
LUMPROVE............................................................................................................. 697
LUSOL ...................................................................................................................... 699
M_CORRELATE...................................................................................................... 701
MACHAR ................................................................................................................. 703
MAKE_ARRAY ........................................................................................................ 705
MAP_CONTINENTS.............................................................................................. 708
MAP_GRID .............................................................................................................. 711
MAP_IMAGE........................................................................................................... 715
MAP_PATCH .......................................................................................................... 718
MAP_PROJ_INFO................................................................................................... 721
MAP_SET ................................................................................................................. 723
MAX .......................................................................................................................... 731
MD_TEST ................................................................................................................ 733
MEAN ....................................................................................................................... 735
MEANABSDEV ........................................................................................................ 736
MEDIAN .................................................................................................................. 738
MESH_OBJ .............................................................................................................. 740
MESSAGE................................................................................................................. 745
MIN .......................................................................................................................... 747
MIN_CURVE_SURF ............................................................................................... 748
MK_HTML_HELP .................................................................................................. 751
MODIFYCT ............................................................................................................. 754
MOMENT ................................................................................................................ 755
MPEG_CLOSE ......................................................................................................... 757
MPEG_OPEN .......................................................................................................... 758
MPEG_PUT ............................................................................................................. 760
MPEG_SAVE............................................................................................................ 762
MULTI ...................................................................................................................... 763
N_ELEMENTS......................................................................................................... 764
N_PARAMS ............................................................................................................. 765
N_TAGS ................................................................................................................... 766
NEWTON ................................................................................................................. 767
NORM ...................................................................................................................... 769
OBJ_CLASS............................................................................................................ 771
OBJ_DESTROY...................................................................................................... 772
xiv Contents
OBJ_ISA................................................................................................................. 773
OBJ_NEW.............................................................................................................. 774
OBJ_VALID........................................................................................................... 776
OBJARR................................................................................................................. 778
ON_ERROR.............................................................................................................. 779
ON_IOERROR ......................................................................................................... 780
ONLINE_HELP ........................................................................................................ 781
OPEN ........................................................................................................................ 783
OPLOT ...................................................................................................................... 792
OPLOTERR............................................................................................................... 794
P_CORRELATE........................................................................................................ 795
PCOMP ..................................................................................................................... 796
PLOT ......................................................................................................................... 800
PLOT_3DBOX .......................................................................................................... 803
PLOT_FIELD ............................................................................................................ 806
PLOTERR.................................................................................................................. 808
PLOTS....................................................................................................................... 809
PNT_LINE ................................................................................................................ 811
POINT_LUN ............................................................................................................ 813
POLAR_CONTOUR ................................................................................................ 815
POLAR_SURFACE................................................................................................... 817
POLY ......................................................................................................................... 819
POLY_2D .................................................................................................................. 820
POLY_AREA ............................................................................................................. 823
POLY_FIT ................................................................................................................. 824
POLYFILL ................................................................................................................. 826
POLYFILLV .............................................................................................................. 829
POLYFITW ............................................................................................................... 831
POLYSHADE ............................................................................................................ 832
POLYWARP.............................................................................................................. 835
POPD ........................................................................................................................ 837
POWELL ................................................................................................................... 838
PRIMES..................................................................................................................... 840
PRINT/PRINTF ........................................................................................................ 841
PRINTD .................................................................................................................... 843
PROFILE ................................................................................................................... 844
PROFILER................................................................................................................. 846
PROFILES ................................................................................................................. 848
PROJECT_VOL ........................................................................................................ 850
PS_SHOW_FONTS.................................................................................................. 853
PSAFM ...................................................................................................................... 854
PSEUDO ................................................................................................................... 855
PTR_FREE ............................................................................................................. 856
Contents xv
PTR_NEW.............................................................................................................. 857
PTR_VALID........................................................................................................... 858
PTRARR ................................................................................................................. 860
PUSHD ..................................................................................................................... 861
QROMB.................................................................................................................... 862
QROMO ................................................................................................................... 864
QSIMP ...................................................................................................................... 866
QUERY_* ROUTINES ............................................................................................ 868
QUERY_BMP........................................................................................................... 870
QUERY_DICOM ..................................................................................................... 871
QUERY_GIF............................................................................................................. 873
QUERY_JPEG .......................................................................................................... 874
QUERY_PICT .......................................................................................................... 875
QUERY_PNG........................................................................................................... 876
QUERY_PPM ........................................................................................................... 878
QUERY_SRF ............................................................................................................ 879
QUERY_TIFF ........................................................................................................... 880
R_CORRELATE ....................................................................................................... 882
R_TEST ..................................................................................................................... 884
RANDOMN ............................................................................................................. 886
RANDOMU ............................................................................................................. 890
RANKS...................................................................................................................... 892
RDPIX ....................................................................................................................... 894
READ/READF .......................................................................................................... 895
READ_ASCII ............................................................................................................ 898
READ_BMP ............................................................................................................. 901
READ_DICOM ........................................................................................................ 903
READ_GIF ............................................................................................................... 904
READ_INTERFILE .................................................................................................. 906
READ_JPEG ............................................................................................................. 907
READ_PICT ............................................................................................................. 910
READ_PNG.............................................................................................................. 911
READ_PPM .............................................................................................................. 913
READ_SPR ............................................................................................................... 915
READ_SRF ............................................................................................................... 916
READ_SYLK ............................................................................................................. 918
READ_TIFF .............................................................................................................. 921
READ_WAVE .......................................................................................................... 926
READ_X11_BITMAP .............................................................................................. 928
READ_XWD ............................................................................................................ 930
READS...................................................................................................................... 931
READU ..................................................................................................................... 933
REBIN ....................................................................................................................... 935
xvi Contents
RECALL_COMMANDS .......................................................................................... 938
RECON3 ................................................................................................................... 939
REDUCE_COLORS ................................................................................................. 944
REFORM ................................................................................................................... 945
REGRESS................................................................................................................... 947
REPLICATE .............................................................................................................. 949
REPLICATE_INPLACE ........................................................................................... 950
RESOLVE_ALL ......................................................................................................... 952
RESOLVE_ROUTINE.............................................................................................. 954
RESTORE .................................................................................................................. 955
RETALL ..................................................................................................................... 957
RETURN ................................................................................................................... 958
REVERSE .................................................................................................................. 960
REWIND ................................................................................................................... 962
RIEMANN ................................................................................................................ 963
RK4 ............................................................................................................................ 967
ROBERTS.................................................................................................................. 969
ROT ........................................................................................................................... 970
ROTATE.................................................................................................................... 972
ROUND .................................................................................................................... 974
ROUTINE_INFO ..................................................................................................... 975
RS_TEST ................................................................................................................... 977
RSTRPOS.................................................................................................................. 979
S_TEST ...................................................................................................................... 980
SAVE.......................................................................................................................... 982
SCALE3 ..................................................................................................................... 984
SCALE3D .................................................................................................................. 985
SEARCH2D ............................................................................................................... 986
SEARCH3D ............................................................................................................... 989
SET_PLOT ................................................................................................................ 992
SET_SHADING ........................................................................................................ 994
SET_SYMBOL .......................................................................................................... 996
SETENV (Unix and Windows Only) ...................................................................... 997
SETLOG (VMS Only) .............................................................................................. 998
SETUP_KEYS ......................................................................................................... 1000
SFIT ......................................................................................................................... 1002
SHADE_SURF ........................................................................................................ 1004
SHADE_SURF_IRR................................................................................................ 1008
SHADE_VOLUME................................................................................................. 1010
SHIFT ...................................................................................................................... 1013
SHOW3 ................................................................................................................... 1015
SHOWFONT .......................................................................................................... 1017
SIN ........................................................................................................................... 1019
Contents xvii
SINDGEN ............................................................................................................... 1020
SINH ....................................................................................................................... 1021
SIZE ........................................................................................................................ 1022
SKEWNESS ............................................................................................................ 1025
SKIPF ...................................................................................................................... 1026
SLICER3 ................................................................................................................. 1027
SLIDE_IMAGE....................................................................................................... 1040
SMOOTH ............................................................................................................... 1043
SOBEL ..................................................................................................................... 1045
SORT ...................................................................................................................... 1046
SPAWN ................................................................................................................... 1047
SPH_4PNT ............................................................................................................. 1051
SPH_SCAT ............................................................................................................. 1052
SPL_INIT ................................................................................................................ 1054
SPL_INTERP.......................................................................................................... 1056
SPLINE ................................................................................................................... 1058
SPLINE_P ............................................................................................................... 1059
SPRSAB................................................................................................................... 1061
SPRSAX .................................................................................................................. 1063
SPRSIN ................................................................................................................... 1064
SQRT ...................................................................................................................... 1066
STANDARDIZE..................................................................................................... 1067
STDDEV ................................................................................................................. 1069
STOP....................................................................................................................... 1070
STR_SEP ................................................................................................................. 1071
STRARR.................................................................................................................. 1073
STRCOMPRESS..................................................................................................... 1074
STRETCH ............................................................................................................... 1075
STRING .................................................................................................................. 1077
STRLEN .................................................................................................................. 1080
STRLOWCASE....................................................................................................... 1081
STRMESSAGE........................................................................................................ 1082
STRMID ................................................................................................................. 1083
STRPOS.................................................................................................................. 1084
STRPUT .................................................................................................................. 1085
STRTRIM ............................................................................................................... 1086
STRUCT_ASSIGN ................................................................................................. 1087
STRUPCASE .......................................................................................................... 1089
SURFACE ............................................................................................................... 1090
SURFR .................................................................................................................... 1095
SVDC ...................................................................................................................... 1096
SVDFIT ................................................................................................................... 1098
SVSOL ..................................................................................................................... 1102
xviii Contents
SWAP_ENDIAN ..................................................................................................... 1104
SYSTIME ................................................................................................................. 1105
T_CVF ..................................................................................................................... 1107
T_PDF ..................................................................................................................... 1108
T3D .......................................................................................................................... 1109
TAG_NAMES ......................................................................................................... 1111
TAN ......................................................................................................................... 1112
TANH ...................................................................................................................... 1113
TAPRD .................................................................................................................... 1114
TAPWRT ................................................................................................................. 1115
TEK_COLOR.......................................................................................................... 1116
TEMPORARY ......................................................................................................... 1117
THIN ....................................................................................................................... 1118
THREED ................................................................................................................. 1119
TIME_TEST2 .......................................................................................................... 1120
TM_TEST ................................................................................................................ 1121
TOTAL .................................................................................................................... 1123
TRACE .................................................................................................................... 1125
TRANSPOSE........................................................................................................... 1126
TRI_SURF ............................................................................................................... 1128
TRIANGULATE ..................................................................................................... 1131
TRIGRID ................................................................................................................. 1134
TRIQL ..................................................................................................................... 1140
TRIRED ................................................................................................................... 1142
TRISOL ................................................................................................................... 1143
TRNLOG................................................................................................................. 1145
TS_COEF ................................................................................................................ 1147
TS_DIFF .................................................................................................................. 1148
TS_FCAST ............................................................................................................... 1149
TS_SMOOTH ......................................................................................................... 1151
TV ............................................................................................................................ 1153
TVCRS..................................................................................................................... 1157
TVLCT .................................................................................................................... 1159
TVRD ...................................................................................................................... 1161
TVSCL ..................................................................................................................... 1164
UINDGEN .............................................................................................................. 1166
UINT ....................................................................................................................... 1167
UINTARR ............................................................................................................... 1168
UL64INDGEN ........................................................................................................ 1169
ULINDGEN ............................................................................................................ 1170
ULON64ARR .......................................................................................................... 1171
ULONARR .............................................................................................................. 1172
ULONG ................................................................................................................... 1173
Contents xix
ULONG64 .............................................................................................................. 1174
UNIQ ...................................................................................................................... 1175
USERSYM ............................................................................................................... 1177
VARIANCE ............................................................................................................ 1179
VAX_FLOAT .......................................................................................................... 1180
VEL ......................................................................................................................... 1182
VELOVECT ............................................................................................................ 1184
VERT_T3D ............................................................................................................. 1186
VOIGT .................................................................................................................... 1188
VORONOI ............................................................................................................. 1190
VOXEL_PROJ ........................................................................................................ 1192
WAIT ...................................................................................................................... 1196
WARP_TRI ............................................................................................................ 1197
WDELETE .............................................................................................................. 1199
WEOF ..................................................................................................................... 1200
WF_DRAW ............................................................................................................ 1201
WHERE .................................................................................................................. 1203
WIDGET_BASE ..................................................................................................... 1205
WIDGET_BUTTON .............................................................................................. 1222
WIDGET_CONTROL ........................................................................................... 1230
WIDGET_DRAW .................................................................................................. 1252
WIDGET_DROPLIST ........................................................................................... 1262
WIDGET_EVENT ................................................................................................. 1268
WIDGET_INFO ..................................................................................................... 1271
WIDGET_LABEL ................................................................................................... 1280
WIDGET_LIST ...................................................................................................... 1285
WIDGET_SLIDER ................................................................................................. 1291
WIDGET_TABLE .................................................................................................. 1298
WIDGET_TEXT .................................................................................................... 1309
WINDOW .............................................................................................................. 1317
WRITE_BMP ......................................................................................................... 1320
WRITE_GIF ........................................................................................................... 1322
WRITE_JPEG ......................................................................................................... 1324
WRITE_NRIF......................................................................................................... 1327
WRITE_PICT ......................................................................................................... 1328
WRITE_PNG ......................................................................................................... 1329
WRITE_PPM ......................................................................................................... 1331
WRITE_SPR ........................................................................................................... 1332
WRITE_SRF ........................................................................................................... 1333
WRITE_SYLK ........................................................................................................ 1335
WRITE_TIFF.......................................................................................................... 1337
WRITE_WAVE ...................................................................................................... 1342
WRITEU ................................................................................................................. 1344
xx Contents
WSET ....................................................................................................................... 1346
WSHOW ................................................................................................................. 1347
WTN ........................................................................................................................ 1348
XBM_EDIT ............................................................................................................. 1352
XDISPLAYFILE ...................................................................................................... 1354
XFONT .................................................................................................................... 1356
XINTERANIMATE ................................................................................................ 1357
XLOADCT .............................................................................................................. 1361
XMANAGER........................................................................................................... 1363
XMNG_TMPL ........................................................................................................ 1369
XMTOOL ................................................................................................................ 1370
XPALETTE.............................................................................................................. 1371
XREGISTERED ....................................................................................................... 1374
XSQ_TEST .............................................................................................................. 1375
XSURFACE ............................................................................................................. 1377
XVAREDIT ............................................................................................................. 1378
XYOUTS ................................................................................................................. 1379
ZOOM ..................................................................................................................... 1382
ZOOM_24 ............................................................................................................... 1384
Chapter 10:
Scientic Data Formats . . . . . . . . . . . . . . . . . . . 1387
CDFCommon Data Format ............................................................................... 1387
HDFHierarchical Data Format .......................................................................... 1388
HDF-EOSHierarchical Data Format-Earth Observing System ....................... 1388
NetCDFNetwork Common Data Format ......................................................... 1389
Chapter 11:
Obsolete Routines . . . . . . . . . . . . . . . . . . . . . . . 1391
Backwards Compatibility ....................................................................................... 1391
Detecting Use of Obsolete Features ....................................................................... 1392
Documentation for Obsolete Routines ................................................................. 1392
Routines That Became Obsolete in IDL Version 5.1 ............................................ 1393
Routines That Became Obsolete in IDL Version 5.0 ............................................ 1393
Routines That Became Obsolete in IDL Version 4.0 or Earlier ........................... 1394
Obsolete System Variables ..................................................................................... 1399
Chapter 12:
VMS Floating-Point Arithmetic in IDL 5.1 . . . . . . 1401
VAX Floating-Point Format Background ............................................................. 1402
Contents xxi
Transition Issues .................................................................................................... 1403
A Warning About Floating-Point Conversions ................................................... 1404
A Strategy For Converting VMS IDL Programs................................................... 1405
Using CALL_EXTERNAL Under IDL 5.1 and Later ........................................... 1406
A Note on the VMS G Float Format ..................................................................... 1407
Index
xxii Contents
23
Chapter 1
Overview
This chapter includes information about IDL, the IDL documentation set, and about
contacting Research Systems regarding problems with IDL.
About IDL
IDL is a complete computing environment for the interactive analysis and visualization
of data. IDLintegratesapowerful, array-orientedlanguagewithnumerousmathematical
analysis and graphical display techniques. Programming in IDL is a time-saving
alternativeto programmingin FORTRAN or CusingIDL, taskswhich requiredaysor
weeksof programmingwithtraditional languagescan beaccomplishedin hours. Youcan
exploredatainteractivelyusingIDLcommandsandthen createcompleteapplicationsby
writing IDL programs.
Advantages of IDL include:
IDL is a complete, structured language that can be used both interactively and to create
sophisticated functions, procedures, and applications.
24 Chapter 1: Overview
IDL Documentation IDL Reference Guide
Operators and functions work on entire arrays (without using loops), simplifying inter-
active analysis and reducing programming time.
Immediatecompilation and execution of IDL commandsprovidesinstant feedback and
hands-on interaction.
Rapid 2Dplotting, multi-dimensional plotting, volumevisualization, imagedisplay, and
animation allow you to observe the results of your computations immediately.
Many numerical and statistical analysis routinesincluding Numerical Recipes rou-
tinesare provided for analysis and simulation of data.
IDLs exible input/output facilities allow you to read any type of custom data format.
Support is also provided for common image standards (including BMP, GIF, JPEG, and
XWD) and scientic data formats (CDF, HDF, and NetCDF).
IDLwidgetscanbeusedtoquicklycreatemulti-platformgraphical user interfacestoyour
IDL programs.
IDL programs run the same across all supported platforms (Unix, VMS, Microsoft
Windows, and Macintosh systems) with little or no modication. This application port-
ability allows you to easily support a variety of computers.
ExistingFORTRANandCroutinescanbedynamically-linkedintoIDLtoaddspecialized
functionality. Alternatively, C and FORTRAN programs can call IDL routines as a sub-
routine library or display engine.
IDL Documentation
IDLsOnlineHelp system gives you access to the complete IDL documentation set in
electronic, hypertext-linked format. You can enter the Online Help system by entering ?
at the IDL command prompt or by selecting Online Help from the Help menu of the
IDL Development Environment user interface.
Research Systems provides a subset of the complete IDL documentation set in printed
form along with your copy of the IDL software. We do not ship the full printed
documentation set because some volumes cover specialized topics, which are of limited
interest to someof our customers. Shippingonly thevolumesof greatest general interest
in printedformallowsustoprovidethehighest qualitydocumentation set possiblewhile
minimizingtheimpact of our documentation on theenvironment. In addition to being
available on-line, volumes not automatically shipped with new or upgrade orders are
available for purchase; use the order sheet included with your shipment or consult your
sales representative or distributor for details.
The IDL documentation set consists of the following volumes:
Using IDL
UsingIDL explainsIDL froman interactiveuserspoint of view. It containsinformation
about theIDL environment, thestructureof IDL, andhowtouseIDL Direct Graphicsto
analyze your data.
Chapter 1: Overview 25
IDL Reference Guide IDL Documentation
Building IDL Applications
Building IDL Applicationsexplains how to use the IDL language to write programs
from simple procedures to large, complex applications. It contains information on the
structureof theIDL language, programmingtechniques, IDL Direct Graphics, and IDLs
user-interface toolkit.
IDL Reference Guide
TheReferenceGuide(this book) is a two-volume set that contains detailed information
about all of IDLs non-object oriented procedures, functions, system variables, and
commands. Information on IDLs object-oriented features is contained in Building IDL
Applications; information on IDL Object Graphics is contained in Object Graphics.
Object Graphics
ObjectGraphicscontainsacompletediscussion of IDLObject Graphics. Thisvolumealso
contains the complete reference to IDLs object class libraries.
Note Eachof theabovebooksincludesacomprehensiveindexthat coversall four volumes.
Using Insight
Using Insight contains information on IDL Insight, the graphical interface to IDLs
analysis capabilities. Insight allows you to import, analyze, and visualize data without
programming in the IDL language.
External Development Guide
TheExternal Development Guideexplains how to use IDL in concert with your
computersoperatingsystemor withprogramswritten in other programminglanguages.
Scientic Data Formats
Scientic Data Formatscontains detailed information about IDLs routines for dealing
with Common DataFormat (CDF), Hierarchical DataFormat (HDF), Earth Observing
Systemextensionsto HDF(HDF-EOS), and Network Common DataFormat (NetCDF)
les.
IDL DataMiner Guide
TheDataMinerGuidecontainsinformationonusingIDLtointeract withdatabasesusing
the Open Database Connectivity (ODBC) interface.
Note The DataMiner option must be purchased separately.
IDL HandiGuide
The HandiGuide is a handy quick reference that contains calling-sequence information
on all IDL routines.
Typographical Conventions IDL Reference Guide
Typographical Conventions
Thefollowingtypographical conventionsareused throughout theIDL documentation set:
UPPER CASE
IDL functions, procedures, and keywordsaredisplayed in UPPERCASEtype. For exam-
ple, the calling sequence for an IDL procedure looks like this:
CONTOUR, Z [, X, Y]
Mixed Case
IDL object class and method names are displayed in Mixed Case type. For example, the
calling sequence to create an object and call a method looks like this:
object = OBJ_NEW('IDLgrPlot')
object -> GetProperty, ALL=properties
Italic type
ArgumentstoIDLproceduresandfunctionsdataor variablesyoumust provideare
displayed in italic type. In the above example, Z, X, and Y are all arguments.
Square brackets ( [ ] )
Square brackets used in calling sequences indicate that the enclosed arguments are
optional. Donot typethebrackets. IntheaboveCONTOURexample, XandYareoptional
arguments. Square brackets are also used to specify array elements.
Courier type
In examplesor programlistings, thingsthat you must enter at thecommand lineor in a
le are displayed in courier type. Results or data that IDL displays on your computer
screen are shown in courier bold type. An example might direct you to enter the
following at the IDL command prompt:
array = INDGEN(5)
PRINT, array
In this case, the results are shown like this:
0 1 2 3 4
Reporting Problems
WestrivetomakeIDL asreliableandbugfreeaspossible. However, noprogramwith the
size and complexity of IDL is perfect, and bugs do surface. When you encounter a
problemwithIDL, themanner in whichyoureport it hasalargebearingon howwell and
quickly we can x it. This section is intended to help you report problems in a way that
will help us correct the problem rapidly.
IDL Reference Guide Reporting Problems
Background Information
Whenabugisreportedandveried, wecorrect it in alater release. Sometimes, abugonly
occurs when running on a certain machine, operating system, or graphics device. For
these reasons, we need to know the following facts when you report a bug:
Your IDL installation number.
The version of IDL you are running.
The type of machine it is running on.
The operating system version it is running under.
The type and version of your windowing system.
The graphics device, if the problem involves graphics.
Theinstallation number isassigned by uswhen you purchaseIDL. TheIDL version, site
number, and type of machine are printed when IDL is started. For example:
IDL. Version 4.0.1c (sunos sparc).
Copyright 1989-1996, Research Systems, Inc.
All rights reserved. Unauthorized reproduction prohibited.
Installation number: 177.
Licensed for use by: ACME Datawhack Corp.
is the startup announcement from IDL version 4.0.1c under SunOS on a Sun Sparc
workstation at installation number 177.
Under Unix, the version of the operating system can usually be found in the le
/etc/motd. It is also printed when the machine boots. In any event, your system
administrator should know.
Under VMS, the DCL statement:
write sys$output f$getsyi("version")
will give you the operating system version.
Under Windows 95 and Windows NT version 4, select About from the Help menu in
the Windows Explorer. Under Windows NT version 3.5, select About from the Help
menu in the File Manager.
On the Macintosh, select About this Macintosh from the apple menu.
Double Check
Before reporting a problem, you should always ask yourself Is it really a bug?
Sometimes, it isasimplematter of misinterpretingwhat issupposed to happen. Double
check with the manual or a local expert.
If you cannot determine what should happen in a given situation by consulting the
reference manual, the manual needs to be improved on that topic. Please let us know if
you feel that the manual was vague or unclear on a subject.
Reporting Problems IDL Reference Guide
It isoften obviouswhether somethingisabugor not. If IDL crashes, it isagenuinebug.
If however, it drawsaplot differently than you would expect or desire, it might beabug,
but it iscertainlylessobvious. Another question toask iswhether theproblemlieswithin
IDL, or with the system running IDL. Is your system properly congured with enough
virtual memoryandsufcient operatingsystemquotas?Doesthesystemseemstableand
is everything else working normally?
Describing The Problem
When describing the problem, it is important to use precise language. Vague terms like
crashes, blows up, and fails are open to many interpretations. Does it really crash
IDL and leave you looking at an operating system prompt?This would be our
interpretation of crash. Perhaps, however, it just issues an unexpected error message
and gives another prompt. What is really meant by a term like fails?
It is also important to separate concrete facts from conjecture about underlying causes.
For example, astatement suchas IDLdumpscorewhen allocatingdynamicmemory. is
not nearlyasuseful asonelike IDLdumpscorewhen I executethefollowingstatements.
I think it might be trying to get dynamic memory. The second version tells us exactly
what happened. Theopinion about what wasgoingon when theproblemsurfacedisalso
useful to us, but it helps to have it clearly labeled as such.
Reproducibility
Intermittent bugsareby far thehardest kind tox. In general, if wecant makeit happen
on our machine, wecant x it. It isthereforefar morelikely that wecan help you if you
can tell us a sequence of IDL statements that cause the problem to happen. Naturally,
there are degrees of reproducibility. Situations where a certain sequence of statements
causes the bug 1 time in 3 tries are fairly likely to be xable. Situations where the bug
happensonceevery fewmonthsand no oneissurewhat triggered it arealmost hopeless.
Simplify the Problem
When reporting a bug, it is important to give us the shortest possible series of IDL
statementsthat causeit. Thelonger andmoreintricatean example, thelesslikelyit isthat
we can help. Sometimes a single statement triggers the bug. Often though, the problem
surfaces when writing a larger system of inter-related procedures and functions. Such a
situation must be simplied before we can tackle it.
Take the following steps to simplify your problem:
Copy the procedure and function les that are involved to a scratch second copy. Never
modify your only copy!
Eliminate everything that is not involved in demonstrating the bug. Dont do this all at
once. Instead, do it in aseriesof slowcareful steps. Between each step, stop and run IDL
on the result to ensure that the bug still appears.
If a simplication causes the bug to disappear, restore the statements involved and look
for other things to eliminate.
IDL Reference Guide Reporting Problems
If theproblemdoesnot involveleInput/Output, strivetoeliminateall leI/Ostatements.
Use IDL routines to generate a dummy data set, rather than including your own data. If
your bug report does not involve I/O, it will be much easier for us to reproduce. If you
have to provide us with a copy of your data, things become more complicated.
On the other hand, if the bug involves le Input/Output, attempt to determine if the
problemonlyhappenswithacertainle, or withanydata. If youarerunningunder VMS,
check the le organization using the DCL DIRECTORY/FULL command, and include
this information in your report.
The end result of such simplication should be a small number of IDL statements that
demonstrate the problem.
Bugs with Dynamic Loading
Under some operating systems, the CALL_EXTERNAL and LINKIMAGE system
routinesallowyoutodynamicallyloadroutineswritten in other languagesintoIDL. This
isavery powerful techniquefor extendingIDL, but it isconsiderably moredifcult than
simplywritingIDLstatements. At thislevel, theprogrammer isunderneaththeuser level
shell of IDL and is not protected from small programming errors that can corrupt data,
giveincorrect results, or even crash IDL. In such situations, theburden of provingthat a
bug is within IDL and not the dynamically loaded code is entirely the programmers.
Although it is certainly true that a bug in this situation can be within IDL, it is very
important that you exhaust all other possibilities before reporting a bug. If you decide
that you need to report abug, thecommentsaboveon simplifyingthingsareeven more
important than usual. If you sendusasmall examplethat ticklesthebug, wecan respond
quickly with a correction or advice. Otherwise, we may not even know where to begin.
Sending Data with Your Bug Report
If thestatementsrequired to reproducethebugaremorethan afewlinesor requiredata
les, we will need you to send them to us on magnetic media or via e-mail. Call us for
details.
Contact Us
To report a problem, contact us at the following addresses.
Mail
Research Systems, Inc.
4990 Pearl East Circle
Boulder, Colorado 80301
Telephone
(303) 786-9900 (Voice)
(303) 786-9909 (Fax)
(303) 413-3920 (IDL technical support direct line)
Reporting Problems IDL Reference Guide
Electronic Mail
support@rsinc.com
31
Chapter 2
Executive Commands
IDL executivecommandscompile programs, continue stopped programs, and start
previously compiled programs. All of thesecommandsbegin with aperiod and must be
enteredin responsetotheIDLprompt. Commandscan beenteredin either uppercaseor
lowercase and can be abbreviated. Under UNIX, lenames are case sensitive, while with
VMS, Windows, and the Macintosh either case can be used. Note that comments
(prefaced by the semicolon character in IDL code) are not allowed within executive
commands. Executive commands are summarized in Table 2-1.
Command Action
.COMPILE Compiles text from les or keyboard without executing
.CONTINUE Continues execution of a stopped program
.EDIT Opens les in editor windows of the IDLDE
(Windows and Motif only)
Table 2-1: Executive Commands
32 Chapter 2: Executive Commands
IDL Reference Guide
.COMPILE
Calling Sequence
.COMPILE [File
1
, ..., File
n
]
.COMPILE -f File TempFile
The .COMPILE command compiles and saves procedures and programs in the same
manner as .RUN. If one or more lenames are specied, 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 les are not yet open, IDL opens the les
within Editor windows and compiles the procedures and functions contained therein.
See RESOLVE_ROUTINE on page 954 for a way to invoke the same operation from
within an IDL routine, and RESOLVE_ALL on page 952 for a way to automatically
compile all user-written or library functions called by all currently-compiled routines.
If the-f agisspecied, Fileiscompiled fromthesourcestored temporarilyin TempFile
rather than on disk in Fileitself. This allows you to make changes to File(in an IDLDE
editor window, for example), store the modied source into the temporary le (IDLDE
does it automatically), compile, and test the changes without overwriting the original
code stored in File.
.GO Executes previously compiled main program from
beginning
.OUT Continues program execution until the current routine
returns
.RETURN Continues execution until encountering a RETURN
statement.
.RNEW Erases main program variables and then .RUN
.RUN Compiles and possibly executes text from les or key-
board
.SKIP Skips over the next statement and then single steps
.STEP Executes a single statement (abbreviated as .S)
.STEPOVER Executesasinglestatement if thestatement doesnot call
a
routine (abbreviated as .SO)
.TRACE Similar to .CONTINUE, but displays each line of code
before execution
Command Action
Table 2-1: Executive Commands
Chapter 2: Executive Commands 33
IDL Reference Guide
.CONTINUE
The.CONTINUEcommand continuesexecution of aprogramthat hasstopped 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 STOPstatements, .CONTINUEcontinuesexecution at the
next statement. The .CONTINUE command can be abbreviated; for example, .C.
Executionof aprograminterruptedbytypingControl-Calsocanberesumedat thepoint
of interruption with the .CONTINUE command.
.EDIT
Calling Sequence
.EDIT File
1
[File
2
... File
n
]
The.EDITcommandopenslesin IDLEditor windowswhen calledfromtheCommand
Input Lineof theIDLDE. Thisfunctionality isonly availableon theWindowsand Motif
platforms.
.GO
The .GO command starts execution at the beginning of a previously-compiled main
program.
.OUT
The .OUT command continues executing statements in the current program until it
returns.
.RETURN
The .RETURN command continues execution of a program until encountering a
RETURNstatement. Thisisconvenient for debuggingprogramssinceit allowsthewhole
program to run, stopping before returning to the next-higher program level so you can
examine local variables.
For information about the RETURN command, see page 958.
.RNEW
Calling Sequence
.RNEW[File
1
, ..., File
n
]
The.RNEWcommandcompilesandsavesproceduresandfunctionsin thesamemanner
as .RUN. In addition, all variables in the main program unit, except those in common
blocks, are erased. The -t and -l lename switches have the same effect as with .RUN.
Example Some statements using the .RUN and .RNEW commands are shown below.
IDL Reference Guide
.RUN Accept a programfromthe key-
board. Retain the present vari-
ables.
.RUN myfile Compile the le myle.pro. If it
is not found in the current di-
rectory, try to nd it in the di-
rectory search path.
.RUN -T A, B, C Compile the les a.pro, b.pro
and c.pro. List the les on the
terminal.
.RNEW -L myfile.lis myfile, yourfile Erase all variables and com-
pile the les myle.pro and
yourle.pro. Produce a listing
on myle.lis.
.RUN
Calling Sequence
.RUN[File
1
, ..., File
n
]
The.RUNcommandcompilesprocedures, functions, and/or mainprogramsinmemory.
Main programsareexecutedimmediately. Thecommandcan befollowedbyalist of les
to be compiled. Filenames are separated by blanks, tabs, or commas.
If a le specication is included in the command, IDL searches for the le rst in the
current directory, then in the directories specied by the system variable !PATH. See
ExecutingProgramFiles onpage29of UsingIDLfor moreinformationonIDLssearch
strategy.
If amain programunit isencountered, execution of theprogramwill begin after all les
havebeen readif therewerenoerrors. Thevaluesof all of thevariablesareretained. If the
le isnt 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 le
extension (sufx) .pro. Files created with the SAVE procedure are assumed to have the
extension .sav. See Preparing and Running Programs on page 28 of Using IDL for
further information.
Note Subsequent calls to .RUN compile the procedure again.
Using .RUN to Make Program Listings
The command arguments -t for terminal listing or -l lename for listing to a named le
can appear after the command name and before the program lenames to produce a
numbered program listing directed to the terminal or to a le.
For instance, to seealistingon thescreen asaresult of compilingaprocedurecontained
in a le named analyze.pro, use the following command:
Chapter 2: Executive Commands 35
IDL Reference Guide
.RUN -T analyze
To compile the same procedure and save the listing in a le 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 le 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 nestingisindentedfour spacestotheright of theprecedingblock
level to improve the legibility of the programs structure.
.SKIP
Calling Sequence
.SKIP[n]
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 OPEN statement fails because the specied le does not exist, program execution
will halt with the OPEN statement as the current statement. Execution can not be
resumed with the executive command .CONTINUE because it attempts to re-execute
the offending OPEN statement, causing the same error. The remainder of the program
can be executed by:
1. Opening the correct le by manually typing in a valid OPEN statement.
2. Entering .SKIP, which skips over the incorrect OPEN statement.
3. Entering.CONTINUE, which resumes execution of the program at theREADF
statement.
.STEP
Calling Sequence
.STEP[n] or .S[n]
IDL Reference Guide
The.STEPcommandexecutesoneor morestatementsin thecurrent programstartingat
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.
.STEPOVER
Calling Sequence
.STEPOVER[n] or .SO[n]
The .STEPOVER command executes one or more statements in the current program
startingat thecurrent position, stops, andreturnscontrol totheinteractivemode. Unlike
.STEP, if .STEPOVER executes a statement that calls another routine, the called routine
runsuntil it endsbeforecontrol returnsto interactivemode. That is, astatement 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.
.TRACE
Continuesexecution of aprogramthat hasstoppedbecauseof an error, astopstatement,
or a keyboard interrupt. .TRACE differs from .CONTINUE in that if IDL is using a
graphical user interface (IDLDE for Windows, IDLDE for Macintosh, or IDLDE for
Motif ), a dialog to control the speed at which each line is executed.. For command-line
versions of IDL, .TRACE is identical to .CONTINUE.
37
Chapter 3
System Variables
Systemvariablesareaspecial classof predened variablesavailableto all programunits.
Their namesalwaysbegin with theexclamation mark character (!). Systemvariablesare
used to set theoptionsfor plotting, to set variousinternal modes, to return error status,
etc.
Systemvariableshaveapredened typeand structurethat cannot bechanged. When an
expression isstoredintoasystemvariable, it isconvertedtothevariabletype, if necessary
and possible. Certain systemvariablesarereadonly, and their valuescannot bechanged.
The user can dene new system variables with the DEFSYSV procedure.
Constant System Variables
The following system variables contain pre-dened constants or values for use by IDL
routines. System variables can be used just like other variables. For example, the
command:
PRINT, ACOS(A) * !RADEG
38 Chapter 3: System Variables
Error Handling and Informational System Variables IDL Reference Guide
converts a result expressed in radians to one expressed in degrees.
!DPI
A read-only variable containing the double-precision value of pi ().
!DTOR
A read-only variable containing the oating-point value used to convert degrees to
radians (/180 0.01745).
!MAP
An array variable containing the information needed to effect coordinate conversions
between points of latitude and longitude and map coordinates. The values in this array
are established by the MAP_SET procedure; the user should not change them directly.
!PI
A read-only variable containing the single-precision value of pi ().
!RADEG
A read-only variable containing the oating-point value used to convert radians to
degrees (180/ 57.2958).
!VALUES
A read-only variable containing the IEEE single- and double-precision oating-point
valuesInnity and NaN (Not A Number). !VALUES is a structure variable with the
following elds:
** Structure !VALUES, 4 tags, length=24:
F_INFINITY FLOAT Infinity
F_NAN FLOAT NaN
D_INFINITY DOUBLE Infinity
D_NAN DOUBLE NaN
whereInnity is the value Innity and NaN is the value Not A Number. (For more
informationonthesespecial oating-point values, seeSpecial Floating-Point Values on
page 152 of Building IDL Applications.)
Error Handling and Informational System Variables
The following system variables are either set by IDL when an error condition occurs or
used by IDL when displaying information about errors.
!ERR
Thiskeywordisnowobsoleteandhasbeenreplacedbythe!ERROR_STATEsystemvariable.
Codethat uses the!ERR system variablewill continueto function as before, but wesuggest
that all new codeuse!ERROR_STATE.CODE.
Chapter 3: System Variables 39
IDL Reference Guide Error Handling and Informational System Variables
!ERROR_STATE
Astructurevariablewhich containsthestatusof thelast error message. !ERROR_STATE
includes the following elds:
** Structure !ERROR_STATE, 7tags, length=52:
NAME STRING 'M_SUCCESS'
BLOCK STRING 'IDL_MBLK_CORE'
CODE LONG 0
SYS_CODE LONG Array[2]
MSG STRING ''
SYS_MSG STRING ''
MSG_PREFIX STRING '%'
NAME: A read-only string variable containing the error name of the IDL-generated
component of the last error message.
BLOCK: Aread-onlystringvariablecontainingthenameof themessageblock for thelast
error messages IDL-generated component.
See theExternal Development Guidefor more information about blocks.
CODE: Along-integer variablecontainingtheerror codeof thelast errorsIDL-generated
component.
SYS_CODE: Along-integer variablecontainingtheerror codeof thelast errorsoperating
system-generated component, if it exists.
MSG: A read-only string variable containing the text of the last IDL-generated error
message.
SYS_MSG: A read-only string variable containing the text of the last errors operating
system-generated component, if it exists.
MSG_PREFIX: A string variable containing the prex string used for error messages.
This system variable replaces !ERROR, !ERR_STRING, !MSG_PREFIX,
!SYSERR_STRING, and!SYSERROR, andincludestwonewelds: error nameandblock
name. For amoredetailedexplanationof !ERROR_STATE, see Error Handling onpage
149 of Building IDL Applications.
!ERROR
Codethatusesthe!ERRORsystemvariablewill continuetofunctionasbefore,butwesuggest
that all new codeuse!ERROR_STATE.NAME.
Error Handling and Informational System Variables IDL Reference Guide
!ERR_STRING
Codethatusesthe!ERR_STRINGsystemvariablewill continuetofunctionasbefore, butwe
suggest that all new codeuse!ERROR_STATE.MSG.
!EXCEPT
An integer variable that controls when IDL checks for invalid mathematical
computations (exceptions), such as division by zero. The three allowed values are:
For more information on invalid mathematical computations and error reporting, see
Math Errors on page 151 of Building IDL Applications.
The value of !EXCEPT is used by the CHECK_MATH function to determine when to
return errors. See CHECK_MATH on page 261 for details.
Note In versionsof IDL uptoandincludingIDL 4.0.1, thedefault exception handlingwas
functionally identical to setting !EXCEPT=2.
!MOUSE
Astructurevariablethat containsthestatusfromthelast cursor readoperation. !MOUSE
has the following elds:
** Structure !MOUSE, 4 tags, length=16:
X LONG 511
Y LONG 252
BUTTON LONG 4
TIME LONG 1428829775
XandY: Containthelocation(indevicecoordinates) of thecursor whenthemousebutton
was pressed.
BUTTON: Contains
- 1 (one) if the left mouse button was pressed,
- 2 (two) if the middle mouse button was pressed
- 4 (four) if the right mouse button was pressed.
0 Never report exceptions.
1 Report exceptions when the interpreter is returning to an
interactive prompt (the default).
2 Report exceptionsat theend of each IDL statement. Notethat
this slows IDL by roughly 5% compared to setting
!EXCEPT=1.
IDL Reference Guide Error Handling and Informational System Variables
TIME: Contains the number of milliseconds since a base time.
See CURSOR on page 332 for details on reading the cursor position.
!MSG_PREFIX
Codethatusesthe!MSG_PREFIXsystemvariablewill continuetofunctionasbefore, butwe
suggest that all new codeuse!ERROR_STATE.MSG_PREFIX.
!SYSERROR
Codethat uses the!SYSERROR system variablewill continueto function as before, but we
suggest that all new codeuse!ERROR_STATE.SYS_CODE.
!SYSERR_STRING
Codethat uses the!SYSERR_STRING system variablewill continueto function as before,
but wesuggest that all new codeuse!ERROR_STATE.SYS_MSG.
!WARN
A structure variable that causes IDL to print warnings to the console or command log
when obsolete IDL features are found at compile time. !WARN has the following elds:
** Structure !WARN, 3 tags, length=3:
OBS_ROUTINES BYTE 0
OBS_SYSVARS BYTE 0
PARENS BYTE 0
TRUNCATED_FILENAME BYTE 0
Setting each of the four elds to 1 (one) generates a warning for a different type of
obsolete code. If the OBS_ROUTINES eld is set equal to one, IDL generates warnings
when it encounters references to obsolete internal or library routines. If the
OBS_SYSVARS eld is set equal to one, IDL generates warnings when it encounters
references to obsolete system variables. If the PARENS eld is set equal to one, IDL
generates warnings when it encounters a use of parentheses to specify an index into an
array. If theTRUNCATED_FILENAMEeld isset equal to one, IDL generateswarnings
whenever a le can only be found by truncating its full name.
Caution IDL version 5.1 is the last version of IDL that will support DOS 8.3 lename
limitations, . All future IDL releases will not truncate lenames. You can use
!WARN.TRUNCATE_FILENAMEto locateand renametruncated lenames. Please
renametheleuponbeingwarnedthat alenamehasbeentruncatedtoavoidfuture
problems.
No warnings are generated when the elds of the !WARN structure are set equal to zero
(the default).
IDL Environment System Variables IDL Reference Guide
IDL Environment System Variables
The following system variables contain information about IDLs conguration.
!DIR
A string variable containing the path to the main IDL directory.
!DLM_PATH
Signicant portions of IDLs built in functionality are packaged in the form of
Dynamically Loadable Modules (DLMs). DLMs correspond to Macintosh code
fragments, Unix sharable libraries, VMS sharable executables, or Windows DLLs,
depending on the operating system in use. At startup, IDL searches for DLM denition
les(whichendinthe.dlm sufx) andmakesnoteof theroutinessuppliedbyeachDLM.
If such areroutineiscalled, IDL loadstheDLM that suppliesit intomemory. Toseealist
of theDLMsthat IDLknowsabout, useHELP, /DLM_PATH (seeHELP onpage537for
more information).
!DLM_PATH isinitializedfromtheenvironment variableIDL_DLM_PATH at startup. If
the IDL_DLM_PATH environment variable is not dened, IDL supplies a default that
containsthedirectory in theIDL distribution wheretheRSI supplied DLMsreside. This
initialization is similar to that performed for IDL_PATH, (see !PATH on page 43),
including recursive path expansion denoted with a leading "+". Once !DLM_PATH is
expanded, IDL uses it as the list of places to look for DLM denition les.
Sinceall DLMsearchinghappensonceat startuptime, it wouldbemeaninglesstochange
thevalueof !DLM_PATH afterwards. For thisreason, it isareadonlysystemvariableand
cannot be assigned to. The value of !DLM_PATH is useful because it shows you where
IDL looked for DLMs when it started.
!EDIT_INPUT
An integer variable indicating whether keyboard line editing is enabled (when set to a
non-zero value) or disabled (when set to zero). By default, !EDIT_INPUT isset equal to
one, and line editing is enabled.
Bydefault, IDLsavesthelast 20commandlines. Youcanchangethenumber of command
linessaved in therecall buffer by setting!EDIT_INPUT equal to thenumber of linesyou
would liketo save. In order for thechangeto takeeffect, IDL must beableto processthe
assignment statement before providing a command prompt. This means that you must
put the assignment statement in the IDL startup le. (See Startup File on page 33 of
Using IDL for more information on startup les.)
!HELP_PATH
AstringvariablelistingthedirectoriesIDL will search for onlinehelp les. Thedefault is
thehelp subdirectory of themain IDL directory. Thedefault can bechanged by setting
theIDL_HELP_PATH environment variable or logical name under UNIX or VMS, by
specifying the desired help path in the IDL Path Preferences dialog under Microsoft
Windows, or by manually setting the variable at the IDL command prompt under the
Macintosh OS.
IDL Reference Guide IDL Environment System Variables
!JOURNAL
A read-only long-integer variablecontainingthelogical unit number of theleused for
journal output.
!MORE
An integer variable indicating whether IDL should paginate help output sent to a tty
device. Setting!MOREto zero (0) preventsIDL frompaginatingtheoutput text. A non-
zero value (the default) causes IDL to display output text one screen at a time.
!PATH
A string variable listing the directories IDL will search for libraries, include les, and
executive commands.
Unix: !PATH is a colon-separated list of directories, similar in concept to the PATH
environment variable which UNIX uses to locate commands.
!PATH is initialized from the environment variable IDL_PATH when IDL starts. Note
that directories that do not contain at least one.pro or .sav le will not be included
in !PATH, even if they arespecied by theIDL_PATH environment variable. Thisinitial
valuecan bechanged, asdesired, oncein IDL. For example, thefollowingstatement adds
the directory /usr2/project/idl_files to the beginning of the search path:
!path = '/usr2/project/idl_files:' + !path
To specify a directory tree that includes all of that directorys subdirectories, use the
EXPAND_PATH function.
Each user can assign IDL_PATH to a series of directories that are searched for IDL
programs, procedures, functions, and include les. It is convenient to set up this
variable in your ~/.cshrc:
setenv IDL_PATH ~/idl_lib:/usr/local/rsi/idl/lib
or ~/.profile:
IDL_PATH=~/idl_lib:/usr/local/rsi/idl/lib ; export IDL_PATH
This causes IDL to search for programs rst in the current directory, then in your
idl/lib directory, and then in the system-wide directory /usr/local/rsi/
idl/lib.
If IDL_PATH is not dened, IDL initializes !PATH to the default value+/usr/
local/rsi/idl. Notethat thecurrent directory isalwayssearched beforeconsulting
!PATH.
VMS:!PATH isacomma-separatedlist of directoriesandtext libraries. Text librariesare
distinguished by prepending a @ character to their name.
!PATH is initialized from the logical name IDL_PATH when IDL starts. Note that
directories that do not contain at least one.pro or .sav le will not be included in
!PATH, even if they are specied by the IDL_PATH logical. This initial value can be
IDL Environment System Variables IDL Reference Guide
changed oncein IDL asdesired. For example, thefollowingstatement addsthedirectory
DISKA:[PROJECTLIB] to the beginning of the search path:
path = 'diska:[projectlib],' + !path
Each user can assign IDL_PATH to a series of directories and text libraries that are
searched in order for IDL programs, procedures, functions, and include les. It is
convenient to set up this variable in your LOGIN.COM le. For example,
DEFINE IDL_PATH "DISKA:[USER.IDLLIB],@IDL_DIR:[LIB]USERLIB.TLB"
causes IDL to search for programs rst in the current directory, then in the directory
DISKA:[USER.IDLLIB], and nally in the library of routines written in IDL and
included in thestandard IDL distribution, which issupplied asaVMStext library. Note
that the current directory is always searched before consulting !PATH.
Thelogical IDL_PATH also can bedened asamulti-valued logical name(e.g., asearch
list logical). Therefore, the above example also can be written as follows:
DEFINE IDL_PATH DISKA:[USER.IDLLIB],"@IDL_DIR:[LIB]USERLIB.TLB"
IDL simply takesthevarioustranslationsand concatenatesthemtogether into acomma-
separated list. Note that the quotes around the second translation in this example are
necessary to keep DCL from seeing the @ character as an invitation to execute a
command le.
Windows:!PATH isasemicolon-separated list of directories, similar in concept tothe
PATH environment variableDOSusestolocatecommands. !PATH isinitializedfromthe
savedIDLforWindowspreferencesdata, or fromaDOSenvironment variableIDL_PATH,
when IDLstarts. Notethat directoriesthat donot contain at least one.pro or .sav le
will not be included in !PATH, even if they are specied by the preferences data or the
IDL_PATH environment variable. Change the path settings by adding to or altering the
list of directoriesin the Path dialog, foundunder the Preferences selection of theIDL
for WindowsFile menu, or by changing the value of !PATH from the IDL command
prompt.
Macintosh:!PATH isacomma-separated list of folders. !PATH isinitialized fromthe
saved IDL for Macintoshpreferences data when IDL starts. Note that folders that do not
contain at least one.pro or .sav le will not be included in !PATH, even if they are
speciedbythepreferencesdata. Changethepathsettingsbyaddingtoor alteringthelist
of directories in the Search Path dialog, found in theIDL for MacintoshFile menu, or
by changing the value of !PATH from the IDL command prompt.
Use the following syntax is used to specify Macintosh path locations:
Filenames are specied as a colon-separated list of drive names and folders.
IDL Reference Guide IDL Environment System Variables
Folder and le names can contain spaces and/or commas.
Thus, thelemyprogram.pro, located in thefolder namedPrograms which resides
on the drive named Macintosh HD would be specied:
'Macintosh HD:Programs:myprogram.pro'
A Note on Order within !PATH
IDL ensuresonly that all directoriescontainingIDL lesareplaced in !PATH. Theorder
in which they appear is completely unspecied, and does not necessarily correspond to
anyspecicorder (suchastop-downalphabetized). ThisallowsIDLtoconstruct thepath
in thefastest possiblewayandspeedsstartup. Thisisonlyaproblemif twosubdirectories
in such a hierarchy contain a le with the same name. Such hierarchies usually are a
collection of cooperative routines designed to work together, so such duplication is rare.
If the order in which + expands directories is a problem for your application, you
shouldaddthedirectoriestothepathexplicitlyandnot use +. Onlytheorder of theles
withinagiven+ entryaredeterminedbyIDL. It never reorders!PATHinanyother way.
You can therefore obtain any search order you desire by writing the path explicitly.
!PROMPT
Astringvariablecontainingthetext stringusedbyIDLtoprompt theuser for input. The
default isIDL>.
!QUIET
Along-integer variableindicatingwhether informational messagesshouldbeprinted(0)
or suppressed (nonzero). By default, !QUIET is set to zero.
!VERSION
A structure variable containing information about the version of IDL in use. The
structure is dened as follows:
{!VERSION, ARCH:'', OS:'', OS_FAMILY:'', RELEASE:'', BUILD_DATE:''}
TheARCH eld reportsthetypeof CPU. TheOSeld reportsthenameof theoperating
system, and the OS_FAMILY eld reports the general type of operating system. The
RELEASEeldreportstheIDLversion number. TheBUILD_DATEeldreportsthedate
the IDL executable was compiled, in the format dictated by ANSI C for the__DATE__
macro.
In theunlikelyevent that youneedtodifferentiatebetween different IDLversionsin your
code, use !VERSION.OS_FAMILY. At present, four operating system families are
supported: MacOS, unix, vms, Windows. If for some reason you need even more detail,
use !VERSION.OS. Operating system names used in the OS eld are: A/UX, AIX,
DG/UX, hp-ux, IRIX, MacOS, OSF, RISC/os, sunos, vms, Win32.
Graphics System Variables IDL Reference Guide
Graphics System Variables
The following system variables control various IDL Direct Graphics functions. These
system variables are structures that contain many tags. For example, the command
!P.TITLE = 'Cross Section'
sets the default plot title.
Many of the functions of the graphics keywords described in Graphics Keywords on
page 99 are also controlled by the system variables !P, !X, !Y, and !Z.
You can changethedefault styleof plots, fonts, etc., by settingthecorrespondingeld in
the appropriate system variable. Also, some effects that persist longer than one call are
controlled only by system variables. The eld !P.MULTI is one example.
!C System Variable
The cursor system variable. Currently, the only function of this system variable is to
contain the subscript of the largest or smallest element found by the MAX and MIN
functions. That informationisbetter obtainedthroughtheoptional output argumentsto
those routines. !C is included only for compatibility with old versions of IDL.
!D System Variable
This system variable is a structure that contains information about the current graphics
output device (or window, on a windowing system). Fields, in alphabetical order, are:
FILL_DIST
The line interval, in device coordinates, required to obtain a solid ll.
FLAGS
A longword of agsthat provideinformation about thecurrent device. Each bit isaag
encoded as shown in Table 3-1, below. To test whether a particular bit is set on your
system, use an IDL command like the following:
IF (!D.FLAGS AND value) NE 0 THEN PRINT, 'Bit is set.'
wherevalueisthevalueassociated with thebit you wish toexaine. For example, tocheck
whether the device supports color, use:
IF (!D.FLAGS AND 16) NE 0 THEN PRINT, 'Bit is set.'
N_COLORS
Thenumber of allowed color values. In thecaseof deviceswith windows, thiseld isset
after the window system is initialized. For a monochrome system, !D.N_COLORS is 2,
and for color systems it is normally between 16 and 256.
NAME
A string containing the name of the device.
IDL Reference Guide Graphics System Variables
ORIGIN
Atwo-element integer arraycontainingthecurrent pan/scroll offset. An offset of (0, 0) is
normal. Positiveoffsetsshift thedisplaymemorytotheright and upwards. Thiseld has
relevance only with devices with hardware pan and scroll abilities.
TABLE_SIZE
The number of color table indices. Devices without color tables have this eld set to 0.
UNIT
The logical number of the le open for output by the current graphics device. This eld
only has meaning for devices that write to a le if the le is accessible to the user from
IDL, and is 0 if no le is open.
For example, thePostScript driver llsthiseld with theunit number of theleopen for
PostScript output. In thecaseof Tektronix output to ale, !D.UNIT may beset to either
+ or - the logical unit number.
Bit Value Function
0 1 Device has scalable pixel size (e.g., PostScript).
1 2 Device can output text at an arbitrary angle using hardware.
2 4 Device can control line thickness with hardware.
3 8 Device can display images.
4 16 Device supports color.
5 32 Device supports polygon lling with hardware.
6 64 Device hardware characters are monospace.
7 128 Device can read pixels (i.e., it supports TVRD).
8 256 Device supports windows.
9 512 Device prints black on a white background (e.g., printers are plotters).
10 1024 Device hasno hardware characters.
11 2048 Device does line-ll style polygon lling in hardware.
12 4096 Device will apply Hershey-style embedded formatting commands to device fonts.
13 8192 Device is a pen plotter.
14 16384 Device can transfer 16-bit pixels.
15 32768 Device supports Kanji characters.
16 65536 Device supports widgets.
17 131072 Device has Z-buffer.
Table 3-1: !D.FLAGS Bit Denitions
WINDOW
The index of the currently open window. This eld is set to -1 if no window is currently
open. This eld is used only with devices that support windows.
X_CH_SIZE, Y_CH_SIZE
Thewidthandheight of therectanglethat enclosestheaverage character in thecurrent
font, in device units (usually pixels).
Thesevaluesdescribethesizeof therectanglethat containstheaverage character in the
current font. (It is not important what the average character is; it is used only to
calculateascalingfactor that will beapplied to all of thecharactersin thefont.) Therst
element species the width of the rectangle in device units (usually pixels), and the
second element species the height.
For vector andTrueTypefonts, theheight of theaverage character isdeterminedbythe
width of the rectangle. The aspect ratio of the average character remains xed; the
character isscaled so that itswidth isthevalueof X_CH_SIZE. Theresultingscalefactor
isthen applied toall of thecharactersin thefont. Theamount of spacingbetween linesis
determined explicitly by the value of Y_CH_SIZE.
For device fonts, the character size is xed. When the device font system is in use, the
value of X_CH_SIZE is silently ignored, and only the Y_CH_SIZE value is used.
X_PX_CM, Y_PX_CM
The approximate number of pixels per centimeter in the X and Y directions.
X_SIZE, Y_SIZE
The total size of the display or window in the X and Y directions, in device units.
X_VSIZE, Y_VSIZE
Thesizeof thevisibleareaof thedisplayor window. Thisareacanbesmaller thanthetotal
size elds.
ZOOM
Thiseldcontainsthecurrent XandYzoomfactorsfor thedisplayor window. Thiseld
hasrelevanceonly with devicesequipped with hardwarezoom. Azoomfactor of [ 1, 1] is
normal.
!ORDER System Variable
Controls the direction of image transfers when using the TV, TVSCL, and TVRD
procedures. If !ORDERis0, imagesaretransferred frombottomto top, i.e. therowwith
a0subscript iswritten on thebottom. Setting!ORDERto1, transfersimagesfromtopto
bottom.
!P System Variable
The main plotting system variable structure. All elds, except !P.MULTI, have a directly
corresponding keyword parameter in the plot procedures: PLOT, OPLOT, CONTOUR,
and SURFACE. Fields, in alphabetical order, are:
BACKGROUND
The background color index. When erasing the screen or page, all pixels are set to this
color. The default value is 0. Not all devices support this feature.
CHANNEL
The default source or destination channel. This eld has meaning only on graphics
devices that contain multiple display channels, and is device dependent. It may contain
either a channel mask or index.
CHARSIZE
Theoverall character sizeof all annotationwhenHersheyfontsareselected. Thiseldhas
no meaning when hardware (i.e. PostScript) fonts are selected. 1.0 is normal size.
CHARTHICK
An integer specifying the thickness of the lines used to draw the characters when using
the vector drawn fonts. This eld has no effect on the appearance of characters drawn
with the hardware fonts. Normal thickness is 1.
CLIP
The device coordinates of the clipping window, a 6-element vector of the form [ (x
0
, y
0
,
z
0
), (x
1
, y
1
, z
1
)] , specifyingtwooppositecornersof thevolumetobedisplayed. In thecase
of two-dimensional displays, the Z coordinates can be omitted. Normally, the clipping
window coordinates are implicitly set by PLOT, CONTOUR, SHADE_SURF, and
SURFACE to correspond to the plot window. You may also manually set !P.CLIP if you
want tospecifyadifferent rectangular clippingwindowor if theclippingcoordinateshave
not yet been set in the current IDL session.
COLOR
The default color index.
FONT
An integer that species the graphics text font system to use. Set FONT equal to -1 to
selectstheHershey character fonts, which aredrawn usingvectors. Set FONT equal to 0
(zero) to select the device font of the output device. Set FONT equal to 1 (one) to select
theTrueTypefont system. SeeFonts on page65for acompletedescription of IDLsfont
systems.
LINESTYLE
The default style of the lines used to connect points. A line style index of 0 yields a solid
line. See Table7-1, IDL Linestyles, on page103 for a description of the linestyles.
MULTI
!P.MULTI allowsmakingmultipleplotsonapageor screen. It isa5-element integer array
dened as follows:
!P.MULTI[ 0] containsthenumber of plotsremainingon thepage. If !P.MULTI[ 0] isless
than or equal to0, thepageiscleared, thenext plot isplacedin theupper left handcorner,
and !P.MULTI[ 0] is reset to the number of plots per page.
Setting!P.MULTI[ 0] toavaluegreater than zerocan beused tomanually set theplotting
area to a specic row and column. For example, to plot in the lower left corner of a
window of two rows and two columns, set !P.MULTI as follows:
!P.MULTI=[2,2,2]
PLOT, X, Y
!P.MULTI[ 1] isthenumber of plot columnsper page. If thisvalueislessthan or equal to
0, one is assumed. If more than two plots are ganged in either the X or Y direction, the
character size is halved.
!P.MULTI[ 2] isthenumber of rowsof plotsper page. If thisvalueislessthan or equal to
0, one is assumed.
!P.MULTI[ 3] contains the number of plots stacked in the Z dimension.
!P.MULTI[ 4] is0tomakeplotsfromleft toright (column major), andtoptobottom, and
is 1 to make plots from top to bottom, left to right (row major).
Note If !P.MULTI[ 0] iszero, an erasewill occur beforethecurrent plot isdisplayed(unless
the/NOERASEkeywordisset). Thisistruenomatter whether !P.POSITIONand/or
!P.REGION are set.
Example To gang two plots across the page:
!P.MULTI = [0, 2, 0, 0, 0]
PLOT, X0, Y0 Make left plot.
PLOT, X1, Y1 Right plot.
To gang two plots vertically:
!P.MULTI = [0, 0, 2, 0, 0]
PLOT, X0, Y0 Make top plot.
PLOT, X1, Y1 Bottom plot.
To make four plots per page, two across and two up and down:
!P.MULTI = [0, 2, 2, 0, 0]
and then call plot four times.
To reset !P.MULTI back to the normal one plot per page:
!P.MULTI = 0
NOCLIP
Aeldwhich, if set, inhibitstheclippingof thegraphicvectorsandvector-drawn text. By
default, most routines clip to the plotting window, with the exception of PLOTS and
XYOUTS. !P.CLIP contains the clipping rectangle.
NOERASE
Set this eld to a non-zero value to inhibit erasing the screen before plotting.
NSUM
The number of adjacent points to average to obtain a plotted point.
POSITION
Species the normalized coordinates of the rectangular plot window. This is a four
element oatingpoint vector (x
0
, y
0
, x
1
, y
1
), where(x
0
, y
0
) istheorigin, and(x
1
, y
1
) isthe
upper right corner.
!P.POSITIONdeterminestheplottingwindowif x
0
doesnot equal x
1
, andthePOSITION
keyword is not present. If set, it overrides the effect of the MARGIN and !P.MULTI
variables and keywords.
Note If !P.POSITION (or the POSITION keyword) or !P.REGION is set, all but the rst
element of !P.MULTI are ignored.
PSYM
The default plotting symbol index. Each point drawn by PLOT, PLOTS, and OPLOT is
marked with asymbol if thiseld isnon-zero. Thepossiblesymbolsaregiven in Table7-
2, Values for the PSYM Keyword, on page105.
REGION
Afour element vector that speciesthenormalizedcoordinatesof therectangleenclosing
the plot region, which includes the plot data window and its surrounding annotation
area. It is in the same form as !P.POSITION, (x
0
, y
0
, x
1
, y
1
), where (x
0
, y
0
) is the origin,
and (x
1
, y
1
) is the upper right corner. It is ignored if !P.REGION[ 0] is equal to
!P.REGION[ 2] .
Note !P.POSITION (or the POSITION keyword) takes precedence over !P.REGION.
SUBTITLE
The plot subtitle, placed under the X axis label.
T
Contains the homogeneous 4 x 4 transformation matrix.
T3D
Enables the three-dimensional to two-dimensional transformation contained in the
homogeneous 4 by 4 matrix !P.T. Note that if T3D is set, !P.T must contain a valid
transformation matrix.
THICK
The thickness of the lines connecting points. 1.0 is normal.
TITLE
The main plot title.
TICKLEN
Thelength of thetick marks, expressedasafraction of theplot size(from0.0to1.0). The
default is 0.02. A value of 0.5 makes a grid. Negative values make the tick marks point
outward.
!X, !Y, !Z System Variables
Thesystemvariables!X, !Y, and!Z, arestructuresof typeAXIS, that affect theappearance
and scaling of the three axes. The elds for !X, !Y, and !Z have identical elds with
identical meaningsand usage. In addition, almost all eldshavecorrespondingkeyword
parameters, with identical function, but with temporary effect. For example, to suppress
the minor tick marks on the X axis using the !X system variable, you could use the
command:
!X.MINOR = -1
To suppress the tick marks for just one call to plot, you could use the command:
PLOT, X, Y, XMINOR = -1
The name of the keyword parameter is simply the name of the system variable eld,
prexed with the letter X, Y, or Z.
The elds for these system variables, in alphabetical order are:
CHARSIZE
The size of the characters used to annotate the axis and its title when Hershey fonts are
selected. This eld has no meaning when hardware (i.e. PostScript) fonts are selected.
This eld is a scale factor applied to the global scale factor. For example, setting
!P.CHARSIZEto 2.0, and !X.CHARSIZEto 0.5resultsin acharacter sizeof 1.0for theX
axis.
CRANGE
The output axis range. Setting this variable has no effect; set ![ XYZ] .RANGE to change
the range. ![ XYZ] .CRANGE[ 0] ) always contains the minimum axis value, and
![ XYZ] .CRANGE[ 1] contains the maximum axis value of the last plot before extending
the axes.
Note If theaxisislogarithmic, theCRANGEeldreportsthelog(base10) of theminimum
and maximum axis values.
Example
a = INDGEN(10) Create a 10-element array.
PLOT, a Plot the straight line.
PRINT, !X.CRANGE Print the minimum and maxi-
mum axis values.
IDL prints:
0.00000 10.0000
PLOT, a, /XLOG Plot a with logarithmic scaling
on the X axis.
PRINT, !X.CRANGE Print the minimum and maxi-
mum axis values.
IDL prints,
-12.0000 2.00000 The axis is scaled from10
-12
to
10
2
GRIDSTYLE
The index of the linestyle to be used for tick marks and grids. See Table7-1, IDL
Linestyles, on page103 for a description of the linestyles
MARGIN
A2-element array specifyingthemargin on theleft (bottom) and right (top) sidesof the
plot window, in units of character size. The plot window is the rectangular area that
contains the plot data, i.e. the area enclosed by the axes.
The default values for !X.MARGIN are [ 10, 3] yielding a 10-character wide left margin
and a 3-character wide right margin. The values for !Y.MARGIN are [ 4, 2] , for a 4-
character high bottom margin and a 2-character high top margin. While specifying
!Z.MARGIN will not cause an error, Z margins are currently ignored.
When calculatingthesizeand position of theplot window, IDL rst determinestheplot
region, theareaenclosingthewindowplustheaxisannotationandtitles. It thensubtracts
the appropriate margin from each side, obtaining the window.
Setting!P.POSITION, or specicationof thePOSITIONparameter overridestheeffect of
this eld.
MINOR
The number of minor tick marks. If !X.MINOR is 0, the default, the number of minor
ticks is automatically determined from the tick mark increment. You can force a given
number of minor ticksbysettingthiseld tothedesired number. Tosuppressminor tick
marks, set !X.MINOR to -1.
OMARGIN
A 2-element array specifying the outer margin on the left (bottom) and right (top)
sidesof amulti-plot window, in unitsof character size. Amulti-plot windowiscreatedby
setting the !P.MULTI system variable eld. OMARGIN controls the amount of space
around theentireplot area, includingindividual plot marginsset with !X.MARGIN and
!Y.MARGIN. The default values for !X.OMARGIN and !Y.OMARGIN are [ 0, 0] .
When calculating the size and position of the individual plots, IDL rst determines the
plot region, the area enclosing the window plus the axis annotation and titles. It then
subtracts the appropriate margin from each side, obtaining the window.
Setting!P.POSITION, or specicationof thePOSITIONparameter overridestheeffect of
this eld.
RANGE
Theinput axisrange, a2-element vector. Therst element istheaxisminimum, and the
second is the maximum. Set this eld, or use the corresponding keyword parameter, to
specify the data range to plot. If axis end point rounding is selected (see STYLE above),
thenal axisrangemay not beequal to thisinput range. Theeld !X.CRANGEcontains
theaxisrangeusedfor theplot beforeextendingtheaxes. Set bothelementsequal to0for
automatic axis ranges:
!X.RANGE = 0
Example To force the X axis to run from 5.5 to 8.3:
!X.RANGE = [5.5, 8.3]
PLOT, X, Y
Alternatively, by using keywords:
PLOT, X, Y, XRANGE=[5.5, 8.3]
Note that even though the range was set to (5.5, 8.3), the resulting plot has a range
of (5.5, 8.5), because axis rounding is the default.
REGION
Containsthenormalized coordinatesof theregion. Thiseld issimilar to WINDOW, in
that it isset bythegraphicsproceduresand isa2-element oatingpoint array. Tochange
the default plotting region, set !P.REGION.
S
Thescalingfactorsfor convertingbetween datacoordinatesand normalized coordinates
(a 2-element array). The formula for conversion from data (X
d
) to normalized (X
n
)
coordinates isX
n
= S
1
X
d
+ S
0
If logarithmic scaling is in effect, substitute log
10
(X
d
) for X
d
.
The CONVERT_COORD function can be used to convert between coordinate systems.
Theuser shouldsaveandrestoretheseeldswhen switchingbetween windowsor devices
with different sizes and/or scaling.
STYLE
The style of the axis encoded as bits in a longword. The axis style can be set to exact,
extended, none, or no box using this eld. See Table 3-2 for details.
Notethat thissystemvariableeld isset bitwise, so multipleeffectscan beset by adding
valuestogether. For example, tomakeanXaxisthat isbothexact (value1) andsuppresses
the box style (setting 8), set the !X.STYLE system variable to 1+8, or 9.
Example To set the Y axis style to exact using the !Y system variable:
!Y.STYLE = 1
or by using a keyword parameter:
PLOT, X, Y, YSTYLE = 1
THICK
The thickness of the axis line. 1.0 is normal.
TICKFORMAT
Set thiseld to aformat stringor astringcontainingthenameof afunction that returns
a string to be used to format the axis tick mark labels.
See the [ XYZ] TICKFORMAT keyword description on page 107 for more information.
TICKLEN
The lengths of tick marks (expressed in normal coordinates) for the individual axes.
TICKNAME
Theannotation for each tick. Astringarrayof up to30elements. Settingelementsof this
arrayallowsdirect specication of thetick label. If thiselement containsanull string, the
default value, IDL annotates the thick with its numeric value. Setting the element to a 1-
blank string suppresses the tick annotation.
Example To produce a plot with an abscissa labeled with the days of the week:
!X.TICKNAME = ['SUN', 'MON', 'TUE', 'WED', $
'THU', 'FRI', 'SAT'] Set up X axis tick labels.
!X.TICKS = 6 Use six tick intervals, requiring
seven tick labels.
Bit Value Function
0 1 Exact. By default, the end points of the axis are rounded in order to
obtain even tick increments. Setting this bit inhibits rounding, mak-
ing the axis t the data range exactly.
1 2 Extend. If this bit is set, the axes are extended by 5% in each direc-
tion, leaving a border around the data.
2 4 None. If this bit is set, the axis and its annotation are not drawn.
3 8 No box. Normally, PLOT and CONTOURdrawabox-styleaxiswith
the data window surrounded by axes.
4 16 Inhibits setting the Y axis minimum value to zero when the data are
all greater than 0. The keyword YNOZERO sets this bit temporarily.
Table 3-2: Axis Style Bit Values
PLOT, Y Plot the data, this assumes that
Y contains 7 elements.
The same plot can be produced, using keyword parameters, with:
PLOT, Y, XTICKN = ['SUN', 'MON', 'TUE', 'WED',$
'THU', 'FRI', 'SAT'], XTICKS = 6
Set elds, as above, only tem-
porarily.
TICKS
Thenumber of major tick intervalstodrawfor theaxis. If !X.TICKSisset to0, thedefault,
IDLwill select fromthreetosixtick intervals. Settingthiseldton, wheren> 1, produces
exactly n tick intervals, and n+1 tick marks. Setting this eld equal to 1 suppresses tick
marks.
TICKV
An array of up to 30 elements containing the data values for each tick mark. You can
directlyspecifythelocation of each tick bysetting!X.TICKStothenumber of tick marks
(the number of intervals plus 1) and storing the data values of the tick marks in
!X.TICKV. If, as is true by default, !X.TICKV[ 0] is equal to !X.TICKV[ 1] , IDL
automatically determines the value of the tick marks.
TITLE
A string containing the axis title.
TYPE
The type of axis, 0 for linear, 1 for logarithmic.
WINDOW
Contains the normalized coordinates of the axis end points, the plot data window. This
eld isset by PLOT, CONTOUR, SHADE_SURF, and SURFACE. Changingitsvaluehas
no effect. A 2-element oating point array. To change the default plotting window, set
!P.POSITION. Thekeywordparameter POSITIONsetstheplot datawindowonaper call
basis.
57
Chapter 4
Special Characters
WithintheIDLenvironment, anumber of charactershavespecial meanings. Table4-1on
page 58 lists characters with special interpretations and states their functions in IDL.
These characters are discussed further in the descriptions below.
58 Chapter 4: Special Characters
IDL Reference Guide
Exclamation Point (!)
The exclamation point is the rst character of names of IDL system-dened variables.
System variables are predened scalar variables of a xed type. Their purpose is to
overridedefaultsfor systemprocedures, to return statusinformation, and to control the
action of IDL.
Apostrophe (')
The apostrophe delimits string literals and indicates part of an octal or hex constant.
UNIX VMS Windows Macintosh Function
! ! ! ! First character of system variable
names
' ' ' ' Delimit string constants or indicate
part of octal or hex constant
; ; ; ; Begin comment eld
$ $ $ $ Continue current command on the
next line, or issue operating system
command if entered on a line by
itself.
" " " " Delimit string constants or precede
octal constants
. . . . Indicateconstant isoatingpoint or
start executive command
& & & & Separatemultiplestatementson one
line
: : : : End label identiers
* * * * Array subscript range, or pointer
dereference if in front of a valid
pointer
@ @ @ @ Include le/Execute IDL batch le
? ? ? ? Online help
Control-C Control-C Control-Break Command-. Interrupt
Control-D Control-Z Alt-F4 Command-Q Exit
Control-\ Control-Y Abort
Table 4-1: Special Characters
Chapter 4: Special Characters 59
IDL Reference Guide
Semicolon (;)
The semicolon is the rst character of the optional comment eld of an IDL statement.
All text onalinefollowingasemicolonisignoredbyIDL. Alinecanconsist of acomment
only or both a valid statement and a comment.
Dollar Sign ($)
The dollar sign at the end of a line indicates that the current statement is continued on
the following line. The dollar sign character can appear anywhere a space is legal except
within astringconstant or between afunction nameand therst open parenthesis. Any
number of continuation lines are allowed.
When the$character isentered astherst character after theIDL prompt, therest of the
line is sent to the operating system as a command. If $ is the only character present, an
interactivesubprocessisstarted. Under Unix andVMS, IDLexecution suspendsuntil the
new shell process terminates. Note that in IDL for Macintosh, there must be no space
between the $ character and the full path name of the application being started.
Quotation Mark (")
The quotation mark precedes octal numbers, which are always integers, and delimits
string constants. Example: "100B is a byte constant equal to 64 base 10 and "Dont
drink the water" is a string constant.
Period (.)
The period or decimal point indicates in a numeric constant that the number is of
oating-point or double-precisiontype. Example: 1.0isaoating-point number. Also, in
response to the IDL prompt, the period begins an executive command. For example,
.run myfile
causes IDL to compile the lemyle.pro. If myle.pro contains a main program, the
program also will be executed. In addition, the period precedes the name of a tag when
referringto aeld within astructure. For example, areferenceto atagcalled NAMEin a
structure stored in the variable A is A.NAME.
Ampersand (&)
The ampersand separates multiple statements on one line. Statements can be combined
until the maximum line length is reached. For example, the following line contains two
statements:
I = 1 & PRINT, 'value:', I
Colon (:)
The colon ends label identiers. Labels can only be referenced by GOTO and
ON_ERROR statements. The following line contains a statement with the label LOOP1.
LOOP1: X = 2.5
IDL Reference Guide
Thecolon also separatesthestartingand endingsubscriptsin subscript rangespeciers.
For example, A(3:6) designates elements three to six of the variable A.
Asterisk (*)
The asterisk represents one of the following, depending on context:
1. Multiplication (3 * 3).
2. An ending subscript range equal to the size of the dimension. For example, A[3:*]
represents all elements of the vector A from A[ 3] to the last element, while B[ *, 3]
represents all elements of row four of matrix B.
3. A pointer dereference operation. For example, if ptr is a valid pointer (created via the
PTR_NEW function), then *ptr is the value held by the heap variable that ptr points
to. For more information on IDL pointers, see Pointers on page 229 of Building IDL
Applications.
At Sign (@)
The at sign is used both as an include character and to signal batch execution.
@ as an Include Character
Theat sign at thebeginningof alinecausestheIDLcompiler tosubstitutethecontents
of thelewhosenameappearsafter the@for theline. If thefull pathnameisnot specied
after the@symbol, IDLsearchesthecurrent directoryandalist of knownlocationswhere
procedures are kept.
Unix: IDLsearchesfor theleinthelist of directories(asestablishedbytheenvironment
variable IDL_PATH) stored in the system variable !PATH.
VMS:IDLsearchesthelist of directories(but not text libraries) establishedbythelogical
name IDL_PATH and stored in the system variable !PATH for the le.
Windows:IDLsearchesfor theleinthelist of directoriesstoredinthesystemvariable
!PATH (specied in the Preferences dialog of the File menu).
Macintosh:IDLsearchesfor theleinthelist of directoriesstoredinthesystemvariable
!PATH (specied in the Search Path dialog of the Edit menu).
For example, the line
@doit
when included in ale, causestheledoit.protobecompiled in itsplace. (Thesufx .pro
is the default for IDL program les.) When the end of the le is reached, compilation
resumes at the line after the @.
@ to Signal Batch Processing
WhenIDLisrunningininteractivemode, alinebeginningwiththecharacter @isentered
in response to the IDL prompt and the le is opened for batch input. See Batch
Execution on page 32 of Using IDL for details.
Chapter 4: Special Characters 61
IDL Reference Guide
Question Mark (?)
Thequestion mark invokestheIDLon-linehelpfacilitywhen enteredat theIDLprompt
(Command Input Line). See IDLs Online Help System on page 242 of Using IDL for
more information.
Control-C / Control-Break / Command-.
This is the interrupt character, and depends on the operating system in use:
Unix: Typing the interrupt characterControl-C (Unix and VMS), Control-Break
(Windows), or Command-. (Command-period) (Macintosh)generates an IDL
keyboard interrupt. See Interrupting Program Execution on page 30 of Using IDL for
more information.
Under VMS, Control-C is always the interrupt character. However, under UNIX, the
interrupt character can bechanged by theuser outsideof IDL. Thisisrarely done. So for
the purposes of this manual, we assume the default convention.
Control-D / Control-Z / Alt-F4 / Command-Q
This is the exit character, and depends on the operating system in use:
Unix: Under UNIX, enteringControl-Dastherst character causesIDL to exit back to
theoperatingsystem. TheEXIT procedurehasthesamefunction. If Control-Disnot the
rst character, it simplyendstheinput lineasif areturn had been entered. Notethat you
can normally useControl-Z to suspend IDL and return you to theshell processwithout
exiting IDL. After completing any shell commands, typefg to return IDL to the fore-
ground. AlthoughtheUNIXsuspendcharacter canbechangedbytheuser outsideof IDL,
this is rarely done. For the purposes of this manual, we assume the default convention.
VMS: Under VMS, entering Control-Z as the rst character causes IDL to exit back to
theoperatingsystem. TheEXIT procedurehasthesamefunction. If Control-Z isnot the
rst character, it ends the input line as if a return had been entered. This input line is
executed, then IDL exits.
Windows: Under Windows, entering Alt-F4 at any point causes IDL to exit back to
Windows. The EXIT procedure has the same function.
Macintosh:Control-Z hasnospecial meaningon theMacintosh. Enter Command-Q
to exit IDL.
Control-\ / Control-Y
This is the abort character, and depends on the operating system in use:
Unix: Control-\ is normally the UNIX quit character. Typing the quit character causes
IDL tobekilled instantly (just likeany UNIXprocess). It isbest toavoid thistypeof exit.
Although theUNIXquit character can bechangedbytheuser, thisisrarelydone. For the
purposes of this manual, we assume the default convention. Control-\ has no special
meaning under VMS, Windows, or the Macintosh.
IDL Reference Guide
VMS:Under VMS, typingControl-Y, thequit character, causesIDLtobekilledinstantly
(just likeanyVMSprocess). It isbest toavoidthistypeof exit. SeeAbortingIDL onpage
30of UsingIDL. If youenter theDCLcommandCONTINUEimmediatelyafter aborting
the IDL session, VMS will resume the session as if you had never aborted it. However, if
you execute any command that causes a program to run, your IDL session will be lost.
Control-Y has no special meaning under UNIX, Windows, or the Macintosh.
63
Chapter 5
Reserved Words
Variables, user-written procedures, and user-written functionsshould not havethesame
namesasIDLfunctionsor procedures. Re-usingnamesof IDLroutinescanleadtosyntax
errors or to hiding variables. In addition, certain words representing IDL language
constructs are strictly forbiddenusing any of thesereserved wordsas a variable,
procedure, or function name will cause an immediate syntax error. Table 5-1 lists all of
the reserved words in IDL.
64 Chapter 5: Reserved Words
IDL Reference Guide
AND BEGIN CASE COMMON DO
ELSE END ENDCASE ENDELSE ENDFOR
ENDIF ENDREP ENDWHILE EQ FOR
FUNCTION GE GOTO GT IF
INHERITS LE LT MOD NE
NOT OF ON_IOERROR OR PRO
REPEAT THEN UNTIL WHILE XOR
Table 5-1: IDL Reserved Words
65
Chapter 6
Fonts
IDL uses three font systems for writing characters on the graphics device: Hershey
(vector) fonts, TrueType (outline) fonts, and device (hardware) fonts. This chapter
describes each of the three types of fonts, discusses when to use each type, and explains
how to use fonts when creating graphical output in IDL.
Vector-drawn fonts, alsoreferred toasHersheyfonts, aredrawn aslines. They aredevice-
independent (within the limits of device resolution). All vector fonts included with IDL
are guaranteed to be available in any IDL installation. See About the Vector Fonts on
page 66 for additional details.
TrueType fonts, also referred to here asoutlinefonts, are drawn as character outlines,
which arelled when displayed. They arelargely device-independent, but do havesome
device-dependent characteristics. Four TrueType font families are included with IDL;
these fonts should display in a similar way on any IDL platform. TrueType font support
for IDL Object Graphics was introduced in IDL version 5.0 and support in IDL Direct
Graphicswasintroduced in IDL version 5.1. SeeAbout theTrueTypeFonts on page68
for additional details.
66 Chapter 6: Fonts
Fonts in IDL Direct vs. Object Graphics IDL Reference Guide
Device fonts, also referred to ashardwarefonts, rely on character-display hardware or
software built in to a specic display device. Device fonts, necessarily, are device-
dependent and differ fromplatformtoplatformand displaydevicetodisplaydevice. See
About Device Fonts on page 72 for additional details.
Fonts in IDL Direct vs. Object Graphics
Thisvolumedealsalmost exclusively with IDL Direct Graphics. However, thevector and
TrueType font systems described here are are also available in the IDL Object Graphics
system, described in Object Graphics.
IDL Direct Graphics
When generatingcharactersfor Direct Graphicsplots, IDL usesthefont systemspecied
by the value of the system variable !P.FONT. The normal default for this variable is -1,
which species that the built-in, vector-drawn (Hershey) fonts should be used. Setting
!P.FONT equal to 1speciesthat TrueTypefontsshould beused. Setting!P.FONT equal
to zero species that fonts supplied by the graphics device should be used.
Thesettingof theIDLsystemvariable!P.FONT can beoverridden for asingleIDLDirect
Graphicsroutine(AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE, or XYOUTS) by
setting the FONT keyword equal to -1, 0, or 1.
Once a font system has been selected, an individual font can be chosen either via a
formattingcommand embedded in atext stringasdescribed in Embedded Formatting
Commands on page 79, or by setting the value of the FONT keyword to the DEVICE
routine (see FONT on page 124).
IDL Object Graphics
IDL Object Graphics can use the vector and TrueType font systems. SeeObject Graphics
for moreinformation on usingfontswith Object Graphics. Any TrueTypefontsyou add
to your IDL installation asdescribed in About theTrueTypeFonts on page68will also
be avialable to the Object Graphics system.
About the Vector Fonts
The vector fonts used by IDL were digitized by Dr. A.V. Hershey of the Naval Weapons
Laboratory. Charactersin thevector fontsarestored asequations, and can bescaled and
rotated in threedimensions. They aredrawn aslineson thecurrent graphicsdevice, and
aredisplayedquicklyandefcientlybyIDL. Thevector fontsarebuilt intoIDLitself, and
are always available.
Chapter 6: Fonts 67
IDL Reference Guide About the Vector Fonts
All the available fonts are illustrated in Vector Font Samples on page 89. The default
vector font (Font 3, Simplex Roman) is in effect if no font changes have been made.
Using Vector Fonts
To use the vector font system with IDL Direct Graphics, either set the value of the IDL
system variable !P.FONT equal to -1 (negative one), or set the FONT keyword of one of
theDirect Graphicsroutinesequal to-1. Thevector font systemisthedefault font system
for IDL.
Oncethevector font systemisselected, usean embedded formattingcommand to select
avector font (or fonts) for eachstring. (See EmbeddedFormattingCommands onpage
79for detailsonembeddedformattingcommands.) Thefont selectedsticks fromstring
tostring; that is, if youchangefontsinonestring, futurestringswill usethenewfont until
you change it again or exit IDL.
For example, to usetheDuplex Roman vector font for thetitleof aplot, you would usea
command that looks like this:
PLOT, mydata, TITLE=!5Title of my plot
Consult Object Graphicsfor details on using the vector font system with IDL Object
Graphics.
Specifying Font Size
To specify the size of a vector font, use the SET_CHARACTER_SIZE keyword to the
DEVICEprocedure. TheSET_CHARACTER_SIZEkeyword takesatwo-element vector
asitsargument. Therst element speciesthewidthof theaverage character inthefont
(in pixels) and calculatesascalingfactor that determinestheheight of thecharacters. (It
isnot important what theaverage character is; it isusedonlytocalculateascalingfactor
that will beapplied to all of thecharactersin thefont.) Thesecond element of thevector
species the number of pixels between baselines of lines of text.
The ratio of the average characters height to its width differs from font to font, so
specifying the same value [ x, y] to the SET_CHARACTER_SIZE keyword may produce
characters of different sizes in different fonts.
Note Whiletherst element of thevector specied toSET_CHARACTER_SIZEistechni-
cally awidth, it isimportant to notethat thewidth valuehasno effect on thewidths
of individual characters in the font. The width value is used only to calculate the
appropriate scaling factor for the font.
For example, thefollowingIDLcommandsdisplaytheword HelloThere on thescreen,
in letters based on an average character that is 70 pixels wide, with 90 pixels between
lines:
DEVICE, SET_CHARACTER_SIZE=[70,90]
XYOUTS, 0.1, 0.5, 'Hello!CThere'
You can also usetheCHARSIZEkeyword to thegraphicsroutines(seeCHARSIZE on
page100) or theCHARSIZEeld of the!PSystemVariable(see !PSystemVariable on
68 Chapter 6: Fonts
About the TrueType Fonts IDL Reference Guide
page49) tochangethesizeof characterstoamultipleof thesizeof thecurrently-selected
character size. For example, to createcharactersonehalf thesizeof thecurrent character
size, you could use the following command:
XYOUTS, 0.1, 0.5, 'Hello!CThere', CHARSIZE=0.5
Note ChangingtheCHARSIZEadjustsboththecharacter sizeandthespacebetweenlines.
ISO Latin 1 Encoding
Thedefault font (Font 3, Simplex Roman) followstheISOLatin 1Encodingschemeand
containsmany international characters. Theillustration of thisfont (Figure6-4on page
90) can be used to nd the octal codes for the special characters.
For example, suppose you want to display some text with an Angstrom symbol in it.
Lookingat thechart of font 3, weseethat theAngstromsymbol hasoctal code305. Non-
printable characters can be represented in IDL using octal or hexadecimal notation and
the STRING function (see Representing Non-Printable Characters on page 18 of
Building IDL Applications for details). So the Angstrom can be printed by inserting a
STRING("305B) character in our text string as follows:
XYOUTS,.1, .5, 'Here is an Angstrom symbol: ' + STRING("305B), $
/NORM, CHARSIZE=3
Customizing the Vector Fonts
The EFONT procedure is a widget application that allows you to edit the Hershey fonts
andsavetheresults. Usethisroutinetoadd special charactersor completelynew, custom
fonts to the Hershey fonts.
About the TrueType Fonts
Beginningwith version 5.2, veTrueTypefont familiesareincluded with IDL. Thefonts
included are:
Font Family Italic Bold BoldItalic
Courier Courier Italic Courier Bold Courier Bold Italic
Helvetica Helvetica Italic Helvetica Bold Helvetica Bold Italic
Monospace Symbol
Times Times Italic Times Bold Times Bold Italic
Chapter 6: Fonts 69
IDL Reference Guide About the TrueType Fonts
When TrueType fonts are rendered on an IDL graphics device or destination object, the
font outlines are rst scaled to the proper size. After scaling, IDL converts the character
outlineinformation to aset of polygonsusingatriangulation algorithm. When text in a
TrueTypefont isdisplayed, IDL isactually drawingaset of polygonscalculated fromthe
font information. This process has two side effects:
1. Computation time is used to triangulate and create the polgyons. This means that
you may noticeaslight delay therst timeyou usetext in aparticular font and size.
Oncethepolygonshavebeen created, theinformation iscached by IDL and thereis
no need to re-triangulate each time text is displayed. Subsequent uses of the same
font and size happen quickly.
2. BecausetheTrueTypefont outlinesareconvertedintopolygons, youmaynoticesome
chunkinessinthedisplayedcharacters, especiallyat small point sizes. Thesmoothness
of the characters will vary with the quality of the TrueType font you are using, the
point size, and the general smoothness of the font outlines.
Using TrueType Fonts
TousetheTrueTypefont systemwithIDLDirect Graphics, either set thevalueof theIDL
system variable !P.FONT equal to 1 (one), or set the FONT keyword to on one of the
Direct Graphics routines equal to 1.
Once the TrueType font system is selected, use the SET_FONT keyword to the DEVICE
routine to select the font to use. The value of the SET_FONT keyword is afont name
string. The font name is the name by which IDL knows the font; the names of the
TrueType fonts included with IDL are listed in Table 6-1. Finally, specify the TT_FONT
keyword in the call to the DEVICE procedure. For example, to use Helvetica Bold Italic,
use the following statement:
DEVICE, SET_FONT='Helvetica Bold Italic', /TT_FONT
To use Times Roman Regular:
DEVICE, SET_FONT='Times', /TT_FONT
IDLs default TrueType font is 12 point Helvetica regular.
Specifying Font Size
To specify the size of a TrueType font, use the SET_CHARACTER_SIZE keyword to the
DEVICEprocedure. TheSET_CHARACTER_SIZEkeyword takesatwo-element vector
asitsargument. Therst element speciesthewidthof theaverage character inthefont
(in pixels) and calculatesascalingfactor that determinestheheight of thecharacters. (It
isnot important what theaverage character is; it isusedonlytocalculateascalingfactor
that will beapplied to all of thecharactersin thefont.) Thesecond element of thevector
species the number of pixels between baselines of lines of text.
Symbol
Table 6-1: TrueType font names.
70 Chapter 6: Fonts
About the TrueType Fonts IDL Reference Guide
The ratio of the average characters height to its width differs from font to font, so
specifying the same value [ x, y] to the SET_CHARACTER_SIZE keyword may produce
characters of different sizes in different fonts.
Note Whiletherst element of thevector specied toSET_CHARACTER_SIZEistechni-
cally awidth, it isimportant to notethat thewidth valuehasno effect on thewidths
of individual characters in the font. The width value is used only to calculate the
appropriate scaling factor for the font.
For example, thefollowingIDL commandsdisplaytheword HelloThere on thescreen
in HelveticaBold, in lettersbasedon an average character that is70pixelswide, with90
pixels between lines:
DEVICE, FONT='Helvetica Bold', /TT_FONT, SET_CHARACTER_SIZE=[70,90]
XYOUTS, 0.1, 0.5, 'Hello!CThere'
You can also usetheCHARSIZEkeyword to thegraphicsroutines(seeCHARSIZE on
page100) or theCHARSIZEeld of the!PSystemVariable(see !PSystemVariable on
page49) tochangethesizeof characterstoamultipleof thesizeof thecurrently-selected
character size. For example, to createcharactersonehalf thesizeof thecurrent character
size, you could use the following command:
XYOUTS, 0.1, 0.5, 'Hello!CThere', CHARSIZE=0.5
Notethat changingtheCHARSIZEadjustsboth thecharacter sizeandthespacebetween
lines.
Using Embedded Formatting Commands
Embedded formatting commands allow you to position text and change fonts within a
singlelineof text. Asubset of theembeddedformattingcommandsavailablefor usewith
thevector fontsarealso availablewhen usingtheTrueTypefont system. See Embedded
Formatting Commands on page 79 for details on which in-line formatting commands
are available when using the TrueType font system.
IDL TrueType Font Resource Files
The TrueType font system relies on a resource le named ttfont.map, located in the
resource/fonts/tt subdirectory of the IDL directory. The format of the ttfont.map
le is:
FontName FileName DirectGraphicsScale ObjectGraphicsScale
where the elds in each row must be separated by white space (spaces and/or tabs). The
elds contain the following information
TheFontnameeld containsthenamethat would beused for theSET_FONT keywords
to the DEVICE routine.
TheFilenameeld contains the name of the TrueType font le. On Unix and VMS
platforms, IDL will search for the le specied in theFileNameeld in the current
Chapter 6: Fonts 71
IDL Reference Guide About the TrueType Fonts
directory (that is, in theresource/fonts/tt subdirectory of the IDL directory) if a
bare lename is provided, or it will look for the le in the location specied by the fully-
qualied le name if a complete path is provided. Because different platforms use
different path-specication syntax, werecommendthat you placeanyTrueTypefont les
youwishtoaddtothettfont.map leintheresource/fonts/tt subdirectoryof the
IDLdirectory. OnMacintoshandWindowsplatforms, thisentrymaybe'*', inwhichcase
thefont will beloadedfromtheoperatingsystemfont list, but that thefollowingtwoscale
entries will be honored.
TheDirectGraphicsScaleeld contains a correction factor that will be applied when
choosingascalefactor for theglyphsprior tobeingrenderedonaDirect Graphicsdevice.
If you want thetallest character in thefont to t exactly within thevertical dimension of
thedevicescurrent character size(asset viatheSET_CHARACTER_SIZEkeywordtothe
DEVICEprocedure), set thescalefactor equal to1.0. Changethescalefactor toasmaller
number to scale a smaller portion of the tallest character into the character size.
For example, suppose the tallest character in your font is . Setting the scale factor to
1.0 will scale this character to t the current character size, and then apply the same
scalingto all charactersin thefont. Asaresult, theletter M will ll only approximately
85% of the full height of the character size. To scale the font such that the height of the
M llsthevertical dimension of thecharacter size, you would includethevalue0.85in
the scale eld of thettfont.map le.
TheObjectGraphicsScaleeld contains contains a correction factor that will be applied
when choosingascalefactor for theglyphsprior to beingrendered on aDirect Graphics
device. (This eld works just like theDirectGraphicsScaleeld.) This scale factor should
be set to 1.0 if the maximum ascent among all glyphs within a given font is to t exactly
within the font size (as set via the SIZE property to the IDLgrFont object).
Adding Your Own Fonts
To add a your own font to the list of fonts known to IDL, use a text editor to edit the
ttfont.map le, adding theFontName, FileName, DirectGraphicsScale, and
ObjectGraphicsScaleelds for your font. You will need to restart IDL for the changes to
thettfont.map le to take effect. On Windows and Macintosh systems, you can use
fontsthat arenot mentioned in thettfont.map le, aslongasthey areinstalled in the
Fonts control panel or Font folder, as described below.
Caution If you choose to modify thettfont.map le, be sure to keep a backup copy of the
original le so you can restore the defaults if necessary. Note also that applications
that use text may appear different on different platforms if the scale entries in the
ttfont.map le have been altered.
Where IDL Searches for Fonts
The TrueType font les included with IDL are located in theresource/fonts/tt
subdirectoryof theIDL directory. When attemptingtoresolveafont name(specied via
the FONT keyword to the DEVICE procedure), IDL will look in thettfont.map le
rst. If it fails to nd the specied font le in thettfont.map le, it will search for the
font le in the following locations:
72 Chapter 6: Fonts
About Device Fonts IDL Reference Guide
Unix and VMS
No further search will be performed. If the specied font is not included in the
ttfont.map le, IDL will substitute Helvetica.
Microsoft Windows
If the specied font is not included in thettfont.map le, IDL will search the list of
fontsinstalledin thesystem(thefontsinstalledin theFont control panel). If thespecied
font is not found, IDL will substitute Helvetica.
Macintosh
If the specied font is not included in thettfont.map le, IDL will search the list of
fonts installed in the system (the fonts installed 1in the Fonts subfolder of the System
folder). If the specied font is not found, IDL will substitute Helvetica.
About Device Fonts
Device, or hardware, fontsarefontsthat areprovided directly by your systemshardware
or by software other than IDL. In past releases of IDL, we have used the term hardware
fonts extensively to discussthesetypesof fonts. Thisisbecausein theearly daysof IDL,
computer displays were either text-only terminals or dedicated graphics display devices
such asplottersor Tektronix graphicsterminals. Thesegraphicsdisplaysgenerally came
with a set of fonts built-in; when IDL asked the device to display characters in a built-in
font, it was making a request to the hardware to display those characters.
Ascomputer displayshavebecomemoresophisticated, theconcept of fontsprovided by
the hardware has expanded to include fonts provided by the computers operating
system, or by font-management software. For example, many computers now use font
management software like Adobe Type Manager to manage the fonts made available by
the operating system to all applications. We use the term device font to refer to a font
that is available to one of IDLs graphics devices from a sourceother than IDL itself. (In
this case, a graphics device can be either a Direct Graphics device as specied by the
DEVICE routine or an Object Graphics destination such as a window or a printer.)
Whiledevicefontsmayincludefontsonlyavailablebecauseaparticular pieceof hardware
knows how to draw characters in that font (a pen plotter is an example of a device that
may still have its own special fonts), in most cases device fonts are fonts supplied by the
operating system to any application that may want to use them.
A PostScript Font
Chapter 6: Fonts 73
IDL Reference Guide About Device Fonts
Which Device Fonts Are Available?
To determine which device fonts are available on your system and the exact font strings
to specify for each, usetheGET_FONTNAMESkeyword to theDEVICEprocedure. You
can also usean operatingsystemspecicmethod to determinewhich fontsareavailable:
Unix and VMS
On most systems, thexlsfonts utility displays a list of fonts available to the operating
system.
Microsoft Windows
Fontsavailableto thesystemaredisplayed in theFontscontrol panel. You may also have
other fontsavailableif you usefont-management softwaresuch asAdobeTypeManager.
Macintosh
Fonts available to the system are displayed in the Fonts folder in the System folder. You
may also have other fonts available if you use font-management software such as Adobe
Type Manager.
Using Device Fonts
To use the Device font system with IDL Direct Graphics, either set the value of the IDL
system variable !P.FONT equal to 0 (zero), or set the FONT keyword to on one of the
Direct Graphics routines equal to 0.
Once the Device font system is selected, use the SET_FONT keyword to the DEVICE
routinetoselect thefont touse. Becausedevicefontsarespecieddifferentlyon different
platforms, the synatax of thefontnamestring depends on which platform you are using.
Unix and VMS
Usually, the window system provides a directory of font les that can be used by all
applications. List thecontentsof that directorytondthefontsavailableon your system.
Thesizeof thefont selected alsoaffectsthesizeof vector drawn text. On somemachines,
fonts are kept in subdirectories of /usr/lib/X11/fonts. You can use thexlsfonts
command to list available X Windows fonts.
For example, to select the font 8X13:
!P.FONT = 0
DEVICE, SET_FONT = '8X13'
Microsoft Windows
The SET_FONT keyword should be set to a string with the following form:
DEVICE, SET_FONT="font*modifier
1
*modifier
2
*...modifier
n
"
where the asterisk (*) acts as a delimiter between the fonts name (font) and any
modiers. The string isnot case sensitive. Modiers are simply keywords that change
aspects of the selected font. Valid modiers are:
For font weight: THIN, LIGHT, BOLD, HEAVY
74 Chapter 6: Fonts
For font quality: DRAFT, PROOF
For font pitch: FIXED, VARIABLE
For font angle: ITALIC
For strikeout text: STRIKEOUT
For underlined text: UNDERLINE
For font size: Any number is interpreted as the font height in pixels.
For example, if you have Garamond installed as one of your Windows fonts, you could
select 24-pixel cell height Garamond italic as the font to use in plotting. The following
commandstell IDL to usehardwarefonts, changethefont, and then makeasimpleplot:
!P.FONT = 0
DEVICE, SET_FONT = "GARAMOND*ITALIC*24"
PLOT, FINDGEN(10), TITLE = "IDL Plot"
Thisfeatureiscompatiblewith TrueTypeand AdobeTypeManager (and, possibly, other
type scaling programs for Windows). If you have TrueType or ATM installed, the
TrueType or PostScript outline fonts are used so that text looks good at any size.
Macintosh
1
*modifier
2
*...modifier
n
"
For font weight: BOLD
For font width: CONDENSED, EXTENDED
For outlined text: OUTLINE, SHADOW
For font size: Any number is interpreted as the font size, in points.
For example, if you haveGaramond installed, you could select 24-point Garamond italic
as the font to use in plotting. The following commands tell IDL to use hardware fonts,
change the font, and then make a simple plot:
IDL> !P.FONT = 0
IDL> DEVICE, SET_FONT = "GARAMOND*ITALIC*24"
IDL> PLOT, FINDGEN(10), TITLE = "IDL Plot"
Chapter 6: Fonts 75
IDL Reference Guide About Device Fonts
Fonts and the PostScript Device
A special set of device fonts are available when the current Direct Graphics device isPS
(PostScript). IDL includesfont metricinformation for 35standard PostScript fonts, and
can createPostScript languagelesthat includetext in thesefonts. (The35fontsknown
to IDL are listed in Table 6-2; they the standard fonts included in memory in the vast
majorityof modernPostScript printers.) ThePostScript font metricles(*.afmles) are
located in theresource/fonts/ps subdirectory of the IDL directory.
Using PostScript Fonts
To use a PostScript font in your Direct Graphics output, you must rst specify that IDL
use the device font system, they switch to thePS device, then choose a font using the
SET_FONT keyword to the DEVICE procedure.
The following IDL commands choose the correct font system, set the graphics device,
select the font Palatino Roman, open a PostScript le to print to, plot a simple data set,
and close the PostScript le:
!P.FONT = 0
SET_PLOT, 'PS'
DEVICE, SET_FONT = 'Palatino-Roman', FILE = 'testfile.ps'
PLOT, INDGEN(10), TITLE = 'My Palatino Title'
DEVICE, /CLOSE
Note Subsequent PostScript output will continuetousethefont PalatinoRomanuntil you
explicitly change the font again, or exit IDL.
AvantGarde-Book Helvetica Palatino-Bold
AvantGarde-BookOblique Helvetica-Bold Palatino-BoldItalic
AvantGarde-Demi Helvetica-BoldOblique Palatino-Italic
AvantGarde-DemiOblique Helvetica-Narrow Palatino-Roman
Bookman-Demi Helvetica-Narrow-Bold Symbol
Bookman-DemiItalic Helvetica-Narrow-BoldOblique Times-Bold
Bookman-Light Helvetica-Narrow-Oblique Times-BoldItalic
Bookman-LightItalic Helvetica-Oblique Times-Italic
Courier NewCenturySchlbk-Bold Times-Roman
Courier-Bold NewCenturySchlbk-BoldItalic ZapfChancery-MediumItalic
Courier-BoldOblique NewCenturySchlbk-Italic ZapfDingats
Courier-Oblique NewCenturySchlbk-Roman
Table 6-2: Names of Supported PostScript Fonts
76 Chapter 6: Fonts
You can also specify PostScript fonts using a set of keywords to the DEVICE procedure.
The keyword combinations for the fonts included with IDL are listed in Table 6-3.
PostScript Font DEVICE Keywords
Courier /COURIER
Courier Bold /COURIER, /BOLD
Courier Oblique /COURIER, /OBLIQUE
Courier Bold Oblique /COURIER, /BOLD, /OBLIQUE
Helvetica /HELVETICA
Helvetica Bold /HELVETICA, /BOLD
Helvetica Oblique /HELVETICA, /OBLIQUE
Helvetica Bold Oblique /HELVETICA, /BOLD, /OBLIQUE
Helvetica Narrow /HELVETICA, /NARROW
Helvetica Narrow Bold /HELVETICA, /NARROW, /BOLD
Helvetica Narrow Oblique /HELVETICA, /NARROW, /OBLIQUE
Helvetica Narrow Bold Oblique /HELVETICA, /NARROW, /BOLD,
/OBLIQUE
ITC Avant Garde Gothic Book /AVANTGARDE, /BOOK
ITC Avant Garde Gothic Book Oblique /AVANTGARDE, /BOOK, /OBLIQUE
ITC Avant Garde Gothic Demi /AVANTGARDE, /DEMI
ITC Avant Garde Gothic Demi Oblique /AVANTGARDE, /DEMI, /OBLIQUE
ITC Bookman Demi /BKMAN, /DEMI
ITC Bookman Demi Italic /BKMAN, /DEMI, /ITALIC
ITC Bookman Light /BKMAN, /LIGHT
ITC Bookman Light Italic /BKMAN, /LIGHT, /ITALIC
ITC Zapf Chancery Medium Italic /ZAPFCHANCERY, /MEDIUM, /ITALIC
ITC Zapf Dingbats /ZAPFDINGBATS
New Century Schoolbook /SCHOOLBOOK
New Century Schoolbook Bold /SCHOOLBOOK, /BOLD
New Century Schoolbook Italic /SCHOOLBOOK, /ITALIC
New Century Schoolbook Bold Italic /SCHOOLBOOK, /BOLD, /ITALIC
Palatino /PALATINO
Palatino Bold /PALATINO, /BOLD
Palatino Italic /PALATINO, /ITALIC
Palatino Bold Italic /PALATINO, /BOLD, /ITALIC
Symbol /SYMBOL
Times /TIMES
Times Bold /TIMES, /BOLD
Times Italic /TIMES, /ITALIC
Times Bold Italic /TIMES, /ITALIC, /BOLD
Table 6-3: The Standard 35 PostScript Fonts
Chapter 6: Fonts 77
IDL Reference Guide Choosing a Font Type
For example to use the PostScript font Palatino Bold Italic, you could use either of the
following DEVICE commands:
DEVICE, SET_FONT = 'Palatino*Bold*Italic'
DEVICE, /PALATINO, /BOLD, /ITALIC
Changing the PostScript Font Assigned to an Index
You can change the PostScript font assigned to a given font index using the
FONT_INDEXkeywordtotheDEVICEprocedure. See FONT_INDEX onpage124for
details. Font indicesand their usearediscussed in Embedded FormattingCommands
on page 79.
Changingthefont index assigned to afont can beuseful when changingPostScript fonts
in the middle of a text string. For example, the following statements map Palatino Bold
Italic to font index 4, and then output text using that font and the Symbol font:
DEVICE, /PALATINO, /BOLD, /ITALIC, FONT_INDEX=4
Map thefont selected by !4 to be
PalatinoBoldItalic.
XYOUTS, .3, .5, /NORMAL, "!4Alpha: !9a", FONT=0, SIZE=5.0
Output Alpha : in PalatinoBo-
ldItalicfollowedbyanAlphachar-
acter.
Adding Your Own PostScript Fonts
Because the 35 PostScript fonts included with IDL are built in to a PostScript printers
memory, the IDL distribution includes only the font metric les, which provide
positioning information. In addition, the.afm les used by IDL are specially processed
to provide the information in a format IDL expects.
You can addyour own PostScript fontstothelist of fontsknown toIDLif you haveaccess
tothePostScript font le(usuallynamedfont.pfb) toloadintoyour printer andtothe
font.afm lesupplied by Adobe. You can convert thestandard .afm leinto aleIDL
understands using the IDL routine PSAFM. Consult the leREADME.TXT in the
resource/fonts/ps subdirectoryof theIDLdirectoryfor detailsonaddingPostScript
fonts to your system.
Choosing a Font Type
Some of the issues involved in choosing between vector, TrueType, and device fonts are
explained below.
Appearance
Vector-drawn characters are of medium quality, suitable for most uses. TrueType
characters are of relatively high quality, although at some point sizes the triangulation
process (described in About the TrueType Fonts on page 68) may cause characters to
78 Chapter 6: Fonts
Choosing a Font Type IDL Reference Guide
appear slightly jagged. The appearance of device characters varies from mediocre
(characters found in many graphics terminals) to publication quality (PostScript).
Three-Dimensional Transformations
Vector or TrueTypefontsshouldalwaysbeusedwiththree-dimensional transformations.
Both vector and TrueType characters pass through the same transformations as the rest
of theplot, yieldingabetter lookingplot. See Three-Dimensional Graphics onpage334
of UsingIDLfor anexampleof vector-drawncharacterswiththree-dimensional graphics.
Device characters are not subject to the three-dimensional transforms.
Portability
The vector-drawn fonts work using any graphics device and look the same on every
device (within the limitations of device resolution) on any system supported by IDL.
TrueType fonts are available only on theX, WIN, MAC, PRINTER, PS, and Z Direct
Graphicsdevices, and in IDLsObject Graphicssystem. If you useonlythefontssupplied
withIDL, TrueTypefontsalsolook thesameon everysupporteddevice(again within the
limitsof thedeviceresolution). If you useTrueTypefontsother than thosesupplied with
IDL, your font may not beintalled on thesystemwhich runsyour program. In thiscase,
IDL will substitute a known font for the missing font.
Theappearance, size, and availabilityof devicefontsvariesgreatlyfromdevicetodevice.
Many, if not most, of the positioning and font changing commands recognized by the
vector-drawing routines are ignored when using device fonts. The exception to this rule
istheDirect GraphicsPS device; if you useoneof thePostScript fontssupported byIDL,
the PostScript output from thePS device will be identical between platforms.
Computational Time
Device fonts are generally rendered the most quickly, since the hardware device or
operating system handles all computations and caching.
It takesmorecomputer timeto drawcharacterswith linevectorsand generally resultsin
more input/output. However, this is not an important issue unless the plot contains a
large number of characters or the transmission link to the device is very slow.
The inital triangulation step used when displaying TrueType fonts for the rst time can
be computationally expensive. However, since the font shapes are cached, subsequent
uses of the same font are relatively speedy.
Flexibility
Vector-drawn fontsprovideagreat deal of exibility. Therearemany different typefaces
available, asshown in thetablesat theend of thischapter. In addition, such fontscan be
arbitrarily scaled, rotated, and transformed.
TrueTypefontssupport fewer embeddedformattingcommandsthan dothevector fonts,
and cannot be scaled, rotated, or transformed.
The abilities of hardware-generated characters differ greatly between devices so it is not
possibleto makeablanket statement on when they should beusedthebest font to use
Chapter 6: Fonts 79
IDL Reference Guide Embedded Formatting Commands
dependson theavailablehardware. In general, however, thevector or TrueTypefontsare
easier touseandoftenprovidesuperior resultstowhat isavailablefromthehardware. See
the discussion of the device you are using in IDL Graphics Devices in Chapter 8 for
details on the hardware-generated characters provided by that device.
Print Quality
For producingpublication-qualityoutput, werecommendusingeither theTrueTypefont
system or the Direct GraphicsPS device and one of the PostScript fonts supported by
IDL.
Embedded Formatting Commands
When you use vector, TrueType, and some device fonts, text strings can include
embedded formatting commands that facilitate subscripting, superscripting, and
equation formatting. The method used is similar to that developed by Grandle and
Nystrom (1980). Embedded formatting commands are always introduced by the
exclamation mark, (!). (The string !! is used to produce a literal exclamation mark.)
Note Embeddedformattingcommandsprefacedbytheexclamation mark havenospecial
signicance for hardware-generated characters unless the ability is provided by the
particular device in use. The IDL PostScript device driver accepts many of the
standard embedded formattingcommands, and isdescribed here. If you wish touse
hardware fonts with IDL Direct Graphics devices other than the PostScript device,
consult thedescription of thedevicein chapter 8of theIDL ReferenceGuidebefore
trying to use these commands with hardware characters.
You can determine whether embedded formatting commands are available for use
with device fonts on your current graphics device by inspecting bit 12 of theFlags
eld of the !D System Variable. Use the IDL statement:
IF (!D.FLAGS AND 4096) NE 0 THEN PRINT, 'Bit is set.'
to determine whether bit 12 of theFlagseld is set for the current graphics device.
Changing Fonts within a String
You can change fonts one or more times within a text string using the embedded font
commands shown in Table 6-4. The character following the exclamation mark can be
either upper or lower case.
Examplesof commandsused to changefontsin mid-stringareincluded in Formatting
Command Examples on page 82.
80 Chapter 6: Fonts
Embedded Formatting Commands IDL Reference Guide
Font
Command
Select
Vector Font
Select
TrueType Font
Select
PostScript Font
!3 Simplex Roman (default) Helvetica Helvetica
!4 Simplex Greek Helvetica Bold Helvetica Bold
!5 Duplex Roman Helvetica Italic Helvetica Narrow
!6 Complex Roman Helvetica Bold Italic Hevetica Narrow Bold Oblique
!7 Complex Greek Times Times Roman
!8 Complex Italic Times Italic Times Bold Italic
!9 Math/special characters Symbol Symbol
!M Math/special characters
(change effective for one
character only)
Symbol Symbol
!10 Special characters Symbol * Zapf Dingbats
!11(!G) Gothic English Courier Courier
!12(!W) Simplex Script Courier Italic Courier Oblique
!13 Complex Script Courier Bold Palatino
!14 Gothic Italian Courier Bold Italic Palatino Italic
!15 Gothic German Times Bold Palatino Bold
!16 Cyrillic Times Bold Italic Palatino Bold Italic
!17 Triplex Roman Helvetica * Avant Garde Book
!18 Triplex Italic Helvetica * New Century Schoolbook
!19 Helvetica * NewCentury Schoolbook Bold
!20 Miscellaneous Helvetica * Undened User Font
!X Revert to the entry font Revert to the entry font Revert to the entry font
* The font assigned to this index may be replaced in a future release of IDL.
Table 6-4: Embedded Font Selection Commands
Chapter 6: Fonts 81
IDL Reference Guide Embedded Formatting Commands
Positioning Commands
The positioning and other font-manipulation commands are described in Table 6-5.
Examples of commands used to position text are included in Formatting Command
Examples on page 82.
Positioning
Commands
Action
!A Shift above the division line.
!B Shift below the division line.
!C Carriagereturn, beginsanewlineof text. Shift back to thestarting
position and down one line.
!D Shift down to therst level subscript and decreasethecharacter size
by a factor of 0.62.
!E Shift up to the exponent level and decrease the character size by a
factor of 0.44.
!I Shift down to the index level and decrease the character size by a
factor of 0.44.
!L Shift down to the second level subscript. Decrease the character size
by a factor of 0.62.
!N Shift back to the normal level and original character size.
!R Restore position. The current position is set from the top of the
saved positions stack.
!S Save position. The current position is saved on the top of the saved
positions stack.
!U Shift to upper subscript level. Decrease the character size by a factor
of 0.62.
!X Return to the entry font.
!Z(u
0
,u
1
,...,u
n
) Display one or more character glyphs according to their unicode
value. Each u
i
within the parentheses will be interpreted as a 16-bit
hexadecimal unicode value. If more than one unicode value is to be
included, the values should be separated by commas.
!! Display the ! symbol.
Table 6-5: Vector-Drawn Positioning and Miscellaneous Commands
82 Chapter 6: Fonts
Formatting Command Examples IDL Reference Guide
Formatting Command Examples
Figure 6-1 illustrates the relative positions and effects on character size of the level
commands. In this gure, the letters !N are normal level and size characters.
The positioning show was created with the following command:
xyouts, 0.1, 0.3, $
!LLower!S!EExponent!R!IIndex!N Normal!S!EExp!R!IInd!N!S!U Up
!R!D Down!N!S!A Above!R!B Below
Notethat thestringargument totheXYOUTSproceduremust beenteredon asingleline
rather than the two lines shown above.
Figure 6-1: Positioning commands with vector fonts (top) and TrueType fonts (bottom).
Chapter 6: Fonts 83
IDL Reference Guide Formatting Command Examples
A Complex Equation
Embedded positioning commands and the vector font system can be used to create the
integral shown below:
The command string used to produce the integral is:
XYOUTS, 0, .2, $
!MI!S!A!E!8x!R!B!Ip!N !7q!Ii!N!8U!S!E2!R!Ii!Ndx, $
SIZE = 3, /NORMAL
Remember that the case of the letter in an embedded command is not important. The
string may be broken down into the following components:
!MI
Changes to the math set and draws the integral sign, uppercase I.
!S
Saves the current position on the position stack.
!A!E!8x
Shifts above the division line and to the exponent level, switches to the Complex Italic
font (Font 8), and draws the x.
!R!B!Ip
Restorestheposition to theposition immediately after theintegral sign, shiftsbelowthe
division line to the index level, and draws the p.
!N !7q
Returnsto thenormal level, advancesonespace, shiftsto theComplex Greek font (Font
7), and draws the Greek letter rho, which is designated by q in this set.
!Ii!N
Shiftsto theindex level and drawsthe i at theindex level. Returnsto thenormal level.
Figure 6-2: An integral created with the vector fonts.
84 Chapter 6: Fonts
Formatting Command Examples IDL Reference Guide
!8U
Shifts to the Complex Italic font (Font 8) and outputs the upper case U.
!S!E2
Saves the position and draws the exponent 2.
!R!Ii
Restores the position and draws the index i.
!N dx
Returns to the normal level and outputs dx.
Note Theequation shown in Figure6-2couldnot becreatedsosimplyusingtheTrueType
font system, becausethelargeintegral symbol isbroken intotwoor morecharacters
in the TrueType fonts.
Vector-Drawn Font Example
IDL uses vector-drawn font when the value of the system variable !P.FONT is -1. This is
the default condition. Initially, all characters are drawn using the Simplex Roman font
(Font 3). When plotting, font changingcommandsmay beembedded in thetitlestrings
keyword arguments (XTITLE, YTITLE, and TITLE) to select other fonts. For example,
the following statement uses the Complex Roman font (Font 6) for thex-axis title:
PLOT, X, XTITLE = '!6X Axis Title'
This font remains in effect until explicitly changed. The order in which the annotations
are drawn is main title, x-axis numbers, x-axis title, y-axis numbers, and y-axis title.
Strings to be output also may contain embedded information selecting subscripting,
superscripting, plus other features that facilitate equation formatting.
Thefollowingstatementswereused toproduceFigure6-3. Theyserveasan exampleof a
plot using vector-drawn characters and of equation formatting.
X = FLTARR(128) Definean array.
X[30:40] = 1.0 Makea step function.
X = ABS(FFT(X, 1)) TakeFFT and magnitude.
PLOT, X[0:64], /YLOG, XTITLE = '!17Frequency', $
YTITLE = '!5Power', $
TITLE = '!18Example of Vector Drawn Plot', $
POSITION = [.2, .2, .9, .6] Producealog-linearplot.UsetheTri-
plex Roman font for thex title(!17),
DuplexRomanfortheytitle(!5),and
Triplex Italic for themain title(!18).
Thepositionkeywordisusedtoshrink
theplottingwindow.
SS = '!6F(s) = (2!4p)!e-1/2!n !mi!s!a!e!m $
!r!b!i ' + '-!m $
Chapter 6: Fonts 85
IDL Reference Guide Formatting Command Examples
!nF(x)e !e-i2!4p!3xs!ndx' Stringto produceequation.
XYOUTS, 0.1, .75, SS, SIZE = 3, $
/NORMAL, /NOCLIP
Outputstringoverplot.TheNOCLIP
keyword is needed becausetheprevi-
ousplotcausedtheclippingregionto
shrink.
Figure 6-3: Example of a Vector-drawn Plot
86 Chapter 6: Fonts
TrueTypeFont Samples IDL Reference Guide
TrueTypeFont Samples
The following gures show roman versions of the four TrueType font families included
with IDL. Thecharacter setsfor thebold, italic, and bold italicversionsof thesefontsare
the same as the roman versions.
Chapter 6: Fonts 87
IDL Reference Guide TrueTypeFont Samples
88 Chapter 6: Fonts
TrueTypeFont Samples IDL Reference Guide
Chapter 6: Fonts 89
IDL Reference Guide Vector Font Samples
Vector Font Samples
The following pages show samples of the different vector-drawn fonts.
90 Chapter 6: Fonts
Vector Font Samples IDL Reference Guide
Figure 6-4: Note that this chart is numbered in octal notation. To read the octal number of a
character, add the column index (along the top) to ten times the row index. Thus, the capital
letter A is octal 101, and the degree symbol is octal 232.
Chapter 6: Fonts 91
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
92 Chapter 6: Fonts
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
Chapter 6: Fonts 93
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
94 Chapter 6: Fonts
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
Chapter 6: Fonts 95
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
96 Chapter 6: Fonts
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
Chapter 6: Fonts 97
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
98 Chapter 6: Fonts
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
A B C D E F G H I J
K L M N O P Q R S T
U V W X Y Z [ \ ] ^
_ a b c d e f g h
i j k l m n o p q r
s t u v w x y z "
# $ % & ( ) * + ,
- . / 0 1 2 3 4 5 6
7 8 9 : ; < = > ? @
99
Chapter 7
Graphics Keywords
The IDL Direct Graphics routines, CURSOR, ERASE, PLOTS, POLYFILL, TV (and
TVSCL), TVCRS, TVRD, andXYOUTS, andtheplottingprocedures, AXIS, CONTOUR,
PLOT, OPLOT, SHADE_SURF, and SURFACE, accept a number of common keywords.
Therefore, insteadof describingeachkeywordalongwiththedescription of eachroutine,
this section contains a brief summary of each graphics keyword. Routine-specic
keywordsaredocumented in thedescription of theroutinein Chapter 9, IDL Routines.
Thegraphicskeywordsaredescribedbelow. Click on akeywordin thescrollinglist at left.
Thenameof thekeyword appearsfollowed by alist of routinesthat accept that keyword.
Keywordsthat haveadirect correspondenceto eldsin asystemvariable(usually !P) are
also indicated.
The keywords that control the plot axes are prexed with the character X, Y, or Z
dependingontheaxisinquestion. Thesekeywordscorrespondtoeldsintheaxissystem
variables: !X, !Y, and !Z, and aredescribed in moredetail in GraphicsSystemVariables
on page 46 The axis keywords are shown in the form [ XYZ] NAME. For example,
[ XYZ] CHARSIZE refers to the three keywords XCHARSIZE, YCHARSIZE, and
ZCHARSIZE, which control the size of the characters annotating the three axes.
100 Chapter 7: Graphics Keywords
AM_PM IDL Reference Guide
The system variable elds that control this are !X.CHARSIZE, !Y.CHARSIZE, and
!Z.CHARSIZE.
AM_PM
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, and SURFACE.
Suppliesastringarrayof 2namestobeusedfor thenamesof theAMandPMstringwhen
processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the
[ XYZ] TICKFORMAT keywords.
BACKGROUND
Accepted by: CONTOUR, PLOT, SURFACE. System variable equivalent:
!P.BACKGROUND.
The background color index to which all pixels are set when erasing the screen or page.
The default is 0 (black). Not all devices support erasing the background to a specied
color index.
Example To produce a black plot with a white background on a color display:
PLOT, Y, BACKGROUND = 255, COLOR = 0
CHANNEL
Accepted by: ERASE, TV, TVRD. System variable equivalent: !P.CHANNEL.
Thiskeyword speciesthememorychannel for theoperation. Thisparameter isignored
on display systems that have only one memory channel. When using a decomposed
display system, the red channel is 1, the green channel is 2, and the blue channel is 3.
Channel 0 indicates all channels. If omitted, !P.CHANNEL contains the default channel
value.
Note CONTOUR, PLOT, SHADE_SURF, and SURFACE also accept the CHANNEL key-
word, but simply pass it to ERASE.
CHARSIZE
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE, XYOUTS. System
variable equivalent: !P.CHARSIZE.
The overall character size for the annotation when Hershey fonts are selected. This
keyword doesnot applywhen hardware(i.e. PostScript) fontsareselected. ACHARSIZE
of 1.0isnormal. Thesizeof theannotation on theaxesmaybeset, relativetoCHARSIZE,
with xCHARSIZE, wherexisX, Y, or Z. Themain titleiswritten with acharacter sizeof
1.25 times this parameter.
[XYZ]CHARSIZE
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE. System variable
equivalents: ![ XYZ] .CHARSIZE.
The size of the characters used to annotate the axis and its title when Hershey fonts are
selected. Thiskeyword doesnot apply when hardware(i.e. PostScript) fontsareselected.
Chapter 7: Graphics Keywords 101
IDL Reference Guide CHARTHICK
This eld is a scale factor applied to the global scale factor set by !P.CHARSIZE or the
keyword CHARSIZE.
CHARTHICK
variable equivalent: !P.CHARTHICK.
An integer value specifying the line thickness of the vector drawn font characters.This
keyword has no effect when used with the hardware drawn fonts. The default value is 1.
CLIP
Accepted by: AXIS, CONTOUR, OPLOT, PLOT, PLOTS, POLYFILL, SHADE_SURF,
SURFACE, XYOUTS. System variable equivalent: !P.CLIP.
Thecoordinatesof arectangleused toclip thegraphicsoutput. Therectangleisspecied
asavector of theform[ X
0
, Y
0
, X
1
, Y
1
] , givingcoordinatesof thelower left andupper right
corners, respectively. Thedefault clippingrectangleistheplot window, theareaenclosed
within theaxesof themost recent plot. Coordinatesarespecied in dataunitsunlessan
overridingcoordinateunit specication keyword ispresent (i.e., NORMAL or DEVICE).
Note The default is not to clip the output of PLOTS and XYOUTS. To enable clipping
includethekeywordparameter NOCLIP=0. WithPLOTS, POLYFILL, andXYOUTS,
this keyword controls the clipping of vectors and vector-drawn text.
Example To draw a vector using normalized coordinates with its contents clipped within a
rectangle covering the upper left quadrant of the display:
PLOTS, X, Y, CLIP=[0.,.5,.5,1.0], /NORM, NOCLIP=0
COLOR
Accepted by: AXIS, CONTOUR, ERASE, OPLOT, PLOT, PLOTS, POLYFILL,
SHADE_SURF, SURFACE, XYOUTS. System variable equivalent: !P.COLOR.
Thecolor index of thedata, text, line, or solid polygon ll to bedrawn. If thiskeyword is
omitted, !P.COLOR species the color index.
When usedwith thePLOTS, POLYFILL, or XYOUTSprocedure, thiskeywordparameter
can be set to a vector to specify multiple color indices.
Gouraudshadingof polygonsisperformedwiththeZ-buffer graphicsoutput deviceand
POLYFILL procedure when COLOR contains an array of color indices, one for each
vertex.
DATA
Accepted by: AXIS, CONTOUR, CURSOR, PLOT, PLOTS, POLYFILL, SHADE_SURF,
SURFACE, TV, TVCRS, XYOUTS.
Set thiskeywordtoindicatethat theclippingand/or positioningcoordinatessuppliedare
speciedinthedatacoordinatesystem. Thedefault coordinatesystemisDATAif noother
coordinate-system specications are present.
DAYS_OF_WEEK IDL Reference Guide
DAYS_OF_WEEK
Suppliesastringarray of 7namesto beused for thenamesof thedaysof theweek when
processingexplicitlyformatted dates(CDWA, CDwA, and CdwAformat codes) with the
DEVICE
AXIS, CONTOUR, CURSOR, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE,
TV, TVCRS, XYOUTS.
specied in the device coordinate system. The default coordinate system is DATA if no
other coordinate-system specications are present.
Example The following code displays an image contained in the variable A and then draws a
contour plot of pixels [ 100:499, 100:399] over the correct section of the image:
TV,A Display theimage.
CONTOUR, A[100:499, 100:399], $
POS = [100,100, 499,399], /DEVICE, $
/NOERASE, XSTYLE=1, YSTYLE=1 Drawthecontourplot,specifythe
coordinates of theplot, in device
coordinates,donoterase,settheX
and Y axis styles to EXACT.
Notethat in theaboveexample, thekeyword specication /DEVICE isequivalent
to DEVICE = 1.
FONT
variable equivalent: !P.FONT.
An integer that species the graphics text font system to use. Set FONT equal to -1 to
selectstheHershey character fonts, which aredrawn usingvectors. Set FONT equal to 0
(zero) to select the device font of the output device. Set FONT equal to 1 (one) to select
theTrueTypefont system. SeeFonts on page65for acompletedescription of IDLsfont
systems.
[XYZ]GRIDSTYLE
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE
The index of the linestyle to be used for plot tickmarks and grids (i.e., when
[ XYZ] TICKLEN is set to 1.0). See Table 7-1 for a list of linestyles.
LINESTYLE
Accepted by: OPLOT, PLOT, PLOTS, SURFACE. System variable equivalent:
!P.LINESTYLE.
IDL Reference Guide [XYZ]MARGIN
This keyword indicates the line style used to draw lines; it indicates the line style of the
linesusedtoconnect thedatapoints. Thiskeywordshouldbeset totheappropriateindex
for the desired linestyle as described in the following table.
[XYZ]MARGIN
equivalent: ![ XYZ] .MARGIN.
A2-element array specifyingthemargin on theleft (bottom) and right (top) sidesof the
plot window, in unitsof character size. Default marginsare10and 3for theXaxis, and 4
and 2 for the Y axis. The ZMARGIN keyword is present for consistency and is currently
ignored.
[XYZ]MINOR
equivalent: ![ XYZ] .MINOR.
The number of minor tick marks.
MONTHS
Supplies a string array of 12 names to be used for the names of the months when
processingexplicitlyformatteddates(CMOA, CMoA, andCmoAformat codes) withthe
NOCLIP
Accepted by: AXIS, CONTOUR, OPLOT, PLOT, PLOTS, POLYFILL, SHADE_SURF,
SURFACE, XYOUTS. System variable equivalent: !P.NOCLIP.
Set this keyword to suppress clipping of the plot. The clipping rectangle is contained in
!P.CLIP. By default, the plot is clipped within the plotting window.
Note The default value is clipping-disabled for PLOTS, POLYFILL, and XYOUTS. For all
other routines, the default is to enable clipping.
Index Linestyle
0 Solid
1 Dotted
2 Dashed
3 Dash Dot
4 Dash Dot Dot Dot
5 Long Dashes
Table 7-1: IDL Linestyles
NODATA IDL Reference Guide
WithPLOTS, POLYFILL, andXYOUTS, thiskeywordcontrolstheclippingof vectorsand
vector-drawn text. The default is to disable clipping, so to enable clipping include the
parameter NOCLIP = 0. To explicitly disable clipping set this parameter to one.
NODATA
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE.
If this keyword is set, only the axes, titles, and annotation are drawn. No data points are
plotted.
Example To draw an empty set of axes between some given values:
PLOT, [XMIN, XMAX],[YMIN, YMAX], /NODATA
NOERASE
Accepted by: AXIS, CONTOUR, PLOT, SURFACE. System variable equivalent:
!P.NOERASE.
Species that the screen or page is not to be erased. By default, the screen is erased, or a
new page is begun, before a plot is produced.
NORMAL
Accepted by: AXIS, CONTOUR, CURSOR, PLOT, PLOTS, POLYFILL, SHADE_SURF,
SURFACE, TV, TVCRS, XYOUTS.
specied in the normalized coordinate system, and range from 0.0 to 1.0. The default
coordinate system is DATA if no other coordinate-system specications are present.
ORIENTATION
Accepted by: POLYFILL, XYOUTS.
Species the counterclockwise angle in degrees from horizontal of the text baseline and
the lines used to ll polygons.When used with the POLYFILL procedure, this keyword
forces the linestyle type of ll, rather than solid or patterned ll.
POSITION
Acceptedby: CONTOUR, MAP_SET, PLOT, SHADE_SURF, SURFACE. Systemvariable
equivalent: !P.POSITION.
Allows direct specication of the plot window. POSITION is a 4-element vector giving,
in order, thecoordinates[ (X
0
, Y
0
), (X
1
, Y
1
)] , of thelower left and upper right cornersof
thedatawindow. Coordinatesareexpressed in normalized unitsrangingfrom0.0to1.0,
unlesstheDEVICEkeyword ispresent, in which casethey arein actual deviceunits. The
valueof POSITION isnever specied in dataunits, even if theDATAkeyword ispresent.
Whensettingthepositionof thewindow, besuretoallowspacefor theannotation, which
residesoutsidethewindow. IDL outputsthemessage %Warning: Plot truncated. if the
plot regionislarger thanthescreenor pagesize. Theplot regionistherectangleenclosing
the plot window and the annotation.
IDL Reference Guide PSYM
When plotting in three dimensions, the POSITION keyword is a 6-element vector with
the rst four elements describing, as above, the XY position, and with the last two
elementsgivingtheminimumandmaximumZcoordinates. TheZspecicationisalways
in normalized coordinate units.
When makingmorethan oneplot per pageit ismoreconvenient toset !P.MULTI than to
manipulate the position of the plot directly with the POSITION keyword.
Example Thefollowingstatement producesacontour plot withdataplottedin onlytheupper
left quarter of the screen:
CONTOUR, Z, POS=[0., 0.5, 0.5, 1.0]
Becausenospaceontheleft or topedgeswasallowedfor theaxesor their annotation,
the above described warning message results.
PSYM
Accepted by: OPLOT, PLOT, PLOTS. System variable equivalent: !P.PSYM.
The symbol used to mark each data point. Normally, PSYM is 0, data points are
connected by lines, and no symbols are drawn to mark the points. Set this keyword, or
the system variable !P.PSYM, to the symbol index as shown in the table below to mark
data points with symbols. The keyword SYMSIZE is used to set the size of the symbols.
PSYMValue Plotting Symbol
1 Plus sign (+)
2 Asterisk (*)
3 Period (.)
4 Diamond
5 Triangle
6 Square
7 X
8 User-dened. See USERSYM procedure.
9 Undened
10 Histogram mode. Horizontal and vertical lines connect the
plotted points, as opposed to the normal method of connect-
ing points with straight lines.
Table 7-2: Values for the PSYM Keyword
[XYZ]RANGE IDL Reference Guide
Negative values of PSYM cause the symbol designated by PSYM to be plotted at each
point with solid lines connecting the symbols. For example, a value of -5 plots triangles
at each data point and connects the points with lines.
Example ThefollowingIDLcodeplotsanarrayusingpoints, andthenoverplotsthesmoothed
array, connecting the points with lines:
PLOT, A, PSYM=3 Plot usingpoints.
OPLOT, SMOOTH(A,7) Overplot smoothed data.
[XYZ]RANGE
equivalent: ![ XYZ] .RANGE.
The desired data range of the axis, a 2-element vector. The rst element is the axis
minimum, and the second is the maximum. IDL will frequently round this range. This
override can be defeated using the [ XYZ] STYLE keywords.
[XYZ]STYLE
equivalent: ![ XYZ] .STYLE.
This keyword allows specication of axis options such as rounding of tick values and
selection of a box axis. Each option is described in Table 7-3.
Note that this keyword is set bitwise, so multiple effects can be set by adding values
together. For example, to make an X axis that is both exact (value 1) and suppresses the
box style (setting 8), set the XAXIS keyword to 1+8, or 9.
SUBTITLE
equivalent: !P.SUBTITLE.
A text string to be used as a subtitle for the plot. Subtitles appear below the X axis.
SYMSIZE
Accepted by: OPLOT, PLOT, PLOTS.
Value Description
1 Force exact axis range.
2 Extend axis range.
4 Suppress entire axis
8 Suppress box style axis (i.e., draw axis on only one side of plot)
16 Inhibit setting the Y axis minimum value to 0 (Y axis only)
Table 7-3: Values for the [XYZ]STYLE Keyword
IDL Reference Guide T3D
Speciesthesizeof thesymbolsdrawnwhenPSYMisset. Thedefault sizeof 1.0produces
symbols approximately the same size as a character.
T3D
Accepted by: AXIS, CONTOUR, MAP_SET, OPLOT, PLOT, PLOTS, POLYFILL,
SHADE_SURF, SURFACE, TV, TVCRS, XYOUTS. System variable equivalent: !P.T3D.
Set this keyword to indicate that the generalized transformation matrix in !P.T is to be
used. If not present, the user-supplied coordinates are simply scaled to screen
coordinates. See the examples in the description of the SAVE keyword.
Note SinceT3D usesthetransformation matrix in !P.T, it isimportant that !P.T contain a
valid transformation matrix. This can be achieved in several ways:
Use the SAVE keyword to save the transformation matrix from an earlier graphics
operation.
Establish a transformation matrix using the T3D, SURFR, or, SCALE3 procedures.
Set the value of !P.T directly.
THICK
Accepted by: AXIS, OPLOT, PLOT, PLOTS, POLYFILL, SHADE_SURF, SURFACE.
System variable equivalent: !P.THICK.
Indicates the line thickness. THICK overrides the setting of !P.THICK.
[XYZ]THICK
equivalent: ![ XYZ] .THICK.
Thiskeyword controlsthethicknessof thelinesformingtheaxisand tick marks. Avalue
of 1.0 is the default.
[XYZ]TICKFORMAT
equivalent: ![ XYZ] .TICKFORMAT.
Set this keyword to a format string or a string containing the name of a function that
returns a string to be used to format the axis tick mark labels.
If the argument to the TICKFORMAT keyword does not begin with the an open
parenthesis, "(", thestringisinterpreted asthenameof afunction. Thefunction iscalled
with three parameters: Axis, Index, and Valuewhere:
Axisis the axis number: 0 for X axis, 1 for Y axis, 2 for Z axis.
Index is the tick mark index which starts at 0.
Valueis the default tick mark value (a oating-point number).
TICKLEN IDL Reference Guide
Used with the LABEL_DATE function, this keyword can easily create axes with date
labels. LABEL_DATE on page 594
Example For example, to display the X axis tick values using a format of F6.2 (six characters,
with 2 places after the decimal point), use the XTICKFORMAT keyword as follows:
PLOT, X, Y, XTICKFORMAT='(F6.2)'
To display the Y tick values using the dollars and cents format $dddd.dd, use:
PLOT, X, Y, YTICKFORMAT='("$", F7.2)'
Example For morecomplicated tick label formatting, labelscan becreated byauser-specied
function that returns a string. For example, to annotate ticks along a time axis with
the format HH:MM:SS, you could use the following function:
FUNCTION YTICKS, axis, index, value
hour = LONG(value)/3600
minute = LONG(value-3600 * hour) / 60
sec = value mod 60
RETURN, STRING(hour, minute, sec, $
FORMAT="(i2.2, ':', i2.2, ':', i2.2)")
END
Then use the call:
PLOT, T, YTICKFORMAT='YTICKS'
TICKLEN
equivalent: !P.TICKLEN.
Controlsthelength of theaxistick marks, expressedasafraction of thewindowsize. The
default valueis0.02. TICKLEN of 1.0producesagrid, whileanegativeTICKLEN makes
tick marks that extend outside the window, rather than inwards.
Example To produce outward-going tick marks of the normal length:
PLOT, X, Y, TICKLEN = -0.02
To provide a new default tick length, set !P.TICKLEN.
[XYZ]TICKLEN
equivalent: ![ XYZ] .TICKLEN.
Thiskeywordcontrolsthelengthsof tick marks(expressedinnormal coordinates) for the
individual axes. This keyword, if nonzero, overrides the global tick length specied in
!P.TICKLEN, and/or the TICKLEN keyword parameter, which is expressed in terms of
the window size.
IDL Reference Guide [XYZ]TICKNAME
[XYZ]TICKNAME
equivalent: ![ XYZ] .TICKNAME.
A string array of up to 30 elements that controls the annotation of each tick mark.
[XYZ]TICKS
equivalent: ![ XYZ] .TICKS.
The number of major tick intervalsto draw for the axis. If this keyword is omitted, IDL
selectsfromthreetosixtick intervals. Settingthiseldton, wheren> 1, producesexactly
n tick intervals, and n+1 tick marks. Setting this eld equal to 1 suppresses tick marks.
[XYZ]TICKV
equivalent: ![ XYZ] .TICKV.
The data values for each tick mark, an array of up to 30 elements. Note: to specify the
number of ticksandtheir valuesexactly, set [ XYZ] TICKS= nand[ XYZ] TICKV = n+ 1,
wheren> 1.
[XYZ]TICK_GET
Accepted by: AXIS, CONTOUR, PLOT, SHADE_SURF, SURFACE.
Anamed variablein which to return thevaluesof thetick marksfor thedesignated axis.
The result is a oating-point array with the same number of elements as ticks.
Example ToretrieveinthevariableVthevaluesof thetick marksselectedbyIDLfor theYaxis:
PLOT, X, Y, YTICK_GET = V
TITLE
equivalent: !P.TITLE.
Produces a main title centered above the plot window. The text size of this main title is
larger than the other text by a factor of 1.25. For example:
PLOT, X, Y, TITLE = 'Final Results'
[XYZ]TITLE
equivalent: ![ XYZ] .TITLE.
A string that contains a title for the specied axis.
ZVALUE IDL Reference Guide
ZVALUE
Accepted by: AXIS, CONTOUR, MAP_SET, OPLOT, PLOT, SHADE_SURF, SURFACE.
SetstheZcoordinate, innormalizedcoordinatesintherangeof 0to1, of theaxisanddata
output from PLOT, OPLOT, and CONTOUR.
This keyword has effect only if !P.T3D is set and the three-dimensional to two-
dimensional transformationisstoredin!P.T. If ZVALUEisnot specied, CONTOURwill
output each contour at its Z coordinate, and the axes and title at a Z coordinate of 0.0.
Z
Accepted by: PLOTS, POLYFILL, TV, TVCRS, XYOUTS.
ProvidestheZ coordinateif aZ parameter isnot present in thecall. Thisisof useonly if
the three-dimensional transformation is in effect (i.e., the T3D keyword is not set).
111
Chapter 8
IDL Graphics Devices
IDL Direct Graphicssupport graphicoutput to thedevicesdescribed in thetablebelow.
Each of thesedevicesisdescribed in asection of thischapter. TheSET_PLOT procedure
can be used to select the graphic device to which IDL directs its output. IDL Object
Graphicsdoesnot relyon theconcept of acurrent graphicsdevice; seeObjectsandObject
Graphicsfor details about IDL Object Graphics.
The DEVICE procedure controls the graphic device-specic functions. An attempt has
been made to isolate all device-specic functions in this procedure.
DEVICE controls the graphics device currently selected by SET_PLOT. When using
DEVICE, it is important to make sure that the current graphics device is the one you
intendtouse. Thisisbecausemost of thedeviceshavedifferent keywordsyouwill most
likelyget aKeyword ... ... not allowed in call to: Device
error if you call DEVICE when the wrong device is selected.
112 Chapter 8: IDL Graphics Devices
Keywords Accepted by the IDL Devices IDL Reference Guide
Keywords Accepted by the IDL Devices
The following table indicates which keywords are accepted by the DEVICE procedure.
TheNULL deviceisnot listed asit acceptsno keywords. Detailsof thevariouskeywords
can be found on the page indicated in the table.
Note Most keywordsto theDEVICEprocedurearesticky that is, onceyou set them,
theyremainineffect until youexplicitlychangethemagain, or endyour IDLsession.
The exceptions are keywords used to return a value from the system
(GET_FONTNAMES, for example) and those that perform a one-time-only opera-
tion (CLOSE_FILE, for example).
Device Name Page Description
CGM 148 Computer Graphics Metale
HP 150 Hewlett-Packard Graphics Language (HP-GL)
LJ 151 Digital Equipment LJ250 (VMS Only)
MAC 154 Macintosh display
NULL 154 No graphics output
PCL 154 Hewlett-Packard Printer Control Language (PCL)
PRINTER 156 System printer
PS 156 PostScript
REGIS 168 Regis graphics protocol (DEC systems only)
TEK 169 Tektronix compatible terminal
WIN 170 Microsoft Windows
X 171 X Window System
Z 178 Z-buffer pseudo device
Table 8-1: IDL Graphics Output Devices
Keywords Page
Devices
C
G
M
H
P
L
J
M
A
C
P
C
L
P
R
I
N
T
E
R
P
S
R
E
G
I
S
T
E
K
W
I
N
XZ
AVANTGARDE 116
AVERAGE_LINES 116
BINARY 116
Chapter 8: IDL Graphics Devices 113
IDL Reference Guide Keywords Accepted by the IDL Devices
BITS_PER_PIXEL 116
BKMAN 116
BOLD 117
BOOK 117
BYPASS_TRANSLATION 117
CLOSE 117
CLOSE_DOCUMENT 117
CLOSE_FILE 117
COLOR 118
COLORS 118
COPY 118
COURIER 118
CURSOR_CROSSHAIR 118
CURSOR_IMAGE 119
CURSOR_MASK 119
CURSOR_ORIGINAL 119
CURSOR_STANDARD 119
CURSOR_XY 120
DECOMPOSED 120
DEMI 121
DEPTH 121
DIRECT_COLOR 121
EJECT 122
ENCAPSULATED 122
ENCODING 123
FILENAME 123
FLOYD 124
FONT 124
FONT_INDEX 124
FONT_SIZE 124
GET_CURRENT_FONT 124
GET_DECOMPOSED 124
GET_FONTNAMES 124
Keywords Page
Devices
C
G
M
H
P
L
J
M
A
C
P
C
L
P
R
I
N
T
E
R
P
S
R
E
G
I
S
T
E
K
W
I
N
XZ
GET_FONTNUM 125
GET_GRAPHICS_FUNC 125
GET_SCREEN_SIZE 125
GET_VISUAL_DEPTH 125
GET_VISUAL_NAME 125
GET_WINDOW_POSITION 126
GET_WRITE_MASK 126
GIN_CHARS 126
GLYPH_CACHE 126
HELVETICA 126
INCHES 126
INDEX_COLOR 126
ISOLATIN1 127
ITALIC 127
LANDSCAPE 127
LIGHT 127
MEDIUM 127
NARROW 127
NCAR 127
OBLIQUE 128
OPTIMIZE 128
ORDERED 129
OUTPUT 129
PALATINO 129
PIXELS 129
PLOT_TO 129
PLOTTER_ON_OFF 129
POLYFILL 130
PORTRAIT 130
PREVIEW 130
PRINT_FILE 131
PSUEDO_COLOR 131
RESET_STRING 131
Keywords Page
Devices
C
G
M
H
P
L
J
M
A
C
P
C
L
P
R
I
N
T
E
R
P
S
R
E
G
I
S
T
E
K
W
I
N
XZ
RESOLUTION 131
RETAIN 132
SCALE_FACTOR 132
SCHOOLBOOK 133
SET_CHARACTER_SIZE 133
SET_COLORMAP 133
SET_COLORS 134
SET_FONT 134
SET_GRAPHICS_FUNCTION 137
SET_RESOLUTION 138
SET_STRING 138
SET_TRANSLATION 139
SET_WRITE_MASK 139
STATIC_COLOR 139
STATIC_GRAY 139
SYMBOL 139
TEK4014 139
TEK4100 140
TEXT 140
THRESHOLD 140
TIMES 140
TRANSLATION 140
TRUE_COLOR 141
TTY 141
USER_FONT 141
VT240 141
VT241 141
VT340 141
VT341 141
WINDOW_STATE 141
XOFFSET 142
XON_XOFF 142
XSIZE 142
Keywords Page
Devices
C
G
M
H
P
L
J
M
A
C
P
C
L
P
R
I
N
T
E
R
P
S
R
E
G
I
S
T
E
K
W
I
N
XZ
Keywords accepted by the DEVICE command are described below. A list of devices that
accept the keyword is included in parentheses below the keyword name.
AVANTGARDE
(PS)
Set this keyword to select the ITC Avant Garde PostScript font.
AVERAGE_LINES
(REGIS)
Controls the method of writing images to the VT240. If this keyword is set, (default
setting), even and odd pairs of image lines are averaged and written to a single line. If
clear, each imagelineiswritten tothescreen. Seethediscussion below. Thiskeyword has
no effect when using a VT300 series terminal.
BINARY
(CGM)
Set this keyword to set the encoding type for the CGM output le to binary.
BITS_PER_PIXEL
(PS)
IDLiscapableof producingPostScript imageswith 1, 2, 4, or 8bitsper pixel. Usingmore
bits per pixel gives higher resolution at the cost of generating larger les.
BITS_PER_PIXEL is used to specify the number of bits to use. If you do not specify a
value of 1, 2, 4, or 8, IDL selects the closest one.
It should benoted that many laser printers, includingtheoriginal AppleLaserwriter are
capable of only 32 different shades of gray (which can be represented by 5 bits). Thus,
specifying8bitsper pixel doesnot give256apparent shadesof greyasmight beexpected,
only32, at acost of sendingtwicethenumber of bitstotheprinter. Often, 4bits(16levels
of gray) will give acceptable results with a large savings in le size.
BKMAN
(PS)
Set this keyword to select the ITC Bookman PostScript font.
YOFFSET 142
YSIZE 143
ZAPFCHANCERY 143
ZAPFDINGBATS 143
Z_BUFFERING 143
Keywords Page
Devices
C
G
M
H
P
L
J
M
A
C
P
C
L
P
R
I
N
T
E
R
P
S
R
E
G
I
S
T
E
K
W
I
N
XZ
BOLD
(PS)
Set thiskeyword to specify that thebold version of thecurrent PostScript font should be
used.
BOOK
(PS)
Set thiskeyword tospecifythat thebook version of thecurrent PostScript font should be
used.
BYPASS_TRANSLATION
(MAC, WIN, X)
Set this keyword to bypass the translation tables, allowing direct specication of color
indices. SeeColor Translation onpage175. Pixel valuesreadviatheTVRDfunctionare
not translated if this keyword is set, and the result contains the byte value of the actual
pixel values present in the display.
Bydefault, thetranslation tablesareusedwith sharedand staticcolor tables. When using
displays with private color tables, the translation tables are bypassed.
ThiskeywordisacceptedbytheWINdevice(for compatibilitywiththeXdevice), but has
no effect when set.
CLOSE
(Z)
Set this keyword to deallocate the memory used by the Z-buffer. The Z-buffer device is
reinitialized if subsequent graphics operations are directed to the device.
CLOSE_DOCUMENT
(PRINTER)
Set this keyword to have IDL send any buffered output to the currently selected printer.
This keyword is applicable only when the printer device is selected. See The Printer
Device on page 156 for details.
CLOSE_FILE
(CGM, HP, LJ, PCL, PS, REGIS, TEK)
Set this keyword to have IDL output any buffered commands and close the current
graphics le.
Caution: Under operatingsystemsother than VMS, if you closetheoutput leand then
causeIDL to producemoreoutput (e.g., by executinganewPLOT command), IDL will
open theleagain, causingthecontentsof therecentlyclosedletobelost. Toavoidthis,
usetheFILENAMEkeyword to specify adifferent lenameor useSET_PLOT to disable
thegraphicsdriver, or besuretoprint theclosed output lebeforecreatingmoreoutput.
See the discussion of printing output les in Printing Graphics Output Files on page
146
COLOR
(PCL, PS)
Set thiskeywordtoenablecolor PCLor PostScript output. See ThePCLDevice onpage
154 or The PostScript Device on page 156.
COLORS
(CGM, TEK)
Thiskeywordspeciesthemaximumnumber of colorsandthesizeof thecolor tableused
for output. The value of the system variable elds !D.N_COLORS and !D.TABLE_SIZE
are set to this value and !P.COLOR is set to one less than this value.
For Tektronix Terminals Only
Thiskeywordsetsthenumber of colorssupportedbya4100seriesterminal. For example,
if your terminal has 4-bit planes, the number of colors is 2
4
= 16:
DEVICE, COLORS = 16
Valid values of this parameter are: 2, 4, 8, 16, or 64; other values will cause problems.
Some Tektronix terminals will not operate properly if this parameter does not exactly
match the number of colors available in the terminal hardware.
Thisparameter setstheeld!D.N_COLORS, whichaffectstheloadingof color tables, the
scaling used by the TVSCL procedure, and the number of bits output by the TV
procedureto theterminal. It also changesthedefault color, !P.COLORto thenumber of
colors minus one.
COPY
(MAC, WIN, X)
Use this keyword to copy a rectangular area of pixels from one region of a window to
another. COPY should be set a six or seven element array: [ X
s
, Y
s
, N
x
, N
y
, X
d
, Y
d
, W] ,
where: (X
s
, Y
s
) isthelower left corner of thesourcerectangle, (N
x
, N
y
) arethenumber of
columns and rows in the rectangle, and (X
d
, Y
d
) is the coordinate of the destination
rectangle. Optionally, Wistheindex of thewindowfromwhichthepixelsshouldbecopied
tothecurrentwindow. If it isnot supplied, thecurrent windowisused asboth thesource
and destination.
COURIER
(PS)
Set this keyword to select the Courier PostScript font.
CURSOR_CROSSHAIR
(WIN, X)
Set this keyword to selects the crosshair cursor type. This is the IDL default.
CURSOR_IMAGE
(X)
Species the cursor pattern. The value of this keyword must be a 16-line by 16-column
bitmap, contained in a 16-element short integer vector. The offset from the upper left
pixel tothepoint that isconsidered the hot spot can beprovided viatheCURSOR_XY
keyword.
CURSOR_MASK
(X)
When the CURSOR_IMAGE keyword is used to specify a cursor bitmap, the
CURSOR_MASKkeywordcanbeusedtosimultaneouslyspecifythemask that shouldbe
used. In the mask, bits that are set indicate bits in the CURSOR_IMAGE that should be
seen and bits that are not set are masked out.
By default, theCURSOR_IMAGEbitmap isused for both theimageand themask. This
can causethecursor to beinvisibleon ablack background (becauseonly black pixelsare
allowed to be displayed).
CURSOR_ORIGINAL
(MAC, WIN, X)
Set thiskeyword toselect thewindowsystemsdefault cursor. Under XWindows, it isthe
cursor in use by the root window when IDL starts. For the Macintosh and Microsoft
Windows devices, it is the arrow pointer.
CURSOR_STANDARD
(MAC, WIN, X)
This keyword can be used to change the appearance of the cursor in IDL graphics
windows.
For X Windows
This keyword selects one of the predened cursors provided by the X Window system.
Theavailablecursorsshapesaredened in thelecursorfonts.h in thedirectory
/usr/include/X11 (Unix), or DECW$INCLUDE: (VMS). In order to use one
of these cursors, you select the number of the cursor and provide it as the value of the
CURSOR_STANDARD keyword. For example, the le gives the value of XC_CROSS as
being 30. In order to make that the current cursor, use the statement:
DEVICE, CURSOR_STANDARD=30
For Microsoft Windows
The table below shows the values for CURSOR_STANDARD that result in different
cursor shapes. For example, tochangethecursor toan I-beam when thecursor isin an
IDL graphics window, use the command:
DEVICE, CURSOR_STANDARD = 32513
For Macintosh
Setting the CURSOR_STANDARD keyword changes the cursor to a crosshair in IDL
graphics windows.
CURSOR_XY
(X)
A two element integer vector giving the (X, Y) pixel offset of the cursor hot spot, the
point which is considered to be the mouse position, from the lower left corner of the
cursor image. This parameter is only applicable if CURSOR_IMAGE is provided. The
cursor image is displayed top-downthe rst row is displayed at the top.
DECOMPOSED
(MAC, WIN, X)
This keyword is used to control the way in which graphics color index values are
interpreted when using displays with decomposed color (TrueColor or DirectColor
visuals). This keyword has no effect with other types of visuals.
Set thiskeywordto1tocausecolor indicestobeinterpretedas3, 8-bit color indiceswhere
the least-signicant 8 bits contain the red value, the next 8 bits contain the green value,
and the most-signicant 8 bits contain the blue value. This is the way IDL has always
interpreted pixels when using visual classes with decomposed color.
Cursor Shape Value
Arrow 32512
I-Beam 32513
Hourglass 32514
Black Crosshair 32515
Up Arrow 32516
Size (Windows NT only) 32640
Icon (Windows NT only) 32641
Size NW-SE 32642
Size NE-SW 32643
Size E-W 32644
Size N-S 32645
Table 8-2: Values for the
WIN device CURSOR_STANDARD
keyword
Set this keyword to 0 to cause the least-signicant 8 bits of the color index value to be
interpreted as a PseudoColor index. This setting allows users with DirectColor and
TrueColor displays to use IDL programs written for standard, PseudoColor displays
without modication.
In older versionsof IDL, color indexvalueshigher than !D.N_COLORS-1wereclippedto
!D.N_COLORS-1inthehigher level graphicsroutines. Insomecases, thisclippingcaused
the exclusive-OR graphics mode to malfunction with raster displays. This clipping has
been removed. Programs that incorrectly specied color indices higher than
!D.N_COLORS-1 will now probably exhibit different behavior.
DEMI
(PS)
Set thiskeyword tospecifythat thedemi version of thecurrent PostScript font should be
used.
DEPTH
(LJ)
The DEPTH keyword species the number of signicant bits in a pixel. The LJ250 can
support between 1and4signicant bits(known alsoasplanes). Thenumber of available
colors is related to the number of signicant planes by the equation:
Colors = 2
#planes
Therefore, theLJ250can support 2, 4, 8, or 16separatecolorson asinglepageof output.
The default is to use a single plane, producing monochrome output.
SinceIDL isbased around 8-bit pixels, it isnecessary to denewhich bitsin a8-bit pixel
are used by the LJ250 driver, and which are ignored. When using a depth of 1
(monochrome), ditheringtechniquesareusedtorender images. In thiscase, all 8bitsare
used. If more than a single plane is used, the least signicant n bits of a 8-bit pixel are
used, wheren istheselecteddepth. For example, usingadepthof 4, pixel valuesof 15, 31,
and 47 are all considered to have the value 15 because all three values have the same
binary representation in their 4 least signicant digits.
When thedepth ischanged, thestandardcolor mapgiven in Table7-5of theLJ250/LJ252
Companion Color Printer Programmer ReferenceManual is automatically loaded.
Therefore, color maps should be loaded with TVLCT after changing the depth.
DIRECT_COLOR
(X)
Set thiskeyword toselect theDirectColor visual. Thevalueof thekeyword representsthe
number of bits per pixel. This keyword has effect only if no windows have been created.
Visual classes are discussed in more detail in X Windows Visuals on page 171
EJECT
(HP)
In order to performan eraseoperation on aplotter, it isnecessary to removethecurrent
sheet of paper and load a fresh sheet. The ability of various plotters to do this varies, so
the EJECT keyword allows you to specify what should be done. Table 8-3 describes the
possible values.
Many HP-GL plotters lack a sheet feeder, and require the user to load the next page
manually. Therefore, thedefault action isfor IDLtonot issueanypageeject instructions.
In this case, you must restrict yourself to generating only a single plot at a time. If your
plotter has a sheet feeder, you will want to issue the command:
DEVICE, /EJECT
to tell IDL that it should use the sheet feeder instead of placing the plotter off-line.
If your plotter does not have a sheet feeder, but it does understand the HP-GL NR
command, use the command:
DEVICE, EJECT=2
to place the plotter off-line at the start of every plot except the rst one. This causes the
plotter to wait between plots for the user to replace the paper. When the user puts the
plotter back on-line, thegraphicscommandsfor thenewpageareexecutedbytheplotter.
Consult the programming manual for your plotter to determine if this instruction is
provided.
ENCAPSULATED
(PS)
Set this keyword to create an encapsulated PostScript le, suitable for importing into
another document (e.g., a LaTeX or FrameMaker document).
Note Youmust explicitlyset thiskeywordtozerotocreateregular PostScript output after
creating encapsulated output. (That is, like most keyword settings to the DEVICE
procedure, the setting sticks until you change it, or until you quit IDL.)
Value Meaning
0 Do nothing. Note that this is likely to cause one page to plot over the previ-
ous one, so you should limit yourself to one page of output per le. This is
the default.
1 Use the sheet feeder to load the next page.
2 Put the plotter off-line at the beginning of each page after the rst.
Table 8-3: Values for the HP-GL Eject Keyword
Normally, IDL assumes that its PostScript-generated output will be sent directly to a
printer. It therefore includes PostScript commands to position the plot on the page and
toeject thepagefromtheprinter. Thesecommandsareundesirableif theoutput isgoing
to be inserted into the middle of another PostScript document. If ENCAPSULATED is
present and non-zero, IDL does not generate these commands.
IDL follows the standard PostScript convention for encapsulated les. It assumes the
standard PostScript scaling is in effect (72 points per inch), In addition, it declares the
size, or bounding box of the plotting region at the top of the output le. This size is
determined when the output le is opened (when the rst graphics command is given),
by multiplying the size of the plotting region (as specied with the XSIZE and YSIZE
keywords) by the current scale factor (as specied by the SCALE_FACTOR keyword).
Changing the size of the plotting region or scale factor once graphics have been output
will not be reected in the declared bounding box, and will confuse programs that
attempt to import the resulting graphics. Therefore, when generating encapsulated
PostScript, do not change the plot region size or scaling factor once any graphics
commandshavebeen issued. If youneedtochangetheseparameters, usetheFILENAME
keyword to start a new le.
ENCODING
(CGM)
Set this keyword to set the CGM encoding type for the output le. Valid values are: 1
(binary encoding, the default), 2 (text encoding), and 3 (NCAR binary encoding). The
encoding type can only be changed when there is no CGM le open.
FILENAME
(CGM, HP, LJ, PCL, PS, REGIS, TEK)
Normally, all generated output is sent to a le named idl.xxx wherexxx is the
lowercasenameof thedeviceshown in Table8-1. TheFILENAMEkeyword can beused
to change these defaults. If FILENAME is specied:
1. If the le is already open (as happens if plotting commands have been directed to the
lesincethecall to SET_PLOT), then theleiscompleted and closed asif CLOSE_FILE
had been specied.
2. The specied le is opened for subsequent graphics output.
HP-GL Only
Under Unix, if youwishtosendHP-GLoutput directlytoaplotter without generatingan
intermediatele, you shouldspecifythedevicespecial lefor theplotter astheargument
to FILENAME. For example, if your plotter is connected to a serial input/output port
known on your system as/dev/ttya, you would issue the command:
DEVICE, FILENAME='/dev/ttya'
All subsequent HP-GL output is sent directly to the plotter connected to serial port
/dev/ttya.
FLOYD
(LJ, MAC, PCL, X)
Set this keyword to select the Floyd-Steinberg method of dithering. This algorithm
distributes the error, due to displaying intermediate shades in either black or white, to
surroundingpixels. Thismethodgenerallygivesthemost pleasingresultsbut requiresthe
most computer time.
FONT
(MAC, WIN, X)
ThiskeywordisnowobsoleteandhasbeenreplacedbytheSET_FONT keyword. Codethat
usestheFONT keywordwill continuetofunctionasbefore, butwesuggestthatall newcode
useSET_FONT.
FONT_INDEX
(PS)
An integer representing the font index to be mapped to the current PostScript font.
Normally thefont specication keywords(AVANTGARDE, etc.) takeeffect immediately
tochangethecurrent font. TheFONT_INDEXkeywordaltersthisbehavior. Thecurrent
font isnot changed. Instead, thespeciedfont ismappedtothespeciedfont index. This
mapping can then be used within text strings to change the font in the middle of the
string. See Using PostScript Fonts on page158.
FONT_SIZE
(PS)
The default height used for displayed text. FONT_SIZE is given in points (a common
typesetting unit of measure). The default size is 12 point text.
GET_CURRENT_FONT
(MAC, PRINTER, WIN, X)
Set thiskeyword toanamed variablein which thenameof thecurrent font isreturned as
a scalar string. A null string is returned if the Windows font is the default font. If the
current device is PRINTER, the current printer font is returned.
GET_DECOMPOSED
(MAC, WIN, X)
Set this keyword to a named variable in which is returned the current state of the
decomposed ag in the current direct graphics device.
GET_FONTNAMES
Set this keyword to a named variable in which a string array containing the names of
available fonts is returned. If no fonts are found, a null scalar string is returned. This
keyword must be used in conjunction with the FONT keyword. Set the FONT keyword
to a scalar string containing the name of the desired font or a wildcard.
GET_FONTNUM
Set this keyword to a named variable in which the number of fonts available to your
installation is returned. This keyword must be used in conjunction with the FONT
keyword. Set theFONTkeywordtoascalar stringcontainingthenameof thedesiredfont
or a wildcard.
GET_GRAPHICS_FUNCTION
(MAC, WIN, X, Z)
Set this keyword to a named variable that returns the value of the current graphics
function (which is set with the SET_GRAPHICS_FUNCTION keyword). This can be
used to remember thecurrent graphicsfunction, changeit temporarily, and then restore
it. See the SET_GRAPHICS_FUNCTION keyword for an example.
GET_SCREEN_SIZE
(MAC, WIN, X)
Set this keyword to a named variable in which to return a two-word array that contains
the width and height of the servers screen, in pixels.
Note For the Macintosh, anchoring the Command Input Line reduces the amount of
available screen space.
GET_VISUAL_DEPTH
(MAC, WIN, X)
Set thiskeyword toanamed variableintowhich alonginteger isreturned containingthe
depth of thevisual associated with thisdevice. Under X, if theXserver isnot connected
when you call the DEVICE procedure with this keyword set, a new connection is made.
GET_VISUAL_NAME
(MAC, WIN, X)
Set thiskeyword equal to anamed variablein which astringcontainingthenameof the
current visual class IDL is using is returned. Possible return values are:
StaticGray (X only)
GrayScale (X only)
StaticColor (X only)
PseudoColor
TrueColor
DirectColor (X only)
Under X, if no connection to the X server has been established when the DEVICE
procedure is called with this keyword set, a new connection is made.
GET_WINDOW_POSITIONrf
(MAC, WIN, X)
Set this keyword to a named variable that returns a two-element array containing the
(X,Y) position of thelower left corner of thecurrent windowon thescreen. Theorigin is
also in the lower left corner of the screen.
GET_WRITE_MASK
(WIN, X)
Species the name of a variable to receive the current value of the write mask.
GIN_CHARS
(TEK)
Thenumber of charactersIDL istoread when acceptingaGIN (GraphicsINput) report.
Thedefault is5. If your terminal isconguredtosendacarriagereturn at theendof each
GIN report, set thisparameter to6. If thenumber of GIN charactersistoolarge, theIDL
CURSORprocedurewill not respond until two or morekeysarestruck. If it istoo small,
the extra characters sent by the terminal will appear as input to the next IDL prompt.
GLYPH_CACHE
(MAC, PRINTER, PS, WIN, Z)
Set this keyword to a scalar specifying the maximum number of glyphs to cache at any
given time. The rst time a glyph from a TrueType font is used, it is tessellated into
triangles. These triangles are cached so that the tessellation step is not repeated for each
useof that glyph. If theglyphcachells, theleast usedglyphwill bereleasedbeforeanew
glyph is generated and cached. The default is 256.
HELVETICA
(PS)
Set this keyword to select the Helvetica PostScript font.
INCHES
(HP, LJ, PCL, PRINTER, PS)
Normally, the XOFFSET, XSIZE, YOFFSET, and YSIZE keywords are specied in
centimeters. However, if INCHESispresent and non-zero, they aretaken to bein inches
instead.
INDEX_COLOR
(PRINTER)
Set thiskeyword to placetheprinter devicein index color mode. Thisisthedefault. This
keyword is applicable only when the printer device is selected. See The Printer Device
on page 156 for details.
ISOLATIN1
(PS)
Set thiskeywordtouseAdobeISOLatin 1font encodingwithanyfont that supportssuch
coding. Use of this keyword allows access to many commonly-used foreign characters.
ITALIC
(PS)
Set thiskeyword to specify that theitalicversion of thecurrent PostScript font should be
used.
LANDSCAPE
IDL normally generates plots with portrait orientation (the abscissa is along the short
dimension of the page). If the LANDSCAPE keyword is set, landscape orientation
(abscissaalongthelongdimensionof thepage) isusedinstead. Notethat explicitlysetting
LANDSCAPE=0 is the same as setting the PORTRAIT keyword.
If thecurrent deviceisPRINTER, and apageisopen in theprinter, it isclosed and anew
page set to landscape layout is started.
Note The ability to set a printer to landscape mode is printer-driver dependent. Your
printer may not support this functionality; use the system native print setup dialog
to set the orientation of the print job.
LIGHT
(PS)
Set thiskeyword to specify that thelight version of thecurrent PostScript font should be
used.
MEDIUM
(PS)
Set thiskeywordtospecifythat themediumversion of thecurrent PostScript font should
be used.
NARROW
(PS)
Set thiskeyword to specify that thenarrowversion of thecurrent PostScript font should
be used.
NCAR
(CGM)
Set this keyword to set the encoding type for the CGM output le to NCAR binary.
The NCAR Binary Encoding
The NCAR binary encoding is used exclusively by the NCAR graphics package. Version
3.01of NCARView(ctrans, ictrans, andcgm2ncgm) doesnot correctlyhandle
the following graphic elements:
Cell arrays (raster images) with an odd number of pixels in the X dimension. Solution:
specify an even number of pixels for the X dimension or make the image one column
wider and ll with zeros.
Raster imagesdrawn in top down order. Solution: invert theimageprior to usingTV or
TVSCL and do not use the /ORDER keyword. For example:
TV, image
TV, ROTATE(image, 7) Draw imagetop to bottom.
OBLIQUE
(PS)
Set thiskeyword to specify that theobliqueversion of thecurrent PostScript font should
be used.
OPTIMIZE
(PCL)
It is desirable, though not always possible, to compress the size of the PCL output le.
Such optimization reduces the size of the output le, and improves I/O speed to the
printer. There are three levels of optimization:
0. No optimization is performed. This is the default because it will work with any PCL
device. However, usersof deviceswhich can support optimization should useoneof the
other optimization levels.
1. Optimization is performed using PCL optimization primitives. This gives the best
output compression and printing speed. Unfortunately, not all PCL devices support it.
On those that cant, the result will be garbage printed on the page.
Consult theprogrammersmanual for your printer to determineit supportstherequired
escapesequences. Therequiredsequencesare: <ESC>*b0M(select full graphicsmode),
<ESC>*b1M (select compacted graphics mode 1), and <ESC>*b2M (select
compacted graphics mode 2). The HP LaserJet II does not support this optimization
level. The DeskJet PLUS does.
2. IDL attempts to optimize the output by explicitly moving the left margin and then
outputting non-blank sections of the page. This is primarily intended for use with the
LaserJet II, which doesnot support optimization level 1. Note: Thisoptimization can be
veryslowon somedevices(suchastheDeskJet PLUS). On suchdevices, it isbest toavoid
this optimization level.
ORDERED
(LJ, MAC, PCL, X)
Set thiskeyword to select theordered dither method. Thisintroducesapseudo-random
error into the display by using a 4 by 4 dither matrix, yielding 16 apparent intensities.
This is the default method.
Macintosh Only
This keyword is identical to the THRESHOLD keyword.
OUTPUT
(HP, PS)
Species a scalar string that is sent directly to the graphics output le without any
processing, allowingtheuser to send arbitrary commandsto thele. SinceIDL doesnot
examinethestring, it istheusersresponsibilitytoensurethat thestringiscorrect for the
target device.
PALATINO
(PS)
Set this keyword to select the Palatino PostScript font.
PIXELS
(LJ, PCL)
Normally, the XOFFSET, XSIZE, YOFFSET, and YSIZE keywords are specied in
centimeters. However, if thePIXELSkeyword isset, theyaretaken tobein pixelsinstead.
Notethat theselected resolution will determinehowlargearegion isactually written on
the page.
PLOT_TO
(REGIS, TEK)
DirectstheTektronix graphicoutput that wouldnormallygototheusersterminal tothe
specied I/Ounit. Thelogical unit specied should beopen with writeaccessto adevice
or le. Graphic output may be saved in les for later playback, redirected to other
terminals, or to devices that can accept Textronix graphic commands.
Do not use the interactive graphics cursor when graphic output is not directed to your
terminal.
To direct thegraphicdatato both theterminal and thele, set theunit to thenegativeof
the actual unit number. Alternatively, you can use the TTY keyword, described below.
If the specied unit number is zero then Tektronix output to the le is stopped.
PLOTTER_ON_OFF
(HP)
There are some congurations in which a HP-GL plotter is connected between the
computer and a terminal. In this mode (known as eavesdrop mode), the plotter ignores
everythingit issent andpassesit throughtotheterminaltheplotter islogicallyoff. This
statecontinuesuntil an escapesequenceissent that turnstheplotter logically on. At this
point theplotter interpretsand executesall input asHP-GL commands. Another escape
sequenceissent at theend of theHP-GL commandsto return theplotter to thelogically
off state.
Most congurations do not use eavesdrop mode, and the plotter is always logically on.
However, if you areusingthisstyleof connection, you must usePLOTTER_ON_OFFto
instruct IDL to generate the necessary on/off commands. If present and non-zero,
PLOTTER_ON_OFF causes each output page to be bracketed by device control
commandsthat turn theplotter logically on and off. Specifyingavalueof zero stopsthe
issuingof such commands. You shouldonlyusethiskeywordbeforeanyoutput hasbeen
generated.
POLYFILL
(HP)
Some plotters (e.g., HP7550A) can perform polygon lling in hardware, while others
(e.g., HP7475) cannot. IDL therefore assumes that the plotter cannot, and generates all
polygon operations in software using line drawing. Specifying a non-zero value for the
POLYFILL keyword causes IDL to use the hardware polygon lling. Setting it to zero
reverts to software lling.
Different implementationsof HP-GLplottersmayhavedifferent limitsfor thenumber of
verticesthat can bespecied for apolygon region beforetheplotter runsout of internal
memory. Sincethislimit can vary, theHP-GL driver cannot check for callsto POLYFILL
that specify too many points. Therefore, it is possible for the user to produce HP-GL
output that causesan error when sent totheplotter. Toavoidthissituation, minimizethe
number of pointsused. OntheHP7550A, thelimit isabout 127points. If youdogenerate
output that exceedsthelimit imposedbyyour plotter, youwill havetobreak that polygon
lling operation into multiple smaller operations.
PORTRAIT
Set the PORTRAIT keyword to generate plots using portrait orientation. Portrait
orientation isthedefault. Notethat explicitlysettingPORTRAIT=0isthesameassetting
the LANDSCAPE keyword.
If thecurrent deviceisPRINTER, and apageisopen in theprinter, it isclosed and anew
page set to portrait layout is started.
Note Theabilitytoset aprinter toportrait modeisprinter-driver dependent. Your printer
maynot support thisfunctionality; usethesystemnativeprint setupdialogtoset the
orientation of the print job.
PREVIEW
(PS)
Set thiskeyword to 1to add aplatform-independent preview to thePostScript output
le in encapsulated PostScript interchange format (EPSI). EPSI is an ASCII format. Set
this keyword to 2 to write the EPS le in EPSF format, including an on-screen preview
that issupported by many windowsapplications, e.g. MSWord. Thedefault (0) isto not
include a preview.
Note EPSFisnot anASCII format andcannot besent directlytoaPostscript printer, unlike
the EPSI format. It must be imported into an application for printing.
PRINT_FILE
(WIN)
Set thiskeyword to thenameof ale(e.g., PostScript or PCL) to besent to thecurrently-
selectedWindowsprinter. IDLperformsnotypecheckingon thislebeforesendingit to
the printer. Therefore, if you have a PostScript printer selected and you send a le that
contains no valid PostScript information, youll simply get text output.
To send the le MYFILE.PS to the currently-selected Windows printer, enter:
DEVICE, PRINT_FILE='MYFILE.PS'
PSEUDO_COLOR
(MAC, X)
If this keyword is present, the PseudoColor visual is used. The value of the keyword
represents the number of bits per pixel to be used. This keyword has effect only if no
windows have been created. Visual classes are discussed in more detail in X Windows
Visuals on page 171
Macintosh Only
Settingthiskeyword causesall screen manipulationstobedonein 8-bit mode. Thevalue
of the keyword is ignored, as is the current bit-depth of the monitor.
RESET_STRING
(TEK)
Thestringusedtoplacetheterminal back intothenormal interactivemodeafter drawing
graphics. Usethisparameter, in conjunction with theSET_STRINGkeyword, to control
the mode switching of your terminal.
For example, the GraphON 200 series terminals require the string<ESC>2 to activate
the alphanumeric window after drawing graphics. The call to set this is:
DEVICE, RESET = string(27b) + '2'
If the 4100 series mode switch is set, using the keyword TEK4100, the default mode
resetting string is<ESC>%!1, which selects the ANSI code mode.
RESOLUTION
(LJ, PCL)
PCL Only
Theresolution at which thePCL printer will work. PCL supportsresolutionsof 75, 100,
150, and 300dotsper inch. Thedefault is300dpi. Lower resolution givessmaller output
les, while higher resolution gives superior quality.
LJ250 Only
The resolution at which the LJ printer will work. LJ supports resolutions of 90 and 180
dots per inch. The default is 180 dpi. Lower resolution gives smaller output les and a
larger selection of colors, while higher resolution gives superior quality.
RETAIN
(MAC, WIN, X)
Usethiskeyword tospecifythedefault method used for backingstorewhen creatingnew
windows. This is the method used when the RETAIN keyword is not specied with the
WINDOWprocedure. Backingstoreisdiscussedinmoredetail under BackingStore on
page144Thepossiblevaluesfor thiskeyword aresummarized in Table8-5. If RETAIN is
not used tospecify thedefault method, method 1(server-supplied backingstore) isused.
Microsoft Windows Only
Theinitial valueof thisparameter can beset byselectingFile-Preferencesfromthemenu
bar. See Backing Store on page144.
A Note on Reading Data from Windows
On some systems, when backing store is provided by the window system (RETAIN=1),
reading data from a window using TVRD may cause unexpected results. For example,
datamay beimproperly read fromthewindoweven when theimagedisplayed on screen
is correct. Having IDL provide the backing store (RETAIN=2) ensures that the window
contentswill bereadproperly. Thesetypesof problemsaredescribedinmoredetail inthe
documentation for TVRD. See Unexpected Results Using TVRD with X Windows on
page1162.
SCALE_FACTOR
(PRINTER, PS)
Speciesascalefactor applied totheentireplot. Thedefault valueis1.0, allowingoutput
to appear at itsnormal size. SCALE_FACTORisused to magnify or shrink theresulting
output.
The SCALE_FACTOR keyword behaves slightly differently in the context of the
PRINTER device than it does in the context of the PS device.
When the current device is PRINTER, the SCALE_FACTOR keyword is designed to
emulateascalableresolution settingon theprinter. For example, if you havea300x 300
pixel imagestored in the variableimagethe following IDL commands will print
imagein a 0.5 inch square on a 600 dpi printer:
SET_PLOT, printer
TV, image
SettingSCALE_FACTORto 2will scaletheimageto a1inch squareon thesame600dpi
printer:
SET_PLOT, printer
DEVICE, SCALE_FACTOR=2
TV, image
The output of IDLs Direct Graphics routines (CONTOUR, PLOT, SURFACE, etc.) is
automatically scaled to ll the available drawing area. As a result, the following IDL
commands will produce two identical copies of the same output on any printer:
SET_PLOT, printer
PLOT, data
DEVICE, SCALE_FACTOR=2
PLOT, data
SCHOOLBOOK
(PS)
Set this keyword to select the New Century Schoolbook PostScript font.
SET_CHARACTER_SIZE
(CGM, HP, LJ, MAC, PCL, PRINTER, PS, REGIS, TEK, WIN, X, Z)
Set this keyword equal to a two-element vector to specify the font size and line spacing
(leading) of vector andTrueTypefonts, andthelinespacingof devicefonts. Thewaythat
the value of this vector determines character size is not completely intuitive.
The vector specied to the SET_CHARACTER_SIZE keyword sets the values of the
X_CH_SIZE and Y_CH_SIZE elds in the !D System Variable structure. These values
describethesizeof therectanglethat containstheaverage character in thecurrent font.
(It is not important what the average character is; it is used only to calculate a scaling
factor that will be applied to all of the characters in the font.) The rst element species
the width of the rectangle in device units (usually pixels), and the second element
species the height.
For vector andTrueTypefonts, theheight of theaverage character isdeterminedbythe
width of the rectangle. The aspect ratio of the average character remains xed; the
character isscaledsothat itswidthtsinthespeciedrectangle. Theresultingscalefactor
is then applied to all of the characters in the font. The amount of spacing between lines
(baseline to baseline) is determined explicitly by the height of the rectangle.
For devicefonts, thecharacter sizeisxed. When thedevicefont systemisin use, therst
element of thevector specied to SET_CHARACTER_SIZEissilently ignored, and only
the line-spacing value is used.
Note Changingbetween font systems(and sometimeschangingfromonefont to another
within thesamefont system) can alsochangethe!Dstructure, sodonot assumethat
the character size you have set is preserved when you change fonts.
SET_COLORMAP
(PCL)
Set this keyword to a 14,739 (= 3 17
3
) element byte vector containing the RGB-to-
printer color translation table for a color PCL printer. The default table is for an HP
Deskjet 500C printer.
Thetranslation tableisdivided into red, green, and blueplanesof 4913(=17
3
) elements
each. For a given RGB triple, the offset into each plane is calculated as follows:
Offset = (Red/16)*289 + (Green/16)*17 + (Blue/16)
Thus, if the RGB triple is [ 16,32,160] , the offset into each plane is 333. The printer will
usethevalueat element 332of thetranslation tableasthered value, thevalueat element
5245(=4913+332) asthegreen value, andthevalueat element 10158(=9826+332) asthe
blue value.
Thefollowingexampleshowshowtoscalean existingcolortablefor usebyaPCL printer.
SET_PLOT, X Set theplot window to theX de-
vice.
WINDOW,0,XS=300,YS=300 Createa window.
LOADCT,13 Load a color table.
TVLCT,r,g,b,/GET Read color tablevalues into vari-
ables.
r2=CONGRID(r,4913) Re-sizecolor tablevariables.
g2=CONGRID(g,4913)
b2=CONGRID(b,4913)
colormap=[r2,g2,b2] Create14,739-elementcolormap.
SET_PLOT, 'PCL' Changeto thePCL device.
DEVICE, FILE = 'pcl.pcl', RESOLUTION = 300, $
/COLOR, SET_COLORMAP = colormap
Set filename, resolution, color,
and color map.
TVSCL,DIST(900) Display an image.
DEVICE,/CLOSE Closethedevice.
Note The color table used need not be one of IDLs predened tables.
SET_COLORS
(Z)
Setsthenumber of pixel values, !D.N_COLORSand !D.TABLE_SIZE. Thisvalueisused
by a number of IDL routines to determine the scaling of pixel data and the default
drawingindex. Allowablevaluesrangefrom2to256, andthedefault valueis256. Usethis
parameter to make the Z-buffer device compatible with devices with fewer than 256
colors indices.
SET_FONT
(MAC, PRINTER, PS, WIN, Z)
Set thiskeyword to ascalar stringspecifyingthenameof thefont used when ahardware
or TrueType font is selected. Note that hardware fonts cannot be rotated, scaled, or
projected, and that the "!" commands for formatting may not work. When generating
three-dimensional plots, it is best to use the vector-drawn or TrueType characters. Note
that for thePSdevice, onlyonehardwarefont (other than thepredenedfontsset viathe
fontname keywords, such as /AVANTEGARDE) may be loaded at a time.
Note on the FONT Keyword
The SET_FONT keyword was introduced with IDL version 5.1 and replaces the FONT
and USER_FONT keywords used in previous versions.
Using TrueType Fonts
For TrueTypefonts, thespecied font namemust exactly match oneof thenamesin the
rst column of thettfont.map le in theresource/fonts/tt directory or (on
Macintosh and Windows platforms)the name of an installed font. See About the
TrueType Fonts on page 68 for details on thettfont.map le and for a listing of
TrueTypefontsdistributedwithIDL. Notethat youmust includetheTT_FONTkeyword
to indicatethat thefont specied isaTrueTypefont. For example, thefollowingsetsthe
font to the font to the TrueType font Helvetica Bold Italic:
DEVICE, SET_FONT='Helvetica-BoldItalic', /TT_FONT
Note You can append additional TrueType fonts to thettfont.map le if desired; on
MacintoshandWindowsplatforms, additional fontscanalsobeaddedviathenormal
font installationproceduresfor your system. ResearchSystemscannot guaranteethat
TrueTypefontsyou add will besatisfactorily tessellated or displayed. SeeAbout the
TrueType Fonts on page 68 for details.
Using Hardware Fonts
Because device fonts are specied differently on different platforms, the synatax of the
fontnamestring depends on which platform you are using.
Unix and VMS
Usually, the window system provides a directory of font les that can be used by all
applications. List thecontentsof that directorytondthefontsavailableon your system.
The size of the font selected also affects the size of vector drawn text. X Windows users
can use thexlsfonts command to list available X Windows fonts.
On some machines, fonts are kept in subdirectories of /usr/lib/X11/fonts.
For example, to select the font 8X13:
!P.FONT = 0
DEVICE, SET_FONT = '8X13'
Microsoft Windows
1
*modifier
2
*...modifier
n
"
For font weight: THIN, LIGHT, BOLD, HEAVY
For font quality: DRAFT, PROOF
For font pitch: FIXED, VARIABLE
For strikeout text: STRIKEOUT
For font size: Any number is interpreted as the font height in pixels.
For example, if you have Garamond installed as one of your Windows fonts, you could
select 24-pixel cell height Garamond italic as the font to use in plotting. The following
commandstell IDL to usehardwarefonts, changethefont, and then makeasimpleplot:
!P.FONT = 0
DEVICE, SET_FONT = "GARAMOND*ITALIC*24"
PLOT, FINDGEN(10), TITLE = "IDL Plot"
Thisfeatureiscompatiblewith TrueTypeand AdobeTypeManager (and, possibly, other
type scaling programs for Windows). If you have TrueType or ATM installed, the
TrueType or PostScript outline fonts are used so that text looks good at any size.
Macintosh
1
*modifier
2
*...modifier
n
"
For font weight: BOLD
For font width: CONDENSED, EXTENDED
For outlined text: OUTLINE, SHADOW
For font size: Any number is interpreted as the font size, in points.
For example, if you haveGaramond installed, you could select 24-point Garamond italic
as the font to use in plotting. The following commands tell IDL to use hardware fonts,
change the font, and then make a simple plot:
IDL> !P.FONT = 0
IDL> DEVICE, SET_FONT = "GARAMOND*ITALIC*24"
IDL> PLOT, FINDGEN(10), TITLE = "IDL Plot"
SET_GRAPHICS_FUNCTION
(MAC, WIN, X, Z)
Most windowsystemsallowapplicationstospecifythegraphicsfunction. Thisisalogical
function which species how the source pixel values generated by a graphics operation
are combined with the pixel values already present on the screen. The complete list of
possible values is given in Table 8-4. The default graphics function is GXcopy, which
causes new pixels to completely overwrite any previous pixels. Not all functions are
available on all window systems.
For example, thefollowingcodesegment invertsthebottombit in therectangledened
by its diagonal corners (x
0
, y
0
) and (x
1
, y
1
):
DEVICE, GET_GRAPHICS_FUNCTION = oldg, SET_GRAPHICS_FUNCTION = 6
Set graphics function to exclusive
or (GXor), and savetheold func-
tion.
Logical Function Code Denition
GXclear 0 0
GXand 1 source AND destination
GXandReverse 2 source AND (NOT destination)
GXcopy 3 source
GXandInverted 4 (NOT source) AND destination
GXnoop 5 destination
GXxor 6 source XOR destination
GXor 7 source OR destination
GXnor 8 (NOT source) AND (NOT destination)
GXequiv 9 (NOT source) XOR destination
GXinvert 10 (NOT destination)
GXorReverse 11 source OR (NOT destination)
GXcopyInverted 12 (NOT source)
GXorInverted 13 (NOT source) OR destination
GXnand 14 (NOT source) OR (NOT destination)
GXset 15 1
Table 8-4: Graphic Function Codes
POLYFILL, [[x0,y0], [x0,y1], [x1,y1], [x1,y0]], $
/DEVICE, COLOR=1 UsePOLYFILLtoselecttheareato
beinverted.Thesourcepixel value
is 1.
DEVICE, SET_GRAPHICS_FUNCTION=oldg Restoretheprevious graphics
function.
SET_RESOLUTION
(Z)
Set this keyword to a two-element vector that species the width and height of the Z-
buffers. The default size is 640 by 480. If this size is not the same as the existing buffers,
the current buffers are destroyed and the device is reinitialized.
SET_STRING
(TEK)
Thestringusedtoplacetheterminal intothegraphicsmodefromthenormal interactive
terminal mode. If the 4100 series mode switch is set, using the keyword TEK4100, the
default graphic mode setting string is<ESC>%!0, which selects the Tektronix code
mode.
SET_TRANSLATION
(X)
This keyword can be used to allow multiple, simultaneous IDL sessions to use the same
colors from a shared colormap. Use this keyword before the X connection is established
(i.e., before a window is created), IDL will use the shared color map without allocating
any additional colors, and will not load a grayscale ramp as is usually done when the X
server startsup. ThefollowingexampleshowstwocooperatingIDLprocessessharingthe
same colormap:
Execute the following commands in the rst IDL session:
WINDOW, GET_X_ID = a
DEVICE, TRANSLATION = t
OPENW, 1, 'junk.dat'
WRITEU, 1, a, !D.N_COLORS, t[0:!D.N_COLORS-1]
CLOSE, 1
LOADCT, 3
Execute the following commands in the second IDL session:
OPENR, 1, 'junk.dat'
a=0L
n=0L
READU,1, a, n
t = BYTARR(n)
READU, 1, t
CLOSE, 1
DEVICE, SET_TRANSLATION = t
WINDOW, COLORS=n, SET_X_ID=a
TV, DIST(256)
SET_WRITE_MASK
(X, Z)
Setsthewritemask to thespecied value. For an n-bit system, thewritemask can range
from 0 to 2
n
-1.
STATIC_COLOR
(X)
Use this keyword to select the X Windows StaticColor visual. The value of the keyword
Visuals on page 171
STATIC_GRAY
(X)
Use this keyword to select the X Windows StaticGray visual. The value of the keyword
Visuals on page 171
SYMBOL
(PS)
Set this keyword to select the Symbol PostScript font.
TEK4014
(TEK)
Set thiskeywordtospecifythat coordinatesaretobeoutput with full 12-bit resolution. If
thiskeywordisnot present or iszero, 10-bit coordinatesareoutput. Normally, IDLsends
10-bit coordinates. 12-bit coordinates are compatible with most terminals, even those
without the full resolution, but require more characters to send.
Note The4014and the4100modescan beused together. ThecoordinatesystemIDL uses
for theTektronix is0to4095in theXdirection and0to3120in theYdirection, even
when not in the 4014 mode. In the 10-bit case the internal coordinates are divided
by 4 prior to output.
TEK4100
(TEK)
Set thiskeywordtoindicatethat theterminal isa4100or 4200seriesterminal. Theuseof
color, ANSI and Tektronix mode switching, hardware line styles, and pixel output with
the TV procedure is supported with these terminals. Also, text is output differently.
TEXT
(CGM)
Set this keyword to set the encoding type for the CGM output le to text.
THRESHOLD
(LJ, MAC, PCL, X)
Set this keyword to select the threshold algorithmthe simplest dithering method. The
value of this keyword is the threshold to be used. This algorithm simply compares each
pixel against thegiven threshold, usually 128. If thepixel equalsor exceedsthethreshold
the display pixel is set to white, otherwise it is black.
Macintosh Only
Set this keyword to use the Macintoshs default thresholding. Values greater than one
cause the keyword to be set but are otherwise ignored.
TIMES
(PS)
Set this keyword to select the Times-Roman PostScript font.
TRANSLATION
(MAC, WIN, X)
As discussed in Shared Colormaps on page 174, using the shared colormap (normally
recommended) causes IDL to translate between IDL color indices (which always start
with zero and are contiguous) and the pixel values actually present in the display. The
TRANSLATIONkeywordspeciesthenameof avariabletoreceivethetranslationvector.
To read the translation table, use the command:
DEVICE, TRANSLATION=TRANSARR
where TRANSARR is a named variable into which the translation array is stored. The
result is a 256-element byte vector. Element zero of the vector contains the pixel value
allocated for the rst color in the IDL colormap, and so forth.
Microsoft Windows Only
This keyword is accepted by the WIN device, for compatibility with the X Windows
driver, but simply returns a 256-element vector where each element has the value of its
subscript (0 to 255).
TRUE_COLOR
(MAC, PRINTER, X)
Use this keyword to select TrueColor visuals. The value of the keyword represents the
number of bitsper pixel tobeused. Thiskeywordhaseffect onlyif nowindowshavebeen
created. Visual classesarediscussed in moredetail in XWindowsVisuals on page171.
If thecurrent deviceisPRINTER, theprinter isplaced in RGBor true-color modeif the
value of the TRUE_COLOR keyword is greater than zero (the number of bits per pixel
specied is ignored.)
Macintosh Only
For best results, set TRUE_COLORequal to 24after settingtheColor Depth to Millions
from the Monitors Control Panel in the Apple menu.
TT_FONT
(MAC, PRINTER, WIN, X, Z)
Set thiskeywordtoindicatethat thefont set viatheSET_FONTkeyword(either toset the
fontname or to retrieve fontnames in conjunction with the GET_FONTNAMES or
GET_FONTNUM keywords) should be treated as a TrueType font.
TTY
(REGIS, TEK)
Set this keyword to specify that output should be sent to the terminal at the same time
that it is being sent to a le due to the FILENAME or PLOT_TO keywords. A zero value
causes output to go only to the le. If no output le is in use, this keyword has no effect.
USER_FONT
(PS)
ThiskeywordisnowobsoleteandhasbeenreplacedbytheSET_FONT keyword. Codethat
uses theUSER_FONT keyword will continueto function as before, but wesuggest that all
new codeuseSET_FONT.
VT240, VT241
(CGM, HP, LJ, MAC, PCL, PRINTER, PS, REGIS, TEK, WIN, X, Z)
(REGIS)
Set this keyword to congure the REGIS device for VT240 series terminals.
VT340, VT341
(REGIS)
Set this keyword to congure the REGIS device for VT340 series terminals.
WINDOW_STATE
(WIN, )
Set this keyword to a named variable that returns an array containing one element for
each possible window. Array element i contains a 1 if windowi is open, otherwise it
contains a 0.
XOFFSET
SpeciestheXposition, on thepage, of thelower left corner of output generated byIDL.
XOFFSET is specied in centimeters, unless INCHES is specied. See Positioning
Graphics Output on page148.
PostScript Only
SCALE does not affect the value of XOFFSET.
XON_XOFF
(HP)
If present andnon-zero, XON_XOFFcauseseachoutput pagetostart withdevicecontrol
commands that instruct the plotter to obey xon/xoff (^ S/^ Q) style ow control.
Specifying a value of zero stops the issuing of such commands. You should only use this
keyword before any output has been generated.
Such handshaking is the default. To turn it off, use the command
DEVICE, XON_XOFF=0
Often, it is not necessary to tell the plotter to obey ow control because the printing
facilities on the system handle such details for you, but it is usually harmless.
XSIZE
Speciesthewidth of output generated by IDL. XSIZEisspecied in centimeters, unless
INCHES is specied.
PostScript Only
SCALE modies the value of XSIZE. Hence, the following statement:
DEVICE,/INCHES,XSIZE=7.0,SCALE_FACTOR=0.5
results in a real width of 3.5 inches.
YOFFSET
SpeciestheYposition, on thepage, of thelower left corner of output generated by IDL.
YOFFSET is specied in centimeters, unless INCHES is specied. See Positioning
Graphics Output on page148.
Note The corner of the page from which the Y offset is measured (lower or upper left)
differs on various devices. Read the device specic information in the following
sections to determine how this is handled for your device.
PostScript Only
SCALE does not affect the value of YOFFSET.
IDL Reference Guide Window Systems
YSIZE
Speciestheheight of output generated byIDL. YSIZEisspecied in centimeters, unless
INCHES is specied.
PostScript Only
SCALE modies the value of YSIZE. Hence, the following statement:
DEVICE,/INCHES,YSIZE=5.0,SCALE_FACTOR=0.5
results in a real width of 2.5 inches.
LJ250 Only
Changingthesize, depth, or orientation of theoutput causesthecurrent pageto besent
to the le. The effect is identical to calling the ERASE procedure.
ZAPFCHANCERY
(PS)
Set this keyword to select the ITC Zapf Chancery PostScript font.
ZAPFDINGBATS
(PS)
Set this keyword to select the ITC Zapf Dingbats PostScript font.
Z_BUFFERING
(Z)
ThiskeywordenablesanddisablestheZ-buffering. If thiskeywordisspeciedwithazero
value, thedriver operatesasastandard 2D device, theZ-bufferingisdisabled, and theZ-
buffer (if any) isdeallocated. Settingthiskeyword to one(thedefault value), enablesthe
Z-buffering.
To disable Z-buffering enter:
DEVICE, Z_BUFFERING = 0
Window Systems
The different window systems supported by IDL have many features in common. This
section describes those features. See the individual descriptions of each system later in
this chapter for additional information about each one.
IDL utilizes the window system by creating and using one or more largely independent
windows, each of which can beused for thedisplayof graphicsand/or images. Onecolor
map table is shared among all these windows. Multiple windows can be active
simultaneously. Windows are referenced using their index which is a non-negative
integer.
Window Systems IDL Reference Guide
Dithering or halftoningtechniquesareused to display imageswith multipleshadesof
gray on monochromedisplaysdisplaysthat can only display whiteor black. Thistopic
is discussed in Image Display On Monochrome Devices on page 145
Graphic and image output is always directed to the current window. When a window
system is selected as the current IDL graphics device, the index number of the current
window is found in the !D.WINDOW system variable. This variable contains -1 if no
windowisopen or selected. TheWSET procedureisused to changethecurrent window.
WSHOW hides, displays, and iconies windows. WDELETE deletes a window.
TheWINDOWprocedurecreatesanewwindowwith agiven index. If awindowalready
exists with the same index, it is rst deleted. The size, position, title, and number of
colors, may also be specied. If you access the display before creating the rst window,
IDL automatically creates a window with an index number of 0 and with the default
attributes.
Backing Store
One of the features that distinguishes various window systems is how they handle the
issueof backingstore. When part of awindowthat waspreviously not visibleisexposed,
there are two basic approaches that a window system can take. Some keep track of the
current contents of all windows and automatically repair any damage to their visible
regions (retained windows). This saved information is known as the backing store.
Others simply report the damage to the program that created the window and leave
repairing the visible region to the program (non-retained windows).
There are convincing arguments for and against both approaches. It is generally more
convenient for IDL if the window system handles this problem automatically, but this
oftencomesat aperformancepenalty. Theactual cost of retainedwindowsvariesbetween
systems and depends partially on the application.
The X Window system does not by default keep track of window contents. Therefore,
when a window on the display is obscured by another window, the contents of its
obscured portion is lost. Re-exposing the window causes the X server to ll the missing
data with the default background color for that window, and request the application to
redrawthemissingdata. Applicationscan request abackingstorefor their windows, but
servers are not required to provide it. Many X servers do not provide backing store, and
Value Description
0 No backing store.
1 Request the server or window system to perform backing store.
2 Make IDL perform backing store.
Table 8-5: Allowed Values for the RETAIN Keyword
IDL Reference Guide Window Systems
even those that do cannot necessarily provide it for all requesting windows. Therefore,
requesting backing store from the server might help, but there is no certainty.
TheIDL windowsystemdriversallowyou to control theissueof backingstoreusingthe
RETAIN keyword to the DEVICE and WINDOW procedures. Using it with DEVICE
allowsyoutoset thedefault actionfor all windows, whileusingit withWINDOWletsyou
override the default for the new window. The possible values for this keyword are
summarized in Table 8-5, and are described below:
Setting the RETAIN keyword to 0 species that no backing store is kept. In this case,
exposingapreviously obscured windowleavesthemissingportion of thewindowblank.
Although this behavior can be inconvenient, it usually has the highest performance
because there is no need to keep a copy of the window contents.
SettingtheRETAINkeywordto1causesIDLtorequest that abackingstorebemaintained.
If thewindowsystemdecidestoaccept therequest, it will automaticallyrepair themissing
portionswhen thewindowisexposed. XWindowsmayor maynot providebackingstore
when requested, dependingon thecapabilitiesof theserver andtheresourcesavailableto
it.
Setting the RETAIN keyword to 2 species that IDL should keep a backing store for the
windowitself, and repair any windowdamagewhen thewindowsystemrequestsit. This
optionexistsfor XWindows. Inthiscase, apixmap(off-screendisplaymemory) thesame
size as the window is created at the same time the window is created, and all graphics
operationssent tothewindowarealsosent tothepixmap. When theserver requestsIDL
to repair freshly exposed windows, this pixmap is used to ll in the missing contents.
Pixmaps are a precious resource in the X server, so backing pixmaps should only be
requested for windows with contents that must absolutely be preserved.
If the type of backing store to use is not explicitly specied using the RETAIN keyword,
IDL assumes option 1 and requests the window system to keep a backing store.
A Note on Reading Data from Windows
On some systems, when backing store is provided by the window system (RETAIN=1),
reading data from a window using TVRD may cause unexpected results. For example,
datamay beimproperly read fromthewindoweven when theimagedisplayed on screen
is correct. Having IDL provide the backing store (RETAIN=2) ensures that the window
contentswill bereadproperly. Thesetypesof problemsaredescribedinmoredetail inthe
documentation for TVRD. See Unexpected Results Using TVRD with X Windows on
page1162.
Image Display On Monochrome Devices
Imagesareautomatically dithered when sent tosomemonochromedevices. Ditheringis
a technique which increases the number of apparent brightness levels at the expense of
spatial resolution. Images with 256 gray levels are displayed on a display with only two
colors, black and white, using halftoning techniques. PostScript handles dithering
directly. IDL supportsditheringfor other devicesif their DEVICEproceduresaccept the
FLOYD, ORDERED, or THRESHOLD keywords.
Printing Graphics Output Files IDL Reference Guide
Printing Graphics Output Files
For printer and plotter devices (e.g., PCL, PostScript, and HP-GL), IDL creates a le
containingoutput commands. Thislecan besent totheprinter viathenormal methods
providedbythelocal operatingsystem. When attemptingtooutput thelebeforeexiting
IDL, the user must be sure that the graphics output le is complete. For example, the
following IDL commands (executed under Unix) will not produce the desired result:
SET_PLOT,'PS'
PLOT,x,y
SPAWN,'lpr idl.ps'
These commands fail because the attempt to print the le is prematurethe le is still
open within IDL and is not yet complete.
The following lines of code are an IDL procedure called OUTPUT_PLOT which closes
thecurrent graphicsleandsendsit totheprinter. Thisroutineassumesthat thegraphics
output leisnamed idl.xxx, wherexxx representsthenameof thegraphicsdriver.
For example, PostScript output le is assumed to beidl.ps. It also assumes that the
graphics output to be printed is from the current graphics device, as selected with
SET_PLOT.
Pro OUTPUT_PLOT, New_file Closethecurrentgraphicsfile,and
printit.IftheNew_fileparameter
is present, renamethefileto the
given nameso it wont beover-
written.
DEVICE,/CLOSE Closecurrent graphics file.
file = 'idl.' + STRLOWCASE(!D.NAME) Buildthedefaultoutputfilename
by usingtheidl namefor thecur-
rent device(!D.NAME).
cmd = 'lpr ' + file Buildshell commandstosendfile
to theprinter. You will probably
haveto changethis command in
accordancewith local usage.
IF N_ELEMENTS(New_file) GT 0 THEN $
cmd = cmd + '; mv' + file + ' ' + New_file
Concatenaterenamecommandif
new filespecified.
SPAWN, cmd Issueshell commands to print/re-
namefile.
END
Thecall to DEVICEcausesIDL to nish theleand closeit, which makesit availablefor
printing.
IDL Reference Guide Printing Graphics Output Files
Setting Up The Printer
In order for IDL generated output les to work properly with printers and plotters, it is
necessaryfor thedevicetobeconguredproperly. Thisusuallyinvolvesconguringboth
the device hardware and the operating system printing software. When setting up your
system, keep the following points in mind:
The device and computer must use some form of ow control to prevent the computer
fromsendingdatafaster than theprintingdevicecan handleit. Themost common form
of owcontrol isknown asXON/XOFF, and involvesthesendingof Control-S(off ) and
Control-Q (on) characters from the device to the printer to manage the ow of data.
Many printers have a large buffer into which they store incoming data they havent yet
processed. Thisreducestheneedtoinvokeowcontrol. When testingyour conguration
to ensure ow control is actually enabled, you must be sure to print a document long
enough to ll any such buffer, or owcontrol may never occur, givingafalseimpression
that the setup is correct. A common source of problems stem from attempting to print
long IDL generated output les without proper ow control.
Some devices (such as PCL) require an eight-bit data path, while others (such as Post-
Script) do not. For devices that do, it is important to ensure that the printer port and
system printing software provide such a connection.
If you are having problems printing on a PostScript printer, theehandler.ps le
provided in theps subdirectory of thefonts subdirectory of theresource
subdirectory of the IDL distribution can help you to debug your problem. Sending this
leto your PostScript Printer causesit to print any subsequent errorsit encounterson a
sheet of paper and eject it. The effect of this le lasts until the printer is reset.
Setting Up Printers Under Unix
Printersarecongured in the/etc/printcap le. Thisledescribesto thesystem
whichprintersareconnectedtoit, thecharacteristicsof eachprinter, andhowtheprinter
port should be congured. Managing the printcap le is usually discussed in the system
management documentation supplied with the system by the manufacturer.
Setting Up Printers Under VMS
Printer queueconguration under VMSisalargetopic. However, it isoften sufcient to
set theprinter port up properly usingtheDCL_SET_TERMINAL command, and set up
a printer queue using the standard printer form. Users can send eight-bit data to such a
printer using the DCL PRINT/PASSALL command (On very small systems, it is even
possibleto dispensewith theprinter queueentirely and simply usetheCOPYcommand
to send data to the printer port directly).
However, muchmoresophisticatedarrangementsarepossibleincludingthedenition of
specializedprinter forms, placingprinterson thelocal areanetwork for usebymorethan
one machine, and so forth. For information on these topics, refer to the relevant VMS
documentation.
The CGM Device IDL Reference Guide
Positioning Graphics Output
ThedifferencebetweentheXOFFSETandYOFFSETkeywordstotheDEVICEprocedure,
and the higher level plot positioning keywords and system variables (discussed in
Graphics Keywords on page 99 and Plotting on page 283 of Using IDL) can lead to
confusion. A common misunderstanding is to attempt to use the DEVICE procedure
offset and size keywordsmultipletimesin an attempt to producemultipleplotson a
single output page.
TheDEVICEkeywordsareintended to specify thesizeand position of theentireoutput
areaon thepage, not to movetheplottingregion for multipleplots. Thedriver doesnot
monitor their values continuously, but only when initializing a new page or ejecting the
current one.
Theproper waytoproducemultipleplotsistousethehighlevel positioningabilities. The
!P.MULTI, !P.POSITION, and !P.REGION system variables can be used to position
individual plotson thepage. Theplottingroutinesalsoaccept thePOSITION, MARGIN
and REGION keywords.
Image Background Color
Graphical output that isdisplayedwithablack backgroundon amonitor frequentlylook
better if the background is changed to white when printed on white paper. This is easily
done with the statement:
a(WHERE(a EQ 0B)) = 255B
The CGM Device
Device Keywords Accepted by the CGM Device
BINARY, CLOSE_FILE, COLORS, ENCODING, FILENAME, NCAR,
SET_CHARACTER_SIZE, TEXT
The CGM, Computer Graphics Metale, standard describes a device independent le
format used for the exchange of graphic information. The IDL CGM driver produces
CGM les encoded in one of three methods: Text, Binary or NCARBinary. To direct
graphics output to a CGM le, issue the command:
SET_PLOT,'CGM'
This causes IDL to use the CGM driver for producing graphical output. Once the CGM
driver isselected, theDEVICEprocedurecontrolsitsactions, asdescribed below. Typing
HELP, /DEVICE displays the current state of the CGM driver. The CGM driver
defaults to the binary encoding using 256 colors.
Abilities and Limitations
This section describes details specic to IDLs CGM implementation:
IDL Reference Guide The CGM Device
IDL uses the CGM default integer encoding for graphic primitives. Coordinate values
rangefrom0to32767. It isadvisabletousethevaluesstoredin!D.X_SIZEand!D.Y_SIZE
instead of assuming a xed coordinate range.
Color information isoutput with aresolution of 8bits(color indicesandintensityvalues
range from 0 to 255).
The denition of background color in the CGM standard is somewhat ambiguous.
Accordingtothestandard, color index 0andthebackgroundcolor arethesame. Because
background color isspecied in themetaleasacolor value(RGBtriple), not an index,
it ispossibletohavethebackgroundcolor not correspondwith thecolor valueof index 0.
The CGM BACKGROUND_COLOUR attribute is explicitly set by IDL only during an
erase operation: changing the value of the color map at index 0 does not cause IDL to
generateaBACKGROUND_COLOURattributeuntil thenext ERASEoccurs. An ERASE
command sets the background color to the value in the color map at index 0. The
command ERASE, INDEX (whereINDEXisnot 0) generatesthemessageValue
of background color is out of allowed range. For consistent
results, modify the color table before any graphics are output.
The CGM standard uses scalable (variable size) pixels for raster images. By default, the
TV and TVSCL procedures output images, regardless of size, using the entire graphics
output area. Tooutput an imagesmaller than thegraphicsoutput area, specifytheXSIZE
and YSIZE keywords with the TV and TVSCL procedures. For example:
SET_PLOT, 'CGM' Select theCGM driver.
X = DIST(64) Createa 64 x 64 element array
TVSCL, X Display theimage(fills entire
screen)
ERASE Now display 4 images on the
screen.
XS = !D.X_SIZE / 2 Sizeof each image, X dimension.
YS = !D.Y_SIZE / 2 Sizeof each image, Y dimension.
TVSCL, X, 0, XSIZE=XS, YSIZE=YS Upper left.
TVSCL, X, 1, XSIZE=XS, YSIZE=YS Upper right.
TVSCL, X, 2, XSIZE=XS, YSIZE=YS Lower left.
TVSCL, X, 3, XSIZE=XS, YSIZE=YS Lower right.
The HP-GL Device IDL Reference Guide
The HP-GL Device
Device Keywords Accepted by the HP-GL Device
CLOSE_FILE, EJECT, FILENAME, INCHES, LANDSCAPE, OUTPUT,
PLOTTER_ON_OFF, POLYFILL, PORTRAIT, SET_CHARACTER_SIZE, XOFFSET,
XON_XOFF, XSIZE, YOFFSET, YSIZE
HP-GL (Hewlett-Packard Graphics Language) is a plotter control language used to
producegraphicson awidefamily of pen plotters. To useHP-GL asthecurrent graphics
device, issue the IDL command:
SET_PLOT,'HP'
ThiscausesIDL touseHP-GL for producinggraphical output. OncetheHP-GL driver is
enabledviaSET_PLOT, theDEVICEprocedureisusedtocontrol itsactions, asdescribed
below. The default settings for the HP-GL driver are shown in Table 8-6. Use the
statement:
HELP, /DEVICE
to view the current state of the HP-GL driver.
Abilities And Limitations
IDL isableto produceawidevariety of graphical output usingHP-GL. Thefollowingis
a list of what is and is not supported:
All typesof vector graphicscan begenerated, includinglineplots, contours, surfaces, etc.
Feature Value
File idl.hp
Orientation Portrait
Erase No action
Polygon lling Software
Turn plotter logically on/off No
Specify xon/xoff ow control Yes
Horizontal offset 3/4 in.
Vertical offset 5 in.
Width 7 in.
Height 5 in.
Table 8-6: Default HP-GL Driver Settings
IDL Reference Guide The LJ Device
HP-GLplotterscandrawlinesindifferent colorsselectedfromthepencarousel. It should
benotedthat color tablesarenot usedwithHP-GL. Instead, eachcolor indexrefersdirectly
to one of the pens in the carousel.
SomeHP-GL plotterscan dopolygon llingin hardware. Otherscan relyon thesoftware
polygon lling provided by IDL.
It ispossibletogenerategraphicsusingthehardwaregenerated text characters, although
such characters do not give much improvement over the standard vector fonts. To use
hardware characters, set the !P.FONT system variable to zero, or set the FONT keyword
to the plotting routines to zero.
Since HP-GL is designed to drive pen plotters, it does not support the output of raster
images. Therefore the TV and TVSCL procedures do not work with HP-GL.
Since pen plotters are not interactive devices, they cannot support such operations as
cursors and windows.
HP-GL Linestyles
The LINESTYLE graphics keyword allows specifying any of 6 linestyles. These linestyles
aredocumented in Chapter . HP-GL doesnot support all of theselinestyles, and styles3
and 4 differ from the denition in Chapter . Table 8-7 summarizes the differences:
The LJ Device
Device Keywords Accepted by the LJ Device
CLOSE_FILE, DEPTH, FILENAME, FLOYD, INCHES, LANDSCAPE, ORDERED,
PIXELS, PORTRAIT, RESOLUTION, SET_CHARACTER_SIZE, THRESHOLD,
XOFFSET, XSIZE, YOFFSET, YSIZE
The LJ250 and LJ252 are color printers sold by Digital Equipment Corporation (DEC).
To direct graphics output to a picture description le compatible with these printers,
issue the command:
Index Normal LineStyle HP-GL Line Style
0 Solid same
1 Dotted same
2 Dashed same
3 Dash Dot Relative size of dash and dot are different.
4 Dash Dot Dot Dot Dash Dot Dot
5 Long Dashes same
Table 8-7: Linestyles for the HP-GL Device
The LJ Device IDL Reference Guide
SET_PLOT, 'LJ'
ThiscausesIDL tousetheLJdriver for producinggraphical output. Toactuallyprint the
generated graphics, send the le to the printer using the normal printing facilities
supplied by the operating system. Once the LJ driver is enabled via SET_PLOT, the
DEVICEprocedureisused tocontrol itsactions, asdescribed below. Thedefault settings
for the LJ driver are given in Table 8-8. Use theHELP, /DEVICE command to view
the current font, le, and other options currently set for LJ output.
LJ Driver Strengths
The LJ250 produces color graphics at a low cost. It is capable of producing good quality
monochromeoutput, and isalsogood at color vector graphicsand simplecolor imaging
using a small number of predened solid colors.
LJ Driver Limitations
The LJ250 is intended to be used as a low cost printer for business color graphics.
Although it can be used to print color images, it is limited in its ability to produce
satisfactoryimagesof thesort commonlyencountered in scienceand engineering. These
limitations make it a poor choice for such work.
Although color is specied via the usual RGB triples using the TVLCT procedure, the
LJ250 is only capable of generating a xed set of colors. The number of possible colors
dependsontheresolutioninuse. Whenproducing180dpi graphics, onlythecolorsgiven
in the table below are possible. In 90 dpi mode, 256 colors are available.
If acolor isspeciedthat theprinter cannot produce, it substitutestheclosest color it can.
However, the results of such substitutions can give unexpected results. The xed set of
possiblecolorsmeansthat theLOADCTprocedureisof limitedusewiththeLJ250. It also
means that it is difcult to produce satisfactory grayscale images.
Feature Value
File idl.lj
Mode Portrait
Dither method Floyd-Steinberg
Resolution 180 dpi
Number of planes 1 (monochrome)
Width 7 in.
Height 5 in.
Table 8-8: Default LJ Driver Settings
IDL Reference Guide The LJ Device
The number of simultaneous colors possible on an output page is limited. Although
imagesarespecied in 8-bit bytes, thenumber of signicant bitsused rangesfrom1to 4
(as specied via the DEPTH keyword to the DEVICE procedure), allowing from 2 to 16
colors. Coupled with theabovelimitation on thecolorsthat arepossible, it isdifcult to
produce high quality image output.
LJ Suggestions
Thefollowingsuggestionsareintended to help you get themost out of theLJ250, taking
its limitations into account:
Usemonochromeoutput when possible. Thisresultsin considerablysmaller output les,
andprovidesmost of theabilitiestheLJ250handleswell. When producingmonochrome
output, theLJ250driver dithersimages. Thiscanoftenproducemoresatisfyinggrayscale
output than possible using the printer in color mode.
Table 8-9 gives the RGB values to use when specifying colors at 180 dpi. To make more
colors available, use 90 dpi resolution. The RGB values for the possible colors at 90 dpi
aregiven in Table7-6of theLJ250/LJ252CompanionColor Printer Programmer Reference
Manual. You can cause the printer to display the complete 256 color palette as follows:
Withthepower off, pressandholdtheREADYandDEC/PCLswitcheswhilemomentarily
pressing the power switch. Wait approximately 2 seconds and release the READY and
DEC/PCL switches. The printer will take a few minutes to print all 256 colors. The
complete display ts on a single page.
Usethetableintheprogrammersmanual withthisdisplaytoselect thecolorstouse. Note
that theRGBvaluesintheprogrammersmanual arescaledfrom1to100, whileIDLscales
such values from 0 to 255. Therefore, multiply the values obtained from the manual by
2.55 to properly scale them for use within IDL.
Unlike most devices, IDL does not initialize the LJ250 color map to a gray scale ramp
because the printer cannot produce a satisfactory gray scale image. Instead, the default
Color Red Value Green Value Blue Value
Black 10 10 10
Yellow 227 212 33
Magenta 135 13 64
Cyan 5 56 163
Red 135 20 36
Green 8 66 56
Blue 10 10 74
White 229 224 217
Table 8-9: LJ250 Colors Available at 180 dpi
The Macintosh Display Device IDL Reference Guide
palettes given in Table 7-5 of theLJ250/LJ252 Companion Color Printer Programmer
ReferenceManual areused. If youmodifythecolor map, theLJLCTprocedurecanbeused
to reset the color table to these defaults. LJLCT examines the !D.N_COLORS system
variabletodeterminethenumber of output planesin use, andthen loadstheappropriate
default color map.
When producingimages, stick to imageswith small amountsof detail and largesections
of uniform color. Complicated images do not reproduce well on this printer.
The Macintosh Display Device
Device Keywords Accepted by the MAC Device
BYPASS_TRANSLATION, COPY, CURSOR_ORIGINAL, CURSOR_STANDARD,
DECOMPOSED, FLOYD, FONT, GET_CURRENT_FONT, GET_FONTNAMES,
GET_FONTNUM, GET_GRAPHICS_FUNCTION, GET_SCREEN_SIZE,
GET_WINDOW_POSITIONrf, ORDERED, PSEUDO_COLOR, RETAIN,
SET_CHARACTER_SIZE, SET_GRAPHICS_FUNCTION, THRESHOLD,
TRANSLATION, TRUE_COLOR
TheMacintosh version of IDLusesthe MAC devicebydefault. Thisdeviceissimilar to
theXWindowsdevicedescribedstartingonpage171. The MAC deviceisonlyavailable
in IDL for Macintosh.
To set plotting to the Macintosh device, use the command:
SET_PLOT, 'MAC'
The Null Display Device
Device Keywords Accepted by the Null Device
No keywords are accepted by the DEVICE procedure when the NULL device is selected.
To suppress graphics output entirely, use the null device:
SET_PLOT, 'NULL'
The PCL Device
Device Keywords Accepted by the PCL Device
CLOSE_FILE, COLOR, FILENAME, FLOYD, INCHES, LANDSCAPE, OPTIMIZE,
ORDERED, PIXELS, PORTRAIT, RESOLUTION, SET_CHARACTER_SIZE,
SET_COLORMAP, THRESHOLD, XOFFSET, XSIZE, YOFFSET, YSIZE
PCL (Printer Control Language) isused by Hewlett-Packard laser and ink jet printersto
produce graphics output. To direct graphics output to a PCL le, issue the command:
SET_PLOT,'PCL'
IDL Reference Guide The PCL Device
This causes IDL to use the PCL driver for producing graphical output. Once the PCL
driver isenabled viaSET_PLOT, theDEVICEprocedureisused to control itsactions, as
described below. Thedefault settingsfor thePCL driver aregiven in Table8-10. ThePCL
device draws into a memory buffer of the specied size (or the default size, if the XSIZE
and YSIZE keywords to DEVICE are not specied). Anything drawn outside this buffer
will be silently discarded.
Note Unlike monitors where white is the most visible color, PCL writes black on white
paper. Setting the output color index to 0, the default when PCL output is selected,
writes in black. A color index of 255 writes white which is invisible on white paper.
Color tables are not used with PCL unless the color mode has been enabled using the
COLOR keyword to the DEVICE procedure. For images, color dithering produces
realisticcolor imageoutput even though PCL printersonly produceeight output colors.
In most cases, simply choosing an appropriate color table (using LOADCT or
XLOADCT), or creating a color table from an image (via TVLCT) will work ne. If you
needner control over thecolorsused, seetheSET_COLORMAPkeywordfor additional
information. For vector graphics, only eight colors are supportedno line dithering is
implemented. Any RGB component that is not zero is treated as 255. The correct RGB
denitions for each color are shown in Table 8-11. Use theHELP, /DEVICE
command to view the current options for PCL output.
Feature Value
File idl.pcl
Mode Portrait
Optimization level 0 (None)
Dither method Floyd-Steinberg
Resolution 300 dpi
Width 7 in.
Height 5 in.
Table 8-10: Default PCL Driver Settings
Red 255 0 0
Green 0 255 0
Table 8-11: PCL RGB Color Denitions
The Printer Device IDL Reference Guide
The Printer Device
Device Keywords Accepted by the PRINTER Device
CLOSE_DOCUMENT, GET_CURRENT_FONT, GET_FONTNAMES,
GET_FONTNUM, INDEX_COLOR, PORTRAIT, SCALE_FACTOR,
SET_CHARACTER_SIZE, TRUE_COLOR, XOFFSET, XSIZE, YOFFSET, YSIZE
The PRINTER device allows IDL Direct Graphics to be output to a system printer. To
direct graphics output to a printer, issue the command:
SET_PLOT, 'printer'
ThiscausesIDLtouseaprinter driver toproducegraphical output. Bydefault, thedefault
systemprinter isused for output. UsetheDIALOG_PRINTERSETUPfunction todene
theprintingparametersfor theprinter device. UsetheDIALOG_PRINTJOBfunction to
control the print job itself.
Notethat theprinter deviceisan IDL Direct Graphicsdevice. Likeother Direct Graphics
devices, you must changeto thenewdeviceand then issuetheIDL commandsthat send
output to that device. With the printer device, you must use the CLOSE_DOCUMENT
keyword to the DEVICE routine to actually initiate the print job and make something
come out of your printer.
The PostScript Device
Device Keywords Accepted by the PS Device
AVANTGARDE, BITS_PER_PIXEL, BKMAN, BOLD, BOOK, CLOSE_FILE, COLOR,
COURIER, DEMI, ENCAPSULATED, FILENAME, FONT_INDEX, FONT_SIZE,
HELVETICA, INCHES, ISOLATIN1, ITALIC, LANDSCAPE, LIGHT, MEDIUM,
NARROW, OBLIQUE, OUTPUT, PALATINO, PORTRAIT, PREVIEW,
SCALE_FACTOR, SCHOOLBOOK, SET_CHARACTER_SIZE, SET_FONT, SYMBOL,
Blue 0 0 255
Cyan 0 255 255
Magenta 255 0 255
Yellow 255 255 0
Black 0 0 0
White 255 255 255
Table 8-11: PCL RGB Color Denitions
IDL Reference Guide The PostScript Device
TIMES, TT_FONT, XOFFSET, XSIZE, YOFFSET, YSIZE, ZAPFCHANCERY,
ZAPFDINGBATS
PostScript is a programming language designed to convey a description of a page
containing text and graphics. Many laser printers and high-resolution, high-quality
photo typesetters support PostScript. Color output or direct color separations can be
produced with color PostScript. To direct graphics output to a PostScript le, issue the
command:
SET_PLOT, 'PS'
This causes IDL to use the PostScript driver for producing graphical output. Once the
PostScript driver isenabled viaSET_PLOT, theDEVICEprocedureisused to control its
actions, as described below. The default settings are given in Table 8-12.
Note Unlikemonitorswherewhiteisthemost visiblecolor, PostScript writesblackonwhite
paper. Setting the output color index to 0, the default when PostScript output is
selected, writes black. A color index of 255 writes white which is invisible on white
paper. Color tables are not used with PostScript unless the color mode has been
enabled using the DEVICE procedure. See Color Images on page158.
Toobtain adequateresolution, thedevicecoordinatesystemusedfor PostScript output is
expressed in units of 0.001 centimeter (i.e., 1000 pixels/cm).
Use theHELP, /DEVICE call to view the current font, le, and other options set for
PostScript output.
Feature Value
File idl.ps
Mode Portrait, non-encapsulated, no color
Width 7 in.
Height 5 in.
Scale factor 1.0
Font size 12 points
Font Helvetica
# Bits / Image Pixel 4
Table 8-12: Default PostScript Driver Settings
The PostScript Device IDL Reference Guide
Using PostScript Fonts
Information necessary for rendering a set of 35 standard PostScript fonts are included
with IDL. (The standard 35 fonts are the fonts found on the Apple Laserwriter II
PostScript printer; thesamefontsarefoundon almost anyPostScript printer madein the
time since the LaserWriter II appeared.) Use of PostScript fonts is discussed in detail in
About Device Fonts on page 72.
Color PostScript
If you have a color PostScript device you can enable the use of color with the statement:
DEVICE, /COLOR
Enablingcolor also enablesthecolor tables. Text and graphiccolor indicesaretranslated
toRGBbydividingthered, green andbluecolor tablevaluesby255. Aswithmost display
devices, color indices range from 0 to 255. Zero is normally black and white is normally
represented by an index of 255. For example, to create and load a color table with four
elements, black, red, green and blue:
TVLCT, [0,255,0,0], [0,0,255,0], [0,0,0,255]
Drawingtext or graphicswith acolor index of 0resultsin black, 1in red, 2in green, and
3 in blue.
Color Images
Aswith black and whitePostScript, imagesmay beoutput with 1, 2, 4, or 8bits, yielding
1, 2, 16, or 256possiblecolors. In addition, imagesareeither pseudo-color or true-color.
A pseudo-color image is a two dimensional image, each pixel of which is used to index
the color table, thereby obtaining an RGB value for each possible pixel value. Pseudo-
color images are similar to those displayed using the workstation monitor.
Note: in thecaseof pseudo-color imagesof fewer than 8bits, thenumber of columnsin
the image should be an exact multiple of the number of pixels per byte (i.e., when
displaying 4 bit images the number of columns should be even, and 2 bit images should
have a column size that is a multiple of 4). If the image column size is not an exact
multiple, extra pixels with a value of 255 are output at the end of each row. This causes
no problemsif thecolor whiteisloaded into thelast color tableentry, otherwiseastripe
of the last (index number 255) color is drawn to the right of the image.
True-Color Images
Atrue-color imageconsistsof an array with threedimensions, oneof which hasasizeof
three, containing the three color components. It may be considered as three two
dimensional images, one each for the red, green and blue components. For example a
true-color nbymelement imagecan beorderedin threeways: pixel interleaved(3, n, m),
row interleaved (n, 3, m), or image interleaved (n, m, 3). By convention the rst color is
always red, the second green, and the last is blue.
True-color images are also routed through the color tables. The red color table array
containstheintensitytranslation tablefor theredimage, andsoforth. Assumingthat the
color tableshavebeen loaded with thevectorsR, G, and B, apixel with acolor valueof (r,
g, b) isdisplayed with acolor of (R
r
, G
g
, B
b
). Aswith other devices, acolor tablevalueof
255representsmaximumintensity, while0indicatesan absenceof thecolor. To passthe
RGB pixel values without change, load the red, green and blue color tables with a ramp
with a slope of 1.0:
TVLCT, INDGEN(256), INDGEN(256), INDGEN(256)
or with the LOADCT procedure:
LOADCT, 0 Load standard black/whitetable.
Use the TRUE keyword to the TV and TVSCL procedures to indicate that the image is a
true-color imageand tospecify thedimension over which color isinterleaved. Avalueof
1 species pixel interleaving, 2 is row interleaving, and 3 is image interleaving. The
following example writes a 24-bit image, interleaved over the 3rd dimension, to a
PostScript le:
SET_PLOT, 'PS'
;Set the PostScript device to *8* bits per color, not 24:
DEVICE, FILE='24bit.ps', /COLOR, BITS=8
TV, [[[r]], [[g]], [[b]]], TRUE=3
DEVICE, /CLOSE
SET_PLOT, mac Return plottingto Macintosh
windows.
Image Background Color
Imagesthat aredisplayed with ablack background on amonitor frequentlylook better if
the background is changed to white when displayed with PostScript. This is easily done
with the statement:
a(WHERE(a EQ 0B)) = 255B
PostScript Positioning
Using the XOFFSET and YOFFSET Keywords
Often, IDL usersareconfused bytheuseof theXOFFSET and YOFFSET keywordstothe
PostScript DEVICE routine. These keywords control the position of IDL plots on the
page. XOFFSETspeciestheX position of thelower left corner of theoutput generated
byIDL. Thisoffset isalwaystaken relativetothelower left-hand corner of thepagewhen
viewed in portrait orientation. YOFFSET species the Y position of the lower left
corner of the output generated by IDL. This offset is also taken relative to the lower left-
hand corner of the page when viewed in portrait orientation.
Figure 8-1 shows how the XOFFSET and YOFFSET keywords are interpreted. The page
on the left shows an IDL plot printed in portrait orientation. Note that the X and Y
offsets work just as we expect them toincreasing the XOFFSET moves the plot to the
right and increasing the YOFFSET moves the plot up the page. The page on the right
shows an IDL plot printed in landscape orientation. Here, the X and Y offsets are still
taken relative to the same points even though the orientation of the plot has changed.
This happens because IDL moves the origin of the plot beforerotating the PostScript
coordinate system 270 degrees clockwise for the landscape plot.
Note The XOFFSET and YOFFSET keywords have no effect when you generate
ENCAPSULATED PostScript output.
Encapsulated PostScript Output
Another formof PostScript output isEncapsulated PostScript. Thisistheformat used to
import PostScript les into page layout and desktop publishing programs. An
Encapsulated PostScript (EPS) le is similar to a regular PostScript le except that it
contains only one page of PostScript output contained in a bounding box that is used
to tell other programs about the size and aspect ratio of the encapsulated image.
Most of thetime, output fromIDLtoanEPSleisproperlyscaledintotheEPSbounding
box because commands such as PLOT take full advantage of the plotting area made
availabletothem. Sometimes, however, thedefault boundingboxisinappropriatefor the
image being displayed.
XOFFSET
Y
O
F
F
S
E
T
X
O
F
F
S
E
T
YOFFSET
Portrait Plot
Landscape Plot
Figure8-1: ThisdiagramshowshowtheXOFFSET andYOFFSET keywordsareinterpretedbythePostScript
deviceinthePortrait (left) andLandscape(right) modes. Notethat thelandscapeplot usesthesameorigin
for determiningtheeffect of theXOFFSETandYOFFSETkeywords, but that theoutput isrotated270degrees
clockwise.
Asan example, supposeyou havean imagethat isnarrowandtall that, when TVedtoan
IDL window, llsonly asmall portion of theplottingwindow. Similarly, when output to
an EPS le, this image will only ll a small portion of the bounding box. When the
resultingEPSleisbrought into adesktop publishingprogram, it becomesvery hard to
properly scale the image since the aspect ratio of the bounding box bears no relation to
the aspect ratio of the image itself.
To solve this problem, use the XSIZE and YSIZE keywords to the DEVICE procedure to
make the bounding box just large enough to contain the image. Since IDL uses a
resolution of 1000dotsper centimeter with thePostScript device, thecorrect XSIZEand
YSIZE (in centimeters) can be computed as:
XSIZE = Width of image in pixels/1000.0 pixels per cm
YSIZE = Height of image in pixels/1000.0 pixels per cm
The following IDL procedure demonstrates this technique. This procedure reads an X
WindowsDump leand writesit back out asaproperly-sized, 8-bit-color Encapsulated
PostScript le:
PRO XWDTOEPS, filename
array = READ_XWD(filename, r, g, b) ReadtheXWDfile.Pixel intensity
information is stored in thevari-
ablearray. Values to reconstruct
thecolor tablearestored in r, g,
and b.
TVLCT, r,g,b Reconstruct thecolor table.
TV, array DisplaytheimageinanIDLwin-
dow.
s = SIZE(array) Find thesizeof thepicture. The
width of thepicture(in pixels) is
stored in s[1]. Theheight of the
pictureis stored in s[2]:
fl = STRLEN(filename) Takethexwd (for X Windows
Dump)extensionoffoftheoldfile-
nameand replaceit with eps.
filename = STRMID(filename, 0, fl-4)
filename = filename + '.eps'
PRINT, 'Making file: ', filename
PRINT, s
SET_PLOT, 'ps' Set theplottingdeviceto Post-
Script.
DEVICE, /ENCAPSUL, BITS_PER_PIXEL=8, /COLOR, $
FILENAME=filename, XSIZE=S[1]/1000., $
YSIZE=S[2]/1000. UsetheDEVICE procedureto
maketheoutput encapsulated, 8
bits, color, and only as wideand
highasitneedstobetocontainthe
XWD image:
TV, array Writetheimageto thefile.
DEVICE, /CLOSE Closethefile.
SET_PLOT, 'x' Return plottingto X Windows.
END
Multiple Plots on the Same Page
To put multiple plots on the same PostScript page, use the !P.MULTI system variable
(described in more detail in !P System Variable on page 49). !P.MULTI is a 5-element
integer arraythat controlsthenumber of rowsandcolumnsof plotstomakeon apageor
in a graphics window.
The rst element of !P.MULTI is a counter that reports how many plots remain on the
page. The second element of !P.MULTI is the number of columns per page. The third
element is the number of rows per page.
For example, the following lines of code create a PostScript le, multi.ps, with 6
different plots arranged as 2 columns and 3 rows:
SET_PLOT, 'PS' Set plottingto PostScript.
DEVICE, FILENAME='multi.ps' Set thefilename.
!P.MULTI = [0, 2, 3] MakeIDLs plottingarea hold 2
columns and 3 rows of plots.
A = FINDGEN(10) Createa simpledataset.
PLOT, A Make6 different plots.
PLOT, SIN(A)
PLOT, COS(A)
PLOT, TAN(A)
PLOT, TANH(A)
PLOT, SINH(A)
DEVICE, /CLOSE Closethefile.
SET_PLOT, 'win' Return plottingto Windows.
!P.MULTI = 0 Reset plottingto 1 plot per page.
The resulting le produces a set of plots as shown in Figure 8-2.
Importing IDL Plots into Other Documents
Thissection showshowto generateIDL PostScript graphicsso that they can beinserted
into other documents. It also provides several examples of how the PostScript graphics
device is used. Simply omit the ENCAPSULATED keyword from the calls to DEVICE if
you wish to produce plots that can be printed directly. Figure 8-3 is an encapsulated
PostScript le suitable for inclusion in other documents. It was produced with the
following IDL statements:
SET_PLOT, 'PS' Select thePostScript driver.
DEVICE, /ENCAPSULATED, FILENAME = 'pic1.ps'
Noteuseof ENCAPSULATED
keyword.
x = FINDGEN(200)
PLOT, 10000 * SIN(x/5) / EXP(x/100), $
Figure 8-2: Multiple plots on a single page produced by setting the !P.MULTI system variable.
LINESTYLE = 2, TITLE = 'IDL PostScript Plot', $
XTITLE = 'Point Number', YTITLE='Y Axis Title', $
FONT = 0 Plot thesinewave.
OPLOT, 10000 * COS(x/5) / EXP(x/100), LINESTYLE = 4
Add thecosine.
XYOUTS, 100, -6000, 'Sine', FONT = 0
Annotatetheplot.
OPLOT, [120, 180], [-6000, -6000], LINESTYLE = 2
XYOUTS, 100, -8000, 'Cosine', FONT = 0
OPLOT, [120, 180], [-8000, -8000], LINESTYLE = 4
Note the use of the ENCAPSULATED keyword in the call to DEVICE. Figure 8-4 is a
more complicated plot. It demonstrates some of the three-dimensional plotting
capabilities of IDL. It was produced with the following IDL statements:
SET_PLOT, 'PS' Select thePostScript driver.
Noteuseof ENCAPSULATED
keyword.
IDL PostScript Plot
0 50 100 150 200
Point Number
-10000
-5000
0
5000
10000
Y

A
x
i
s

T
i
t
l
e
Sine
Cosine
Figure 8-3: Sample PostScript plot using Helvetica font.
OPENR, 1, !DIR+'/images/abnorm.dat'
Access thedata.
aa = ASSOC(1, BYTARR(64, 64))
a = SMOOTH(aa[0], 3) Get a smoothed version.
SURFACE, a, /SAVE, ZAXIS = 1, XSTYLE = 1, YSTYLE = 1
Generatethesurface.
CONTOUR, a, /T3D, /NOERASE, ZVALUE = 1, $
XSTYLE = 1, YSTYLE = 1, C_LINESTYLE = [0,1,2], $
TITLE = 'IDL PostScript Plot'
Add thecontour.
CLOSE, 1
Figure8-5illustratespolygon lling. It wasproduced with thefollowingIDL statements:
SET_PLOT, 'PS'
x = FINDGEN(200)
Figure 8-4: Three-Dimensional Plot with Vector-Drawn Characters
a = 10000 * sin(x / 5) / exp(x / 100)
Upper sinewave.
PLOT, a, /NODATA, TITLE = 'IDL PostScript Plot', $
XTITLE='Point Number', YTITLE='Y Axis Title', $
FONT = 0 Maketheaxes and titles.
C = [X, ROTATE(X, 2)] VectorofXverticesforpolygonfill-
ing. Notethat theROTATE(V,2)
function call returns thevector V
in reverseorder.
D = [A, ROTATE(A-2000, 2)] VectorofYverticesforpolygonfill-
ing.
POLYFILL, C, D, COLOR=192 Filltheregionusinganintensityof
about 75% white.
Figure 8-6 illustrates IDL PostScript images. In this case, the same image is reproduced
four times. In each case, a different number of bits are used per image pixel. It was
produced with the following IDL statements:
IDL PostScript Plot
0 50 100 150 200
Point Number
-10000
-5000
0
5000
10000
Y

A
x
i
s

T
i
t
l
e
Figure 8-5: Polygon Filling Example
SET_PLOT, 'PS'
OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data'])
Open imagefile.
a = BYTARR(192, 192, /NOZERO)
Variableto hold image.
READU, 1, a Input theimage.
CLOSE, 1 Donewith thefile.
A[0,0] = BYTSCL(INDGEN(192))#REPLICATE(1,16)
Addacolor tableramptothebot-
tom of theimage.
FOR i = 0,3 DO BEGIN Output theimagefour times.
DEVICE, BITS_PER_PIXEL=2^i Use1, 2, 4, and 8 bits per pixel.
Figure 8-6: 1, 2, 4, and 8-bit PostScript Images
The Regis Terminal Device IDL Reference Guide
TV, a, i, XSIZE=2.5, YSIZE=2.5, /INCHES
Output usingTV with position
numbers 0, 1, 2, and 3.
ENDFOR
The Regis Terminal Device
Device Keywords Accepted by the REGIS Device
AVERAGE_LINES, CLOSE_FILE, FILENAME, PLOTTER_ON_OFF,
SET_CHARACTER_SIZE, TTY, VT240, VT241, VT340, VT341
IDL provides Regis graphics output for the DEC VT240, VT330, and VT340 series of
terminals. To output graphics to such terminals, issue the IDL command:
SET_PLOT, 'REGIS'
This causes IDL to use the Regis driver for producing graphical output.
Defaults for Regis Devices
The default setting for Regis output is: VT340, 16 colors, 4 bits per pixel.
Regis Limitations
Four colors are available with VT240 and VT241 terminals, sixteen colors are available
with the VT330 and VT340.
Thick lines are emulated by lling polygons. There may be a difference in linestyle
appearance between thick and normal lines.
Imageoutput isslowand isof poor quality, especially on theVT240series. TheVT240is
onlyabletowritepixelsonevennumberedscreenlines. IDLofferstwomethodsof writing
images to the 240:
Even and odd pairs of rows are averaged and written to the screen. An n, mimage will
occupy n columns and mscreen rows. If this method is selected, graphics and image
coordinatescoincide. Thismethod isthedefault (AVERAGE_LINES = 1). Routines
that relyonauniformgraphicsandimagecoordinatesystem, suchasSHADE_SURF, work
only in this mode.
Eachlineof theimageiswrittentothescreen, displayingeveryimagepixel. Ann, mimage
occupies 2mlines on the screen. (AVERAGE_LINES = 0). Graphics and image
coordinates coincide only at the lower left corner of the image.
Pixel values cannot be read back from the terminal, rendering the TVRD function
inoperable.
IDL Reference Guide The Tektronix Device
The Tektronix Device
Device Keywords Accepted by the REGIS Device
CLOSE_FILE, COLORS, FILENAME, GIN_CHARS, PLOT_TO, RESET_STRING,
SET_CHARACTER_SIZE, SET_STRING, TEK4014, TEK4100, TTY
The Tektronix 4000 (4010, 4014, etc.), 4100 and 4200 series of graphics terminals (and
themultitudeof terminalsand microcomputersthat emulatethem) areamongthemost
common graphics devices available. To use IDL graphics with such terminals, issue the
command:
SET_PLOT,'TEK'
This causes IDL to use the Tektronix driver for producing graphical output. Once the
Tektronix driver is enabled via SET_PLOT, the DEVICE procedure is used to control its
actions, and to congure IDL for the specic features of your terminal. If you never call
the DEVICE procedure, IDL assumes a plain vanilla Tektronix 4000 series compatible
terminal. The4200seriesisupwardlycompatiblewiththe4100series; all referencestothe
4100 series also include the 4200 series. To set up IDL for use with a 4100 series
compatible terminal with n colors, enter the following commands:
SET_PLOT, 'TEK'
DEVICE, /TEK4100, COLORS = n
The number of colors should be set to 2B where B is the number of bit planes in your
terminal. If you use a Tektronix compatible terminal that requires calling the DEVICE
procedurefor conguration, youshouldprobablycreateanduseastart-upprocedurethe
calls the DEVICE procedure, as described in Chapter 2. Because of the tremendous
variation among the requirements and abilities of these terminals, it is crucial that you
congure IDL properly for your terminal. In particular, the mode switching character
sequences, set by the keyword parameters SET_STRING and RESET_STRING must be
set correctly.
The DEVICE Procedure For Tektronix Terminals
Thedefault settingfor Tektronix output is: 10-bit coordinates, 4000seriesterminals, and
no use of color. The DEVICE keywords can be used to modify these defaults.
Tektronix Limitations
Thelinedrawingprocedureswork with all models. Linestyleand color capabilitiesvary
greatly among terminal models and/or emulation programs.
Color and the display of images (albeit very slowly and frequently of a poor quality
because of the small number of colors) is usable only with 4100 series terminals.
Hardware polygon ll and thick lines do not work with the 4000 series.
The image coordinate system does not match the graphics coordinate system. The
graphics coordinates range from 0 to 3071 in Y, and from 0 to 4095 in X. Image
coordinatesvary accordingto terminal model. A typical rangeisfrom0to 479in Y, and
The Microsoft Windows Device IDL Reference Guide
0to639inX. Becauseof this, theSHADE_SURFproceduredoesnot work withTektronix
terminals.
Warning: Not all 4100 series terminals are capable of displaying imagesthe Tektronix
pixel operationsoption isrequired. Manyterminal emulatorsdonot emulatethisoption.
TheTektronix commandsused to output imagesare: RU, begin pixel operations, RS, set
pixel viewport, and RP, raster write. If your terminal or emulator does not accept these
commands, you will not be able to display images.
TheTektronix graphicsprotocol doesnot allowthespecication of linethickness. Lines
with athicknessmorethan 1.0aredrawn usingpolygon llingin thecaseof 4100series
terminals. With 4000seriesterminals, thick linesareemulated by drawingmultiplethin
lines. Thisschemewill produceartifactson someTektronix emulatingdevicesbecauseof
differing resolutions, normal line thicknesses and inexact coordinate conversions.
Tektronix Device Limitations
Usage of Tektronix and Tektronix-compatible terminals with IDL has the following
limitations:
Image coordinates do not match the coordinates used by the rest of the graphic proce-
dures. Thisisbecausenotwomodelsof Tektronixterminalsarecompatible. Thegraphics
procedures utilize the default coordinate system of 1024 by 780, or 4096 by 3120 in the
12-bit mode. The size of the pixel memory and coordinate system vary widely between
models. ThePosition parameter of the TV and TVSCL procedures does not work.
Thecursor can not bepositionedfromthecomputer meaningthat theTVCRSprocedure
cannot be used with the Tektronix driver.
Pixel values may not be read back from the terminal, rendering the TVRD function
inoperable.
The Microsoft Windows Device
Device Keywords Accepted by the WIN Device
BYPASS_TRANSLATION, COPY, CURSOR_CROSSHAIR, CURSOR_ORIGINAL,
CURSOR_STANDARD, DECOMPOSED, FONT, GET_CURRENT_FONT,
GET_FONTNAMES, GET_FONTNUM, GET_GRAPHICS_FUNCTION,
GET_SCREEN_SIZE, GET_WINDOW_POSITIONrf, PRINT_FILE, RETAIN,
SET_CHARACTER_SIZE, SET_GRAPHICS_FUNCTION, TRANSLATION,
WINDOW_STATE
TheMicrosoft Windowsversion of IDL usestheWIN deviceby default. Thisdeviceis
similar to the X Windows device described below (starting on page 171). The WIN
device is only available in IDL for Windows.
To set plotting to the Microsoft Windows device, use the command:
SET_PLOT, 'WIN'
IDL Reference Guide The X Windows Device
The X Windows Device
Device Keywords Accepted by the X Device
BYPASS_TRANSLATION, COPY, CURSOR_CROSSHAIR, CURSOR_IMAGE,
CURSOR_MASK, CURSOR_ORIGINAL, CURSOR_STANDARD, CURSOR_XY,
DECOMPOSED, DIRECT_COLOR, FLOYD, FONT, GET_CURRENT_FONT,
GET_FONTNAMES, GET_FONTNUM, GET_GRAPHICS_FUNCTION,
GET_SCREEN_SIZE, GET_VISUAL_NAME, GET_WINDOW_POSITIONrf,
GET_WRITE_MASK, ORDERED, PSEUDO_COLOR, RETAIN,
SET_CHARACTER_SIZE, SET_GRAPHICS_FUNCTION, SET_TRANSLATION,
SET_WRITE_MASK, STATIC_COLOR, STATIC_GRAY, THRESHOLD, TRUE_COLOR,
TTY, WINDOW_STATE
X Windows is a network-based windowing system developed by MITs project Athena.
IDL uses the X System (often referred to simply as X), to provide an environment in
which theuser can createoneor moreindependent windows, each of which can beused
for the display of graphics and/or images.
In the X system, there are two basic cooperating processes: clientsand servers. A server
consistsof adisplay, keyboard, and pointer (such asamouse) aswell asthesoftwarethat
controlsthem. Client processes(such asIDL) displaygraphicsand text on thescreen of a
server by sending X protocol requests across the network to the server. Although in the
most common case, theserver andclient resideon thesamemachine, thisnetwork based
design allows much more elaborate congurations.
To use X Windows as the current graphics device, issue the IDL command:
SET_PLOT, 'X'
This causes IDL to use the X Window System for producing graphical output. Once the
X driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions,
as described below.
Use the statement:
HELP, /DEVICE
to view the current state of the X Windows driver.
X Windows Visuals
Visuals specify how the hardware deals with color. The X Window server (your display)
mayprovidecolorsor onlygrayscale(black and white), or both. Thecolor tablesmaybe
changeablefromwithin IDL (read-write), or maybexed (read-only). Thevalueof each
pixel value may be mapped to any color (Un-decomposed Colormap), or certain bits of
each pixel are dedicated to the red, green, and blue primary colors (Decomposed
Colormap).
Therearesix XWindowsvisual classesread-writeand read-onlyvisualsfor threetypes
of displays: Gray Scale, Pseudo Color, and Decomposed Color. The names of the visuals
are shown in Table 8-13.
The X Windows Device IDL Reference Guide
IDL supportsall six typesof visuals, although not at all possibledepths. Unix XWindow
System users can use the command xdpyinfo to determine which visuals are
supported by their systems.
Each X Window server has a default visual class. Many servers may provide multiple
visual classes. For example, a server with display hardware that supports an 8-bit-deep,
un-decomposed, writablecolor map(PseudoColor), mayalsoeasilyprovideStaticColor,
StaticGray, and GrayScale visuals.
You can select the visual used by IDL using the DEVICE procedure before a window is
created, or by including the resourceidl.gr_visual in your X defaults le, as
explained in Setting the X Window Defaults on page 177
How IDL Selects a Visual Class
When openingthedisplay, IDL asksthedisplayfor thefollowingvisuals, in order, until a
supported visual class is found:
You can overridethisbehavior by usingtheDEVICEroutinetospecify thedesired visual
class and depth before you create a window. For example, if you are using a display that
supportsboththeDirectColor, 24-bit-deepvisual, andan8-bit-deepPseudoColor visual,
IDL will select the24-bit-deep DirectColor visual. To instead usePseudoColor, issuethe
following command before creating a window:
DEVICE, PSEUDO_COLOR = 8
Visual Name Writable Description
StaticGray no Gray scale
GrayScale yes Gray scale
StaticColor no Undecomposed color
PseudoColor yes Undecomposed color
TrueColor no Decomposed color
DirectColor yes Decomposed color
Table 8-13: X Windows Visual Classes
DirectColor, 24-bit
TrueColor, 24-bit
PseudoColor, 8-bit, then 4-bit
StaticColor, 8-bit, then 4-bit
GrayScale, any depth
StaticGray, any depth
The colormap/visual class combination is chosen when IDL rst connects with the X
Windowserver. Notethat if you connect with theXserver bycreatingawindowor using
the DEVICE keyword to the HELP procedure, the visual class will be set; it then cannot
bechanged until IDL isrestarted. If you wish to useavisual classother than thedefault,
besuretoset it withacall totheDEVICEprocedurebeforecreatingwindowsor otherwise
connecting with the X Window server.
Windows are created in two ways:
1. Using the WINDOW procedure. WINDOW allows you to explicitly control many
aspects of how the window is created.
2. If no windows exist and a graphics operation requiring a window is executed, IDL
implicitly creates window 0 with the default characteristics.
Once the visual class is selected, all subsequently-created windows share the same class
and colormap. The number of simultaneous colors available is stored in the system
variable !D.N_COLORS. The visual class and number of colors, once initialized, cannot
be changed without rst exiting IDL.
How IDL Obtains a Colormap
IDL chooses the type of colormap in the following manner:
Bydefault, thesharedcolormapisusedwhenever possible(i.e., whenever IDLisusingthe
default visual for thesystem). All availablecolorsfromtheshared colormap areallocated
for use by IDL. This is what happens when no window currently exists and a graphics
operation causes IDL to implicitly create one.
If thenumber of colorsto useisexplicitly specied usingtheCOLORSkeyword with the
WINDOW procedure, IDL attempts to allocate the number of colors specied from the
shared colormap using the default visual of the screen. If there arent enough colors
available, a private colormap with that number of colors is used instead.
Specifyinganegativevaluefor theCOLORSkeywordtotheWINDOWprocedurecauses
IDL to attempt to use the shared colormap, allocating all but the specied number of
colors. For example:
WINDOW, COLORS = -8
allocates all but 8 of the currently available colors. This allows other applications that
might need their own colors to run in tandem with IDL.
If avisual typeand depth isspecied, viatheDEVICEprocedure, which doesnot match
the default visual of the screen, a new, private, colormap is created.
Using Color Under X
Colormaps dene the mapping from color index to screen color. Two attributes of
colormapsareimportant totheIDL user: theymaybeprivateor shared; and theymaybe
static or writable. These different types of colormaps are described below.
Shared Colormaps
Thewindowmanager createsacolormap when it isstarted. Thisisknown asthedefault
colormap, and can be shared by most applications using the display. When each
application requires a colormap entry (i.e., a mapping from a color index to a color), it
allocatesonefromthisshared table. Advantagesand disadvantagesof shared colormaps
include:
Usingthesharedcolormapensuresthat all applicationssharetheavailablecolorswithout
conict. A given application will not change a color that is allocated to a different
application. In the case of IDL it means that IDL can change the colors it has allocated
without changing the colors in use by the window manager or other applications.
The window system interface routines must translate between the actual and allocated
pixel values, signicantly slowing the transfer of images.
The shared colormap might not have enough colors available to perform the desired
operations with IDL.
Thenumber of availablecolorsin theshared colormap dependson thewindowmanager
in use and the demands of other applications. Thus, the number of available colors can
vary.
Theallocated colorsin ashared colormap do not generally start at zero and they arenot
necessarilycontiguous. Thismakesit difcult tousethewritemask for certainoperations.
Private Colormaps
An application can create its own private color map. Most hardware can only display a
single colormap at a time, so these private colormaps are called virtual color maps, and
onlyoneat atimeisactuallyinuseandvisible. Whenthewindowmanager givesthecolor
focus to a window with a private colormap, the X window system loads its virtual
colormap into the hardware colormap.
Everycolor index supportedbythehardwareisavailabletoIDL, improvingthequalityof
images.
Allocated colors always start at zero and are contiguous. This simplies using the write
mask.
No translation between internal pixel values and the values required by the server is
required, making the transfer of images more efcient.
WhentheIDLcolormapisloaded, other applicationsaredisplayedusingthewrongcolors.
Furthermore, colors from the shared colormap are usually allocated from the lower end
of themap rst. Thesearethecolorsallocated by thewindowmanager for such thingsas
windowborders, thecolor of text, andsoforth. Sincemost IDLcolormapshaveverydark
colors in the lower entries, the end effect with the IDL colormap loaded is that the non-
IDL portions of the screen go blank.
Static Colormaps
Asmentioned above, thecontentsof staticcolormapsaredetermined outsideof IDL and
cannot be changed. When using a static colormap, the TVLCT procedure simulates
writable colormaps by nding the closest RGB color entry in the colormap to the
requested color. The colormap translation table is then set to map IDL color indices to
those of the closest colors in the colormap.
The colors present in the colormap may, and probably will, not match the requested
colors exactly. For example, with a typical static color map, loading the IDL standard
color table number 0, which consists of 256 intensities of gray, results in only 8 or 16
distinct intensities.
With static colormaps, loading a new color table does not affect the appearance of
previously written objects. The internal translation tables are modied, which only
affects objects that are subsequently written.
Color Translation
Asmentionedabove, colorsfromthesharedcolormapdonot necessarilystart fromindex
zero, and are not necessarily contiguous. IDL preserves the illusion of a zero based
contiguous colormap by maintaining a translation table between user color indices,
which rangefrom0to !D.TABLE_SIZE, and theactual pixel valuesallocated fromtheX
server. Normally, the user need not be concerned with this translation table, but it is
available using the statement:
DEVICE, TRANSLATION=T
This statement stores the current translation table, a 256 element byte vector, in the
variable T. Element zero of the vector contains the value pixel allocated for the zeroth
color in theIDL colormap, and so forth. In thecaseof aprivatecolormap, each element
of thetranslation vector containsitsown index value, becauseprivatecolormapsstart at
zero and are contiguous.
The translation table may be bypassed, allowing direct access to the displays color
indices, by setting the BYPASS_TRANSLATION keyword in the DEVICE procedure.
DEVICE, /BYPASS_TRANSLATION
Translation can be reestablished by setting the keyword to zero:
DEVICE, BYPASS_TRANSLATION=0
When aprivateor static(read-only) color tableisinitialized, thebypassagiscleared. It
is set when initializing a shared color table.
Using Pixmaps
XWindowscan direct graphicsto windowsor pixmaps. Windowsaretheusual windows
that appear on the screen and contain graphics. Pixmaps are invisible graphics memory
contained in theserver. Drawingto awindowproducesaviewableresult, whiledrawing
to a pixmap simply updates the pixmap memory.
Pixmapsareuseful becauseit ispossibleto writegraphicsto apixmap and then copy the
contents of the pixmap to a window where it can be viewed. Furthermore, this copy
operation is very fast because it happens entirely within the server. Provided enough
pixmap memory is available, this technique works very well for animating a series of
images by placing the images into pixmap memory and then sequentially copying them
to a visible window.
To create a pixmap, use the PIXMAP keyword with the WINDOW procedure. For
example, to create a square pixmap with 128 pixels per side as IDL window 1, use the
command:
WINDOW, 1, /PIXMAP, XSIZE=128, YSIZE=128
Once they are created, pixmaps are treated just like normal windows, although some
operations (WSHOW for instance) dont do anything useful when applied to a pixmap.
The following procedure shows how animation can be done using pixmap memory. It
uses a series of 15 heart images taken from the leabnorm.dat. This le is supplied
with all IDL distributions in thedata subdirectory of the imagesexamples of the
main IDL directory. It createsapixmap and writestheheart imagesto it. It then usesthe
COPY keyword of the DEVICE procedure to copy the images to a visible window.
Pressing any key causes the display process to halt:
PRO animate_heart Animateheart series.
OPENR, u, FILEPATH('abnorm.dat', SUBDIR = ['examples','data']), $
/GET_LUN Openthefilecontainingtheimag-
es.
frame = ASSOC(u, BYTARR(64,64)) Associatea filevariablewith the
file. Each heart imageis 64x64
pixels.
WINDOW, pixwin, /PIXMAP, XSIZE = 512, YSIZE = 512, /FREE
Window pixwin is a pixmap
whichis4imagestalland4images
wide.Theimageswill beplacedin
this pixmap.
FOR i=0, 15-1 DO TV, REBIN(SMOOTH(frame[i],3), 128, 128),i
Writeeach imageto thepixmap.
SMOOTHisusedtoimprovethe
appearanceofeachimageandRE-
BINisusedtoenlarge/shrinkeach
imageto thefinal display size.
FREE_LUN, u Closetheimagefileandfreethefile
unit.
WINDOW, win, XSIZE = 128, YSIZE=128, TITLE='Heart', /FREE
Window win is a visiblewindow.
It will beused to display theani-
mated heart cycle.
i = 0L Current framenumber.
WHILE GET_KBRD(0) EQ '' DO BEGIN Display frames until any key is
pressed.
x = (i mod 4) * 128 & y = 384 - (i/4) * 128
Computexandylocationsofpix-
map images lower left corner.
DEVICE, COPY = [x, y, 128, 128, 0, 0, pixwin]
Copythenextimagefromthepix-
map to thevisiblewindow.
i = (i + 1) MOD 15 Keep track of total framecount.
ENDWHILE
END
Animation sequences with more and/or larger images can be made. See the
documentationfor theXANIMATEprocedure, whichisamoregeneralizedembodiment
of the above procedure.
Note: Some X Windows servers will refuse to create a pixmap that is larger than the
physical screen in either dimension.
Setting the X Window Defaults
Youcan set theinitial default valueof thefollowingparametersbysettingresourcesin the
le.Xdefaults (Unix), or DECW$SM_GENERAL.DAT (VMS) in your home
directory as follows:
Resource
Name
Description
idl.colors The number of colors used by IDL.
idl.gr_depth The depth, in bits, of the visual used by IDL.
idl.retain The default setting for theretainparameter: 0=none, 1= by
server, 2=by IDL.
idl.gr_visual The type of visual: StaticGray, GrayScale, StaticColor, Pseudo-
Color, TrueColor, or DirectColor.
idl.olh_text_widt
h
The width for the online help window.
idl.olh_text_heigh
t
The height for the online help window.
Table 8-14: IDL/ X Window Defaults
The Z-Buffer Device IDL Reference Guide
For example, toset thedefault visual toPseudoColor, andtoallocate100colors, insert the
following lines in your defaults le:
idl.gr_visual: PseudoColor
idl.colors: 100
The Z-Buffer Device
Device Keywords Accepted by the Z Device
CLOSE, GET_GRAPHICS_FUNCTION, GET_WRITE_MASK,
SET_CHARACTER_SIZE, SET_COLORS, SET_GRAPHICS_FUNCTION,
SET_RESOLUTION, Z_BUFFERING
The IDL Z-buffer device is a pseudo device that draws 2D or 3D graphics in a buffer
contained in memory. This driver implements the classic Z buffer algorithm for hidden
surface removal. Although primarily used for 3D graphics, the Z-buffer driver can be
used to create2D objectsin aframebuffer in memory. Theresolution of thisdevicecan
be set by the user.
All of the IDL plotting and graphics routines work with the Z-buffer device driver. In
addition, the POLYFILL procedure has a few keyword parameters, allowing Gouraud
shadingandwarpingimagesover 3Dpolygons, that areonlyeffectivewhen usedwiththe
Z-buffer.
When used for 3D graphics, two buffers are present: an 8-bit-deep frame buffer that
containsthepicture; and a16-bit-deep Z-buffer of thesameresolution, containingthez-
valueof thevisiblesurfaceof eachpixel. TheZ-buffer isinitializedtothedepthat theback
of the viewing volume. When objects are drawn, the z-value of each pixel is compared
with thevalueat thesamelocation in theZ-buffer, and if thez-valueisgreater (closer to
theviewer), thenewpixel iswritten in theframebuffer and theZ-buffer isupdated with
the new z-value.
The Z-buffer device is a pseudo device in that drawing commands update buffers in
memory rather than sendingcommandsto aphysical deviceor le. TheTVRD function
reads the contents of either buffer to an IDL array. This array may then be further
processed, written to a le, or output to a raster-based graphics output device.
The Z-buffer driver can be used for 2D graphics by disabling the depth computations.
To use the Z-buffer as the current graphics device, issue the IDL command:
SET_PLOT, 'Z'
OncetheZ-buffer driver isenabled theDEVICEprocedureisused to control itsactions,
as described below.
Use the statement:
HELP, /DEVICE
IDL Reference Guide The Z-Buffer Device
to view the current state of the Z-buffer driver and the amount of memory used for the
buffers.
Reading and Writing Buffers
The contents of both buffers are directly accessed by the TV and TVRD routines. The
frame buffer that contains the picture is 8 bits deep and is accessed as channel 0. The Z
depth buffer contains 16 bit integers and is accessed as channel 1. Always use
CHANNEL=1 and set the keyword WORDS when reading or writing the depth buffer.
Thenormal procedureistoset thegraphicsdeviceto Z, drawtheobjects, readtheframe
buffer, and then select another graphics device and write the image. For example, to
create an image with the Z-buffer driver and then display it on an X-Window display:
SET_PLOT,Z Select Z-buffer device.
... ... ... Writeobjects to theframebuffer
usingnormal graphics routines,
e.g. PLOT, SURFACE, POLY-
FILL.
a=TVRD() Readbacktheentireframebuffer.
SET_PLOT,X Select X Windows.
TV, a Display thecontents of theframe
buffer.
To read the depth values in the Z-buffer, use the command:
a = TVRD(CHANNEL=1, /WORDS)
To write the depth values, use the command:
TV, a, /WORDS, CHANNEL=1
TheTV, TVSCL, and TVRDroutineswriteor read pixelsdirectly to arectangular areaof
the designated buffer without affecting the other buffer.
Z-Axis Scaling
The values in the depth buffer are short integers, scaled from -32765 to +32765,
corresponding to normalized Z-coordinate values of 0.0 to 1.0.
Polyll Procedure
The following POLYFILL keywords are active only with the Z-buffer device:
IMAGE_COORDINATES, IMAGE_INTERPOLATE, and TRANSPARENT. These
parametersallowimages, speciedviathePATTERNkeyword, tobewarpedover 2Dand
3D polygons.
The IMAGE_COORDINATES keyword contains a 2 by N array containing the image
space coordinates that correspond to each of theN vertices of the polygon. The
IMAGE_INTERPOLATE keyword indicates that bilinear interpolation is to be used,
rather than the default nearest neighbor sampling. Pixels less than the value of
TRANSPARENT are not drawn, simulating transparency. For Gouraud shading of
polygons, the COLOR keyword can contain an array specifying the color index for each
polygon vertex.
Examples Using the Z-Buffer
ThisexampleformsaBessel function, drawsitsshaded surfaceand overlaysitscontour,
using the Z-buffer as shown in Figure 8-8The nal output is directed to PostScript.
SET_PLOT, 'Z' Select theZ-buffer.
n = 50 Sizeof array for Bessel.
a = BESELJ(SHIFT(DIST(n), n/2, n/2)/2, 0)
MaketheBessel function.
SHADE_SURF, a, /SAVE, COLOR=1, BACKGROUND=255
Draw thesurface, label axes in
black, background in white.
nlev = 8 Number of contour levels.
CONTOUR, a, /OVERPLOT, ZVALUE=.6, /T3D, $
LEVELS=FINDGEN(nlev)*1.5/nlev-.5, COLOR=1
MaketheContour at normalized
Z=.6.
b=TVRD() Read image.
Figure 8-7: Combined Shaded Surface and Contour Plot
IDL Reference Guide The Z-Buffer Device
SET_PLOT, 'PS' Select PostScript output.
TV, b Output theimage.
DEVICE, /CLOSE Closethenew PostScript file.
Thefollowingexamplewarpsan imageto acubeasshown in Figure8-8. Thelower two
quadrants of the image are warped to the front two faces of the cube. The upper-right
quadrant is warped to the top face of the cube. The image is held in the array a, with
dimensionsnx by ny.
SET_PLOT, 'Z' Select theZ-buffer.
ERASE, 255 Makeawhitebackgroundforfinal
output to PostScript.
SCALE3, XRANGE=[0,1], YRANGE=[0,1], ZRANGE=[0,1]
Establish3Dscalingas(0,1) cube.
verts = [[0,0,0], [1,0,0], [1,1,0], [0,1,0], $
[0,0,1], [1,0,1], [1,1,1], [0,1,1]]
Definevertices of cube. Vertices 0-
3 arebottom, 4-7 aretop.
POLYFILL, verts[*, [3,0,4,7]], /T3D, PATTERN=a, $
IMAGE_COORD=[[0,0], [nx/2,0], [nx/2,ny/2], [0,ny/2]]
Fill lower left face.
IMAGE_COORD=[[nx/2,0], [nx-1,0], $
[nx-1,ny/2], [nx/2,ny/2]] Lower right face.
IMAGE_COORD = [[nx/2,ny/2], [nx-1,ny/2], $
[nx-1,ny-1], [nx/2,ny-1]] Top face.
PLOTS, verts[*, [0,4]], /T3D, COLOR=0 Draw edges of cubein black.
PLOTS, verts[*, [4,5,6,7,4]], /T3D, COLOR=0
Edges of top face.
The image is then output to PostScript as in the previous example.
Figure 8-8: Image Warped to a Cube Using the Z-Buffer
183
Chapter 9
IDL Routines
This chapter describes IDLs built-in functions and procedures. Graphics routines that
useIDL Direct Graphicsaredescribed here; IDL Object Graphicsroutinesaredescribed
in Objects and Object Graphics. Conventions used in this chapter are described below.
How to Use this Chapter
All of IDLsroutinesaredocumentedalphabeticallyin thischapter. Adescription of each
routinefollowsitsname. Beneath thegeneral description of theroutineareanumber of
sections that describe the calling sequence for the routine, its arguments (if any), its
keywords (if any), and an example of using the routine. These sections are described
below.
Routineswritten in theIDL languagearenoted assuch, and thelocation of the.pro le
within theIDL distribution isspecied. You may wish toinspect theIDL sourcecodefor
some of these routines to gain further insight into their inner workings.
184 Chapter 9: IDL Routines
How to Use this Chapter IDL Reference Guide
Calling Sequence
The Calling Sequence section shows the proper syntax for calling the function or
procedure.
Procedures
IDL procedures have the calling sequence:
PROCEDURE_NAME, Argument [, Optional_Arguments]
where PROCEDURE_NAME is the name of the procedure, Argument is a required
parameter, and Optional_Argumentisan optional parameter totheprocedure. Notethat
the square brackets around optional arguments are not used in the actual call to the
procedure, they are simply used to denote the optional nature of the arguments within
this document.
Functions
IDL functions have the calling sequence:
Result = FUNCTION_NAME(Argument [, Optional_Arguments])
whereResultisthereturnedvalueof thefunction, FUNCTION_NAMEisthenameof the
function, Argument is a required parameter, and Optional_Argument is an optional
parameter. Notethat thesquarebracketsaround optional argumentsarenot used in the
actual call to the function, they are simply used to denote the optional nature of the
arguments within this document. Note also that all arguments and keyword arguments
to functions should be supplied within the parentheses that follow the functions name.
Functionsdo not alwayshaveto beused 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
argumentsarepositional parametersthat must besupplied in theorder indicated by the
routines calling sequence.
Named Variables
Often, arguments that contain values upon return from the function or procedure
(output arguments ) aredescribed asaccepting named variables. Anamed variableis
simply avalid IDL variablename. Thisvariabledoesnot need to bedened beforebeing
used as an output argument. Note, however that when an argument calls for a named
variable, only a named variable can be usedsending an expression causes an error.
Chapter 9: IDL Routines 185
IDL Reference Guide How to Use this Chapter
Keywords
The Keywords section describeseachvalidkeywordargument totheroutine. Notethat
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
valuecanbeavalue, anexpression, or anamedvariable(anamedvariableissimplyavalid
IDL variable name).
Note If you set a keyword equal to an undened 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
Keywords can be abbreviated to their shortest unique length. For example, the XSTYLE
keyword can be abbreviated to XST.
Setting Keywords
When the documentation for a keyword says something similar to, Set this keyword to
enablelogarithmicplotting, thekeyword issimply aswitch that turnsan option on and
off. Usually, settingsuchkeywordsequal to1causestheoption tobeturnedon. Explicitly
setting the keyword to zero (or not including the keyword) turns the option off.
Thereisashortcut that can beusedtoset akeywordequal to1without theusual syntax
(i.e., KEYWORD=1). To set akeyword, simply prefaceit with aslash character ( / ). For
example, to plot awiremesh surfacewith askirt around it, set theSKIRT keyword to the
SURFACE routine as follows:
SURFACE, DIST(10), /SKIRT
Named Variables
Often, keywords that contain values upon return from the function or procedure
(output arguments ) are described as accepting named variables. Variables that will
contain output valuesdo not need to be dened before being used with the keyword.
Note, however that when akeywordcallsfor anamedvariable, onlyanamedvariablecan
be usedsending an expression causes an error.
For example, theWIDGET_CONTROL procedurecan return theuser valuesof widgets
in a named variable using the GET_UVALUE keyword. To return the user value for a
widget ID(containedin thevariablemywidget) in thevariableuserval, youwoulduse
the command:
WIDGET_CONTROL, mywidget, GET_UVALUE = userval
Upon return fromtheprocedure, userval containstheuser value. Notethat userval
did not have to be dened before the call to WIDGET_CONTROL.
How to Use this Chapter IDL Reference Guide
Examples
Most routinesincludeashort examplethat demonstrateshowthefunction or procedure
isused. Most of theexamplesarejust oneor two linesof IDL codethat can beentered at
theIDL prompt. Othersarecodefragmentsor routinesdesignedtoserveasexamplesfor
you own programs.
See Also
The names of related routines are listed in this section.
IDL Reference Guide A_CORRELATE
A_CORRELATE
The A_CORRELATE function computes the autocorrelation P
x
(L) or autocovariance
R
x
(L)of a sample population X as a function of the lagL.
wherexis the mean of the sample population x = (x
0
, x
1
, x
2
, ... , x
N-1
).
Note This routine is primarily designed for use in 1-D time-series analysis. The mean is
subtracted before correlating.
This routine is written in the IDL language. Its source code can be found in the le
a_correlate.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = A_CORRELATE(X, Lag)
Arguments
X
An n-element integer, single-, or double-precision oating-point vector.
Lag
Ann-element integer vector intheinterval [ -(n-2), (n-2)] , specifyingthesigneddistances
between indexed elements of X.
Keywords
COVARIANCE
Set this keyword to compute the sample autocovariance rather than the sample
autocorrelation.
P
x
L ( ) P
x
L ( )
x
k
x ( ) x
k L +
x ( )
k 0 =
N L 1
x
k
x ( )
2
k 0 =
N 1
---------------------------------------------------------------- = =
R
x
L ( ) R
x
L ( )
1
N
---- x
k
x ( ) x
k L +
x ( )
k 0 =
N L 1
= =
A_CORRELATE IDL Reference Guide
DOUBLE
Set this keyword to force the computation to be done in double-precision arithmetic.
Example
Dene 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
IDL Reference Guide ABS
ABS
The ABS function returns the absolute value of its argument.
Calling Sequence
Result = ABS(X)
Arguments
X
Thevaluefor which theabsolutevalueisdesired. If Xisof complex type, ABSreturnsthe
magnitude of the complex number:
If Xisof complextype, theresult isreturnedasthecorrespondingoatingpoint type. For
all other types, the result has the same type asX. If X is an array, the result has the same
structure, with each element containingtheabsolutevalueof thecorrespondingelement
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)
25
Real
2
I maginary
2
+
ACOS IDL Reference Guide
ACOS
The ACOS function returns the angle, expressed in radians, whose cosine isX (i.e., the
arc-cosine). The range of ACOS is between 0 and .
Calling Sequence
Result = ACOS(X)
Arguments
X
Thecosineof thedesiredanglein therange(-1 X 1). If Xisdouble-precision oating,
the result of ACOS is also double-precision. X cannot be complex. All other types are
converted to single-precision oating-point and yield oating-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 nd the arc-cosine of 0.707 and store the result in the variable B, enter:
B = ACOS(0.707)
See Also
COS
IDL Reference Guide ALOG
ALOG
TheALOGfunction returnsthenatural logarithmof X. Theresult hasthesamestructure
asX.
Calling Sequence
Result = ALOG(X)
Arguments
X
The value for which the natural log is desired. The result of ALOG is double-precision
oating if X is double-precision, and complex if X is complex. All other types are
converted to single-precision oating-point and yield oating-point results. When
applied to complex numbers, the denition 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
ALOG10 IDL Reference Guide
ALOG10
TheALOG10function returnsthelogarithmto thebase10of X. Thisfunction operates
in the same manner as the ALOG function.
Calling Sequence
Result = ALOG10(X)
Arguments
X
The value for which the base 10 log is desired.
Example
To nd the base 10 logarithm of 5 and store the result in the variable L, enter:
L = ALOG10(5)
See Also
ALOG
IDL Reference Guide AMOEBA
AMOEBA
The AMOEBA function performs multidimensional minimization of a function Func(x),
wherex is an n-dimensional vector, using the downhill simplex method of Nelder and
Mead, 1965, Computer Journal, Vol 7, pp 308-313.
Thedownhill simplex method isnot asefcient asPowellsmethod, and usuallyrequires
more function evaluations. However, the simplex method requires only function
evaluationsnot derivativesand may be more reliable than Powells method.
If the minimum is found, AMOEBA returns an n-element vector corresponding to the
functionsminimumvalue. If aminimumwithin thegiven toleranceisnot found within
the specied number of iterations, AMOEBA returns a scalar value of -1. Results are
returned with the same precision (single- or double-precision oating-point) as is
returned by the user-supplied function to be minimized.
amoeba.pro in thelib subdirectory of theIDL distribution. AMOEBAisbased on the
routineamoeba described in section 10.4of Numerical RecipesinC: TheArt of Scientic
Computing(Second Edition), published by Cambridge University Press, and is used by
permission.
Calling Sequence
Result = AMOEBA(Ftol)
Arguments
Ftol
The fractional tolerance to be achieved in the function valuethat is, the fractional
decreasein thefunction valuein theterminatingstep. If thefunction you supply returns
a single-precision result, Ftol should never be less than your machines oating-point
precisionthe value contained in the EPS eld of the structure returned by the
MACHARfunction. If thefunction you supplyreturnsadouble-precision oating-point
value, Ftol should not be less than your machine double-precision oating-point
precision. See MACHAR on page 703 for details.
Keywords
FUNCTION_NAME
Set thiskeyword equal to astringcontainingthenameof thefunction to beminimized.
If thiskeyword isomitted, AMOEBAassumesthat an IDL function named FUNC isto
be used.
AMOEBA IDL Reference Guide
Thefunction tobeminimized must bewritten asan 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 oating-point value as its result.
See theExamplesection below for an example function.
FUNCTION_VALUE
Set thiskeyword equal to anamed variablethat will contain an (n+1)-element vector of
the function values at the simplex points. The rst 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 thiskeyword equal to an n-element single- or double-precision oating-point vector
specifying the initial starting point. Note that if you specify P0, you must also specify
SCALE.
For example, in a3-dimensional problem, if theinitial guessisthepoint [ 0,0,0] , and you
know that the functions 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 problems
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.
SIMPLEX
Set this keyword equal to an n by n+1 single- or double-precision oating-point array
containing the starting simplex. After AMOEBA has returned, the SIMPLEX array
contains the simplex enclosing the function minimum. The rst point in the array,
SIMPLEX[ *,0] , corresponds to the functions minimum. This keyword is ignored if the
P0 and SCALE keywords are set.
Example
Use AMOEBA to nd the slope and intercept of a straight line that ts a given set of
points, minimizing the maximum error. The function to be minimized (FUNC, in this
IDL Reference Guide AMOEBA
case) returns the maximum error, given p[ 0] = intercept, and p[ 1] = slope. First dene
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
Dene 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
ANNOTATE IDL Reference Guide
ANNOTATE
TheANNOTATEprocedurestartsanIDLwidget programthat allowsyoutointeractively
annotateimagesandplotswithtext anddrawings. Drawingobjectsincludelines, arrows,
polygons, rectangles, circles, andellipses. Annotation lescan besavedandrestored, and
annotateddisplayscanbewrittentoTIFF, GIF, or PostScript les. TheAnnotationwidget
will work on any IDL graphics window or draw widget.
annotate.pro in thelib subdirectory of the IDL distribution.
Using the Annotation Widget
Before calling the Annotation widget, plot or display your data in an IDL graphics
window or draw widget. Unless you specify otherwise (using the DRAWABLE or
WINDOW keywords), annotations will be made in the current graphics window.
For information on using the Annotation widget, click on the widgets Help button.
Calling Sequence
ANNOTATE
Arguments
This procedure has no required arguments.
Keywords
COLOR_INDICES
An array of color indices from which the user can choose colors. For example, to allow
the user to choose 10 colors, spread evenly over the available indices, set the keyword as
follows:
COLOR_INDICES = INDGEN(10) * (!D.N_COLORS-1) / 9
If neither TEK_COLORS or COLOR_INDICES are specied, the default is to
load 10 colors, evenly distributed over those available.
DRAWABLE
Thewidget ID of thedrawwidget for theannotations. Do not set both DRAWABLEand
WINDOW. If neither WINDOW or DRAWABLE are specied, the current window is
used.
IDL Reference Guide ANNOTATE
LOAD_FILE
The name of an annotation format le to load after initialization.
TEK_COLORS
Set this keyword and the Tektronix color table is loaded starting at color index
TEK_COLORS(0), with TEK_COLORS(1) color indices. The Tektronix color table
contains up to 32 distinct colors suitable for graphics. If neither TEK_COLORS or
COLOR_INDICES are specied, the default is to load 10 colors, evenly distributed over
those available.
WINDOW
The window index number of the window to receive the annotations. Do not set both
DRAWABLE and WINDOW. If neither WINDOW or DRAWABLE are specied, the
current window is used.
Example
TVSCL, HANNING(300,200) Output an imagein thecurrent
window.
ANNOTATE Annotateit.
See Also
PLOTS, XYOUTS
ARG_PRESENT IDL Reference Guide
ARG_PRESENT
The ARG_PRESENT function returns a nonzero value if the following conditions are
met:
The argument to ARG_PRESENT was passed as a plain or keyword argument to the
current routine by its caller, and
Theargument toARG_PRESENTisanamedvariableintowhichavaluewill becopied
when the current routine exits.
In other words, ARG_PRESENT returns TRUE if the value of the specied variable will
bepassed back to thecaller. Thisfunction isuseful in user-written proceduresthat need
to know if the lifetime of a value they are creating extends beyond the current routines
lifetime. This can be important for two reasons:
1. To avoid expensive computations that the caller is not interested in.
2. To prevent heap variable leakage that would result if the routine creates pointers or
object referencesandassignsthemtoargumentsthat arenotpassedback tothecaller.
Calling Sequence
Result = ARG_PRESENT(Variable)
Arguments
Variable
The variable to be tested.
Example
Suppose that you are writing an IDL procedure that has the following procedure
denition line:
PRO myproc, RET_PTR = ret_ptr
The intent of the RET_PTR keyword is to pass back a pointer to a new pointer heap
variable. Thefollowingcommand could beused toavoid creating(and possiblylosing) a
pointer if no named variable is provided by the caller:
IF ARG_PRESENT(ret_ptr) THEN BEGIN
The commands that follow would only be executed if ret_ptr is supplied and will be
copied into a variable in the scope of the calling routine.
IDL Reference Guide ARG_PRESENT
See Also
KEYWORD_SET, N_ELEMENTS, N_PARAMS
ARROW IDL Reference Guide
ARROW
The ARROW procedure draws one or more vectors with arrow heads.
arrow.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
ARROW, X0, Y0, X1, Y1
Arguments
X0, Y0
Arrays or scalars containing the coordinates of the tail end of the vector or vectors.
Coordinates are in DEVICE coordinates unless otherwise specied.
X1,Y1
Arraysor scalarscontainingthecoordinatesof thearrowheadendof thevector or vectors.
X1 and Y1 must have the save number of elements asX0 and Y0.
Keywords
DATA
Set this keyword if vector coordinates are DATA coordinates.
NORMALIZED
Set this keyword if vector coordinates are NORMALIZED coordinates.
HSIZE
Usethiskeyword to set thelength of thelinesused to drawthearrowhead. Thedefault is
1/64th the width of the display (!D.X_SIZE / 64.). If the HSIZE is positive, the value is
assumed to be in device coordinate units. If HSIZE is negative, the arrowhead length is
set to thevector length * ABS(HSIZE). Thelinesareseparated by 60degreesto makethe
arrowhead.
COLOR
The color of the arrow. The default is the highest color index.
HTHICK
The thickness of the arrowheads. The default is 1.0.
SOLID
Set thiskeyword to makeasolid arrow, usingpolygon lls, looksbetter for thick arrows.
IDL Reference Guide ARROW
THICK
The thickness of the body. The default is 1.0.
Examples
Draw an arrow from (100,150) to (300,350) in DEVICE units.
ARROW, 100, 150, 300, 350
Draw a sine wave with arrows from the line Y = 0 to SIN(X/4).
X = FINDGEN(50)
Y = SIN(x/4)
PLOT, X, Y
ARROW, X, REPLICATE(0,50), X, Y, /DATA
See Also
ANNOTATE, PLOTS, VELOVECT
ASCII_TEMPLATE IDL Reference Guide
ASCII_TEMPLATE
The ASCII_TEMPLATE function presents a graphical user interface (GUI) which
generatesatemplatedeningan ASCII leformat. TemplatesareIDL structurevariables
that may be used when reading ASCII les with the READ_ASCII routine. See
READ_ASCII on page 898 for details on reading ASCII les.
ascii_template.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = ASCII_TEMPLATE([Filename])
Arguments
Filename
Astringcontainingthenameof aletobasethetemplateon. If Filenameisnot specied,
a dialog allows you to choose a le.
Keywords
BROWSE_LINES
Set this keyword equal to the number of lines that will be read in at a time when the
Browse button is selected. The default is 50 lines.
CANCEL
Set thiskeyword to anamed variablethat will contain thebytevalue1if theuser clicked
the Cancel button or 0 otherwise.
GROUP
Thewidget IDof anexistingwidget that servesasgroupleader for theASCII_TEMPLATE
GUI. When a group leader is killed, for any reason, all widgets in the group are also
destroyed.
Examples
Use the following command to generate a template structure from the le myFile.
myTemplate = ASCII_TEMPLATE(myFile)
See Also
READ_ASCII
IDL Reference Guide ASIN
ASIN
The ASIN function returns the angle, expressed in radians, whose sine isX (i.e., the arc-
sine). Therangeof ASIN isbetween -/2and /2. Rulesfor thetypeand structureof the
result are the same as those given for the ACOS function.
Calling Sequence
Result = ASIN(X)
Arguments
X
The sine of the desired angle, -1 X 1.
Example
To print the arc-sine of 0.707, enter:
PRINT, ASIN(0.707)
IDL prints:
0.785247
See Also
SIN
ASSOC IDL Reference Guide
ASSOC
TheASSOCfunction associatesan array structurewith ale. It providesabasicmethod
of random access input/output in IDL. An associated variable, which stores this
association, is created by assigning the result of ASSOC to a variable. This variable
provides a means of mapping a le into vectors or arrays of a specied type and size.
Note Unformatted data les generated by FORTRAN programs under UNIX contain an
extra long word before and after each logical record in the le. ASSOC does not
interpret theseextrabytesbut considersthemtobepart of thedata. Thisistrueeven
if theF77_UNFORMATTEDkeywordisspeciedontheOPENstatement. Therefore,
ASSOC should not be used with such les. Instead, such les should be processed
usingREADU and WRITEU. An exampleof usingIDL to read such dataisgiven in
Using Unformatted Input/Output on page 191 of Building IDL Applications.
Calling Sequence
Result = ASSOC(Unit, Array_Structure[, Offset])
Arguments
Unit
The IDL le unit to associate with Array_Structure.
Array_Structure
An expression of the data type and structure to be associated with Unit are taken from
Array_Structure. The actual value of Array_Structureis not used.
Offset
The offset in the le to the start of the data in the le. For stream les, and RMS (VMS)
block mode les, this offset is given in bytes. For RMS record-oriented les, the offset is
specied in records. Offset is useful for dealing with data les that contain a descriptive
header block followed by the actual data.
Keywords
PACKED
When ASSOC is applied to structures, the default action is to map the actual denition
of the structure for the current machine, including any holes required to properly align
the elds. (IDL uses the same rules for laying out structures as the C language). If the
PACKEDkeyword isspecied, I/Ousingtheresultingvariableinstead worksin thesame
manner asREADU and WRITEU, and dataismoved oneeld at atimeand thereareno
alignment gaps between the elds.
IDL Reference Guide ASSOC
Example
Supposethat theleimages.dat holds5imagesas256-element by 256-element arrays
of bytes. Open the le for reading and create an associated variable by entering:
OPENR, 1, 'images.dat' Open thefileas fileunit 1.
A = ASSOC(1, BYTARR(256, 256)) Makean associated variable.
Now A[ 0] corresponds to the rst image in the le, A[ 1] is the second element, etc. To
display the rst image in the le, you could enter:
TV, A[0]
Thedatafor therst imageisread and then displayed. Notethat thedataassociated with
A[ 0] is not held in memory. It is read in every time there is a reference to A[ 0] . To store
the image in the memory-resident array B, you could enter:
B = A[0]
See Also
OPEN, READU
ATAN IDL Reference Guide
ATAN
The ATAN function returns the angle, expressed in radians, whose tangent isX (i.e., the
arc-tangent). If two parameters are supplied, the angle whose tangent is equal to Y/X is
returned. Therangeof ATAN isbetween -/2and /2for thesingleargument case, and
between - and if two arguments are given.
Calling Sequence
Result = ATAN(X)
or
Result = ATAN(Y, X)
Arguments
X
The tangent of the desired angle.
Y
An optional argument. If this argument is supplied, ATAN returns the angle whose
tangent is equal to Y/X. If both arguments are zero, the result is undened.
Example
To nd the arc-tangent of 0.707 and store the result in the variable B, enter:
B = ATAN(0.707)
The following code denes a function that converts Cartesian coordinates to polar
coordinates. It returns r and theta given an x and y position:
FUNCTION TO_POLAR, X, Y DefinefunctionTO_POLARthat
accepts X and Y as arguments.
RETURN, [SQRT(X^2 + Y^2), ATAN(Y, X)]
Returnthedistanceandangleasa
two-element array.
END End of function.
See Also
TAN, TANH
IDL Reference Guide AXIS
AXIS
TheAXISproceduredrawsan axisof thespecied typeand scaleat agiven position. The
newscaleissaved for useby subsequent overplotsif theSAVEkeyword parameter isset.
Thekeyword parametersXAXIS, YAXIS, and ZAXISspecifythetypeof axistobedrawn,
and its position.
Calling Sequence
AXIS[[[, X], Y], Z]
Arguments
X, Y, and Z
Scalarsgivingthestartingcoordinatesof thenewaxis. If nocoordinatesarespecied, the
axisisdrawn in itsdefault position asgiven by the[ XYZ] AXISkeyword. When drawing
an Xaxis, theXcoordinateisignored, similarlytheYandZparametersareignoredwhen
drawing their respective axes (i.e., new axes will always point in the correct direction).
Keywords
SAVE
Set thiskeyword to indicatethat thescalingto and fromdatacoordinatesestablished by
thecall to AXISisto besaved in theappropriateaxissystemvariable, !X, !Y, or !Z. If this
keyword is not present, the scaling is not changed.
XAXIS
Set thiskeyword todrawan Xaxis. If theXparameter isnotpresent, settingXAXISequal
to 0 draws an axis under the plot window with the tick marks pointing up, and setting
XAXIS equal to one draws an axis above the plot window with the tick marks pointing
down. If theX parameter ispresent, the X axis is positioned accordingly, and setting
XAXIS equal to 0 or 1 causes the tick marks to point up or down, respectively.
YAXIS
Set this keyword to draw a Y axis. If theY parameter is not present, setting YAXIS equal
to 0drawsan axison theleft sideof theplot windowwith thetick markspointingright,
and setting YAXIS equal to one draws an axis on the right side of the plot window with
the tick marks pointing left. If theY parameter ispresent, the Y axis is positioned
accordingly, and settingYAXISequal to0or 1causesthetick markstopoint right or left,
respectively.
ZAXIS
Set thiskeyword todrawaZ axis. If theZparameter isnotpresent, settingZAXIShasthe
following meanings:
AXIS IDL Reference Guide
0 = lower (front) right, with tickmarks pointing left
1 = lower (front) left, with tickmarks pointing right
2 = upper (back) left, with tickmarks pointing right
3 = upper (back) right, with tickmarks pointing left
If theZparameter ispresent, theZaxisispositionedaccordingly, andsettingZAXISequal
to 0 or 1 causes the tick marks to point left or right, respectively.
Note that AXIS uses the 3D plotting transformation stored in the system variable eld
!P.T.
XLOG
Set this keyword to specify a logarithmic X axis
YNOZERO
Set thiskeyword to inhibit settingtheminimumYaxisvalueto zero when theYdataare
all positiveandnon-zero, andnoexplicit minimumYvalueisspecied(usingYRANGE,
or !Y.RANGE). By default, theYaxisspanstherangeof 0to themaximumvalueof Y, in
the case of positive Y data. Set bit 4 in !Y.STYLE to make this option the default.
YLOG
Set this keyword to specify a logarithmic Y axis.
Graphics Keywords Accepted
SeeChapter 7, GraphicsKeywords, for thedescription of graphicsandplottingkeywords
not listed above. AM_PM CHARSIZE CHARTHICK COLOR DATA DAYS_OF_WEEK
DEVICE FONT NODATA NOERASE NORMAL SUBTITLE, T3D TICKLEN
[ XYZ] CHARSIZE [ XYZ] GRIDSTYLE [ XYZ] MARGIN [ XYZ] MINOR MONTHS
[ XYZ] RANGE [ XYZ] STYLE [ XYZ] THICK [ XYZ] TICKFORMAT [ XYZ] TICKLEN
[ XYZ] TICKNAME [ XYZ] TICKS [ XYZ] TICKV [ XYZ] TICK_GET [ XYZ] TITLE
ZVALUE.
Example
ThefollowingexampleshowshowtheAXISprocedurecan beused with normal or polar
plots to draw axes through the origin, dividing the plot window into four quadrants:
PLOT, /POLAR, XSTYLE=4, YSTYLE=4, TITLE='Polar Plot', r, theta
Maketheplot,polarinthisexam-
ple,andsuppresstheXandYaxes
usingtheXSTYLE and YSTYLE
keywords.
AXIS,0,0,XAX=0,/DATA Draw an X axis, through data Y
coordinateof0.BecausetheXAX-
IDL Reference Guide AXIS
ISkeywordparameterhasavalue
of 0, thetick marks point down.
AXIS,0,0,0,YAX=0,/DATA Similarly,drawtheYaxisthrough
data X =0. Thetick marks point
left.
See Also
LABEL_DATE, PLOT
BAR_PLOT IDL Reference Guide
BAR_PLOT
The BAR_PLOT procedure creates a bar graph.
bar_plot.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
BAR_PLOT, Values
Arguments
Values
A vector containing the values to be represented by the bars. Each element in Values
corresponds to a single bar in the output.
Keywords
BACKGROUND
Ascalar that speciesthecolor index tobeused for thebackground color. Bydefault, the
normal IDL background color is used.
BARNAMES
A string array, containing one string label per bar. If the bars are vertical, the labels are
placedbeneaththem. If horizontal (rotated) barsarespecied, thelabelsareplacedtothe
left of the bars.
BAROFFSET
A scalar that species the offset to be applied to the rst bar, in units of nominal bar
width. This keyword allows, for example, different groups of bars to be overplotted on
the same graph. If not specied, the default offset is equal to BARSPACE.
BARSPACE
A scalar that species, in units of nominal bar width, the spacing between bars. For
example, if BARSPACE is 1.0, then all bars will have one bar-width of space between
them. If not specied, the bars are spaced apart by 20% of the bar width.
BARWIDTH
Aoating-point valuethat speciesthewidthof thebarsin unitsof nominal bar width.
Thenominal bar width iscomputed sothat all thebars(and thespacebetween them, set
by default to 20% of the width of the bars) will ll the available space (optionally
controlled with the BASERANGE keyword).
IDL Reference Guide BAR_PLOT
BASELINES
Avector, thesamesizeasValues, that containsthebasevalueassociated with each bar. If
not specied, a base value of zero is used for all bars.
BASERANGE
A oating-point scalar in the range 0.0 to 1.0, that determines the fraction of the total
available plotting area (in the direction perpendicular to the bars) to be used. If not
specied, the full available area is used.
COLORS
Avector, thesamesizeasValues, containingthecolor index tobeusedfor each bar. If not
specied, the colors are selected based on spacing the color indices as widely as possible
within the range of available colors (specied by !D.N_COLORS).
OUTLINE
If set, this keyword species that an outline should be drawn around each bar.
OVERPLOT
If set, thiskeyword speciesthat thebar plot should beoverplotted on an existinggraph.
ROTATE
If set, this keyword indicates that horizontal rather than vertical bars should be drawn.
The bases of horizontal bars are on the left, Y axis and the bars extend to the right.
TITLE
A string containing the main title to for the bar plot.
XTITLE
A string containing the title for the X axis.
YTITLE
A string containing the title for the Y axis.
Example
By using the overplotting capability, it is relatively easy to create stacked bar charts, or
different groups of bars on the same graph.
For example, if ARRAYisatwo-dimensional array of 5columnsand 8rows, it isnatural
to make a plot with 5 bars, each of which is a stacked composite of 8 sections. First,
createa2D COLORSarray, equal in sizeto ARRAY, that hasidentical color index values
across each row to ensure that the same item is represented by the same color in all bars.
array = INDGEN(5,8)
colors = INTARR(5,8)
FOR I = 0, 7 DO colors[*,I]=(20*I)+20
BAR_PLOT IDL Reference Guide
WithARRAYSandCOLORSdened, thefollowingcodefragment illustratesthecreation
of stacked bars (note that the number of rows and columns is arbitrary):
!Y.RANGE = [0, MAX(array)] Scalerangeto accommodatethe
total bar lengths.
nrows = N_ELEMENTS(array[0,*])
base = INTARR(nrows)
FOR I = 0, nrows-1 DO BEGIN
BAR_PLOT, array[*,I], COLORS=colors[*,I], BASELINES=base, $
BARWIDTH=0.75, BARSPACE=0.25, OVER=(I GT 0)
base = array[*,I]
ENDFOR
To plot each row of ARRAY as a clustered group of bars within the same graph, use the
BASERANGE keyword to restrict the available plotting region for each set of bars. The
sample code fragment below illustrates this method:
ncols = N_ELEMENTS(array[*,0])
FOR I = 0, nrows-1 DO $
BAR_PLOT, array[*,I], COLORS=colors[*,I], BARWIDTH=0.8, $
BARSPACE=0.2, BAROFFSET=I*(1.5*ncols), $
OVER=(I GT 0), BASERANGE=0.19
whereNCOLSisthenumber of columnsinARRAY. (Inthisexample, eachgroupusesthe
same set of colors, but this could easily be changed.)
See Also
PLOT, PSYM Graphics Keyword
IDL Reference Guide BESELI
BESELI
TheBESELI function returnstheI Bessel function of order Nfor theargument X. If Xis
double-precision, the result is double precision, otherwise the argument is converted to
oating-point and the result is oating-point.
Calling Sequence
Result = BESELI(X, N)
Arguments
X
Theexpression for which theI Bessel function isrequired. Theresult will havethesame
dimensions asX.
N
Theorder of theI Bessel function tocalculate. Nmust bean integer greater than or equal
to 0.
See Also
BESELJ, BESELY
BESELJ IDL Reference Guide
BESELJ
TheBESELJfunction returnstheJBessel function of order Nfor theargument X. If Xis
oating-point and the result is oating-point. BESELJ uses thej0(3M), j1(3M), and
jn(3M) functions from the standard C math library.
Calling Sequence
Result = BESELJ(X, N)
Arguments
X
The expression for which the J Bessel function is required. The result has the same
dimensions asX.
N
Theorder of theJBessel function tocalculate. Nmust bean integer greater than or equal
to 0.
See Also
BESELI, BESELY
IDL Reference Guide BESELY
BESELY
TheBESELYfunction returnstheYBessel function of order Nfor theargument X. If Xis
oating-point and the result is oating-point. BESELY uses they0(3M), y1(3M), and
yn(3M) functions from the standard C math library.
Calling Sequence
Result = BESELY(X, N)
Arguments
X
Theexpression for which theYBessel function isrequired. Xmust begreater than 0. The
result has the same dimensions asX.
N
Theorder of theYBessel function tocalculate. Nmust bean integer greater than or equal
to 0.
See Also
BESELI, BESELJ
BETA IDL Reference Guide
BETA
The BETA function returns the value of the beta function B(Z, W).
beta.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = BETA(Z, W)
Arguments
Z, W
The point at which the beta function is to be evaluated. Z and W can be scalar or array.
Keywords
DOUBLE
Example
To evaluate the beta function at the point (1.0, 1.1) and print the result:
PRINT, BETA(1.0, 1.1)
IDL prints:
0.909091
The exact solution is:
((1.00 * .95135077) / (1.10 * .95135077)) = 0.909091.
See Also
GAMMA, IBETA, IGAMMA, LNGAMMA
IDL Reference Guide BILINEAR
BILINEAR
TheBILINEARfunction usesabilinear interpolation algorithmto computethevalueof
adataarray at each of aset of subscript values. Thefunction returnsatwo-dimensional,
oating-point interpolated array.
bilinear.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = BILINEAR(P, IX, JY)
Arguments
P
A two-dimensional data array.
IX and JY
Arrays containing the X and Y virtual subscripts of P to interpolate values for.
IX and JY can be either of the following:
One-dimensional, n-element oating-point arrays of subscripts to look up in P. One-
dimensional arrayswill beconverted to two-dimensional arraysin such away that IX
containsn identical rows and JY containsn identical columns.
Two-dimensional, n-element oating-point arrays that uniquely specify the X sub-
scripts(theIXarray) and theYsubscripts(theJYarray) of thepointsto becomputed
from the input array P.
In either case, IX must satisfy the expressions
0 <= MIN(IX) < N0 and 0 < MAX(IX) <= N0
whereN0 is the total number of columns in the array P. JY must satisfy the expressions
0 <= MIN(JY) < M0 and 0 < MAX(JY) <= M0
whereM0 is the total number of rows in the array P.
It isbetter tousetwo-dimensional arraysfor IXandJYbecausethealgorithmissomewhat
faster. If IXandJYarespeciedasone-dimensional, thereturnedtwo-dimensional arrays
IXandJYcan bere-usedon subsequent callstotakeadvantageof thefaster 2Dalgorithm.
Example
Create a 3 x 3 oating point array P:
BILINEAR IDL Reference Guide
P = FINDGEN(3,3)
Suppose we wish to nd the value of a point half way between the rst and second
elements of the rst row of P. Create the subscript arraysIX and JY:
IX = 0.5 DefinetheX subscript.
JY = 0.0 DefinetheY subscript.
Z = BILINEAR(P, IX, JY) Interpolate.
PRINT, Z Print thevalueat thepoint IX,JY
within P.
IDL prints:
0.500000
Suppose we wish to nd the values of a 2 x 2 array of points in P. Create the subscript
arraysIX and JY:
IX = [[0.5, 1.9], [1.1, 2.2]] DefinetheX subscripts.
JY = [[0.1, 0.9], [1.2, 1.8]] DefinetheY subscripts.
Z = BILINEAR(P, IX, JY) Interpolate.
PRINT, Z Print thearray of values.
IDL prints:
0.800000 4.60000
4.70000 7.40000
See Also
INTERPOL, INTERPOLATE, KRIG2D
IDL Reference Guide BIN_DATE
BIN_DATE
The BIN_DATE function converts a standard form ASCII date/time string to a binary
string. The function returns a six-element integer array where:
Element 0 is the year (e.g., 1994)
Element 1 is the month (1-12)
Element 2 is the day (1-31)
Element 3 is the hour (0-23)
Element 4 is minutes (0-59)
Element 5 is seconds (0-59)
bin_date.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = BIN_DATE(Ascii_Time)
Arguments
Ascii_Time
A string containing the date/time to convert in standard ASCII format. If this argument
is omitted, the current date/time is used. Standard form is a 24 character string:
DOW MON DD HH:MM:SS YYYY
where DOW is the day of the week, MON is the month, DD is the day of month,
HH:MM:SS is the time in hours, minutes, second, YYYY is the year.
See Also
CALDAT, JULDAY, SYSTIME
BINDGEN IDL Reference Guide
BINDGEN
TheBINDGENfunctionreturnsabytearraywiththespecieddimensions. Eachelement
of the array is set to the value of its one-dimensional subscript.
Calling Sequence
Result = BINDGEN(D
1
, ...,D
n
)
Arguments
D
i
Thedimensionsof theresult. Thedimensionparameterscanbeanyscalar expression. Up
to eight dimensionscan bespecied. If thedimension argumentsarenot integer values,
IDL will convert them to integer values before creating the new array.
Example
To create a four-element by four-element byte array, and store the result in the variable
A, enter:
A = BINDGEN(4,4)
Each element in A holds the value of its one-dimensional subscript. That is, if you enter
the command:
PRINT, A
IDL prints the result:
0 1 2 3
4 5 6 7
8 9 10 11
12 13 14 15
See Also
CINDGEN, DCINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, LINDGEN,
SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN
IDL Reference Guide BINOMIAL
BINOMIAL
The BINOMIAL function computes the probability that in a cumulative binomial
(Bernoulli) distribution, arandomvariableXisgreater than or equal to auser-specied
valueV, given Nindependent performancesand aprobability of occurrenceor successP
in a single performance.
binomial.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = BINOMIAL(V, N, P)
Arguments
V
A non-negative integer specifying the minimum number of times the event occurs in N
independent performances.
N
A non-negative integer specifying the number of performances. If the number of
performances exceeds 25, the Gaussian distribution is used to approximate the
cumulative binomial distribution.
P
Anon-negativesingle- or double-precisionoating-point scalar, intheinterval [ 0.0, 1.0] ,
that species the probability of occurrence or success of a single independent
performance.
Examples
Computetheprobabilityof obtainingat least two6sin rollingadiefour times. Theresult
should be 0.131944.
result = binomial(2, 4, 1.0/6.0)
Computetheprobabilityof obtainingexactlytwo6sin rollingadiefour times. Theresult
should be 0.115741.
result = binomial(2, 4, 1./6.) - binomial(3, 4, 1./6.)
Compute the probability of obtaining three or fewer 6s in rolling a die four times. The
result should be 0.999228.
result = (binomial(0, 4, 1./6.) - binomial(1, 4, 1./6.)) + $
(binomial(1, 4, 1./6.) - binomial(2, 4, 1./6.)) + $
BINOMIAL IDL Reference Guide
(binomial(2, 4, 1./6.) - binomial(3, 4, 1./6.)) + $
(binomial(3, 4, 1./6.) - binomial(4, 4, 1./6.))
See Also
CHISQR_PDF, F_PDF, GAUSS_PDF, T_PDF
IDL Reference Guide BLAS_AXPY
BLAS_AXPY
The BLAS_AXPY procedure updates an existing array by adding a multiple of another
array. It can also beused to updateoneor moreone-dimensional subvectorsof an array
according to the following vector operation:
where A is a scale factor and X is an input vector.
BLAS_AXPY can be faster and use less memory than the usual IDL array notation
(e.g. Y=Y+A*X) for updating existing arrays.
Note BLAS_AXPY is much faster when operating on entire arrays and rows, than when
used on columns or higher dimensions.
Calling Sequence
BLAS_AXPY, Y, A, X [, D1, Loc1 [, D2, Range]]
Arguments
Y
Thearraytobeupdated. Ycan beof anynumerictype. BLAS_AXPYdoesnot changethe
size and type of Y.
A
Thescalingfactor tobemultiplied withX. Amaybeanyscalar or one-element arraythat
IDL can convert to the type of X. BLAS_AXPY does not changeA.
X
The array to be scaled and added to array Y, or the vector to be scaled and added to
subvectors of Y.
D1
An optional parameter indicating which dimension of X is to be updated.
Loc1
Avariablewiththesamenumber of elementsasthenumber of dimensionsof X. TheLoc1
and D1argumentstogether determinewhich one-dimensional subvector (or subvectors,
if D1 and Rangeare provided) of X is to be updated.
D2
An optional parameter, indicatingin which dimension of Xagroup of one-dimensional
subvectors are to be updated. D2 should be different fromD1.
Y aX Y + =
BLAS_AXPY IDL Reference Guide
Range
A variable containingD2 indices indicating where to put one-dimensional updates of X.
Example
seed = 5L A seed valueneeds to bedefined
A = FINDGEN(40, 90, 10) Createa multidimensional array.
B = RANDOMU(40, 90, 10) Createa random update.
BLAS_AXPY, A, 4.5, B Add a multipleof B to A.
(i.e., A =A +4.5*B )
BLAS_AXPY, A, 1., REPLICATE(4.3, 40), 1, [0,4,9]
AddaconstanttoasubvectorofA.
(i.e. A[*,4,9] =A[*,4,9] +4.3)
C = FINDGEN(90) Createa vector update.
BLAS_AXPY, A, 1., C, 2, [9,0,0], 3, LINDGEN(10)
Add C to a group of subvectors of
A. ( i.e. A[ 9,*,*] =A[ 9,*,*] +C)
See Also
REPLICATE_INPLACE
IDL Reference Guide BLK_CON
BLK_CON
The BLK_CON function computes a fast convolution of a digital signal and an
impulse-response sequence. It returns the ltered signal.
blk_con.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = BLK_CON(Filter, Signal)
Arguments
Filter
A P-element oating-point vector containing the impulse-response sequence of the
digital lter.
Signal
An n-element oating-point vector containing the discrete signal samples.
Keywords
B_LENGTH
Ascalar specifyingtheblocklengthof thesubdivided signal segments. If thisparameter is
not specied, anear-optimal valueischosen bythealgorithmbased upon thelength Pof
the impulse-response sequence. If P is a value less than 11 or greater than 377, then
B_LENGTH must be specied.
B_LENGTH must be greater than the lter length, P, and less than the number of signal
samples.
Example
Create a lter of length P = 32:
filter = REPLICATE(1.0,32) Set all points to 1.0
filter(2*INDGEN(16)) = 0.5 Set even points to 0.5
Create a sampled signal with random noise:
signal = SIN((FINDGEN(1000)/35.0)^2.5)
noise = (RANDOMU(SEED,1000)-.5)/2.
signal = signal + noise
BLK_CON IDL Reference Guide
Convolve the lter and signal using block convolution:
result = BLK_CON(filter, signal)
See Also
CONVOL
IDL Reference Guide BOX_CURSOR
BOX_CURSOR
The BOX_CURSOR procedure emulates the operation of a variable-sized box cursor
(also known as a marquee selector).
Caution BOX_CURSORdoesnot function properlywhen usedwithin adrawwidget. Seethe
BUTTON_EVENTS and MOTION_EVENTS keywords in WIDGET_DRAW on
page 1252.
box_cursor.pro in thelib subdirectory of the IDL distribution.
Using BOX_CURSOR
Oncethebox cursor hasbeen realized, hold down theleft mousebutton tomovethebox
by dragging. Hold down the middle mouse button to resize the box by dragging. (The
corner nearest theinitial mouseposition ismoved.) Presstheright mousebutton to exit
the procedure and return the current box parameters.
Calling Sequence
BOX_CURSOR, [ X0, Y0, NX, NY ]
Arguments
X0, Y0
Named variables that will contain the coordinates of the lower left corner of the box
cursor.
NX, NY
Named variables that will contain the width and height of the cursor, in pixels.
Keywords
INIT
If thiskeyword isset, theargumentsX0, Y0, NX, and NYcontain theinitial position and
size of the box.
FIXED_SIZE
If thiskeyword isset, NXand NYcontain theinitial sizeof thebox. Thissizemay not be
changed by the user.
MESSAGE
If this keyword is set, IDL prints a message describing operation of the cursor.
BOX_CURSOR IDL Reference Guide
See Also
CURSOR, CURSOR_CROSSHAIR keyword, CURSOR_IMAGE keyword,
CURSOR_STANDARD keyword, CURSOR_XY keyword
IDL Reference Guide BREAKPOINT
BREAKPOINT
TheBREAKPOINT procedureallowsyou to insert and removebreakpointsin programs
for debugging. A breakpoint causes program execution to stop after the designated
statement is executed. Breakpoints are specied using the source le name and line
number. For multiple-line statements (statements containing $, the continuation
character), specify the line number of the last line of the statement.
You can insert breakpoints in programs without editing the source le. Enter the
following:
HELP, /BREAKPOINT
todisplaythebreakpoint tablewhich givestheindex, moduleand sourcelelocationsof
each breakpoint.
Calling Sequence
BREAKPOINT [, File], Index
Arguments
File
An optional stringargument that containsthenameof thesourcele. Notethat if Fileis
not in thecurrent directory, thefull path namemust bespecied even if Fileisin oneof
the directories specied by !PATH.
Index
The line number at which to clear or set a breakpoint.
Keywords
AFTER
Set this keyword equal to an integer n. Execution will stop only after thenth time the
breakpoint is hit. For example:
BREAKPOINT, /SET, 'test.pro', 8, AFTER=3
sets a breakpoint at the eighth line of the letest.pro, but only stops execution after
the breakpoint has been encountered three times.
CLEAR
Set thiskeywordtoremoveabreakpoint. Thebreakpoint toberemovedisspeciedeither
by index, or by thesourceleand linenumber. Usecommand HELP, /BREAKPOINT to
display the indices of existing breakpoints. For example:
BREAKPOINT IDL Reference Guide
BREAKPOINT, /CLEAR, 3 Clearbreakpointwithanindexof
3.
BREAKPOINT, /CLEAR, 'test.pro',8 Clear thebreakpoint correspond-
ingto thestatement in thefile
test.pro, linenumber 8.
CONDITION
Set this keyword to a string containing an IDL expression. When a breakpoint is
encountered, theexpression isevaluated. If theexpression istrue(if it returnsanon-zero
value), programexecutionisinterrupted. Theexpressionisevaluatedinthecontext of the
program containing the breakpoint.
Example BREAKPOINT, myfile.pro, 6, CONDITION=i gt 2
If i is greater than 2 at line6 of
myfile.pro, theprogram is inter-
rupted.
ONCE
Set this keyword to make the breakpoint temporary. If ONCE is set, the breakpoint is
cleared as soon as it is hit. For example:
BREAKPOINT, /SET, 'file.pro', 12, AFTER=3, /ONCE
setsabreakpoint at line12of file.pro. Executionstopswhenline12isencounteredthe
third time, and the breakpoint is automatically cleared.
SET
Set this keyword to set a breakpoint at the designated source le line. If this keyword is
set, the rst input parameter, Filemust be a string expression that contains the name of
thesourcele. Thesecond input parameter must bean integer that representsthesource
line number.
For example, to set a breakpoint at line 23 in the source lexyz.pro, enter:
BREAKPOINT, /SET, 'xyz.pro', 23
See Also
Executive Commands on page 31.
IDL Reference Guide BROYDEN
BROYDEN
The BROYDEN function solves a system of n nonlinear equations (wheren 2) in n
dimensions using a globally-convergent Broydens method. The result is an n-element
vector containing the solution.
BROYDEN isbased on theroutinebroydn described in section 9.7of Numerical Recipes
in C: TheArt of Scientic Computing(Second Edition), published by Cambridge
University Press, and is used by permission.
Calling Sequence
Result = BROYDEN(X, Vecfunc)
Arguments
X
An n-element vector (wheren 2) containing an initial guess at the solution of the
system.
Vecfunc
A scalar string specifying the name of a user-supplied IDL function that denes the
system of non-linear equations. This function must accept a vector argument X and
return a vector result.
For example, suppose we wish to solve the following system:
To represent this system, we dene an IDL function named BROYFUNC:
FUNCTION broyfunc, X
RETURN, [3.0 * X[0] - COS(X[1]*X[2]) - 0.5,$
X[0]^2 - 81.0*(X[1] + 0.1)^2 + SIN(X[2]) + 1.06,$
EXP(-X[0]*X[1]) + 20.0 * X[2] + (10.0*!PI - 3.0)/3.0]
END
3x yz ( ) 1 2 cos
x
2
81 y 0.1 + ( )
2
z ( ) 1.06 + sin +
e
xy
20z
10 3
3
------------------ + +
0 =
BROYDEN IDL Reference Guide
Keywords
CHECK
BROYDEN calls an internal function named fmin() to determine whether the routine
has converged to a local rather than a global minimum (seeNumerical Recipes, section
9.7). Use the CHECK keyword to specify a named variable which will be set to 1 if the
routine has converged to a local minimum or to 0 if not. If the routine does converge to
a local minimum, try restarting from a different initial guess to obtain the global
minimum.
DOUBLE
ITMAX
Usethiskeywordtospecifythemaximumallowednumber of iterations. Thedefault is200.
STEPMAX
Usethiskeywordtospecifythescaledmaximumsteplengthallowedin linesearches. The
default value is 100.0.
TOLF
Set the convergence criterion on the function values. The default value is 1.0 10
-4
.
TOLMIN
Set the criterion for deciding whether spurious convergence to a minimum of the
function fmin() has occurred. The default value is 1.0 10
-6
.
TOLX
Set the convergence criterion on X. The default value is 1.0 10
-7
.
Example
We can use BROYDEN to solve the non-linear system of equations dened by the
BROYFUNC function above:
X = [-1.0, 1.0, 2.0] Providean initial guess as theal-
gorithms startingpoint.
result = BROYDEN(X, 'BROYFUNC') Computethesolution.
PRINT, result Print theresult.
IDL prints:
0.500000 -1.10731e-07 -0.523599
The exact solution (to eight-decimal accuracy) is [ 0.5, 0.0, -0.52359877] .
See Also
FX_ROOT, NEWTON, FZ_ROOTS
IDL Reference Guide BYTARR
BYTARR
The BYTARR function returns a byte vector or array.
Calling Sequence
Result = BYTARR(D
1
, ..., D
n
)
Arguments
D
i
to eight dimensions can be specied.
Keywords
NOZERO
Normally, BYTARR sets every element of the result to zero. If the NOZERO keyword is
set, thiszeroingisnot performed (array elementscontain randomvalues) and BYTARR
executes faster.
Example
To create B as a 3 by 3 by 5 byte array where each element is set to zero, enter:
B = BYTARR(3, 3, 5)
See Also
COMPLEXARR, DBLARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY,
STRARR, UINTARR, ULON64ARR, ULONARR
BYTE IDL Reference Guide
BYTE
The BYTE function returns a result equal to Expression converted to byte type. If
Expression is a string, each string is converted to a byte vector of the same length as the
string. Each element of thevector isthecharacter codeof thecorrespondingcharacter in
thestring. TheBYTEfunction can alsobeused toextract datafromExpressionand place
it in a byte scalar or array without modication, if more than one parameter is present.
See Type Conversion Functions on page 19 of Building IDL Applications for details.
Calling Sequence
Result = BYTE(Expression[, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to type byte.
Offset
The byte offset from the beginning of Expression. Specifying this argument allows elds
of data extracted fromExpression to be treated as byte data without conversion.
D
i
When extractingeldsof data, theD
i
argumentsspecifythedimensionsof theresult. The
dimension parameters can be any scalar expression. Up to eight dimensions can be
specied. If no dimension arguments are given, the result is taken to be scalar.
Example
If the variable A contains the oating-point value 10.0, it can be converted to byte type
and saved in the variable B by entering:
B = BYTE(A)
See Also
COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT,
ULONG, ULONG64
IDL Reference Guide BYTEORDER
BYTEORDER
TheBYTEORDERprocedureconvertsintegersbetween host and network byteordering
or oating-point valuesbetween thenativeformat andXDR(IEEE) format. Thisroutine
can alsobeusedtoswaptheorder of byteswithin bothshort andlongintegers. If thetype
of byte swapping is not specied via one of the keywords below, bytes within short
integers are swapped (even and odd bytes are interchanged).
The size of the parameter, in bytes, must be evenly divisible by two for short integer
swaps, and by four for long integer swaps. BYTEORDER operates on both scalars and
arrays. The parameter must be a variable, not an expression or constant, and may not
contain strings. The contents of Variableare overwritten by the result.
Network byte ordering is big endian. That is, multiple byte integers are stored in
memory beginning with the most signicant byte.
Calling Sequence
BYTEORDER, Variable
1
, ..., Variable
n
Arguments
Variable
n
Anamed variable(not an expression or constant) that containsthedatatobeconverted.
The contents of Variableare overwritten by the new values.
Keywords
DTOVAX
Set thiskeywordtoconvert native(IEEE) double-precision oating-point format toVAX
D oat format. See Note On IEEE to VAX Format Conversion on page 237.
DTOXDR
Set thiskeywordtoconvert nativedouble-precisionoating-point format toXDR(IEEE)
format.
FTOVAX
Set thiskeyword to convert native(IEEE) single-precision oating-point format to VAX
F oat format. See Note On IEEE to VAX Format Conversion on page 237.
FTOXDR
Set thiskeyword to convert nativesingle-precision oating-point format to XDR(IEEE)
format.
BYTEORDER IDL Reference Guide
HTONL
Set this keyword to perform host to network conversion, longwords.
HTONS
Set this keyword to perform host to network conversion, short integers.
L64SWAP
Set this keyword to perform a 64-bit swap (8 bytes). Swap the order of the bytes within
each64-bit word. For example, theeight byteswithina64-bit wordarechangedfrom(B
0
,
B
1
, B
2
, B
3
B
4
, B
5
, B
6
, B
7
), to (B
7
, B
6
, B
5
, B
4,
B
3
, B
2
, B
1
, B
0
).
LSWAP
Set this keyword to perform a 32-bit longword swap. Swap the order of the bytes within
each longword. For example, thefour byteswithin alongword arechanged from(B
0
, B
1
,
B
2
, B
3
), to (B
3
, B
2
, B
1
, B
0
).
NTOHL
Set this keyword to perform network to host conversion, longwords.
NTOHS
Set this keyword to perform network to host conversion, short integers.
SSWAP
Set thiskeywordtoperformashort wordswap. Swapthebyteswithin short integers. The
even and odd numbered bytes are interchanged. This is the default action, if no other
keyword is set.
SWAP_IF_BIG_ENDIAN
If this keyword is set, the BYTEORDER request will only be performed if the platform
running IDL uses big endian byte ordering. On little endian machines, the
BYTEORDER 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 BYTEORDER request will only be performed if the platform
running IDL uses little endian byte ordering. On big endian machines, the
BYTEORDER 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.
VAXTOD
Set this keyword to convert VAX D oat format to native (IEEE) double-precision
oating-point format. See Note On IEEE to VAX Format Conversion on page 237.
Note If you have VAX G oat format data, see the VMS-Only Keywords on page 237.
VAXTOF
Set thiskeyword toconvert VAXFoat format tonative(IEEE) single-precision oating-
point format. See Note On IEEE to VAX Format Conversion on page 237.
IDL Reference Guide BYTEORDER
Note If you have VAX G oat format data, see the VMS-Only Keywords on page 237.
XDRTOD
Set this keyword to convert XDR (IEEE) format to native double-precision oating-
point.
XDRTOF
Set thiskeyword to convert XDR(IEEE) format to nativesingle-precision oating-point.
VMS-Only Keywords
DTOGFLOAT
Set thiskeywordtoconvert native(IEEE) double-precision oating-point format toVAX
G oat format. Note that IDL does not support the VAX G oat format via any other
mechanism. See Note On IEEE to VAX Format Conversion on page 237.
GFLOATTOD
Set this keyword to convert VAX G oat format to native (IEEE) double-precision
oating-point format. Note that IDL does not support the VAX G oat format via any
other mechanism. See Note On IEEE to VAX Format Conversion on page 237.
Note On IEEE to VAX Format Conversion
Translation of oating-point values from the IDLs native (IEEE) format to the VAX
formats and back (IEEE to VAX to IEEE) is not a completely reversible operation, and
should be avoided when possible. There are many cases where the recovered values will
differ from the original, including:
TheVAXoatingpoint format lackssupport for theIEEEspecial values(NaN, Innity).
Hence, their special meaningislost whentheyareconvertedtoVAXformat andcannot
be recovered.
Differences in precision and range can also cause information to be lost in both
directions.
Research Systems recommends using IEEE/VAX conversions only to read existing VAX
format data, andstronglyrecommendsthat all newlesbecreatedusingtheIEEEformat.
See Also
SWAP_ENDIAN
BYTSCL IDL Reference Guide
BYTSCL
TheBYTSCL function scalesall valuesof Arraythat liein therange(Min x Max) into
the range (0 x Top). The returned result has the same structure as the original
parameter and is of byte type.
Calling Sequence
Result = BYTSCL(Array)
Arguments
Array
The array to be scaled and converted to bytes.
Keywords
MAX
Themaximumvalueof Arraytobeconsidered. If MAXisnot provided, Arrayissearched
for its maximum value. All values greater or equal to MAX are set equal to TOP in the
result.
MIN
Theminimumvalueof Arrayto beconsidered. If MIN isnot provided, Arrayissearched
for itsminimumvalue. All valueslessthan or equal toMINareset equal to0in theresult.
NAN
Set thiskeyword to causetheroutineto check for occurrencesof theIEEEoating-point
value NaN in the input data. Elements with the value NaN are treated as missing data.
(SeeSpecial Floating-Point Values on page152of BuildingIDL Applicationsfor more
information on IEEE oating-point values.)
TOP
The maximum value of the scaled result. If TOP is not specied, 255 is used. Note that
the minimum value of the scaled result is always 0.
Example
BYTSCL isoften used to scaleimagesinto theappropriaterangefor 8-bit displays. Asan
example, enter the following commands:
IM = DIST(200) Createa simpleimagearray.
TV, IM Display thearray as an image.
IDL Reference Guide BYTSCL
Now scale the image into the full range of bytes (0 to 255) and re-display it by entering:
IM = BYTSCL(IM) Bytescaletheimageandstorethe
result in thesamevariable.
TV, IM Display thenew image.
See Also
BYTE, TVSCL
C_CORRELATE IDL Reference Guide
C_CORRELATE
TheC_CORRELATEfunction computesthecrosscorrelation P
xy
(L) or crosscovariance
R
xy
(L) of two sample populationsX and Y as a function of the lagL.
wherex andy arethemeansof thesamplepopulationsx= (x
0
, x
1
, x
2
, ... , x
N-1
) and y
= (y
0
, y
1
, y
2
, ... , y
N-1
), respectively.
c_correlate.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = C_CORRELATE(X, Y, Lag)
Arguments
X
P
xy
L ( )
x
k L +
x ( ) y
k
y ( )
k 0 =
N L 1
x
k
x ( )
2
k 0 =
N 1
y
k
y ( )
2
k 0 =
N 1
-------------------------------------------------------------------------------- - For L < 0

x
k
x ( ) y
k L +
y ( )
k 0 =
N L 1
x
k
x ( )
2
k 0 =
N 1
y
k
y ( )
2
k 0 =
N 1
-------------------------------------------------------------------------------- - For L 0
'
=
R
xy
L ( )
1
N
---- x
k L +
x ( ) y
k
y ( )
k 0 =
N L 1
For L < 0
1
N
---- x
k
x ( ) y
k L +
y ( )
k 0 =
N L 1
For L 0
'
=
IDL Reference Guide C_CORRELATE
Y
Lag
A scalar or n-element integer vector in theinterval [ -(n-2), (n-2)] , specifyingthesigned
distances between indexed elements of X.
Keywords
COVARIANCE
Set this keyword to compute the sample cross covariance rather than the sample cross
correlation.
DOUBLE
Example
Dene two n-element sample populations.
X = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57]
Y = [2.31, 2.76, 3.02, 3.13, 3.72, 3.88, 3.97, 4.39, 4.34, 3.95]
Compute the cross correlation of X and Y for LAG = -5, 0, 1, 5, 6, 7
lag = [-5, 0, 1, 5, 6, 7]
result = C_CORRELATE(X, Y, lag)
PRINT, result
IDL prints:
-0.428246 0.914755 0.674547 -0.405140 -0.403100 -0.339685
See Also
A_CORRELATE, CORRELATE, M_CORRELATE, P_CORRELATE, R_CORRELATE
CALDAT IDL Reference Guide
CALDAT
The CALDAT procedure computes the month, day, year, hour, minute, or second
corresponding to a given Julian date. The inverse of this procedure is JULDAY.
Note TheJulian calendar, establishedbyJuliusCaesar in theyear 45BCE, wascorrectedby
Pope Gregory XIII in 1582, excising ten days from the calendar. The CALDAT
procedure reects the adjustment for dates after October 4, 1582. See the example
below for an illustration.
caldat.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
CALDAT, Julian, Month, Day, Year, Hour, Minute, Second
Arguments
Julian
Anumericvalueor arraythat speciestheJulian DayNumber (which beginsat noon) to
be converted to a calendar date.
Note Although Julian can be of any numeric value, CALDAT will convert all values to
longword integer, retaining the same dimensionality.
Month
A named variable that, on output, contains the number of the desired month (1 =
January, ..., 12 = December).
Day
A named variable that, on output, contains the number of the day of the month (1-31).
Year
A named variable that, on output, contains the number of the desired year (e.g., 1994).
Hour
A named variable that, on output, contains the number of the hour of the day (0-23).
Minute
Anamedvariablethat, on output, containsthenumber of theminuteof theday(0-1439).
Second
A named variable that, on output, contains the number of the second of the day
(0-86399).
IDL Reference Guide CALDAT
Examples
In 1582, Pope Gregory XIII adjusted the Julian calendar to correct for its inaccuracy of
slightlymorethan 11minutesper year. Asaresult, thedayfollowingOctober 4, 1582was
October 15, 1582. CALDAT follows this convention, as illustrated by the following
commands:
CALDAT, 2299160, Month, Day, Year
PRINT, Month, Day, Year
IDL prints:
10 4 1582
Caution You should be aware of this discrepancy between the original and revised Julian
calendar reckonings if you calculate dates before October 15, 1582.
Be sure to distinguish between Month and Minutewhen assigning variable names:
CALDAT, 2529161.36, M, D, Y, H, M, S FinddatecorrespondingtoJulian
day 2529161.36.
CALDAT, 2529161.36, Month, Day, Year, Hour, Minute, Second
PRINT, M, D, Y, H, M, S
PRINT, Month, Day, Year, Hour, Month, Second
IDL prints:
9 19 1938 6 0 0.0000000
This is thecorrect value,
September 19, 1938.
9 19 1938 6 9 0.0000000
TheMinutevalueisincorrect;itis
thesameas theMonth value.
You can use arrays for theJulian argument:
CALDAT,FINDGEN(4)+2449587L, m, d, y
PRINT, m, d, y
IDL prints:
8 8 8 8
22 23 24 25
1994 1994 1994 1994
See Also
BIN_DATE, JULDAY, SYSTIME
CALENDAR IDL Reference Guide
CALENDAR
The CALENDAR procedure displays a calendar for a month or an entire year on the
current plotting device. This IDL routine imitates the Unix cal command.
calendar.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
CALENDAR[[, Month] , Year]
Arguments
Month
Thenumber of themonth for which acalendar isdesired (1isJanuary, 2isFebruary, ...,
12 is December). If called without arguments, CALENDAR draws a calendar for the
current month.
Year
The number of the year for which a calendar should be drawn. If YEAR is provided
without MONTH, a calendar for the entire year is drawn. If called without arguments,
CALENDAR draws a calendar for the current month.
Example
CALENDAR, 5, 1995 DisplayacalendarforMay, 1995.
See Also
SYSTIME
IDL Reference Guide CALL_EXTERNAL
CALL_EXTERNAL
The CALL_EXTERNAL function calls a function in an external sharable object and
returnsascalar value. Parameterscan bepassedbyreference(thedefault) or byvalue. See
the Call External chapter of theExternal Development Guidefor examples.
CALL_EXTERNAL issupported under all systemsoperatingsystemssupported by IDL,
although there are system specic details of which you must be aware. This function
requires no interface routines and is much simpler and easier to use than the
LINKIMAGEprocedure. However, CALL_EXTERNALperformsnocheckingof thetype
and number of parameters. Programming errors are likely to cause IDL to crash or to
corrupt your data.
Caution Input andoutput actionsshouldbeperformedwithin IDLcode, usingIDLsbuilt-in
input/output facilities, or by usingIDL_Message(). Usingexternal codeoptionsfor
input and output, such as stdin or stdout, may generate unexpected results.
CALL_EXTERNAL supportstheIDL PortableConvention, aportablecallingconvention
that workson all platforms. Thisconvention passestwo argumentsto thecalled routine,
an argument count (argc) and an array of arguments (argv). On non-VMS systems,
this is the only available convention. Under VMS, the VMS LIB$CALLG convention is
alsoavailable,. Thisconvention, which isthedefault, usestheVMSLIB$CALLGruntime
library routine to call functions without requiring a special (argc, argv) convention.
The result of the CALL_EXTERNAL function is a scalar value returned by the external
function. Bydefault, thisisascalar longinteger. Thisdefault canbechangedbyspecifying
one of the keywords described below that alter the result type.
Calling Sequence
Result = CALL_EXTERNAL(Image, Entry [, P
0
, ..., P
N-1
])
Arguments
Image
Thenameof thele, which must beasharableimage(VMS), sharablelibrary (Unix and
Macintosh), or DLL (Windows), which contains the routine to be called.
Under VMS the full interpretation of this argument is discussed in VMS
CALL_EXTERNAL and LIB$FIND_IMAGE_SYMBOL on page 250.
Entry
Astringcontainingthenameof thesymbol in thelibrary which istheentry point of the
routine to be called.
CALL_EXTERNAL IDL Reference Guide
P
0
, ..., P
N-1
The parameters to be passed to the external routine. All array and structure arguments
arepassed by reference(address). Thedefault isto also passscalarsby reference, but the
ALL_VALUEor VALUEkeywordscan beused topassthemby value. Caremust betaken
toensurethat thetype, structure, andpassingmechanismof theparameterspassedtothe
external routinematchwhat it expects. Therearesomerestrictionson datatypesthat can
bepassed by value, and theuser needsto beawareof howIDL passesstrings. Both issues
discussed in further detail below.
Keywords
ALL_VALUE
Set this keyword to indicate that all parameters are passed by value. There are some
restrictions on data types that should be considered when using this keyword., as
discussed below.
B_VALUE
If set, this keyword indicates that the called function returns a byte value.
CDECL
TheMicrosoft Windowsoperatingsystemhastwodistinct systemdened standardsthat
govern howroutinespassarguments: stdcall, which isused by much of theoperating
system as well as languages such as Visual Basic, and cdecl, which is used widely for
programmingin theClanguage. Thesestandardsdiffer in howand when argumentsare
pushedontothesystemstack. Thestandardusedbyagiven function isdeterminedwhen
thefunction iscompiled, and can usuallybecontrolled bytheprogrammer. If afunction
is called using the wrong standard (e.g. calling astdcall function as if it werecdecl,
or the reverse), incorrect results may result, including memory corruption or even IDL
crashing. Unfortunately, there is no way for IDL to know which convention a given
function uses, thisinformation must besuppliedbytheuser of CALL_EXTERNAL. If the
CDECL keyword is present, IDL will use thecdecl convention to call the function.
Otherwise, stdcall is used.
DEFAULT
Thiskeywordisignoredon non-VMSplatforms. Under VMS, it isastringcontainingthe
default device, directory, lename, andletypeinformation for thelethat containsthe
sharable image. See VMS CALL_EXTERNAL and LIB$FIND_IMAGE_SYMBOL on
page 250 for additional information.
D_VALUE
If set, thiskeyword indicatesthat thecalled function returnsadouble-precision oating
value.
F_VALUE
If set, this keyword indicates that the called function returns a single-precision oating
value.
I_VALUE
If set, this keyword indicates that the called function returns an integer value.
L64_VALUE
If set, this keyword indicates that the called function returns a 64-bit integer value.
PORTABLE
Under VMS, causes CALL_EXTERNAL to use the IDL Portable calling convention for
passing arguments to the called function instead of the default VMS LIB$CALLG
convention. Under other operatingsystems, only theportableconvention isavailable, so
this keyword is quietly ignored. The details of these calling conventions are described in
Calling Convention on page 249.
RETURN_TYPE
Thetypecodeto set thetypeof theresult. Seethedescription of theSIZEfunction for a
list of the IDL type codes.
S_VALUE
If set, this keyword indicates that the called function returns a pointer to a
null-terminated string.
UI_VALUE
If set, this keyword indicates that the called function returns an unsigned integer value.
UL_VALUE
If set, this keyword indicates that the called function returns an unsigned long integer
value.
UL64_VALUE
If set, this keyword indicates that the called function returns an unsigned 64-bit integer
value.
VALUE
A byte array, with as many elements as there are optional parameters, indicating the
method of parameter passing. Arrays are always passed by reference. If parameter P
i
is a
scalar, it is passed by reference if VALUE[ i] is 0; and by value if it is non-zero. There are
some restrictions on data types that should be considered when using this keyword, as
discussed below.
VAX_FLOAT (VMS Only)
If specied, all datapassed tothecalled function isrst converted toVAXF(single) or D
(double) oating point formats. On return, any data passed by reference is converted
back totheIEEEformat usedbyIDL. Thisfeatureallowyoutocall codecompiledtowork
with earlier versions of IDL, which used the old VAX formats.
The default setting for this keyword is FALSE, unless IDL was started with the
VAX_FLOAT startup option, in which case the default is TRUE. See Command Line
Options on page 68 for details on this qualier. You can change this setting at runtime
using the VAX_FLOAT function.
format and back (IEEE to VAX to IEEE) is not a completely reversible operation, and
be recovered.
directions.
String Parameters
IDL representsstringsinternallyasIDL_STRINGdescriptors, which aredened in theC
language as:
typedef struct {
unsigned short slen;
unsigned short stype;
char *s;
} IDL_STRING;
To pass a string by reference, IDL passes the address of its IDL_STRING descriptor. To
pass a string by value the string pointer (thes eld of the descriptor) is passed.
Programmers should be aware of the following when manipulating IDL strings:
Called codeshould treat theinformation in thepassed IDL_STRINGdescriptor and the
string itself as readonly, and should not modify these values.
Theslen eldcontainsthelengthof thestringwithout includingtheNULLtermination
that is required at the end of all C strings.
Thestype eld is used internally by IDL to know keep track of how the memory for
the string was obtained, and should be ignored by CALL_EXTERNAL users.
s isthepointer totheactual Cstringrepresented bythedescriptor. If thestringisNULL,
IDL represents it as a NULL (0) pointer, not as a pointer to an empty null terminated
string. Hence, called codethat expectsastringpointer should check for aNULL pointer
before dereferencing it.
These issues are examined in greater detail in the IDL External Development Guide.
Calling Convention
CALL_EXTERNAL supports two distinct calling conventions for calling user-supplied
routines. Theprimaryconvention istheIDL Portableconvention, which issupportedon
all platforms. The second is the VMS LIB$CALLG convention which is only available
under VMS.
Portable
Theportableinterfaceconvention passesall argumentsaselementsof an array of Cvoid
pointers(void *). TheClanguageprototypefor auser function called thisway lookslike
one of the following:
RET_TYPE xxx(int argc, void *argv[])
Where RET_TYPE is one of the following: UCHAR, short, IDL_UINT, IDL_LONG,
IDL_ULONG, IDL_LONG64, IDL_ULONG64, float, double, or char *. Thereturntype
used must agree with the type assumed by CALL_EXTERNAL as specied via the
keywords described above.
Argc is the number of arguments, and the vector argv contains the arguments
themselves, one argument per element. Arguments passed by reference map directly to
these (void *) pointers, and can be cast to the proper type and then dereferenced
directlybythecalledfunction. Passingargumentsbyvalueisallowed, but sincethevalues
are passed in (void *) pointers, there are some limitations and restrictions on what is
possible:
Types that are larger than a pointer cannot be passed by value, and CALL_EXTERNAL
will issue an error if this is attempted.
Integer valuescan beeasily passed by value. IDL widensany of theinteger typesto theC
int type and they are then converted to a (void *) pointer using a C cast operation.
ThereisnoClanguage-dened conversion between pointersand oatingpoint types, so
IDL copiesthedatafor thevaluedirectly into thepointer element. Although such values
can be retrieved by the called routine with the correct C casting operations, this is
inconvenient and error prone. It is best to pass non-integer data by reference.
VMS LIB$CALLG
TheLIB$CALLGcallingconvention isbuilt directlyupon theVMSLIB$CALLGruntime
library function. This function allows calling functions with a natural interface without
requiring a special (argc, argv) convention. In Fortran, a typical routine might be
declared:
INTEGER *4 FUNCTION XXX(P1, P2, ..., PN)
As with the Portable convention described above, the return type for the function must
be one of the following types: UCHAR, short, IDL_UINT, IDL_LONG, IDL_ULONG,
IDL_LONG64, IDL_ULONG64, float, double, or char *.
It is possible to pass arguments of any data type by reference, but there are some
limitations and restrictions on passing arguments by value. Unfortunately, the interface
to LIB$CALLG was designed explicitly for the VAX hardware architecture, and does not
provide sufcient information to the operating system to pass all data types by value
properlyon ALPHARiscCPUswhichpassargumentsin registersaswell ason thesystem
stack. To the best of our knowledge, Digital Equipment Corporation has no plans to
supplyanupdatedversionof LIB$CALLGthat doesnot havetheselimitations. Therefore,
this calling convention has the following restrictions on ALPHA/VMS:
A singleor double-precision oating-point argument can only bepassed by valueif it is
one of the rst six arguments to the function.
Single- and double-precision complex arguments cannot be passed by value.
TheLIB$CALLGcallingconventionisthedefault for VMSIDLbecauseit wastheoriginal
convention supportedon that platform, andbecauseit allowscallingroutinesthat donot
adhere to the (argc, argv) style interface required by the portable convention. The
Portableconvention, describedabove, can beusedunder VMSbysettingthePORTABLE
keyword. If you arewritingexternal codeto beused under operatingsystemsother than
VMS, using the portable interface simplies cross platform development.
VMS CALL_EXTERNAL and LIB$FIND_IMAGE_SYMBOL
The VMS implementation of CALL_EXTERNAL uses the system runtime library
function LIB$FIND_IMAGE_SYMBOL to perform the dynamic linking. This function
has a complicated interface in which the name of the library to be linked is given in two
separatearguments. WeencourageVMSuserswishingtouseCALL_EXTERNAL toread
and fully understand the documentation for LIB$FIND_IMAGE_SYMBOL in order to
understandhowit isusedbyIDL. Thefollowingdiscussion assumesthat you haveacopy
of the LIB$FIND_IMAGE_SYMBOL documentation available to consult as you read.
LIB$FIND_IMAGE_SYMBOL uses an argument called lenameto specify the name of
the sharable library or executable to be loaded. This means that none of the le
specication punctuation characters (:, [ , <, ;, .) are allowed. Filename can also be a
logical name, in which case its translated value is the name of the le to be loaded. The
translation of such a logical name is allowed to contain additional le specication
information. VMSusesthisinformation tondtheletoload, usingSYS$SHAREasthe
default location if alocation isnot speciedviaalogical name. Alternatively, theuser can
supply theimage-nameargument, which isused asadefault lespec to ll in theparts
of the le specication not contained in lename. IDL uses the following rules, in the
order listed, to determine how to call LIB$FIND_IMAGE_SYMBOL:
1. If CALL_EXTERNAL is called with both the Image argument and DEFAULT key-
word, Imageispassed to LIB$FIND_IMAGE_SYMBOL aslename, and DEFAULT
is passed as image-name. Both are passed directly to the function without any
interpretation.
2. If DEFAULT isnot present and Imagedoesnot contain alespecication character
(:, [, <, ;, .) then it is passed to LIB$CALL_IMAGE_SYMBOL as its lename
argument without any further interpretation.
3. If DEFAULTisnot present andImagecontainsalespecicationcharacter, thenIDL
examines it and locates the lename part. The lename part is passed to
LIB$FIND_IMAGE_SYMBOLaslenameandtheentirestringfromImageispassed
asimage-name.
Thismeansthat althoughLIB$CALL_IMAGE_SYMBOLhasacomplicatedinterface, the
CALL_EXTERNAL user can supply a simple le specication for Image and it will be
properlyloadedbyIDL. Full control of LIB$CALL_IMAGE_SYMBOLisstill availablefor
those who require it.
Important Changes Since IDL 5.0
Thecurrent version of CALL_EXTERNAL differsfromIDL versionsup toand including
IDL 5.0in afewimportant waysthat areimportant to usersmovingcodeto thecurrent
version:
Under Windows, CALL_EXTERNAL would passIDL stringsbyvaluenomatter howthe
ALL_VALUE or VALUE keywords were set. This was inconsistent with all the other
platformsandcreatedunnecessaryconfusion. IDLnowusesthesekeywordstodecidehow
to passstringson all platforms. Windowsuserswith existingcodethat expectsstringsto
bepassedbyvaluewithout havingspeciedit viaoneof thesekeywordswill needtoadjust
their use of CALL_EXTERNAL or their code.
VMSIDL through version 5.0wasonly capableof usingtheLIB$CALLGcallingconven-
tion. Newer versions can also use the portable convention.
Older versionsof IDLwouldquietlypassbyvalueargumentsthat arelarger thanapointer
without issuinganerror whenusingtheportablecallingconvention. Althoughthismight
work on somehardware, it iserror proneand can causeIDL to crash. IDL nowissuesan
error in this case. Programmers with existing code moving to a current version of IDL
should change their code to pass such data by reference.
Example
See the IDL Advanced Development Guidefor examples using CALL_EXTERNAL.
See Also
LINKIMAGE, VAX_FLOAT
CALL_FUNCTION IDL Reference Guide
CALL_FUNCTION
CALL_FUNCTION calls the IDL function specied by the stringName, passing any
additional parametersasitsarguments. Theresult of thecalledfunction ispassedback as
the result of this routine.
Although not as exible as the EXECUTE function, CALL_FUNCTION is much faster.
Therefore, CALL_FUNCTION should be used in preference to EXECUTE whenever
possible.
Calling Sequence
Result = CALL_FUNCTION(Name[, P
1
, ..., P
n
])
Arguments
Name
A string containing the name of the function to be called. This argument can be a
variable, which allows the called function to be determined at runtime.
P
i
The arguments to be passed to the function given by Name. These arguments are the
positional andkeywordargumentsdocumentedfor thecalledfunction, andarepassedto
the called function exactly as if it had been called directly.
Example
The following command indirectly calls the IDL function SQRT (the square root
function) with an argument of 4 and stores the result in the variable R:
R = CALL_FUNCTION('SQRT', 4)
See Also
CALL_PROCEDURE, EXECUTE
IDL Reference Guide CALL_METHOD
CALL_METHOD
CALL_METHOD calls the object method specied by Name, passing any additional
parameters as its arguments. CALL_METHOD can be used as either a function or a
procedure, depending on whether the called method is a function or procedure.
Although not as exible as the EXECUTE function, CALL_METHOD is much faster.
Therefore, CALL_METHOD should be used in preference to EXECUTE whenever
possible.
Calling Sequence
CALL_METHOD, Name, ObjRef, [, P
1
, ..., P
n
]
or
Result = CALL_METHOD(Name, ObjRef, [, P
1
, ..., P
n
])
Arguments
Name
Astringcontainingthenameof themethodtobecalled. Thisargument can beavariable,
which allows the called method to be determined at runtime.
ObjRef
A scalar object reference that will be passed to the method as theSelf argument.
P
i
The arguments to be passed to the method given by Name. These arguments are the
positional and keyword argumentsdocumented for thecalled method, and arepassed to
the called method exactly as if it had been called directly.
See Also
CALL_FUNCTION, CALL_PROCEDURE, EXECUTE
CALL_PROCEDURE IDL Reference Guide
CALL_PROCEDURE
CALL_PROCEDURE calls the procedure specied by Name, passing any additional
parameters as its arguments.
Although not asexibleastheEXECUTEfunction, CALL_PROCEDUREismuch faster.
Therefore, CALL_PROCEDURE should be used in preference to EXECUTE whenever
possible.
Calling Sequence
CALL_PROCEDURE, Name[, P
1
, ..., P
n
]
Arguments
Name
A string containing the name of the procedure do be called. This argument can be a
variable, which allows the called procedure to be determined at runtime.
P
i
The arguments to be passed to the procedure given by Name. These arguments are the
positional and keyword argumentsdocumented for thecalled procedure, and arepassed
to the called procedure exactly as if it had been called directly.
Example
Thefollowingexampleshowshowto call thePLOT procedureindirectly with anumber
of arguments. First, create a dataset for plotting by entering:
B = FINDGEN(100)
Call PLOT indirectly to create a polar plot by entering:
CALL_PROCEDURE, 'PLOT', B, B, /POLAR
A spiral plot should appear.
See Also
CALL_FUNCTION, EXECUTE
IDL Reference Guide CATCH
CATCH
TheCATCH procedureprovidesageneralizedmechanismfor thehandlingof exceptions
and errors within IDL. Calling CATCH establishes an error handler for the current
procedure that intercepts all errors that can be handled by IDL, excluding non-fatal
warnings such as math errors.
When an error occurs, each active procedure, beginning with the offending procedure
and proceeding up the call stack to the main program level, is examined for an error
handler. If an error handler is found, control resumes at the statement after the call to
CATCH. Theindex of theerror isreturned in theargument toCATCH. The!ERROR(or
!SYSERROR) and!ERR_STRING(or !SYSERR_STRING) systemvariablesarealsoset. If
no error handlers are found, program execution stops, an error message is issued, and
control reverts to the interactive mode. A call to ON_IOERROR in the procedure that
causes an I/O error supersedes CATCH, and takes the branch to the label dened by
ON_IOERROR.
Thismechanismissimilar, but not identical to, thesetjmp/longjmp facilitiesin Cand
thecatch/throw facilities in C++.
Error handlingisdiscussedinmoredetail inControllingErrors onpage141of Building
IDL Applications.
Calling Sequence
CATCH, Variable
Arguments
Variable
A named variable in which the error index is returned. When an error handler is
established byacall toCATCH, Variableisset tozero. If an error occurs, Variableisset to
the error index, and control is transferred to the statement after the call to CATCH.
Keywords
CANCEL
Set thiskeyword to cancel theerror handler for thecurrent procedure. Thiscancellation
does not affect other error handlers that may be established in other active procedures.
Example
The following procedure illustrates the use of CATCH:
PRO ABC
CATCH IDL Reference Guide
A = FLTARR(10) DefinevariableA.
CATCH, Error_status Establish error handler. When er-
rorsoccur,theindexoftheerroris
returned in thevariable
Error_status.
IF Error_status NE 0 THEN BEGIN This statement begins theerror
handler.
PRINT, 'Error index: ', Error_status
PRINT, 'Error message:', !ERR_STRING
A=FLTARR(12) Handletheerror by extendingA.
ENDIF
A[11]=12 Causean error.
HELP, A Eventhoughanerroroccursinthe
lineabove, program execution
continuestothispointbecausethe
eventhandlerextendedthedefini-
tionofAsothatthestatementcan
bere-executed.
END
Running the ABC procedure causes IDL to produce the following output and control
returns to the interactive prompt:
Error index: -101
Error message:
Attempt to subscript A with <INT ( 11)> is out of range.
A FLOAT = Array[12]
See Also
ON_ERROR, ON_IOERROR, Controlling Errors on page 141 of Building IDL
Applications
IDL Reference Guide CD
CD
The CD procedure is used to set and/or change the current working directory. This
routinechangestheworkingdirectoryfor theIDLsession andanychildprocessesstarted
from IDL during that session after the directory change is made. Under Unix, CD does
not affect theworkingdirectoryof theprocessthat startedIDL. ThePUSHD, POPD, and
PRINTD procedures provide a convenient interface to CD.
Calling Sequence
CD [, Directory]
Arguments
Directory
A scalar string specifying the path of the new working directory. If Directory is specied
asanull string, theworkingdirectory ischanged to theusershomedirectory (Unix and
VMS) or to the directory specied by !DIR (Windows and Macintosh OS). If this
argument is not specied, the working directory is not changed.
Keywords
CURRENT
If CURRENT is present, it species a named variable into which the current working
directory is stored as a scalar string. The returned directory is the working directory
beforethedirectory ischanged. Thus, you can obtain thecurrent workingdirectory and
change it in a single statement:
CD, new_dir, CURRENT=old_dir
Example
Under Unix, to change the working directory to the data subdirectory of the current
directory, enter:
CD, 'data'
Under VMS, you could use:
CD, '[.data]'
See Also
PUSHD, POPD
CD IDL Reference Guide
IDL Reference Guide CEIL
CEIL
TheCEIL function returnstheclosest integer greater than or equal to itsargument. This
value is returned as a longword integer with the same structure as the input argument.
Calling Sequence
Result = CEIL(X)
Arguments
X
The value for which the ceiling function is to be evaluated. This value can be single- or
double-precision, real or complex oating-point. CEIL returns a longword integer with
the same structure asX.
Example
To print the ceiling function of 5.1, enter:
PRINT, CEIL(5.1)
IDL prints:
6
See Also
COMPLEXROUND, FLOOR, ROUND
CHEBYSHEV IDL Reference Guide
CHEBYSHEV
The CHEBYSHEV function returns the forward or reverse Chebyshev polynomial
expansion of aset of data. Note: Resultsfromthisfunction aresubject to roundoff error
given discontinuous data.
chebyshev.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CHEBYSHEV(D, N)
Arguments
D
A vector containing the values at the zeros of Chebyshev polynomial.
N
A ag that, if set to -1, returns a set of Chebyshev polynomials. If set to +1, the original
data is returned.
See Also
FFT, WTN
IDL Reference Guide CHECK_MATH
CHECK_MATH
TheCHECK_MATH function returnsandclearstheaccumulatedmatherror status. The
returned value is the sum of the bit values (described in Table 9-1 below) of the
accumulated errors.
Notethat each typeof error isonlyrepresented oncein thereturn valueanynumber of
Integer divided by zero errors will result in a return value of 1.
The math error status is cleared (reset to zero) when CHECK_MATH is called, or when
errorsarereported. Matherrorsarereportedeither never, when theinterpreter returnsto
an interactiveprompt, or after execution of each IDL statement, dependingon thevalue
of the!EXCEPT systemvariable(see !EXCEPT on page40). See Examples, below, for
further discussion.
Calling Sequence
Result = CHECK_MATH( )
Keywords
PRINT
Set this keyword to print an error message to the IDL command log if any accumulated
math errors exist. If this keyword is not present, CHECK_MATH executes silently.
Value Condition
0 No errors detected since the last interactive prompt or call to
CHECK_MATH
1 Integer divided by zero
2 Integer overow
16 Floating-point divided by zero
32 Floating-point underow
64 Floating-point overow
128 Floating-point operand error. An illegal operand was encountered,
such as a negative operand to the SQRT or ALOG functions, or an
attempt to convert to integer a number whose absolute value is
greater than 2
31
- 1
Table 9-1: Math Error Status Values (note that not all machines detect all errors)
CHECK_MATH IDL Reference Guide
Examples
To simply check and clear theaccumulated math error statususingall thedefaults, enter:
PRINT, CHECK_MATH()
IDL prints the accumulated math error status code and resets to zero.
CHECK_MATH and !EXCEPT
Because the accumulated math error status is cleared when it is reported, the behavior
and appropriate use of CHECK_MATH depends on the value of the system variable
!EXCEPT.
If !EXCEPT is set equal to 0, math exceptions are not reported automatically, and thus
CHECK_MATH will alwaysreturn theerror statusaccumulated sincethelast timeit was
called.
If !EXCEPT is set equal to 1, math exceptions are reported when IDL returns to the
interactivecommandprompt. In thiscase, CHECK_MATH will return appropriateerror
codeswhen used withinan IDL procedure, but will alwaysreturn zerowhen called at the
IDL prompt.
If !EXCEPT is set equal to 2, math exceptions are reported after each IDL statement. In
thiscase, CHECK_MATH will return appropriateerror codesonly when used withinan
IDL statement, and will always return zero otherwise.
For example:
!EXCEPT=0 Set valueof !EXCEPT to zero.
PRINT, 1./0., 1/0 Both of theseoperations causeer-
rors.
IDL prints:
Inf 1 Thespecial floating-point value
Infisreturnedfor1./0.Thereis
no integer analogueto thefloat-
ing-pointInf.
PRINT, CHECK_MATH() Check theaccumulated error sta-
tus.
IDL prints:
17 CHECK_MATHreportsfloating-
point and integer divide-by-zero
errors.
!EXCEPT=1 Set valueof !EXCEPT to one.
PRINT, 1./0., 1/0 Both of theseoperations causeer-
rors.
IDL prints:
IDL Reference Guide CHECK_MATH
Inf 1 This timeIDL also prints error
messages.
% Program caused arithmetic error: Integer divide by 0
% Program caused arithmetic error: Floating divide by 0
PRINT, CHECK_MATH() Check theaccumulated error sta-
tus.
IDL prints:
0 Status was reset.
However, if we do not allow IDL to return to an interactive prompt before checking the
math error status:
!EXCEPT=1 Set valueof !EXCEPT to one.
PRINT, 1./0., 1/0 & PRINT, CHECK_MATH()
Call toCHECK_MATHhappens
beforereturningto theIDL com-
mand prompt.
IDL prints:
Inf 1
17
In this case, the math error status code (17) is printed, but because the error status has
been cleared by the call to CHECK_MATH, no error messages are printed when IDL
returns to the interactive command prompt. Finally,
!EXCEPT=2 Set valueof !EXCEPT to two.
PRINT, 1./0., 1/0 & PRINT, CHECK_MATH()
Call toCHECK_MATHhappens
beforereturningto theIDL com-
mand prompt.
IDL prints:
Inf 1
% Program caused arithmetic error: Integer divide by 0
% Program caused arithmetic error: Floating divide by 0
% Detected at $MAIN$
0
Errors are printed before executing the CHECK_MATH function, so CHECK_MATH
reports no errors. However, if we include the call to CHECK_MATH in the rst PRINT
command, we see the following:
PRINT, 1./0., 1/0, CHECK_MATH() Call toCHECK_MATHispartof
a singleIDL statement.
CHECK_MATH IDL Reference Guide
IDL prints:
Inf 1 17
Printing Error Messages
The following code fragment prints abbreviated names of errors that have occurred:
ERRS = ['Divide by 0', 'Underflow', 'Overflow', $
'Illegal Operand'] Createa stringarray of error
names.
J = CHECK_MATH() Get math error status.
FOR I = 4, 7 DO IF ISHFT(J, -I) AND 1 THEN $
PRINT, ERRS(I-4), ' Occurred' Check to seeif an error occurred
andprintthecorrespondingerror
message.
Testing Critical Code
Assumeyouhaveacritical section of codethat islikelytoproducean error. Thefollowing
exampleshowshowtocheck for errors, andif oneisdetected, howtorepeat thecodewith
different parameters.
JUNK = CHECK_MATH(/PRINT) Clear error status from previous
operations, and print error mes-
sages if an error exists.
!EXCEPT=0 Disableautomatic printingof
subsequent math errors.
AGAIN: ... Critical section goes here.
IF CHECK_MATH() NE 0 THEN BEGIN Did an arithmetic error occur? If
so,printerrormessageandrequest
new values.
PRINT, 'Math error occurred in critical section.'
READ, 'Enter new values.',... Get new parameters from user.
!EXCEPT=2 Enableautomatic printingof
math errors.
GOTO, AGAIN And retry.
ENDIF
See Also
FINITE, ISHFT, MACHAR, !VALUES on page38, !EXCEPT on page40, and Math
Errors on page 151 of Building IDL Applications.
IDL Reference Guide CHISQR_CVF
CHISQR_CVF
The CHISQR_CVF function computes the cutoff valueV in a Chi-square distribution
with Df degreesof freedomsuch that theprobability that arandomvariableXisgreater
than V is equal to a user-supplied probability P.
chisqr_cvf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CHISQR_CVF(P, Df)
Arguments
P
that species the probability of occurrence or success.
Df
A positive integer, single- or double-precision oating-point scalar that species the
number of degrees of freedom of the Chi-square distribution.
Example
Use the following command to compute the cutoff value in a Chi-square distribution
withthreedegreesof freedomsuchthat theprobabilitythat arandomvariableXisgreater
than the cutoff value is 0.100. The result should be 6.25139.
PRINT, CHISQR_CVF(0.100, 3)
IDL prints:
6.25139
See Also
CHISQR_PDF, F_CVF, GAUSS_CVF, T_CVF
CHISQR_PDF IDL Reference Guide
CHISQR_PDF
The CHISQR_PDF function computes the probability P that, in a Chi-square
distribution with Df degrees of freedom, a random variableX is less than or equal to a
user-specied cutoff valueV.
chisqr_pdf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CHISQR_PDF(V, Df)
Arguments
V
An integer, single-, or double-precision oating-point scalar that species the cutoff
value.
Df
number of degrees of freedom of the Chi-square distribution.
Examples
Use the following command to compute the probability that a random variable X, from
the Chi-square distribution with three degrees of freedom, is less than or equal to 6.25.
The result should be 0.899939.
result = CHISQR_PDF(6.25, 3)
PRINT, result
IDL prints:
0.899939
Computetheprobabilitythat arandomvariableXfromtheChi-squaredistribution with
three degrees of freedom, is greater than 6.25. The result should be 0.100061.
PRINT, 1 - chisqr_pdf(6.25, 3)
IDL prints:
0.100061
See Also
BINOMIAL, CHISQR_CVF, F_PDF, GAUSS_PDF, T_PDF
IDL Reference Guide CHOLDC
CHOLDC
Given a positive-denite symmetric n by n array A, the CHOLDC procedure constructs
its Cholesky decomposition A = LL
T
, whereL is a lower triangular array and L
T
is the
transpose of L.
CHOLDCisbased on theroutinecholdc described in section 2.9of Numerical Recipes
Calling Sequence
CHOLDC, A, P
Arguments
A
An n by n array. On input, only the upper triangle of A need be given. On output, L is
returned in thelower triangleof A, except for thediagonal elements, which arereturned
in the vector P.
P
An n-element vector containing the diagonal elements of L.
Keywords
DOUBLE
Example
See the description of CHOLSOL for an example using this function.
See Also
CHOLSOL
CHOLSOL IDL Reference Guide
CHOLSOL
The CHOLSOL function returns an n-element vector containing the solution to the set
of linear equationsAx = b, whereA is the positive-denite symmetric array returned by
the CHOLDC procedure.
CHOLSOL isbased on theroutinecholsl described in section 2.9of Numerical Recipes
Calling Sequence
result = CHOLSOL(A, P, B)
Arguments
A
An n by n positive-denite symmetric array, as output by CHOLDC. Only the lower
triangle of A is accessed.
P
The diagonal elements of the Cholesky factor L, as computed by CHOLDC.
B
An n-element vector containing the right-hand side of the equation.
Keywords
DOUBLE
Example
To solve a positive-denite symmetric system Ax = b:
A = [[ 6.0, 15.0, 55.0], $ Definethecoefficient array.
[15.0, 55.0, 225.0], $
[55.0, 225.0, 979.0]]
B = [9.5, 50.0, 237.0] Definetheright-hand sidevector
B.
CHOLDC, A, P ComputeCholeskydecomposition
of A.
IDL Reference Guide CHOLSOL
PRINT, CHOLSOL(A, P, B) Computeand print thesolution.
IDL prints:
-0.499998 -1.00000 0.500000
The exact solution vector is [ -0.5, -1.0, 0.5] .
See Also
CRAMER, GS_ITER, LU_COMPLEX, CHOLDC, LUSOL, SVSOL, TRISOL
CINDGEN IDL Reference Guide
CINDGEN
The CINDGEN function returns a complex, single-precision, oating-point array with
thespecied dimensions. Each element of thearray hasitsreal part set to thevalueof its
one-dimensional subscript. The imaginary part is set to zero.
Calling Sequence
Result = CINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
To create C, a 4-element vector of complex values with the real parts set to the value of
their subscripts, enter:
C = CINDGEN(4)
See Also
BINDGEN, DCINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, LINDGEN,
IDL Reference Guide CIR_3PNT
CIR_3PNT
TheCIR_3PNT procedurereturnstheradiusand center of acircle, given 3pointson the
circle. This is analogous to nding the circumradius and circumcircle of a triangle; the
center of the circumcircle is the point at which the three perpendicular bisectors of the
triangle formed by the points meet.
cir_3pnt.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
CIR_3PNT, X, Y, R, X0, Y0
Arguments
X
A three-element vector containing the X-coordinates of the points.
Y
A three-element vector containing the Y-coordinates of the points.
R
A named variable that will contain the radius of the circle. The procedure returns 0.0 if
the points are co-linear.
X0
A named variable that will contain the X-coordinate of the center of the circle.
The procedure returns 0.0 if the points are co-linear.
Y0
A named variable that will contain the Y-coordinate of the center of the circle. The
procedure returns 0.0 if the points are co-linear.
Example
X = [1.0, 2.0, 3.0]
Y = [1.0, 2.0, 1.0]
CIR_3PNT, X, Y, R, X0, Y0
PRINT, 'The radius is: ', R
PRINT, 'The center of the circle is at: ', X0, Y0
CIR_3PNT IDL Reference Guide
See Also
PNT_LINE, SPH_4PNT
IDL Reference Guide CLOSE
CLOSE
The CLOSE procedure closes the le units specied as arguments. All open les are also
closed when IDL exits.
Calling Sequence
CLOSE[,Unit
1
, ..., Unit
n
]
Arguments
Unit
i
The IDL le units to close.
Keywords
ALL
Set thiskeyword to closeall open leunits. In addition, any leunitsthat wereallocated
via GET_LUN are freed.
FILE
Set this keyword to close all le units from 1 to 99. File units greater than 99, which are
associated with the GET_LUN and FREE_LUN procedures, are not affected.
Example
If le units 1 and 3 are open, they can both be closed at the same time by entering the
command:
CLOSE, 1, 3
See Also
OPEN
CLUST_WTS IDL Reference Guide
CLUST_WTS
The CLUST_WTS function computes the weights (the cluster centers) of an m-column,
n-row array, wheremis the number of variables and n is the number of observations or
samples. The result is an m-column, N_CLUSTERS-row array of cluster centers.
Calling Sequence
Result = CLUST_WTS(Array)
Arguments
Array
An m-column, n-row array of any data type except string, single- or double-precision
complex.
Keywords
DOUBLE
N_CLUSTERS
Set this keyword equal to the number of cluster centers. The default is to computen
cluster centers.
N_ITERATIONS
Set this keyword equal to the number of iterations used when in computing the cluster
centers. The default is to use 20 iterations.
VARIABLE_WTS
Set this keyword equal to an m-element vector of oating-point variable weights. The
elementsof thisvector areusedtogivegreater or lesser importancetoeachvariable(each
column) in determining the cluster centers. The default is to give all variables equal
weighting using a value of 1.0.
Example
See the documentation for CLUSTER.
See Also
CLUSTER, Multivariate Analysis on page 470 of Using IDL.
IDL Reference Guide CLUSTER
CLUSTER
TheCLUSTERfunction computestheclassication of an m-column, n-rowarray, where
mis the number of variables and n is the number of observations or samples. The
classication isbased upon acluster analysisof sample-based distances. Theresult isa1-
column, n-row array of cluster number assignments that correspond to each sample.
Calling Sequence
Result = CLUSTER(Array, Weights)
Arguments
Array
An M-column, N-row array of type oat or double.
Weights
An arrayof weights(thecluster centers) computedusingtheCLUST_WTSfunction. The
dimensions of this array vary according to keyword values.
Keywords
DOUBLE
N_CLUSTERS
Set this keyword equal to the number of clusters. The default is based upon the row
dimension of theWeightsarray.
Example
Dene an array with 4 variables and 10 observations.
array = $
[[ 1.5, 43.1, 29.1, 1.9], $
[24.7, 49.8, 28.2, 22.8], $
[30.7, 51.9, 7.0, 18.7], $
[ 9.8, 4.3, 31.1, 0.1], $
[19.1, 42.2, 0.9, 12.9], $
[25.6, 13.9, 3.7, 21.7], $
[ 1.4, 58.5, 27.6, 7.1], $
CLUSTER IDL Reference Guide
[ 7.9, 2.1, 30.6, 5.4], $
[22.1, 49.9, 3.2, 21.3], $
[ 5.5, 53.5, 4.8, 19.3]]
Compute the cluster weights, using two distinct clusters.
weights = CLUST_WTS(array, N_CLUSTERS=2)
Compute the classication of each sample.
result = CLUSTER(array, weights, N_CLUSTERS=2)
Print each sample (each row) of the array and its corresponding cluster assignment.
FOR k = 0, N_ELEMENTS(result)-1 DO PRINT, $
array[*,k], result(k), FORMAT = '(4(f4.1, 2x), 5x, i1)'
IDL prints:
1.5 43.1 29.1 1.9 1
24.7 49.8 28.2 22.8 0
30.7 51.9 7.0 18.7 0
9.8 4.3 31.1 0.1 1
19.1 42.2 0.9 12.9 0
25.6 13.9 3.7 21.7 0
1.4 58.5 27.6 7.1 1
7.9 2.1 30.6 5.4 1
22.1 49.9 3.2 21.3 0
5.5 53.5 4.8 19.3 0
See Also
CLUST_WTS, PCOMP, STANDARDIZE, Multivariate Analysis on page 470 of Using
IDL.
IDL Reference Guide COLOR_CONVERT
COLOR_CONVERT
The COLOR_CONVERT procedure converts colors to and from the RGB (Red Green
Blue), HLS(HueLightnessSaturation), and HSV (HueSaturation Value) color systems.
A keyword parameter indicates the type of conversion to be performed (one of the
keywordsmust bespecied). Therst threeparameterscontain theinput color triple(s)
which may be scalars or arrays of the same size. The result is returned in the last three
parameters, O
0
, O
1
, and O
2
. RGB values are bytes in the range 0 to 255.
Hueismeasured in degrees, from0to 360. Saturation, Lightness, and Valueareoating-
point numbers in the range 0 to 1. A Hue of 0 degrees is the color red. Green is 120
degrees. Blue is 240 degrees. A reference containing a discussion of the various color
systemsis: FoleyandVan Dam, Fundamentalsof InteractiveComputer Graphics, Addison-
Wesley Publishing Co., 1982.
Calling Sequence
COLOR_CONVERT, I
0
, I
1
, I
2
, O
0
, O
1
, O
2
Arguments
I
0
, I
1
, I
2
The input color triple(s). These arguments may be either scalars or arrays of the same
length.
O
0
, O
1
, O
2
The variables to receive the result. Their structure is copied from the input parameters.
Keywords
HLS_RGB
Set this keyword to convert from HLS to RGB.
HSV_RGB
Set this keyword to convert from HSV to RGB.
RGB_HLS
Set this keyword to convert from RGB to HLS.
RGB_HSV
Set this keyword to convert from RGB to HSV.
COLOR_CONVERT IDL Reference Guide
Example
The command:
COLOR_CONVERT, 255, 255, 0, h, s, v, /RGB_HSV
convertstheRGBcolor triple(255, 255, 0), which isthecolor yellowat full intensity and
saturation, to the HSV system. The resulting hue in the variable h is 60.0 degrees. The
saturation and value, s and v, are set to 1.0.
See Also
HLS, HSV
IDL Reference Guide COLOR_QUAN
COLOR_QUAN
The COLOR_QUAN function quantizes a true-color image and returns a pseudo-color
image and palette to display the image on standard pseudo-color displays. The output
image and palette can have from 2 to 256 colors.
COLOR_QUAN solves the general problem of accurately displaying decomposed, true-
color images, that contain apaletteof up to2
24
colors, on pseudo-color displaysthat can
only display 256 (or fewer) simultaneous colors.
One of two color quantization methods can be used:
Method 1 is a statistical method that attempts to nd the N colors that most accurately
represent the original color distribution. This algorithm uses a variation of the Median
Cut Algorithm, described in Color ImageQuantization for FrameBuffer Display, from
ComputerGraphics, Volume16, Number 3(July, 1982), Page297. It repeatedlysubdivides
thecolor spaceintosmaller andsmaller rectangular boxes, until therequestednumber of
colors are obtained.
The original colors are then mapped to the nearest output color, and the original image
is resampled to the new palette with optional Floyd-Steinberg color dithering. The
resultingpseudo-color imageandpaletteareusuallyagoodapproximationof theoriginal
image.
Thenumber of colorsin theoutput palettedefaultstothenumber of colorssupportedby
thecurrently-selectedgraphicsoutput device. Thenumber of colorscan alsobespecied
by the COLOR keyword parameter.
Method2, selectedbysettingthekeywordparameter CUBE, dividesthethree-dimension-
al color space into equal-volume cubes. Each color axis is divided into CUBE segments,
resultinginCUBE
3
volumes. Theoriginal input imageissampledtothiscolor spaceusing
Floyd-Steinberg dithering, which distributes the quantization error to adjacent pixels.
TheCUBEmethodhastheadvantagethat thecolor tablesit producesareindependent of
the input image, so that multiple quantized images can be viewed simultaneously. The
statistical method usually provides a better-looking result and a smaller global error.
COLOR_QUAN can use the same color mapping for a series of images. See the
descriptions of the GET_TRANSLATION, MAP_ALL, and TRANSLATION keywords,
below.
Calling Sequence
Result = COLOR_QUAN(Image_R, Image_G, Image_B, R, G, B)
or
Result = COLOR_QUAN(Image, Dim, R, G, B)
COLOR_QUAN IDL Reference Guide
Note that the input image parameter can be passed as either three, separate color-
component arrays (Image_R, Image_G, Image_B) or as a three-dimensional array
containingall threecomponents, Image, andascalar, Dim, indicatingthedimension over
which the colors are interleaved.
Arguments
Image_R, Image_G, Image_B
Arrays containing the red, green, and blue components of the decomposed true-color
image. For best results, the input image(s) should be scaled to the range of 0 to 255.
Image
A three-dimensional array containing all three components of the true-color image.
Dim
A scalar that indicates the method of color interleaving in theImageparameter. A value
of 1 indicates interleaving by pixel: (3, n, m). A value of 2 indicates interleaving by row:
(n, 3, m). A value of 3 indicates interleaving by image: (n, m, 3).
R, G, B
Three output byte arrays containing the red, green, and blue components of the output
palette.
Keywords
COLORS
Thenumber of colorsintheoutput palette. Thisvaluemust at least 2andnot greater than
256. Thedefault isthenumber of colorssupportedbythecurrent graphicsoutput device.
CUBE
If thiskeyword isset, thecolor spaceisdivided into CUBE
3
volumes, to which theinput
imageisquantized. Thisresult isalwaysFloyd-Steinbergdithered. Thevalueof CUBEcan
rangefrom2to6; providingfrom2
3
= 8, to6
3
= 216output colors. If thiskeyword isset,
the COLORS, DITHER, and ERROR keywords are ignored.
DITHER
Set thiskeywordtodither theoutput image. Ditheringcanimprovetheappearanceof the
output image, especially when using relatively few colors.
ERROR
Set this optional keyword to a named variable. A measure of the quantization error is
returned. Thiserror isproportional tothesquareof theEuclideandistance, inRGBspace,
between corresponding colors in the original and output images.
IDL Reference Guide COLOR_QUAN
GET_TRANSLATION
Set this keyword to a named variable in which the mapping between the original RGB
triples (in the true-color image) and the resulting pseudo-color indices is returned as a
vector. Do not use this keyword if CUBE is set.
MAP_ALL
Set this keyword to establish a mapping for all possible RGB triples into pseudo-color
indices. Set thiskeywordonlyif GET_TRANSLATIONisalsopresent. Notethat mapping
all possible colors requires more compute time and slightly degrades the quality of the
resultant color matching.
TRANSLATION
Set this keyword to a vector of translation indices obtained by a previous call to
COLOR_QUAN using the GET_TRANSLATION keyword. The resulting image is
quantized using this vector.
Example
The following code segment reads a true-color, row interleaved, image from a disk le,
and displays it on the current graphics display, using a palette of 128 colors:
OPENR, unit, 'XXX.DAT', /GET_LUN Open an input file.
a = BYTARR(512, 3, 480) Dimensions of theinput image.
READU, unit, a Read theimage.
FREE LUN, unit Closethefile.
TV, COLOR_QUAN(a, 2, r, g, b, COLORS=128)Showthequantizedimage.The2
indicates that thecolors areinter-
leaved by row.
TVLCT, r, g, b Load thenew palette.
To quantize the image into 216 equal-volume color cubes, replace the call to
COLOR_QUAN with the following:
TV, COLOR_QUAN(a, 2, r, g, b, CUBE=6)
See Also
PSEUDO
COMFIT IDL Reference Guide
COMFIT
The COMFIT function ts the paired data {x
i
, y
i
} to one of six common types of
approximating models using a gradient-expansion least-squares method. The result is a
vector containing the model parametersa
0
, a
1
, a
2
, etc.
comfit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = COMFIT(X, Y, A)
Arguments
X
Y
A
Avector of initial estimatesfor each model parameter. Thelength of thisvector depends
upon the type of model selected.
Keywords
Note One of the following keywords specifying a type of model must be set when using
COMFIT. If you do not specify a model, IDL will display a warning message when
COMFIT is called.
EXPONENTIAL
Set this keyword to compute the parameters of the exponential model.
GEOMETRIC
Set this keyword to compute the parameters of the geometric model.
GOMPERTZ
Set this keyword to compute the parameters of the Gompertz model.
y a
0
a
1
x
a
2
+ =
y a
0
x
a
1
a
2
+ =
IDL Reference Guide COMFIT
HYPERBOLIC
Set this keyword to compute the parameters of the hyperbolic model.
LOGISTIC
Set this keyword to compute the parameters of the logistic model.
LOGSQUARE
Set this keyword to compute the parameters of the logsquare model.
SIGMA
Set thiskeyword toanamed variablethat will contain avector of standard deviationsfor
the computed model parameters.
WEIGHTS
Set thiskeywordequal toavector of weightsfor Y
i
. Thisvector shouldbethesamelength
asX and Y. The error for each term is weighted by WEIGHTS
i
when computing the t.
Frequently, WEIGHTS
i
= 1.0/
2
i
, where is the measurement error or standard
deviation of Y
i
(Gaussian or instrumental weighting), or WEIGHTS= 1/Y (Poisson or
statistical weighting). If WEIGHTS is not specied, WEIGHTS
i
is assumed to be 1.0.
YFIT
Set this keyword to a named variable that will contain an n-element vector of y-data
corresponding to the computed model parameters.
y a
0
a
1
a
2
x
a
3
+ =
y
1
a
0
a
1
x +
-------------------- =
y
1
a
0
a
1
x
a
2
+
----------------------- =
y a
0
a
1
x ( ) a
2
x ( )
2
log + log + =
COMFIT IDL Reference Guide
Example
Dene two n-element vectors of paired data.
X = [ 2.27, 15.01, 34.74, 36.01, 43.65, 50.02, 53.84, 58.30, $
62.12, 64.66, 71.66, 79.94, 85.67, 114.95]
Y = [ 5.16, 22.63, 34.36, 34.92, 37.98, 40.22, 41.46, 42.81, $
43.91, 44.62, 46.44, 48.43, 49.70, 55.31]
Dene a 3-element vector of initial estimates for the logsquare model.
A = [1.5, 1.5, 1.5]
Compute the model parameters of the logsquare model, A[ 0] , A[ 1] , & A[ 2] .
result = COMFIT(X, Y, A, /LOGSQUARE)
The result should be the 3-element vector: [ 1.42494, 7.21900, 9.18794] .
See Also
CURVEFIT, LADFIT, LINFIT, LMFIT, POLY_FIT, POLYFITW, SVDFIT
IDL Reference Guide COMPLEX
COMPLEX
The COMPLEX function returns complex scalars or arrays given one or two scalars or
arrays. If only one parameter is supplied, the imaginary part of the result is zero,
otherwiseit isset to thevalueof theImaginaryparameter. Parametersarerst converted
tosingle-precision oating-point. If either or bothof theparametersarearrays, theresult
is an array, following the same rules as standard IDL operators. If three parameters are
supplied, COMPLEX extracts elds of data fromExpression.
Calling Sequence
Result = COMPLEX(Real [, Imaginary])
or
Result = COMPLEX(Expression, Offset, Dim
1
[, ..., Dim
n
])
Arguments
Real
Scalar or array to be used as the real part of the complex result.
Imaginary
Scalar or array to be used as the imaginary part of the complex result.
Expression
The expression from which data is to be extracted.
Offset
Offset frombeginningof theExpressiondataarea. Specifyingthisargument allowselds
of data extracted fromExpression to be treated as complex data. See the description in
Constants and Variables on page 11 of Building IDL Applications for details.
D
i
i
When convertingfromastringargument, it ispossiblethat thestringdoesnot contain a
valid oating-point valueand no conversion ispossible. Thedefault action in such cases
istoprint awarningmessageandreturn 0. TheON_IOERRORprocedurecan beusedto
establish a statement to be jumped to in case of such errors.
Example
Create a complex array from two integer arrays by entering the following commands:
COMPLEX IDL Reference Guide
A = [1,2,3] Createthefirst integer array.
B = [4,5,6] Createthesecond integer array.
C = COMPLEX(A, B) MakeA thereal parts and B the
imaginary parts of thenew com-
plex array.
PRINT, C Seehowthetwoarrayswerecom-
bined.
IDL prints:
( 1.00000, 4.00000)( 2.00000, 5.00000)
( 3.00000, 6.00000)
See Also
BYTE, CONJ, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT,
ULONG, ULONG64
IDL Reference Guide COMPLEXARR
COMPLEXARR
TheCOMPLEXARRfunction returnsacomplex, single-precision, oating-point vector
or array.
Calling Sequence
Result = COMPLEXARR(D
1
, ..., D
n
)
Arguments
D
i
The dimensions of the result. The dimension parameters may be any scalar expression.
Up to eight dimensions can be specied.
Keywords
NOZERO
Normally, COMPLEXARR sets every element of the result to zero. If the NOZERO
keyword is set, this zeroing is not performed, and COMPLEXARR executes faster.
Example
To create an empty, 5-element by 5-element, complex array C, enter:
C = COMPLEXARR(5, 5)
See Also
DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR,
MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR
COMPLEXROUND IDL Reference Guide
COMPLEXROUND
TheCOMPLEXROUND function roundsreal and imaginary componentsof acomplex
array and returns the resulting array.
complexround.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = COMPLEXROUND(Input)
Arguments
Input
The complex array to be rounded.
Example
X = [COMPLEX(1.245, 3.88), COMPLEX(9.1, 0.3345)]
PRINT, COMPLEXROUND(X)
IDL prints:
( 1.00000, 4.00000)( 9.00000, 0.00000)
See Also
ROUND
IDL Reference Guide COMPUTE_MESH_NORMALS
COMPUTE_MESH_NORMALS
The COMPUTE_MESH_NORMALS function computes normal vectors for a set of
polygonsdescribed bytheinput array. Thereturn valueisa3xMarraycontainingaunit
normal for each vertex in the input array.
Calling Sequence
Result = COMPUTE_MESH_NORMALS( fVerts [, iConn])
Arguments
fVerts
A 3 x M array of vertices.
iConn
A connectivity array (see the POLYGONS keyword to IDLgrPolygon::Init). If no iConn
array is provided, it is assumed that the vertices in fVertsconstitute a single polygon.
Keywords
None.
COND IDL Reference Guide
COND
TheCOND function returnsthecondition number of an nby nreal or complex array A
byexplicitlycomputingNORM(A)NORM(A
-1
). If Aisreal andA
-1
isinvalid(duetothe
singularity of A or oating-point errors in the INVERT function), COND returns -1. If
A is complex and A
-1
is invalid (due to the singularity of A), calling COND results in
oating-point errors.
cond.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = COND(A)
Arguments
A
An n by n real or complex array.
Keywords
DOUBLE
Example
Dene a complex array A:
A = [[COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3, 1)], $
[COMPLEX(1,-2), COMPLEX(2, 2), COMPLEX(1, 0)], $
[COMPLEX(1, 1), COMPLEX(0, 1), COMPLEX(1, 5)]]
Compute the condition number of the array using internal double-precision arithmetic.
PRINT, COND(A, /DOUBLE)
IDL prints:
5.93773
See Also
DETERM, INVERT
IDL Reference Guide CONGRID
CONGRID
TheCONGRIDfunction shrinksor expandsthesizeof an arraybyan arbitraryamount.
CONGRIDissimilar toREBINinthat it canresizeaone, two, or threedimensional array,
but where REBIN requires that the new array size must be an integer multiple of the
original size, CONGRID will resize an array to any arbitrary size. (REBIN is somewhat
faster, however.) REBIN averages multiple points when shrinking an array, while
CONGRID just resamples the array.
Thereturnedarrayhasthesamenumber of dimensionsastheoriginal arrayandisof the
same data type.
congrid.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CONGRID(Array, X, Y, Z)
Arguments
Array
A1-, 2-, or 3-dimensional arraytoresize. Arraycan beanytypeexcept stringor structure.
X
The new X-dimension of the resized array. X must be an integer or a long integer, and
must be greater than or equal to 2.
Y
ThenewY-dimension of theresized array. If theoriginal arrayhasonly1dimension, Yis
ignored. If the original array has 2 or 3 dimensionsY MUST be present.
Z
ThenewZ-dimensionof theresizedarray. If theoriginal arrayhasonly1or 2dimensions,
Z is ignored. If the original array has 3 dimensions then Z MUST be present.
Keywords
CUBIC
Set this keyword to a value between -1 and 0 to use the cubic convolution interpolation
method with the specied value as the interpolation parameter. Setting this keyword
equal to a value greater than zero species a value of -1 for the interpolation parameter.
Park and Schowengerdt (see reference below) suggest that a value of -0.5 signicantly
improves the reconstruction properties of this algorithm. This keyword has no effect
when used with 3-dimensional arrays.
CONGRID IDL Reference Guide
Cubicconvolution isan interpolation methodthat closelyapproximatesthetheoretically
optimum sinc interpolation function using cubic polynomials. According to sampling
theory, detailsof which arebeyond thescopeof thisdocument, if theoriginal signal, f, is
a band-limited signal, with no frequency component larger than
0
, and f is sampled
withspacinglessthanor equal to1/(2
0
), thenfcanbereconstructedbyconvolvingwith
a sinc function: sinc(x) = sin(x) / (x).
In the one-dimensional case, four neighboring points are used, while in the two-
dimensional case 16 points are used. Note that cubic convolution interpolation is
signicantly slower than bilinear interpolation.
For further details see:
Rifman, S.S. and McKinnon, D.M., Evaluation of Digital Correction Techniques for
ERTSImages; Final Report, Report 20634-6003-TU-00, TRWSystems, Redondo Beach,
CA, July 1974.
S. Park and R. Schowengerdt, 1983 Image Reconstruction by Parametric Cubic
Convolution, Computer Vision, Graphics & Image Processing 23, 256.
INTERP
Set this keyword to force CONGRID to use linear interpolation when resizing a 1- or 2-
dimensional array. CONGRID automatically uses linear interpolation if the input array
is 3-dimensional. When the input array is 1- or 2-dimensional, the default is to employ
nearest-neighbor sampling.
MINUS_ONE
Set this keyword to prevent CONGRID from extrapolating one row or column beyond
theboundsof theinput array. For example, if theinput arrayhasthedimensions(i, j) and
the output array has the dimensions (x, y), then by default the array is resampled by a
factor of (i/x) in the X direction and (j/y) in the Y direction. If MINUS_ONE is set, the
array will be resampled by the factors (i-1)/(x-1) and (j-1)/(y-1).
Example
Given vol is a 3-D array with the dimensions (80, 100, 57), resize it to be a (90, 90, 80)
array
vol = CONGRID(vol, 90, 90, 80)
See Also
REBIN
IDL Reference Guide CONJ
CONJ
The CONJ function returns the complex conjugate of X. The complex conjugate of the
real-imaginary pair (x, y) is (x, -y). If X is not complex, a complex-valued copy of X is
used.
Calling Sequence
Result = CONJ(X)
Arguments
X
The value for which the complex conjugate is desired. If X is an array, the result has the
same structure, with each element containing the complex conjugate of the
corresponding element of X.
Example
Print the conjugate of the complex pair (4.0, 5.0) by entering:
PRINT, CONJ(COMPLEX(4.0, 5.0))
IDL prints:
( 4.00000, -5.00000)
See Also
CINDGEN, COMPLEX, COMPLEXARR, DCINDGEN, DCOMPLEX,
DCOMPLEXARR
CONSTRAINED_MIN IDL Reference Guide
CONSTRAINED_MIN
The CONSTRAINED_MIN procedure solves nonlinear optimization problems of the
following form:
Minimize or maximize gp(X), subject to:
glb
i
g
i
(X) gub
i
for i = 0,...,nfuns-1, i p
xlb
j
x
j
xub
j
for j = 0,...,nvars-1.
X is a vector of nvarsvariables, x
0
,...,x
nvars
-1 and G is a vector of nfunsfunctions
g
0
,...,g
nfuns
-1whichall dependon X. Anyof thesefunctionsmaybenonlinear. Anyof the
bounds may be innite and any of the constraints may be absent. If there are no
constraints, the problem is solved as an unconstrained optimization problem. The
programsolvesproblemsof thisformbytheGeneralizedReducedGradient Method. See
References 1-4.
CONSTRAINED_MIN uses rst partial derivatives of each function g
i
with respect to
each variablex
j
. These are automatically computed by nite difference approximation
(either forward or central differences).
CONSTRAINED_MINisbasedonanimplementationof theGRGalgorithmsuppliedby
Windward Technologies, Inc. See Reference 11.
Calling Sequence
CONSTRAINED_MIN, X, Xbnd, Gbnd, Nobj, Gcomp, Inform
Arguments
X
An nvars-element vector. On input, Xcontainsinitial valuesfor thevariables. On output,
X contains nal values of the variable settings determined by CONSTRAINED_MIN.
Xbnd
Bounds on variables. Xbnd is an nvars x 2 element array.
Xbnd[j,0] is the lower bound for variablex[j].
Xbnd[j,1] is the upper bound for variablex[j].
Use -1.0e30 to denote no lower bound and 1.0e30 for no upper bound.
Gbnd
Bounds on constraint functions. Gbnd is an nfuns x 2 element array.
Gbnd[i,0] is the lower bound for function g[i].
Gbnd[i,1] is the upper bound for function g[i].
IDL Reference Guide CONSTRAINED_MIN
use -1.0e30 to denote no lower bound and 1.0e30 for no upper bound.
Bounds on the objective function are ignored; set them to 0.
Nobj
Index of the objective function.
Gcomp
A scalar stringspecifyingthenameof auser-supplied IDL function. Thisfunction must
accept an nvars-element vector argument x of variable values and return an nfuns-
element vector G of function values.
Inform
Termination status returned from CONSTRAINED_MIN.
Informvalue Message
0 Kuhn-Tucker conditions satised.
This is the best possible indicator that an optimal point has been
found.
1 Fractional change in objective less than EPSTOP for NSTOP con-
secutive iterations. See Keywords below.
This is not as good asInform=0, but still indicates the likelihood
that an optimal point has been found.
2 All remedies have failed to nd a better point.
User should check functionsand boundsfor consistency and, per-
haps, try other starting values.
3 Number of completed 1-dimensional searchesexceeded LIMSER.
See Keywords below.
User should check functionsand boundsfor consistency and, per-
haps, try other starting values. It might help to increase limser.
Use LIMSER=larger_valueto do this.
4 Objective function is unbounded.
CONSTRAINED_MIN has observed dramatic change in the
objective function over several steps. This is a good indication
that the objective function is unbounded. If this is not the case,
the user should check functions and bounds for consistency.
5 Feasible point not found.
CONSTRAINED_MIN wasnot ableto nd afeasiblepoint. If the
problemisbelieved tobefeasible, theuser should check functions
and bounds for consistency and perhaps try other starting values.
Table 9-2: Inform argument values
Keywords
EPSTOP
Set this keyword to specify the CONSTRAINED_MIN convergence criteria. If the
fractional change in the objective function is less than EPSTOP for NSTOP consecutive
iterations, theprogramwill accept thecurrent point asoptimal. CONSTRAINED_MIN
will accept the current point as optimal if the Kuhn-Tucker optimality conditions are
satised to EPSTOP. By default, EPSTOP = 1.0e-4.
LIMSER
If the number of completed one dimensional searches exceeds LIMSER,
CONSTRAINED_MIN terminatesand returnsinform= 3. By default: LIMSER= 10000.
MAXIMIZE
By default, the CONSTRAINED_MIN procedure performs a minimization. Set the
MAXIMIZE keyword to perform a maximization instead.
REPORT
Set this keyword to specify a name for the CONSTRAINED_MIN report le. If the
specied ledoesnot exist it will becreated. If it exists, it will beoverwritten. By default,
CONSTRAINED_MIN does not create a report le.
TITLE
Set this keyword to specify a title for the problem in the CONSTRAINED_MIN report.
6 Degeneracy has been encountered.
The point returned may be close to optimal. The user should
check functionsandboundsfor consistencyandperhapstryother
starting values.
7 Noisy and nonsmooth function values. Possible singularity or
error in the function evaluations.
8 Optimization process terminated by user request.
9 Maximum number of function evaluations exceeded.
-1 Fatal Error.
Some condition, such asnvars < 0, was encountered.
CONSTRAINED_MIN documented the condition in the report
and terminated. In this case, the user needs to correct the input
and rerun CONSTRAINED_MIN.
Informvalue Message
Table 9-2: Inform argument values
Example
This example has 5 variables {X0, X1, ..., X4}, bounded above and below, a quadratic
objective function {G3}, and three quadratic constraints {G0, G1, G2}, with both upper
and lower bounds. See the Himmelblau text [ 7] , problem 11.
Minimize:
G3 = 5.3578547X2X2 + 0.8356891X0X4 + 37.293239X0 - 40792.141
Subject to:
0 < G0 = 85.334407 + 0.0056858X1X4 + 0.0006262X0X3 - 0.0022053X2X4 < 92
90 < G1 = 80.51249 + 0.0071317X1X4 + 0.0029955X0X1 + 0.0021813X2X2 < 110
20 < G2 = 9.300961 + 0.0047026X2X4 + 0.0012547X0X2 + 0.0019085X2X3 < 25
and,
78 < X0 < 102
33 < X1 < 45
27 < X2 < 45
27 < X3 < 45
27 < X4 < 45
This problem is solved starting from X = {78, 33, 27, 27, 27} which is infeasible because
constraint G2 is not satised at this point.
The constraint functions and objective function are evaluated by HMBL11:
FUNCTION HMBL11, x ;HimmelblauProblem11,5vari-
ables and 4 functions.
g = DBLARR(4)
g[0] = 85.334407 + 0.0056858*x[1]*x[4] + 0.0006262*x[0]*x[3] $
- 0.0022053*x[2]*x[4]
g[1] = 80.51249 + 0.0071317*x[1]*x[4] + 0.0029955*x[0]*x[1] $
+ 0.0021813*x[2]*x[2]
g[2] = 9.300961 + 0.0047026*x[2]*x[4] + 0.0012547*x[0]*x[2] $
+ 0.0019085*x[2]*x[3]
g[3] = 5.3578547*x[2]*x[2] + 0.8356891*x[0]*x[4] $
+ 37.293239*x[ 0] - 40792.141
RETURN, g
END
; Example problem for CONSTRAINED_MIN
; Himmelblau Problem 11
; 5 variables and 3 constraints
; Constraints and objective dened in HMBL11
xbnd = [[78, 33, 27, 27, 27], [102, 45, 45, 45, 45]]
gbnd = [[0, 90, 20, 0], [92, 110, 25, 0 ]]
nobj = 3
gcomp = HMBL11
title = IDL: Himmelblau 11
report = hmbl11.txt
x = [78, 33, 27, 27, 27]
CONSTRAINED_MIN, x, xbnd, gbnd, nobj, gcomp, inform, $
REPORT = report, TITLE = title
g = HMBL11(x)
PRINT, g[nobj] Print minimized objective
function for HMBL11 problem.
References
1. Lasdon, L.S., Waren, A.D., Jain, A., and Ratner, M., "Design and Testing of a
Generalized Reduced Gradient Code for Nonlinear Programming", ACM Transactions
on Mathematical Software, Vol. 4, No. 1, March 1978, pp. 34-50.
2. Lasdon, L.S. and Waren, A.D., "Generalized Reduced Gradient Software for Linearly
and Nonlinearly Constrained Problems", in "Design and Implementation of
Optimization Software", H. Greenberg, ed., Sijthoff and Noordhoff, pubs, 1979.
3. Abadie, J. andCarpentier, J. "Generalization of theWolfeReducedGradient Methodto
the Case of Nonlinear Constraints", in Optimization, R. Fletcher (ed.), Academic Press
London; 1969, pp. 37-47.
4. Murtagh, B.A. and Saunders, M.A. "Large-scale Linearly Constrained Optimization",
Mathematical Programming, Vol. 14, No. 1, January 1978, pp. 41-72.
5. Powell, M.J.D., "Restart Procedures for the Conjugate Gradient Method,"
Mathematical Programming, Vol. 12, No. 2, April 1977, pp. 241-255.
6. Colville, A.R., "A Comparative Study of Nonlinear Programming Codes," I.B.M. T.R.
no. 320-2949 (1968).
7. Himmelblau, D.M., Applied Nonlinear Programming, McGraw-Hill Book Co., New
York, 1972.
8. Fletcher, R., "ANewApproachtoVariableMetricAlgorithms", Computer Journal, Vol.
13, 1970, pp. 317-322.
9. Smith, S. and Lasdon, L.S., Solving Large Sparse Nonlinear Programs Using GRG,
ORSA Journal on Computing, Vol. 4, No. 1,Winter 1992, pp. 1-15.
10. Luenbuerger, David G., Linear and Nonlinear Programming, Second Edition,
Addison-Wesley, Reading Massachusetts, 1984.
11. Windward Technologies, GRG2 Userss Guide, http://web.wt.net/~wti, 1997.
CONTOUR IDL Reference Guide
CONTOUR
TheCONTOURproceduredrawsacontour plot fromdatastored in arectangular array
or from a set of unstructured points. Both line contours and lled contour plots can be
created. Note that outline and ll contours cannot be drawn at the same time. To create
a contour plot with both lled contours and outlines, rst create the lled contour plot,
then addtheoutlinecontoursbycallingCONTOURasecondtimewith theOVERPLOT
keyword.
Contours can be smoothed by using the MIN_CURVE_SURF function on the contour
data before contouring.
Usingvariouskeywords, describedbelow, it ispossibletospecifycontour levels, labeling,
colors, line styles, and other options. CONTOUR draws contours by searching for each
contour line and then following the line until it reaches a boundary or closes.
Smoothing Contours
The MIN_CURVE_SURF function can be used to smoothly interpolate both regularly
and irregularly sampled surfaces before contouring. This function replaces the older
SPLINE keyword to CONTOUR, which was inaccurate and is no longer supported.
MIN_CURVE_SURF interpolates the entire surface to a relatively ne grid before
drawing the contours.
Calling Sequence
CONTOUR, Z [, X, Y]
Arguments
Z
Aone- or two-dimensional arraycontainingthevaluesthat makeupthecontour surface.
If argumentsX and Y are provided, the contour is plotted as a function of the (X, Y)
locationsspeciedbytheir contents. Otherwise, thecontour isgeneratedasafunction of
the two-dimensional array index of each element of Z.
If the IRREGULAR keyword is set, X, Y, and Z are treated as vectors. Each point has a
value of Z
i
and a location of (X
i
, Y
i
)
This argument is converted to single-precision oating-point before plotting. Plots
created with CONTOUR are limited to the range and precision of single-precision
oating-point values.
X
A vector or two-dimensional array specifying the X coordinates for the contour surface.
If Xisavector, each element of XspeciestheXcoordinatefor acolumn of Z(e.g., X[ 0]
IDL Reference Guide CONTOUR
speciestheXcoordinatefor Z[ 0,*] ). If Xisatwo-dimensional array, each element of X
species the X coordinate of the corresponding point in Z (i.e., X
ij
species the X
coordinate for Z
ij
).
Y
A vector or two-dimensional array specifying the Y coordinates for the contour surface.
If Yavector, eachelement of YspeciestheYcoordinatefor arowof Z(e.g., Y[ 0] species
the Y coordinate for Z[ *,0] ). If Y is a two-dimensional array, each element of Y species
the Y coordinate of the corresponding point in Z (Y
ij
species the Y coordinate for Z
ij
).
Keywords
C_ANNOTATION
The label to be drawn on each contour. Usually, contours are labeled with their value.
This parameter, a vector of strings, allows any text to be specied. The rst label is used
for therst contour drawn, andsoforth. If theLEVELSkeywordisspecied, theelements
of C_ANNOTATION correspond directly to the levels specied, otherwise, they
correspond to the default levels chosen by the CONTOUR procedure. If there are more
contour levelsthan elementsin C_ANNOTATION, theremaininglevelsarelabeled with
their values.
Use of this keyword implies use of the FOLLOW keyword.
Example
To produce a contour plot with three levels labeled low, medium, and high :
CONTOUR, Z, LEVELS = [0.0, 0.5, 1.0], $
C_ANNOTATION = ['low', 'medium', 'high']
C_CHARSIZE
The size of the characters used to annotate contour labels. Normally, contour labels are
drawn at 3/4 of the size used for the axis labels (specied by the CHARSIZE keyword or
!P.CHARSIZEsystemvariable. Thiskeyword allowsthecontour label sizeto bespecied
directly. Use of this keyword implies use of the FOLLOW keyword.
C_CHARTHICK
Thethicknessof thecharactersusedtoannotatecontour labels. Set thiskeywordequal to
an integer value specifying the line thickness of the vector drawn font characters. This
keyword has no effect when used with the hardware drawn fonts. The default value is 1.
C_COLORS
The color index used to draw each contour. This parameter is a vector, converted to
integer type if necessary. If there are more contour levels than elements in C_COLORS,
the elements of the color vector are cyclically repeated.
Example If C_COLORS contains three elements, and there are seven contour levels to be
drawn, the colorsc
0
, c
1
, c
2
, c
0
, c
1
, c
2
, c
0
will be used for the seven levels. To call
CONTOUR and set the colors to [ 100,150,200] , use the command:
CONTOUR, Z, C_COLORS = [100,150,200]
C_LABELS
Species which contour levels should be labeled. By default, every other contour level is
labeled. C_LABELSallowsyou to overridethisdefault and explicitly specify thelevelsto
label. This parameter is a vector, converted to integer type if necessary. If the LEVELS
keyword is specied, the elements of C_LABELS correspond directly to the levels
specied, otherwise, they correspond to the default levels chosen by the CONTOUR
procedure. Setting an element of the vector to zero causes that contour label to not be
labeled. A nonzero value forces labeling.
Example To produce a contour plot with four levels where all but the third level is labeled:
CONTOUR, Z, LEVELS = [0.0, 0.25, 0.75, 1.0], $
C_LABELS = [1, 1, 0, 1]
C_LINESTYLE
Thelinestyleusedtodraweach contour. Aswith C_COLORS, C_LINESTYLEisavector
of line style indices. If there are more contour levels than line styles, the line styles are
cyclically repeated. See Table 7-1 on page 103 for a list of available styles.
Note Thecell drawingcontouringalgorithmdrawsall thecontoursineachcell, rather than
following contours. Since an entire contour is not drawn as a single operation, the
appearanceof themorecomplicated linestyleswill suffer. Useof thecontour follow-
ingmethod (selected with theFOLLOWkeyword) will givebetter lookingresultsin
such cases.
Example To produce a contour plot, with the contour levels directly specied in a vector V,
with all negative contours drawn with dotted lines, and with positive levels in solid
lines:
CONTOUR, Z, LEVELS = V, C_LINESTYLE = (V LT 0.0)
C_ORIENTATION
If the FILL keyword is set, this keyword can be set to the angle, in degrees
counterclockwise from the horizontal, of the lines used to ll contours. If neither
C_ORIENTATION or C_SPACING are specied, the contours are solid lled.
C_SPACING
If the FILL keyword is set, this keyword can be used to control the distance, in
centimeters, between the lines used to ll the contours.
C_THICK
The line used to draw each contour level. As with C_COLORS, C_THICK is a vector of
line thickness values, although the values are oating point. If there are more contours
than thickness elements, elements are repeated. If omitted, the overall line thickness
specied by the THICK keyword parameter or !P.THICK is used for all contours.
CELL_FILL
Set thiskeyword to producealled contour plot usingacell lling algorithm. Usethis
keywordinsteadof FILLwhenyouaredrawinglledcontoursover amap, whenyouhave
missingdata, or when contoursthat extendoff theedgesof thecontour plot. CELL_FILL
islessefcient than FILLbecauseit makesoneor morepolygonsfor each datacell. It also
gives poor results when used with patterned (line) lls, because each cell is assigned its
ownpattern. Otherwise, thiskeywordoperatesidenticallytotheFILLkeyword, described
below.
Caution In order for CONTOUR to ll the contours properly when using a map projection,
the X and Y arrays (if supplied) must be arranged in increasing order. This ensures
that the polygons generated will be in counterclockwise order, as required by the
mapping graphics pipeline.
Caution Do not draw lled contours over the poles on Cylindrical map projections. In this
case, the polar points map to lines on the map, and the interpolation becomes
ambiguous, causing errors in lling. One possible work-around is to limit the
latitudes to the range of -89.9 degrees to + 89.9 degrees, avoiding the poles.
CLOSED
Set thiskeyword toclosecontoursthat intersect theplot boundaries. After acontour hits
a boundary, it is follows the plot boundary until it connects with its other boundary
intersection.
DOWNHILL
Set thiskeyword tolabel each contour with short, perpendicular tick marksthat point in
the downhill direction, making the direction of the grade readily apparent. If this
keyword is set, the contour following method is used in drawing the contours.
FILL
Set this keyword to produce a lled contour plot. The contours are lled with solid or
line-lled polygons. For solid polygons, usetheC_COLORkeyword to specify thecolor
index of the polygons for each contour level. For line lls, use C_ORIENTATION,
C_SPACING, C_COLOR, C_LINESTYLE, and/or C_THICKtospecifyattributesfor the
lines.
If thecurrent deviceisnot apen plotter, each polygon iserased to thebackground color
before the ll lines are drawn, to avoid superimposing one pattern over another.
Contours that are not closed can not be lled because their interior and exterior are
undened. Contours created from data sets with missing data may not be closed; many
mapprojectionscanalsoproducecontoursthat arenot closed. Filledcontoursshouldnot
be used in these cases.
Note If the current graphics device is the Z-buffer, the algorithm used when the FILL
keyword isspecied will not work when aZ valueisalso specied with thegraphics
keywordZVALUE. In thissituation, usetheCELL_FILLkeywordinsteadof theFILL
keyword.
FOLLOW
InIDL version5, CONTOURalwaysusesaline-followingmethod. TheFOLLOWkeyword
remains availablefor compatibility with existing code, but is no longer necessary. As in
previous versions of IDL, setting FOLLOW will causeCONTOUR to draw contour labels.
IRREGULAR
Set this keyword to indicate that the input data is irregularly gridded. Setting
IRREGULAR is the same as performing an explicit triangulation. That is:
CONTOUR, Z, X, Y, /IRREGULAR
is the same as
TRIANGULATE, X, Y, tri ;Get triangulation.
CONTOUR, Z, X, Y, TRIANGULATION=tri
ISOTROPIC
Set this keyword to force the scaling of the X and Y axes to be equal.
Note TheXandYaxeswill bescaledisotropicallyandthen t within therectangledened
by thePOSITION keyword; oneof theaxesmay beshortened. See POSITION on
page 104 for more information.
LEVELS
Species a vector containing the contour levels drawn by the CONTOUR procedure. A
contour is drawn at each level in LEVELS.
Example
To draw a contour plot with levels at 1, 100, 1000, and 10000:
CONTOUR, Z, LEVELS = [1, 100, 1000, 10000]
To draw a contour plot with levels at 50, 60, ..., 90, 100:
CONTOUR, Z, LEVELS = FINDGEN(6) * 10 + 50
MAX_VALUE
Data points with values above this value are ignored (i.e., treated as missing data) when
contouring. Cells containing one or more corners with values above MAX_VALUE will
have no contours drawn through them. Note that the IEEE oating-point value NaN is
alsotreatedasmissingdata. (SeeSpecial Floating-Point Values on page152of Building
IDL Applications for more information on IEEE oating-point values.)
MIN_VALUE
Datapointswithvalueslessthanthisvalueareignored(i.e., treatedasmissingdata) when
contouring. Cells containing one or more corners with values below MIN_VALUE will
have no contours drawn through them. Note that the IEEE oating-point value NaN is
alsotreatedasmissingdata. (SeeSpecial Floating-Point Values on page152of Building
IDL Applications for more information on IEEE oating-point values.)
NLEVELS
The number of equally spaced contour levels that are produced by CONTOUR. If the
LEVELS parameter, which explicitly species the value of the contour levels, is present
this keyword has no effect. If neither parameter is present, approximately six levels are
drawn. NLEVELS should be an integer between 1 and 29.
OVERPLOT
Set this keyword to make CONTOUR overplot. That is, the current graphics screen is
not erased, noaxesaredrawnandthepreviouslyestablishedscalingremainsineffect. You
must explicitly specify either thevaluesof thecontour levelsor thenumber of levels(via
theNLEVELSkeyword) when usingthisoption, unlessgeographicmappingcoordinates
are in effect.
PATH_DATA_COORDS
Set this keyword to cause the output contour positions to be measured in data units
rather than thedefault normalized units. Thiskeyword isuseful only if thePATH_XYor
PATH_FILENAME keywords are set.
PATH_FILENAME
Species the name of a le to contain the contour positions. If PATH_FILENAME is
present, CONTOURdoesnot drawthecontours, but rather, opensthespecied leand
writes the positions, in normalized coordinates, into it. The le consists of a series of
logical records containing binary data. Each record is preceded with a header structure
dening the contour as follows:
{CONTOUR_HEADER, TYPE:0B, HIGH:0B, LEVEL:0, NUM:0L, VALUE:0.0}
The elds are:
TYPE
A byte that is zero if the contour is open, and one if it is closed.
HIGH
A byte that is 1 if the contour is closed and above its surroundings, and is 0 if the
contour is below. This eld is meaningless if the contour is not closed.
LEVEL
A short integer with value greater or equal to zero (It is an index into the LEVELS
array).
NUM
The longword number of data points in the contour.
VALUE
The contour value. This is a single precision oating point value.
Followingtheheader in each record areNUM X-coordinatevaluesfollowed by NUM Y-
coordinate values, expressed in normalized coordinates.
PATH_XY is ignored if the TRIANGULATION keyword is set. Use of this keyword
implies use of the FOLLOW keyword.
PATH_INFO
Set thiskeyword to anamed variablethat will return path information for thecontours.
This information can be used, along with data stored in a variable named by the
PATH_XYkeyword, totraceclosedcontours. If PATH_INFOispresent, CONTOURdoes
not drawthecontours, but rather recordsthepath information in an array of structures
of the following type:
{CONTOUR_PATH_STRUCTURE, TYPE:0B, HIGH_LOW:0B, $
LEVEL:0, N:0L, OFFSET:0L, VALUE:0.0}
The elds are:
TYPE
A byte that is zero if the contour is open, and one if it is closed. In the present
implementation, all contours are closed.
HIGH_LOW
Abytethat is1if thecontour isaboveitssurroundings, andis0if thecontour isbelow.
LEVEL
Ashort integer indicatingtheindex of thecontour level, fromzerotothenumber of
levels minus one.
N
A long integer indicating the number of XY pairs in the contours path.
OFFSET
Alonginteger that istheoffset intothearray dened by PATH_XY, representingthe
rst XY coordinate for this contour.
VALUE
The contour value. This is a single precision oating point value.
PATH_INFO is ignored if the TRIANGULATION keyword is set.
See the examples section below for an example using the PATH_INFO and PATH_XY
keywords to return contour path information.
PATH_XY
Set this keyword to a named variable that returns the normalized coordinates of a set of
closed polygonsdeningtheclosed pathsof thecontours. Thisinformation can beused,
alongwith datastored in avariablenamed by thePATH_INFOkeyword, to traceclosed
contours. If PATH_XY is present, CONTOUR does not draw the contours, but rather
recordsthenormalized path coordinatesin thenamed array. PATH_XYisignored if the
TRIANGULATION keyword is set.
See the examples section below for an example using the PATH_INFO and PATH_XY
keywords to return contour path information.
TRIANGULATION
Set this keyword to a variable that contains an array of triangles returned from the
TRIANGULATE procedure. Providing triangulation data allows you to contour
irregularly gridded data directly, without gridding.
XLOG
Set this keyword to specify a logarithmic X axis.
YLOG
ZAXIS
Set this keyword to draw a Z axis for the CONTOUR plot. CONTOUR draws no Z axis
by default. This keyword is of use only if a three-dimensional transformation is
established.
not listed above. AM_PM BACKGROUND CHARSIZE CHARTHICK CLIP COLOR
DATA DAYS_OF_WEEK DEVICE FONT NOCLIP NODATA NOERASE NORMAL
POSITION SUBTITLE, T3D THICK TICKLEN TITLE [ XYZ] CHARSIZE
[ XYZ] GRIDSTYLE [ XYZ] MARGIN [ XYZ] MINOR MONTHS [ XYZ] RANGE
[ XYZ] STYLE[ XYZ] THICK [ XYZ] TICKFORMAT [ XYZ] TICKLEN [ XYZ] TICKNAME
[ XYZ] TICKS [ XYZ] TICKV [ XYZ] TICK_GET [ XYZ] TITLE ZVALUE.
Examples
To create a contour plot with 10 contour levels where every other contour is labeled:
Z = DIST(100) Createa simpledataset to plot.
CONTOUR, Z, NLEVELS=10, /FOLLOW, TITLE='Simple Contour Plot'
Draw theplot.
The following commands describe a more complicated example that shows the use of
polygon lling and smoothing.
First, create a surface to contour:
A = RANDOMU(seed, 5, 6) Createa 2D array of random
numbers.
Smooth thedataset beforecon-
touring.
Draw solid-lled contours:
TEK_COLOR Load discretecolors for contours.
CONTOUR, B, /FILL, NLEVELS=5, C_COLOR=INDGEN(5)+2
Draw filled contours.
CONTOUR, B, NLEVELS=5, /DOWNHILL, /OVERPLOT
Overplot thecontour lines with
tickmarks.
Draw line-lled contours:
CONTOUR, B, C_ORIENTATION=[0, 22, 45]
CONTOUR, B, /OVERPLOT, NLEVELS=5 Overplot thecontours.
The following program saves the closed path information of a set of contours and plots
the result:
PRO path
A = RANDOMU(seed, 8, 10) Createa 2D array of random
numbers.
B = MIN_CURVE_SURF(A) Smooth thedataset beforecon-
touring.
CONTOUR, B, PATH_XY=xy, PATH_INFO=info
Computecontour paths.
FOR I = 0, (N_ELEMENTS(info) - 1 ) DO BEGIN
S = [INDGEN(info(I).N), 0]
PLOTS, xy(*,INFO(I).OFFSET + S ), /NORM
Plot theclosed paths.
ENDFOR
END
To contour irregularly-gridded data without having to call TRIGRID, rst use the
TRIANGULATEprocedureto get theDelaunay triangulation of your data, then passthe
triangulation array to CONTOUR:
TRIANGULATE, X, Y, tri Get triangulation.
CONTOUR, Z, X, Y, TRIANGULATION = tri
Draw thecontours.
See Also
IMAGE_CONT, SHADE_SURF, SHOW3, SURFACE
IDL Reference Guide CONVERT_COORD
CONVERT_COORD
The CONVERT_COORD function transforms one or more sets of coordinates to and
fromthecoordinatesystemssupportedbyIDL. Theresult of thefunctionisa(3, n) vector
containing the (x, y, z) components of the n output coordinates.
The input coordinatesX and, optionally, Y and/or Z can be given in data, device, or
normalizedformbyusingtheDATA, DEVICE, or NORMALkeywords. Thedefault input
coordinatesystemisDATA. ThekeywordsTO_DATA, TO_DEVICE, and TO_NORMAL
specify the output coordinate system.
If the input points are in 3D data coordinates, be sure to set the T3D keyword.
Caution For devices that support windows, CONVERT_COORD can only provide valid
resultsif awindowisopen and current. Also, CONVERT_COORD only appliesfor
Direct Graphics devices.
Calling Sequence
Result = CONVERT_COORD(, X [, Y [, Z]])
Arguments
X
Avector or scalar argument providingtheXcomponentsof theinput coordinates. If only
one argument is specied, X must be an array of either two or three vectors (i.e., (2,*)
or (3,*)). In thisspecial case, X[0,*] aretaken astheXvalues, X[1,*] aretaken asthe
Y values, and, if present, X[2,*] are taken as the Z values.
Y
An optional argument providing the Y input coordinate(s).
Z
An optional argument providing the Z input coordinate(s).
Keywords
DATA
Set this keyword if the input coordinates are in data space (the default).
DEVICE
Set this keyword if the input coordinates are in device space.
NORMAL
Set this keyword if the input coordinates are in normalized space.
CONVERT_COORD IDL Reference Guide
T3D
Set this keyword if the 3D transformation !P.T is to be applied.
TO_DATA
Set this keyword if the output coordinates are to be in data space.
TO_DEVICE
Set this keyword if the output coordinates are to be in device space.
TO_NORMAL
Set this keyword if the output coordinates are to be in normalized space.
Example
Convert, using the currently established viewing transformation, 11 points along the
parametriclinex=t, y= 2t, z= t
2
, alongtheinterval [ 0, 1] fromdatacoordinatestodevice
coordinates:
X = FINDGEN(11)/10. Makea vector of X values.
D = CONVERT_COORD(X, 2*X, X^2, /T3D, /TO_DEVICE)
Convertthecoordinates.Dwill be
an (3,11) element array.
See Also
CV_COORD
IDL Reference Guide CONVOL
CONVOL
The CONVOL function convolves an array with a kernel, and returns the result.
Convolution isageneral processthat can beused for varioustypesof smoothing, signal
processing, shifting, differentiation, edgedetection, etc. TheCENTERkeyword controls
the alignment of the kernel with the array and the ordering of the kernel elements. If
CENTERisexplicitly set to 0, convolution isperformed in thestrict mathematical sense,
otherwise the kernel is centered over each data point.
AssumeR= CONVOL(A, K, S), whereAisan n-element vector, Kisan m-element vector
(m< n), and S is the scale factor. If the CENTER keyword is omitted or set to 1:
where the valuem/2 is determined by integer division. This means that the result of the
division is the largest integer value less than or equal to the fractional number.
If CENTER is explicitly set to 0:
In thetwo-dimensional, zeroCENTERcasewhereAisan mbyn-element array, and Kis
thel by l element kernel; the result R is an mby n-element array:
The centered case is similar, except thet-i and u-j subscripts are replaced by t+i-l/2 and
u+j-l/2.
Calling Sequence
Result = CONVOL(Array, Kernel [, Scale_Factor])
R
t
1
S
--- A
t i m 2 +
K
i
i 0 =
m 1
if m 2 t n m 2 <
0 otherwise
'
=
R
t
1
S
--- A
t i
K
i
i 0 =
m 1
if t m 1
0 otherwise
'
=
R
t u ,
1
S
--- A
t i u j ,
K
i j ,
j 0 =
l 1
i 0 =
l 1
if t l 1 and u l 1
0 otherwise
'
=
CONVOL IDL Reference Guide
Arguments
Array
An array of any basic type except string. The result of CONVOL has the same type and
dimensions asArray.
If theArray parameter is of byte type, the result is clipped to the range of 0 to 255.
Negative results are set to 0, and values greater than 255 are set to 255.
Kernel
An array of any typeexcept string. If thetypeof Kernel isnot thesameasArray, acopy of
Kernel is made and converted to the appropriate type before use. The size of the kernel
dimensions must be smaller than those of Array.
Scale_Factor
A scale factor, for use with integer and byte type data only, that is divided into each
resulting value. This argument allows the use of fractional kernel values and avoids
overow with byte arguments. If omitted, a scale factor of 1 is used.
Keywords
CENTER
Set or omit this keyword to center the kernel over each array point. If CENTER is
explicitly set to zero, the CONVOL function works in the conventional mathematical
sense. Inmanysignal andimageprocessingapplications, it isuseful tocenter asymmetric
kernel over the data, thereby aligning the result with the original array.
Note that for the kernel to be centered, it must be symmetric about the point
K(FLOOR(m/2), wheremis the number of elements in the kernel.
EDGE_WRAP
Set thiskeyword to makeCONVOL computethevaluesof elementsat theedgeof Array
by wrapping thesubscriptsof Arrayat theedge. For example, if CENTERisset tozero:
wheren is the number of elements in Array. The mod operator in the formula above is
dened asa mod b = a - b * floor(a/b). For example, -1 mod 5 is 4. If neither
EDGE_WRAPnor EDGE_TRUNCATEisset, CONVOLsetsthevaluesof elementsat the
edges of Array to zero.
EDGE_TRUNCATE
Set thiskeyword to makeCONVOL computethevaluesof elementsat theedgeof Array
by repeating the subscripts of Array at the edge. For example, if CENTER is set to zero:
R
t
1
S
--- A
t i ( )mod n ( ) ( )
K
i
i 0 =
m 1
[ ]
'
=
IDL Reference Guide CONVOL
wheren is the number of elements in Array. The < and > operators in the above
formula return the smaller and larger of their operands, respectively. If neither
EDGE_WRAPnor EDGE_TRUNCATEisset, CONVOLsetsthevaluesof elementsat the
edges of Array to zero.
Example
Convolveavector of randomnoiseand aone-dimensional triangular kernel and plot the
result. Create a simple vector as the original dataset and plot it by entering:
A = RANDOMN(SEED, 100) & PLOT, A
Create a simple kernel by entering:
K = [1, 2, 3, 2, 1]
Convolve the two and overplot the result by entering:
OPLOT, CONVOL(A, K, TOTAL(K))
See Also
BLK_CON
R
t
1
S
--- A
t i ( ) 0 n 1 ( ) < > ( )
K
i
i 0 =
m
'
=
COORD2TO3 IDL Reference Guide
COORD2TO3
The COORD2TO3 function returns a three-element vector containing 3D data
coordinates given the normalized X and Y screen coordinates and one of the three data
coordinates. Note: A valid 3D transform must exist in !P.T or be specied by the PTI
keyword. The axis scaling variables, !X.S, !Y.S and !Z.S must be valid.
coord2to3.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = COORD2TO3(Mx, My, Dim, D0 [, PTI])
Arguments
Mx, My
The normalized X and Y screen coordinates.
Dim
A parameter used to specify which data coordinate is xed. Use 0 for a xed X data
coordinate, 1 for a xed Y data coordinate, or 2 for a xed Z data coordinate.
D0
The value of the xed data coordinate.
PTI
Theinverseof !P.T. If thisparameter isnot supplied, or set to0, COORD2TO3computes
theinverse. If thisroutineisto beused in aloop, thecaller should supply PTI for highest
efciency.
Example
To return the data coordinates of the mouse, xing the data Z value at 10, enter the
commands:
CREATE_VIEW Makesurea transformation ma-
trix exists.
CURSOR, X, Y, /NORM Getthenormalizedmousecoords.
PRINT, COORD2TO3(X, Y, 2, 10.0) Print the3D coordinates.
See Also
CONVERT_COORD, CREATE_VIEW, CV_COORD, SCALE3, T3D
IDL Reference Guide CORRELATE
CORRELATE
The CORRELATE function computes the linear Pearson correlation coefcient of two
vectors or the correlation matrix of an mx n array. If vectors of unequal lengths are
specied, the longer vector is truncated to the length of the shorter vector and a single
correlationcoefcient isreturned. If anmxnarrayisspecied, theresult will beanmx m
array of linear Pearson correlation coefcients, with the element i,j corresponding to
correlation of theith and jth columns of the input array.
Alternatively, this function computes the covariance of two vectors or the covariance
matrix of an mx n array.
correlate.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CORRELATE(X [,Y])
Arguments
X
A vector or an mx n array. X can be integer, single-, or double-precision oating-point.
Y
An integer, single-, or double-precision oating-point vector. If X is an mx n array, Y
should not be supplied.
Keywords
COVARIANCE
Set this keyword to compute the sample covariance rather than the correlation
coefcient.
DOUBLE
Examples
Dene the data vectors.
X = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71]
Y = [68, 66, 68, 65, 69, 66, 68, 65, 71, 67, 68, 70]
CORRELATE IDL Reference Guide
Compute the linear Pearson correlation coefcient of x and y. The result should be
0.702652:
PRINT, CORRELATE(X, Y)
IDL prints:
0.702652
Compute the covariance of x and y. The result should be 3.66667.
PRINT, CORRELATE(X, Y, /COVARIANCE)
IDL prints:
3.66667
Dene an array with x and y as its columns.
A = TRANSPOSE([[X],[Y]])
Compute the correlation matrix.
PRINT, CORRELATE(A)
IDL prints:
1.00000 0.702652
0.702652 1.00000
See Also
A_CORRELATE, C_CORRELATE, M_CORRELATE, P_CORRELATE, R_CORRELATE
IDL Reference Guide COS
COS
The periodic function COS returns the trigonometric cosine of X.
Calling Sequence
Result = COS(X)
Arguments
X
The angle for which the cosine is desired, specied in radians. If X is double-precision
oatingor complex, theresult isof thesametype. All other typesareconverted tosingle-
precision oating-point and yield oating-point results. When applied to complex
numbers:
COS(x) = COMPLEX(cosI cosh R, -sin R sinh (-I))
whereR and I are the real and imaginary parts of x.
If Xisan array, theresult hasthesamestructure, witheachelement containingthecosine
of the corresponding element of X.
Example
Find the cosine of 0.5 radians and print the result by entering:
PRINT, COS(.5)
IDL prints:
0.877583
See Also
ACOS, COSH
COSH IDL Reference Guide
COSH
The COSH function returns the hyperbolic cosine of X.
Calling Sequence
Result = COSH(X)
Arguments
X
The value for which the hyperbolic cosine is desired, specied in radians. If X is double-
precision oating, the result is also double- precision. Complex values are not allowed.
All other types are converted to single-precision oating-point and yield oating-point
results. COSH is dened as:
COSH(u) = (e
u
+ e
-u
) / 2
If X is an array, the result has the same structure, with each element containing the
hyperbolic cosine of the corresponding element of X.
Example
Find the hyperbolic cosine of 0.5 radians and print the result by entering:
PRINT, COSH(.5)
IDL prints:
1.12763
See Also
ACOS, COS
IDL Reference Guide CRAMER
CRAMER
The CRAMER function solves an n by n linear system of equations using Cramers rule.
cramer.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CRAMER(A, B)
Arguments
A
An n by n single- or double-precision oating-point array.
B
An n-element single- or double-precision oating-point vector.
Keywords
DOUBLE
ZERO
Usethiskeyword to set thevalueof theoating-point zero. A oating-point zero on the
main diagonal of a triangular array results in a zero determinant. A zero determinant
results in a Singular matrix error and stops the execution of CRAMER. For single-
precision inputs, the default value is 1.0 10
-6
. For double-precision inputs, the default
value is 1.0 10
-12
.
Example
Dene an array A and right-hand side vector B.
A = [[ 2.0, 1.0, 1.0], $
[ 4.0, -6.0, 0.0], $
[-2.0, 7.0, 2.0]]
B = [3.0, 10.0, -5.0]
PRINT, CRAMER(A,B) Computethesolution and print.
IDL prints:
1.00000 -1.00000 2.00000
CRAMER IDL Reference Guide
See Also
GS_ITER, LU_COMPLEX, CHOLSOL, LUSOL, SVSOL, TRISOL
IDL Reference Guide CREATE_STRUCT
CREATE_STRUCT
TheCREATE_STRUCT function createsastructuregiven pairsof tagnamesand values.
CREATE_STRUCT can also be used to concatenate structures.
Calling Sequence
Result = CREATE_STRUCT(Tags, Values)
Arguments
Tags
The structure tag names. Tag names may be specied either as scalar strings or string
arrays. If scalar strings are specied, values alternate with tag names. If a string array is
provided, values must still be specied individually. Tag names must be enclosed in
quotes.
Values
The value of each eld of the structure must be provided.
Keywords
Name
Use this keyword to create a named structure using the specied string as the structure
name.
Examples
To create the anonymous structure { A: 1, B: 'xxx'} in the variableP, enter:
p = CREATE_STRUCT('A', 1, 'B', 'xxx')
To add the elds FIRST and LAST to the structure, enter the following:
p = CREATE_STRUCT('FIRST', 0, p, 'LAST', 3)
The resulting structure contains { FIRST: 0, A: 1, B: 'xxx', LAST: 3}.
Finally, the statement:
p = CREATE_STRUCT(name='list', ['A','B','C'], 1, 2, 3)
creates the structure { LIST, A: 1, B: 2, C: 3}.
CREATE_STRUCT IDL Reference Guide
See Also
N_TAGS, TAG_NAMES, Creatingand DeningStructures on page42of BuildingIDL
Applications.
IDL Reference Guide CREATE_VIEW
CREATE_VIEW
The CREATE_VIEW procedure sets the various system variables required to dene a
coordinatesystemanda3Dview. Thisprocedurebuildsthesystemviewingmatrix (!P.T)
in such a way that the correct aspect ratio of the data is maintained even if the display
window is not square. CREATE_VIEW also sets the Data to Normal coordinate
conversion factors (!X.S, !Y.S, and !Z.S) so that center of the unit cube will be located at
the center of the display window.
CREATE_VIEW sets the following IDL system variables:
!P.T, !P.T3D, !P.Position, !P.Clip, !P.Region !X.S, !X.Style, !X.Range, !X.Margin !Y.S,
!Y.Style, !Y.Range, !Y.Margin, !Z.S, !Z.Style, !Z.Range, !Z.Margin.
create_view.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
CREATE_VIEW
Arguments
This procedure has no required arguments.
Keywords
AX
A oating-point value specifying the orientation (X rotation) of the view. The default is
0.0.
AY
A oating-point value specifying the orientation (Y rotation) of the view. The default is
0.0.
AZ
A oating-point value specifying the orientation (Z rotation) of the view. The default is
0.0.
PERSP
A oating-point value specifying the perspective projection distance. A value of 0.0
indicates an isometric projection (NO perspective). The default is 0.0.
RADIANS
Set this keyword if AX, AY, and AZ are specied in radians. The default is degrees.
CREATE_VIEW IDL Reference Guide
WINX
Alonginteger specifyingtheXsize, in pixels, of thewindowthat theviewisbeingset up
for. The default is 640.
WINY
Alonginteger specifyingtheYsize, in pixels, of thewindowthat theviewisbeingset up
for. The default is 512.
XMAX
A scalar specifying the maximum data value on the X axis. The default is 1.0.
XMIN
A scalar specifying the minimum data value on the X axis. The default is 0.0.
YMAX
A scalar specifying the maximum data value on the Y axis. The default is 1.0.
YMIN
A scalar specifying the minimum data value on the Y axis. The default is 0.0.
ZFAC
Set this keyword to a oating-point value to expand or contract the view in the Z
dimension. The default is 1.0.
ZMAX
A scalar specifying the maximum data value on the Z axis. The default is 1.0.
ZMIN
A scalar specifying the minimum data value on the Z axis. The default is 0.0.
ZOOM
Aoating-point number or 3-element vector specifyingtheviewzoomfactor. If zoomis
a single value then the view will be zoomed equally in all 3 dimensions. If zoom is a 3-
element vector then theviewwill bescaled zoom[ 0] in X, zoom[ 1] in Y, and zoom[ 2] in
Z. The default is 1.0.
Example
Set up a view to display an iso-surface from volumetric data. First, create some data:
vol = FLTARR(40, 50, 30)
vol(3:36, 3:46, 3:26) = RANDOMU(S, 34, 44, 24)
FOR I = 0, 10 DO vol = SMOOTH(vol, 3)
Generate the iso-surface.
SHADE_VOLUME, vol, 0.2, polygon_list, vertex_list, /LOW
IDL Reference Guide CREATE_VIEW
Set up the view. Note that the subscripts into the Vol array range from 0 to 39 in X, 0 to
49in Y, and 0to29in Z. Assuch, the3-Dcoordinatesof theiso-surface(vertex_list) may
have the same range. Set XMIN, YMIN, and ZMIN to zero (the default), and set
XMAX=39, YMAX=49, and ZMAX=29.
WINDOW, XSIZE = 600, YSIZE = 400
CREATE_VIEW, XMAX = 39, YMAX = 49, ZMAX = 29, $
AX = (-60.0), AZ = (30.0), WINX = 600, WINY = 400, $
ZOOM = (0.7), PERSP = (1.0)
Display the iso-surface in the specied view.
img = POLYSHADE(polygon_list, vertex_list, /DATA, /T3D)
TVSCL, img
See Also
SCALE3, T3D
CROSSP IDL Reference Guide
CROSSP
TheCROSSPfunctionreturnsaoating-point vector that isthevector (or cross) product
of two 3-element vectors, V1 and V2.
Calling Sequence
Result = CROSSP(V1, V2)
Arguments
V1, V2
Three-element vectors.
See Also
Matrix Multiplication on page 31 of Building IDL Applications.
IDL Reference Guide CRVLENGTH
CRVLENGTH
TheCRVLENGTHfunctioncomputesthelengthof acurvewithatabular representation,
Y[ i] = F(X[ i] ).
CautionDatathat ishighly oscillatory requiresasufcient number of samplesfor an accurate
curve length computation.
crvlength.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CRVLENGTH(X, Y)
Arguments
X
An n-element single- or double-precision oating-point vector. X must contain at least
three elements, and values must be specied in ascending order. DuplicateX values will
result in a warning message.
Y
An n-element single- or double-precision oating-point vector.
Keyword
DOUBLE
Example
Dene a 21-element vector of X-values.
x = [-2.00, -1.50, -1.00, -0.50, 0.00, 0.50, 1.00, 1.50, 2.00, $
2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 5.50, 6.00, 6.50, $
7.00, 7.50, 8.00]
Dene a 21-element vector of Y-values.
y = [-2.99, -2.37, -1.64, -0.84, 0.00, 0.84, 1.64, 2.37, 2.99, $
3.48, 3.86, 4.14, 4.33, 4.49, 4.65, 4.85, 5.13, 5.51, $
6.02, 6.64, 7.37]
result = CRVLENGTH(x, y) Computethelength of thecurve.
Print, result Print result.
CRVLENGTH IDL Reference Guide
IDL prints:
14.8115
See Also
INT_TABULATED, PNT_LINE
IDL Reference Guide CT_LUMINANCE
CT_LUMINANCE
TheCT_LUMINANCEfunctioncalculatestheluminanceof colors. Thefunctionreturns
an array containing the luminance values of the specied colors. If theR, G, and B
parametersarenot specied, or if Risof integer, byteor longtype, theresult isalongword
array with thesamenumber of elementsastheinput arguments. Otherwise, theresult is
a oating-point array with the same number of elements as the input arguments.
ct_luminance.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CT_LUMINANCE([R, G, B])
Arguments
R
An array representing the red color table. If omitted, the color values from either the
COLORS common block, or the current color table are used.
G
An array representing the green color table. This parameter is optional.
B
An array representing the blue color table. This parameter is optional.
Keywords
BRIGHT
Set this keyword to a named variable in which the array index of the brightest color is
returned.
DARK
Set this keyword to a named variable in which the array index of the darkest color is
returned.
READ_TABLES
Set thiskeyword, anddont specifytheR,G, andBarguments, toreadcolorsdirectlyfrom
the current colortable (using TVLCT, /GET) instead of using the COLORS common
block.
See Also
GAMMA_CT, STRETCH
CTI_TEST IDL Reference Guide
CTI_TEST
The CTI_TEST function constructs a contingency table from an array of observed
frequenciesandteststhehypothesisthat therowsandcolumnsareindependent usingan
extension of the chi-square goodness-of-t test. The result is a two-element vector
containing the chi-square test statistic X2 and the one-tailed probability of obtaining a
value of X2 or greater.
cti_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CTI_TEST(Obfreq)
Arguments
Obfreq
An mx narraycontainingobservedfrequencies. Obfreqcan contain either integer, single-
, double-precision oating-point values.
Keywords
COEFF
Set thiskeywordtoanamedvariablethat will containtheCoefcient of Contingency. The
Coefcient of Contingency is a non-negative scalar, in the interval [ 0.0, 1.0] , which
measures the degree of dependence within a contingency table. The larger the value of
COEFF, the greater the degree of dependence.
CORRECTED
Set this keyword to use the Yates Correction for Continuity when computing the Chi-
squared test statistic, X2. TheYatescorrection alwaysdecreasesthemagnitudeof X2. In
general, this keyword should be set for small sample sizes.
CRAMV
Set this keyword to a named variable that will contain Cramers V. Cramers V is a non-
negativescalar, intheinterval [ 0.0, 1.0] , whichmeasuresthedegreeof dependencewithin
a contingency table.
DF
Set thiskeyword to anamed variablethat will contain thenumber of degreesof freedom
usedtocomputetheprobabilityof obtainingthevalueof theChi-squaredtest statisticor
greater. DF= (n- 1) * (m- 1) wheremand narethenumber of columnsand rowsof the
contingency table, respectively.
IDL Reference Guide CTI_TEST
EXFREQ
Set thiskeywordtoanamedvariablethat will contain an arrayof m-columnsandn-rows
containing expected frequencies. The elements of this array are often referred to as the
cells of theexpectedfrequencies. Theexpectedfrequencyof eachcell iscomputedasthe
product of rowand column marginal frequenciesdivided bytheoverall total of observed
frequencies.
RESIDUAL
Set thiskeywordtoanamedvariablethat will contain an arrayof m-columnsandn-rows
containing signed differences between corresponding cells of observed frequencies and
expected frequencies.
Example
Dene a 5-column and 4-row array of observed frequencies.
obfreq = [[748, 821, 786, 720, 672], $
[ 74, 60, 51, 66, 50], $
[ 31, 25, 22, 16, 15], $
[ 9, 10, 6, 5, 7]]
Test the hypothesis that the rows and columns of obfreq contain independent data at
the 0.05 signicance level.
result = CTI_TEST(obfreq, COEFF = coeff)
The result should be the two-element vector [ 14.3953, 0.276181] .
The computed value of 0.276181 indicates that there is no reason to reject the proposed
hypothesis at the 0.05 signicance level. The Coefcient of Contingency returned in the
parameter coeff (coeff = 0.0584860) also indicatesthelack of dependencebetween the
rows and columns of the observed frequencies. Setting the CORRECTED keyword
returnsthetwo-element vector [ 12.0032, 0.445420] and (coeff = 0.0534213) resultingin
the same conclusion of independence.
See Also
CORRELATE, M_CORRELATE, XSQ_TEST
CURSOR IDL Reference Guide
CURSOR
The CURSOR procedure is used to read the position of the interactive graphics cursor
from the current graphics device. Note that not all graphics devices have interactive
cursors. CURSOR enables the graphic cursor on the device and optionally waits for the
operator to position it. On devices that have a mouse, CURSOR normally waits until a
mouse button is pressed (or already down). If no mouse buttons are present, CURSOR
waits for a key on the keyboard to be pressed.
Thesystemvariable!MOUSEisset tothebutton status. Each mousebutton isassigned a
bit in !MOUSE, bit 0 is the left most button, bit 1 the next, etc. See !MOUSE on page
40 for details.
Using CURSOR with Draw Widgets
Note that the CURSOR procedure is only for use with IDL graphics windows. It should
not be used with draw widgets. To obtain the cursor position and button state
information from a draw widget, examine the X, Y, PRESS, and RELEASE elds in the
structures returned by the draw widget in response to cursor events.
Using CURSOR with the TEK Device
Note that for the CURSOR procedure to work properly with Tektronix terminals, you
may need to execute the command, DEVICE, GIN_CHARS=6.
Calling Sequence
CURSOR, X, Y [, Wait]
Arguments
X
A named variable to receive the cursors current column position.
Y
A named variable to receive the cursors current row position.
Wait
An integer that species the conditions under which CURSOR returns. This parameter
can be used interchangeably with the keyword parameters listed below that specify the
type of wait. The default value is 1. The table below describes each type of wait.
Note that not all modes of waiting work with all display devices.
IDL Reference Guide CURSOR
Keywords
CHANGE
Set thiskeyword to wait for pointer movement or button transition within thecurrently
selected window.
DATA
Set this keyword to return X and Y in data coordinates.
DOWN
Set this keyword to wait for a button down transition within the currently selected
window.
DEVICE
Set this keyword to return X and Y in device coordinates.
NORMAL
Set this keyword to return X and Y in normalized coordinates.
NOWAIT
Set thiskeyword to read thepointer position and button statusand return immediately.
If the pointer is not within the currently selected window, the device coordinates -1, -1
are returned.
UP
Set this keyword to wait for a button up transition within the current window.
WAIT
Set this keyword to wait for a button to be depressed within the currently selected
window. If a button is already pressed, return immediately.
Wait
Value
Corresponding
Keyword
Action
0 NOWAIT Return immediately.
1 WAIT Return if a button is down.
2 CHANGE Return if a button is pressed, released, or the
pointer is moved.
3 DOWN Return when a button down transition is
detected.
4 UP Return when a button up transition is
detected.
Table 9-3: Values for CURSOR Wait Parameter
CURSOR IDL Reference Guide
Example
Activate the graphics cursor, select a point in the graphics window, and return the
position of the cursor in device coordinates. Enter:
CURSOR, X, Y, /DEVICE
Movethecursor over thegraphicswindowand pressthemousebutton. Theposition of
the cursor in device coordinates is stored in the variables X and Y. To label the location,
enter:
XYOUTS, X, Y, 'X marks the spot.', /DEVICE
See Also
RDPIX, TVCRS, CURSOR_CROSSHAIR (and other CURSOR_ keywords),
WIDGET_DRAW, !MOUSE on page 40
IDL Reference Guide CURVEFIT
CURVEFIT
The CURVEFIT function uses a gradient-expansion algorithm to compute a non-linear
least squarest toauser-supplied function with an arbitrarynumber of parameters. The
user-supplied function may beany non-linear function wherethepartial derivativesare
known or can beapproximated. Iterationsareperformed until thechi squarechangesby
aspecied amount, or until amaximumnumber of iterationshavebeen performed. The
CURVEVIT function returns a vector of values for the dependent variables, as tted by
the function t.
curvefit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CURVEFIT(X, Y, Weights, A [, Sigma])
Arguments
X
An n-element vector of independent variables.
Y
A vector of dependent variables, the same length asX.
Weights
For instrumental (Gaussian) weighting, set Weights
i
= 1.0/standard_deviation(Y
i
)
2
. For
statistical (Poisson) weighting, Weights
i
= 1.0/Y
i
. For no weighting, set Weights
i
= 1.0.
A
A vector with as many elements as the number of terms in the user-supplied function,
containing the initial estimate for each parameter. On return, the vector A contains the
tted model parameters. If A is double-precision, calculations are performed in double-
precision arithmetic, otherwise they are performed in single-precision arithmetic.
Sigma
Anamedvariablethat will contain avector of standarddeviationsfor theelementsof the
output vector A.
Keywords
CHISQ
Set this keyword equal to a named variable that will contain the value of chi-squared.
CURVEFIT IDL Reference Guide
FUNCTION_NAME
Use this keyword to specify the name of the function to t. If this keyword is omitted,
CURVEFIT assumesthat theIDL procedureFUNCT isto beused. If FUNCT isnot already
compiled, IDL compiles the function from the lefunct.pro, located in thelib
subdirectory of the IDL distribution. FUNCT evaluates the sum of a Gaussian and a
second-order polynomial.
Thefunction tobet must bewritten asan IDL procedureand compiled prior tocalling
CURVEFIT. The procedure must accept values of X (the independent variable), and A
(thetted functionsinitial parameter values). It must return valuesfor F(thefunctions
value at X), and optionally PDER (a 2D array of partial derivatives).
ITER
Set this keyword equal to a named variable that will contain the actual number of
iterations performed.
ITMAX
Set this keyword to specify the maximum number of iterations. The default value is 20.
NODERIVATIVE
If thiskeyword isset, theroutinespecied by theFUNCTION_NAMEkeyword will not
be requested to provide partial derivatives. The partial derivatives will be estimated by
CURVEFIT using forward differences. If analytical derivatives are available they should
always be used.
TOL
Usethiskeyword tospecify thedesired convergencetolerance. Theroutinereturnswhen
therelativedecreasein chi-squared islessthan TOL in oneiteration. Thedefault valueis
1.0 10
-3
.
Example
Fit a function of the formF(x) = a * exp(b*x) + c to sample pairs contained in
arraysX and Y. The partial derivatives are easily computed symbolically:
df/da = exp(b*x)
df/db = a * x * exp(b*x)
df/dc = 1.0
First, deneaprocedureto return F(x) and thepartial derivatives, given X. Notethat A
is an array containing the valuesa, b, and c.
PRO gfunct, X, A, F, pder
bx = EXP(A[1] * X)
F = A[0] * bx + A[2]
IDL Reference Guide CURVEFIT
IF N_PARAMS() GE 4 THEN $ Iftheprocedureiscalledwithfour
parameters, calculatethepartial
derivatives.
pder= [[bx], [A[0] * X * bx], [replicate(1.0, N_ELEMENTS(X))]][
END
Compute the t to the function we have just dened. First, dene the independent and
dependent variables:
X = FLOAT(INDGEN(10))
Y = [12.0, 11.0, 10.2, 9.4, 8.7, 8.1, 7.5, 6.9, 6.5, 6.1]
weights = 1.0/Y Definea vector of weights.
A = [10.0,-0.1,2.0] Providean initial guess of the
functions parameters.
yfit = CURVEFIT(X, Y, weights, A, SIGMA, FUNCTION_NAME='gfunct')
Computetheparameters.
PRINT, 'Function parameters: ', A Print theparameters returned in
A.
IDL prints:
Function parameters: 9.91120 -0.100883 2.07773
Thus, the function that best ts the data is:
f (x) = 9.91120(e
-0.100883x
) + 2.07773
See Also
COMFIT, GAUSS2DFIT, GAUSSFIT, LMFIT, POLY_FIT, POLYFITW, REGRESS, SFIT,
SVDFIT
CV_COORD IDL Reference Guide
CV_COORD
The CV_COORD function converts 2D and 3D coordinates between the rectangular,
polar, cylindrical, and spherical coordinate systems.
If thevaluepassedtothe FROM_ keywordisdoubleprecision, then all calculationsare
performed in double precision and the returned value is double precision. Otherwise,
singleprecision isused. If noneof the FROM_ keywordsarespecied, 0isreturned. If
none of the TO_ keywords are specied, the input coordinates are returned.
cv_coord.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CV_COORD()
Arguments
This function has no required arguments. All data is passed in via keywords.
Keywords
DEGREES
If set, then the input and output coordinates are in degrees (where applicable).
Otherwise, the angles are in radians.
FROM_CYLIN
A vector of the form [ angle, radius, z] , or a (3, n) array of cylindrical coordinates to
convert.
FROM_POLAR
A vector of the form [ angle, radius] , or a (2, n) array of polar coordinates to convert.
FROM_RECT
A vector of the form [ x, y] or [ x, y, z] , or a (2, n) or (3, n) array containing rectangular
coordinates to convert.
FROM_SPHERE
Avector of theform[ longitude, latitude, radius] , or a(3, n) arrayof spherical coordinates
to convert.
TO_CYLIN
If set, cylindrical coordinates are returned in a vector of the form [ angle, radius, z] , or a
(3, n) array.
IDL Reference Guide CV_COORD
TO_POLAR
If set, polar coordinates are returned in a vector of the form [ angle, radius] , or a (2, n)
array.
TO_RECT
If set, rectangular coordinates are returned in a vector of the form [ x, y] or [ x, y, z] , or a
(2, n) or (3, n) array.
TO_SPHERE
If set, spherical coordinates are returned in a vector of the form [longitude, latitude,
radius] , or a (3, n) array.
Examples
Convert from spherical to cylindrical coordinates:
sph_coord = [[45.0, -60.0, 10.0], [0.0, 0.0, 0.0]]
rect_coord = CV_COORD(FROM_SPHERE=sph_coord, /TO_CYLIN, /DEGREES)
Convert from rectangular to polar coordinates:
rect_coord = [10.0, 10.0]
polar_coord = CV_COORD(FROM_RECT=rect_coord, /TO_POLAR)
See Also
CONVERT_COORD, COORD2TO3, CREATE_VIEW, SCALE3, T3D
CVTTOBM IDL Reference Guide
CVTTOBM
The CVTTOBM function converts a byte array in which each byte represents one pixel
into a bitmap byte array in which each bit represents one pixel. This is useful when
creating bitmap labels for buttons created with the WIDGET_BUTTON function.
Bitmap byte arrays are monochrome; by default, CVTTOBM converts pixels that are
darker than themedian valuetoblack andpixelsthat arelighter than themedian valueto
white. You can supply a different threshold value via the THRESHOLD keyword.
Most of IDLs image le format reading functions (READ_BMP, READ_PICT, etc.)
return abytearray which must beconverted beforeuseasabutton label. Notethat there
is one exception to this rule; the READ_X11_BITMAP routine returns a bitmap byte
array that needs no conversion before use.
cvttobm.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CVTTOBM(Array)
Arguments
Array
A 2-dimensional pixel array, one byte per pixel.
Keywords
THRESHOLD
Abytevalue(or an integer valuebetween 0and255) tobeusedasathresholdvaluewhen
determining if a particular pixel is black or white. If THRESHOLD is not specied, the
threshold is calculated to be the average of the input array.
Example
The following example creates a bitmap button label from a byte array:
image = BYTSCL(DIST(100)) Createa bytearray.
base = WIDGET_BASE(/COLUMN) Createa widget base.
button = WIDGET_BUTTON(base, VALUE = CVTTOBM(image))
UseCVTTOBM to createa bit-
map bytearray for a button label.
WIDGET_CONTROL, base, /REALIZE ;Realizethewidget.
IDL Reference Guide CW_ANIMATE
CW_ANIMATE
The CW_ANIMATE function creates a compound widget that displays an animated
sequenceof imagesusingoff-screen windowsknowsaspixmaps. Thespeedanddirection
of the display can be adjusted using the widget interface.
CW_ANIMATE provides the graphical interface used by the XINTERANIMATE
procedure, which is the preferred routine for displaying animation sequences in most
situations. Usethiswidget instead of XINTERANIMATEwhen you need torun multiple
instancesof theanimation widget simultaneously. Notethat if morethan oneanimation
widget is running, they will have to share resources and will display images more slowly
than a single instance of the widget.
The returned value of this function is the widget ID of the newly-created animation
widget.
cw_animate.pro in thelib subdirectory of the IDL distribution.
Using CW_ANIMATE
Unlike XINTERANIMATE, using the CW_ANIMATE widget requires calls to two
separate procedures, CW_ANIMATE_LOAD and CW_ANIMATE_RUN, to load the
images to be animated and to run the animation. Alternatively, you can supply a vector
of pre-existingpixmapwindowIDs, eliminatingtheneedtouseCW_ANIMATE_LOAD.
The vector of pixmaps is commonly obtained from a call to CW_ANIMATE_GETP
applied to a previous animation widget. Once the images are loaded, they are displayed
by copying the images from the pixmap or buffer to the visible draw widget.
See the documentation for CW_ANIMATE_LOAD, CW_ANIMATE_RUN, and
CW_ANIMATE_GETP for more information.
The only event returned by CW_ANIMATE indicates that the user has clicked on the
End Animation button. The parent application should use this as a signal to kill the
animation widget viaWIDGET_CONTROL. When thewidget isdestroyed, thepixmaps
used in the animation are destroyed as well, unless they were saved by a call to
CW_ANIMATE_GETP.
See the animation widgets help le (available by clicking the Help button on the
widget) for more information about the widgets controls.
Calling Sequence
Result = CW_ANIMATE(Parent, Sizex, Sizey, Nframes)
CW_ANIMATE IDL Reference Guide
Arguments
Parent
The widget ID of the parent widget.
Sizex
The width of the displayed image, in pixels.
Sizey
The height of the displayed image, in pixels
Nframes
The number of frames in the animation sequence.
Keywords
NO_KILL
Set this keyword to omit the End Animation button from the animation widget.
OPEN_FUNC
Set this keyword equal to a scalar string specifying the name of a user-written function
that loads animation data. If a function is specied, an Open ... button is added to the
animation widget.
For anexampleshowingtheformat anduseof ananimation-loadingfunction, seethele
animate.pro in thegeneral subdirectory of theexamples subdirectory of the IDL
distribution.
PIXMAPS
Use this keyword to provide the animation widget with a vector of pre-existing pixmap
(off screen window) IDs. This vector is usually obtained from a call to
CW_ANIMATE_GETP applied to a previous animation widget.
TRACK
Set this keyword to cause the frame slider to track the frame number of the currently-
displayed frame.
UVALUE
The user value to be assigned to the widget.
Keywords to WIDGET_CONTROL and WIDGET_INFO
Thewidget ID returned by most compound widgetsisactually theID of thecompound
widgetsbasewidget. Thismeansthat many keywordsto theWIDGET_CONTROL and
WIDGET_INFO routines that affect or return information on base widgets can be used
with compound widgets.
IDL Reference Guide CW_ANIMATE
SeeCompoundWidgets onpage314of BuildingIDLApplicationsfor amorecomplete
discussion of controlling compound widgets using WIDGET_CONTROL and
WIDGET_INFO.
Widget Events Returned by the CW_ANIMATE Widget
The only event returned by this widget indicates that the user has pressed the DONE
button. Theparent application shouldusethisasasignal tokill theanimation widget via
WIDGET_CONTROL.
Example
Assume the following event handler procedure exists:
PRO EHANDLER, EV
WIDGET_CONTROL, /DESTROY, EV.TOP
end
(If you wish to create this event handler starting from the IDL command prompt,
remember to begin with the.RUN command.)
Enter the following commands to open the leABNORM.DAT (a series of images of a
human heart) and load the images it contains into an array H.
OPENR, 1, FILEPATH('abnorm.dat', SUBDIR = ['examples','data'])
H = BYTARR(64, 64, 16)
READU, 1, H
CLOSE, 1
H = REBIN(H, 128, 128, 16)
Create an instance of the animation widget and load the frames. Note that because the
animation widget is realized before the call to CW_ANIMATE_LOAD, the frames are
displayed asthey areloaded. Thisprovidestheuser with an indication of howthingsare
progressing.
base = WIDGET_BASE(TITLE = 'Animation Widget')
animate = CW_ANIMATE(base, 128, 128, 16)
WIDGET_CONTROL, /REALIZE, base
FOR I=0,15 DO CW_ANIMATE_LOAD, animate, FRAME=I, IMAGE=H[*,*,I]
Save the pixmap window IDs for future use:
CW_ANIMATE_GETP, animate, pixmap_vect
Start the animation:
CW_ANIMATE_RUN, animate
CW_ANIMATE IDL Reference Guide
XMANAGER, 'CW_ANIMATE Demo', base, EVENT_HANDLER = 'EHANDLER'
Pressing the End Animation button kills the application.
See Also
CW_ANIMATE_LOAD, CW_ANIMATE_RUN, CW_ANIMATE_GETP,
XINTERANIMATE
Figure 9-1: The animation interface created by
CW_ANIMATE.
IDL Reference Guide CW_ANIMATE_GETP
CW_ANIMATE_GETP
The CW_ANIMATE_GETP procedure gets a copy of the vector of pixmap window IDs
being used by a CW_ANIMATE animation widget. If this routine is called,
CW_ANIMATEdoesnot destroythepixmapswhen it isdestroyed. You can then provide
the pixmaps to a later instance of CW_ANIMATE to re-use them, skipping the pixmap
creation and rendering step (CW_ANIMATE_LOAD).
Calling Sequence
CW_ANIMATE_GETP, Widget, Pixmaps
Arguments
Widget
Thewidget ID of theanimation widget (created with CW_ANIMATE) that containsthe
pixmaps.
Pixmaps
A named variable that will contain a vector of the window IDs of the pixmap windows.
Keywords
KILL_ANYWAY
Set thiskeyword to ensurethat thepixmapsaredestroyed anyway when CW_ANIMATE
exits, despite the fact that CW_ANIMATE_GETP has been called.
Example
See the documentation for CW_ANIMATE for an example using this procedure.
See Also
CW_ANIMATE, CW_ANIMATE_LOAD, CW_ANIMATE_RUN, XINTERANIMATE
CW_ANIMATE_LOAD IDL Reference Guide
CW_ANIMATE_LOAD
TheCW_ANIMATE_LOADprocedurecreatesanarrayof pixmapswhichareloadedinto
a CW_ANIMATE compound widget.
Calling Sequence
CW_ANIMATE_LOAD, Widget
Arguments
Widget
The widget ID of the animation widget (created with CW_ANIMATE) into which the
image should be loaded.
Keywords
CYCLE
Set this keyword to cause the animation to cycle. Normally, frames are displayed going
either forwardor backward. If CYCLEisset, theanimationreversesdirectionafter thelast
frame in either direction is displayed.
FRAME
The frame number to be loaded. This is a value between 0 and NFRAMES. If not
supplied, frame 0 is loaded.
IMAGE
The image to be loaded.
ORDER
Set this keyword to display images from the top down instead of the default bottom up.
This keyword is only used when loading images with the IMAGE keyword.
IDL Reference Guide CW_ANIMATE_LOAD
WINDOW
When this keyword is specied, an image is copied from an existing window to the
animation pixmap. Under some windowing systems, this technique is much faster than
reading from the display and then loading with the IMAGE keyword.
The value of this parameter is either an IDL window number (in which case the entire
windowiscopied), or avector containingthewindowindex and therectangular bounds
of the area to be copied. For example:
WINDOW = [Window_Number, X0, Y0, Sx, Sy]
XOFFSET
Thehorizontal offset, in pixelsfromtheleft of theframe, of theimagein thedestination
window.
YOFFSET
Thevertical offset, in pixelsfromthebottomof theframe, of theimagein thedestination
window.
Example
See the documentation for CW_ANIMATE for an example using this procedure. Note
that if the widget is realized before calls to CW_ANIMATE_LOAD, the frames are
displayed asthey areloaded. Thisprovidestheuser with an indication of howthingsare
progressing.
See Also
CW_ANIMATE, CW_ANIMATE_GETP, CW_ANIMATE_RUN, XINTERANIMATE
CW_ANIMATE_RUN IDL Reference Guide
CW_ANIMATE_RUN
The CW_ANIMATE_RUN procedure displays a series of images that have been loaded
into a CW_ANIMATE compound widget by a call to CW_ANIMATE_LOAD.
Calling Sequence
CW_ANIMATE_RUN, Widget [, Rate]
Arguments
Widget
The widget ID of the animation widget (created with CW_ANIMATE) that will display
the animation.
Rate
A valuebetween 0and 100that representsthespeed of theanimation asapercentageof
themaximumdisplayrate. Thefastest animation hasavalueof 100and theslowest hasa
value of 0. The default animation rate is 100.
The animation rate can also be adjusted after the animation has begun by changing the
value of the Animation Speed slider.
Keywords
NFRAMES
Set this keyword equal to the number of frames to animate. This number must be less
than or equal to theNframesargument to CW_ANIMATE.
STOP
If this keyword is set, the animation is stopped.
Example
See the documentation for CW_ANIMATE for an example using this procedure.
IDL Reference Guide CW_ANIMATE_RUN
See Also
CW_ANIMATE, CW_ANIMATE_GETP, CW_ANIMATE_LOAD, XINTERANIMATE
CW_ARCBALL IDL Reference Guide
CW_ARCBALL
TheCW_ARCBALL function createsacompoundwidget for intuitivelyspecifyingthree-
dimensional orientations.
The user drags a simulated track-ball with the mouse to interactively obtain arbitrary
rotations. Sequencesof rotationsmay becascaded. Therotationsmay beunconstrained
(about any axis), constrained to theviewX, Y, or Z axes, or constrained to theobjectsX,
Y, or Z axis.
This widget is based on ARCBALL: A User Interface for Specifying Three-Dimensional
Orientation Using a Mouse, by Ken Shoemake, Computer Graphics Laboratory,
University of Pennsylvania, Philadelphia, PA 19104.
Thiswidget cangenerateanyrotationabout anyaxis. Note, however, that not all rotations
are compatible with the IDL SURFACE procedure, which is restricted to rotations that
project the object Z axis parallel to the view Y axis.
The returned value of this function is the widget ID of the newly-created ARCBALL
widget.
cw_arcball.pro in thelib subdirectory of the IDL distribution.
Using CW_ARCBALL
Use the command:
WIDGET_CONTROL, id, GET_VALUE = matrix
to return the current 3x3 rotation matrix in the variablematrix.
You can set the arcball to new rotation matrix using the command:
WIDGET_CONTROL, id, SET_VALUE = matrix
after the widget is initially realized.
Calling Sequence
Result = CW_ARCBALL(Parent)
Arguments
Parent
IDL Reference Guide CW_ARCBALL
Keywords
COLORS
A 6-element array containing the color indices to be used.
Colors[ 0] = view axis color,
Colors[ 1] = object axis color,
Colors[ 2] = XZ plane +Y side (body top) color,
Colors[ 3] = YZ plane (n) color,
Colors[ 4] = XZ plane -Y side (body bottom),
Colors[ 5] = background color.
The default value is[1,7,2,3,7,0], which yields good colors with the TEK_COLOR
table: (white, yellow, red, green, yellow, black).
FRAME
Set this keyword to draw a frame around the widget.
LABEL
Set this keyword to a string containing the widgets label.
RETAIN
Set thiskeyword to zero, one, or two to specify howbackingstoreshould behandled for
the draw widget. RETAIN=0 species no backing store. RETAIN=1 requests that the
server or window system provide backing store. RETAIN=2 species that IDL provide
backing store directly. See Backing Store on page 144for details.
SIZE
The size of the square drawable area containing the arcball, in pixels. The default is 192.
UPDATE
Set this keyword to cause the widget will send an event each time the mouse button is
releasedafter adragoperation. Bydefault, eventsareonlysent when the Update button
is pressed.
UVALUE
VALUE
Set this keyword to a 3 x 3 array that will be the initial value for the rotation matrix.
VALUE must be a valid rotation matrix (no translation or perspective) where
TRANSPOSE(VALUE) = INVERSE(VALUE). This can be the upper-left corner of !P.T
after executing the command
T3D, /RESET, ROTATE = [x,y,z].
The default is the identity matrix.
CW_ARCBALL IDL Reference Guide
In addition, you can use the GET_VALUE and SET_VALUE keywords to
WIDGET_CONTROL to obtain or set the 3 x 3 rotation matrix in the arcball widget.
WIDGET_INFO.
Widget Events Returned by the CW_ARCBALL Widget
Arcball widgets generate event structures with the following denition:
event = {ID:0L, TOP:0L, HANDLER:0L, VALUE:fltarr(3,3) }
The VALUE eld contains the 3 x 3 array representing the new rotation matrix.
Example
See the procedureARCBALL_TEST, contained in thecw_arcball.pro le. To test
CW_ARCBALL, enter the following commands:
Figure 9-2: The CW_ARCBALL widget.
IDL Reference Guide CW_ARCBALL
.RUN cw_arcball
ARCBALL_TEST
See Also
CREATE_VIEW, SCALE3, T3D
CW_BGROUP IDL Reference Guide
CW_BGROUP
The CW_BGROUP function creates a widget base of buttons. It handles the details of
creatingtheproper base(standard, exclusive, or non-exclusive) and llingin thedesired
buttons. Events for the individual buttons are handled transparently, and a
CW_BGROUP event returned. This event can return any one of the following:
the index of the button within the base,
the widget ID of the button,
the name of the button,
an arbitrary value taken from an array of user values.
Onlybuttonswithtextual namesarehandledbythiswidget. Bitmapsarenot understood.
The returned value of this function is the widget ID of the newly-created button group
widget.
cw_bgroup.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_BGROUP(Parent, Names)
Arguments
Parent
Names
A string array, one string per button, giving the name of each button.
Keywords
BUTTON_UVALUE
An array of user values to be associated with each button and returned in the event
structure. If thiskeyword isset, theuser valuesarealwaysreturned, even if theany of the
RETURN_ID, RETURN_INDEX, or RETURN_NAME keywords are set.
COLUMN
Buttons will be arranged in the number of columns specied by this keyword.
IDL Reference Guide CW_BGROUP
EVENT_FUNCT
Astringcontainingthenameof afunctiontobecalledbytheWIDGET_EVENTfunction
when an event arrivesfromawidget in thewidget hierarchy rooted at thenewly-created
widget. This function is called with the return value structure whenever a button is
pressed, and follows the conventions for user-written event functions.
EXCLUSIVE
Set this keyword to cause buttons to be placed in an exclusive base, in which only one
button can be selected at a time.
FONT
Thenameof thefont to beused for thebutton titles. Thefont specied isadevicefont
(an X Windows font on Motif systems; a TrueType or PostScript font on Windows or
Macintoshsystems). SeeAbout DeviceFonts onpage72for detailsonspecifyingnames
for device fonts. If this keyword is omitted, the default font is used.
FRAME
Species the width of the frame to be drawn around the base.
IDS
A named variable in which the button IDs will be stored, as a longword vector.
LABEL_LEFT
Creates a text label to the left of the buttons.
LABEL_TOP
Creates a text label above the buttons.
MAP
Set thiskeyword tocausethebasetobemapped when thewidget isrealized (thedefault).
NONEXCLUSIVE
Set this keyword to cause buttons to be placed in an non-exclusive base, in which any
number of buttons can be selected at once.
NO_RELEASE
If set, button release events will not be returned.
RETURN_ID
Set this keyword to return the widget ID of the button in the VALUE eld of returned
events. This keyword is ignored if the BUTTON_UVALUE keyword is set.
RETURN_INDEX
Set this keyword to return the zero-based index of the button within the base in the
VALUE eld of returned events. This keyword is ignored if the BUTTON_UVALUE
keyword is set. THIS IS THE DEFAULT.
CW_BGROUP IDL Reference Guide
RETURN_NAME
Set this keyword to return the name of the button within the base in the VALUE eld of
returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set.
ROW
Buttons will be arranged in the number of rows specied by this keyword.
SCROLL
If set, the base will include scroll bars to allow viewing a large base through a smaller
viewport.
SET_VALUE
Allows changing the current state of toggle buttons (i.e., exclusive and nonexclusive
groups of buttons). The behavior of SET_VALUE differs between EXCLUSIVE and
NONEXCLUSIVE CW_BGROUP widgets. With EXCLUSIVE CW_BGROUP widgets,
the argument to SET_VALUE is the id of the widget to be turned on. With
NONEXCLUSIVE CW_BGROUP widgets the argument to SET_VALUE should be an
array of on/off ags for the array of buttons.
SPACE
The space, in pixels, to be left around the edges of a row or column major base. This
keyword is ignored if EXCLUSIVE or NONEXCLUSIVE are specied.
UVALUE
XOFFSET
The X offset of the widget relative to its parent.
XPAD
The horizontal space, in pixels, between children of a row or column major base. This
XSIZE
The width of the base.
X_SCROLL_SIZE
The width of the viewport if SCROLL is specied.
YOFFSET
The Y offset of the widget relative to its parent.
YPAD
The vertical space, in pixels, between children of a row or column major base. This
YSIZE
The height of the base.
IDL Reference Guide CW_BGROUP
Y_SCROLL_SIZE
The height of the viewport if SCROLL is specied.
WIDGET_CONTROL to obtain or set the value of the button group. The values for
different types of CW_BGROUP widgets is shown in the table below:
WIDGET_INFO.
Widget Events Returned by the CW_BGROUP Widget
Button Group widgets generates event structures with the following denition:
event = {ID:0L, TOP:0L, HANDLER:0L, SELECT:0, VALUE:0 }
TheSELECT eld ispassed through fromthebutton event. VALUEiseither theINDEX,
ID, NAME, or BUTTON_UVALUE of the button, depending on how the widget was
created.
See Also
CW_PDMENU, WIDGET_BUTTON
Type Value
normal None
exclusive Index of currently set button
non-exclusive Vector indicating the position of
each button (1-set, 0-unset)
Table 9-4: Button Group Values.
CW_CLR_INDEX IDL Reference Guide
CW_CLR_INDEX
The CW_CLR_INDEX function creates a compound widget for the selection of a color
index. A horizontal color bar is displayed. Clicking on the bar sets the color index.
The returned value of this function is the widget ID of the newly-created color index
widget.
cw_clr_index.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_CLR_INDEX(Parent)
Arguments
Parent
Keywords
COLOR_VALUES
Avector of color indicescontainingthecolorstobedisplayedin thecolor bar. If omitted,
NCOLORS and START_COLOR specify the range of color indices.
EVENT_FUNCT
widget. This function is called with the return value structure whenever a button is
pressed, and follows the conventions for user-written event functions.
FRAME
If set, a frame will be drawn around the widget.
LABEL
A text label that appears to the left of the color bar.
NCOLORS
The number of colors to place in the color bar. The default is !D.N_COLORS.
START_COLOR
The starting color index, placed at the left of the bar.
UVALUE
IDL Reference Guide CW_CLR_INDEX
XSIZE
The width of the color bar in pixels. The default is 192.
YSIZE
The height of the color bar in pixels. The default is 12.
In addition, you can use the GET_UVALUE and SET_VALUE keywords to
WIDGET_CONTROL to obtain or set thevalueof thecolor selection widget. Thevalue
of a CW_CLR_INDEX widget is the index of the color selected.
WIDGET_INFO.
Widget Events Returned by the CW_CLR_INDEX Widget
This widget generates event structures with the following denition:
Event = {CW_COLOR_INDEX, ID: base, TOP: ev.top, HANDLER: 0L, VALUE:c}
The VALUE eld is the color index selected.
See Also
CW_COLORSEL, XLOADCT, XPALETTE
CW_COLORSEL IDL Reference Guide
CW_COLORSEL
TheCW_COLORSEL function createsacompound widget that displaysall thecolorsin
thecurrent colormap in a16x 16(320x 320pixels) grid. Toselect acolor index, theuser
moves the mouse pointer over the desired color square and presses any mouse button.
Alternatively, thecolor index can beselected by movingoneof thethreeslidersprovided
around the grid.
The returned value of this function is the widget ID of the newly-created color index
widget.
cw_colorsel.pro in thelib subdirectory of the IDL distribution.
Using CW_COLORSEL
The command:
WIDGET_CONTROL, widgetID, SET_VALUE = -1
informs the widget to initialize itself and redraw. It should be called when any of the
following happen:
the widget is realized,
the widget needs redrawing,
the brightest or darkest color has changed.
To set the current color index, use the command:
WIDGET_CONTROL, widgetID, SET_VALUE = index
To retrieve the current color index and store it in the variablevar, use the command:
WIDGET_CONTROL, widgetID, GET_VALUE = var
Calling Sequence
Result = CW_COLORSEL(Parent)
Arguments
Parent
IDL Reference Guide CW_COLORSEL
Keywords
FRAME
If set, a frame is drawn around the widget.
UVALUE
XOFFSET
The X offset position
YOFFSET
The Y offset position
Widget Events Returned by the CW_COLORSEL Widget
Event = {COLORSEL_EVENT, ID: base, TOP: ev.top, HANDLER: 0L, VALUE:c}
The VALUE eld is the color index selected.
See Also
CW_CLR_INDEX, XLOADCT, XPALETTE
CW_DEFROI IDL Reference Guide
CW_DEFROI
The CW_DEFROI function creates a compound widget that allows the user to dene a
region of interest within a widget draw window.
Caution This is amodal widget. No other widget applications will be responsive while this
widget isin use. Also, sinceCW_DEFROI hasitsown event-handlingloop, it should
not be created as a child of a modal base.
The returned value of this function is an array of subscripts dening the region. If no
region is dened, the scalar -1 is returned.
cw_defroi.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_DEFROI(Draw)
Arguments
Draw
Thewidget ID of drawwindowin which to drawtheregion. Notethat thedrawwindow
must have both BUTTON and MOTION events enabled (see WIDGET_DRAW on
page-1252 for more information).
Keywords
IMAGE_SIZE
The size of the underlying array, expressed as a two element vector: [columns, rows] .
Default is the size of the draw window divided by the value of ZOOM.
OFFSET
The offset of lower left corner of image within the draw window. Default = [ 0,0] .
ORDER
Set this keyword to return inverted subscripts, as if the array were output from top to
bottom.
RESTORE
Set this keyword to restore the draw window to its previous appearance on exit.
Otherwise, the regions remain on the drawable.
IDL Reference Guide CW_DEFROI
ZOOM
If the image array was expanded (using REBIN, for example) specify this two element
vector containing the expansion factor in X and Y. Default = [ 1,1] . Both elements of
ZOOM must be integers.
WIDGET_INFO.
Widget Events Returned by the CW_DEFROI Widget
Region denition widgets do not return an event structure.
Example
The following two procedures create a region-of-interest widget and its event handler.
Createalecontainingtheprogramcodeusingatext editor andcompileusingthe.RUN
command, or type .RUN at the IDL prompt and enter the lines interactively.
First, create the event handler:
PRO test_event, ev
COMMON T, draw, dbutt, done, image
Thecommonblockholdsvariables
that areshared between therou-
tineand its event handler.
IF ev.id EQ dbutt THEN BEGIN Definewhat happens when you
click theDraw ROI button.
Q = CW_DEFROI(draw) TheROI definition will bestored
in thevariableQ.
HELP, Q ShowthesizeoftheROI definition
array.
image2 = image Duplicatetheoriginal image.
image2(Q)=!P.COLOR-1 SetthepointsintheROI arrayQ
equal to a singlecolor value.
CW_DEFROI IDL Reference Guide
WIDGET_CONTROL, draw, GET_VALUE=W
Get thewindow ID of thedraw
widget.
WSET, W Setthedrawwidgetasthecurrent
graphics window.
TV, image2 LoadtheimageplustheROI into
thedraw widget.
ENDIF
IF ev.id EQ done THEN WIDGET_CONTROL, ev.top, /DESTROY
Definewhat happens when you
click theDone button.
END
Next, create a draw widget that can call CW_DEFROI. Note that you must specify both
button events and motion events when creating the draw widget, if it is to be use with
CW_DEFROI.
PRO test
COMMON T, draw, dbutt, done, image
base = WIDGET_BASE(/COLUMN) Createa baseto hold thedraw
widget and buttons.
draw = WIDGET_DRAW(base, XSIZE=256, YSIZE=256, /BUTTON, /MOTION)
Createadrawwidgetthatwill re-
turn both button and motion
events.
dbutt = WIDGET_BUTTON(base, VALUE='Draw ROI')
done = WIDGET_BUTTON(base, VALUE='Done')
WIDGET_CONTROL, base, /REALIZE
WIDGET_CONTROL, draw, GET_VALUE=W GetthewidgetIDofthedrawwid-
get.
WSET, W Setthedrawwidgetasthecurrent
graphics window.
image = BYTSCL(SIN(DIST(256))) Createan original image.
TV, image Display theimagein thedraw
widget.
XMANAGER, "test", base Start XMANAGER.
IDL Reference Guide CW_DEFROI
END
See Also
DEFROI
Figure 9-3: The Region of Interest Definition Widget.
CW_DICE IDL Reference Guide
CW_DICE
The CW_DICE function creates a compound widget that implements a single die. The
widget uses a button with a bitmap label. If the user presses the button, the die tumbles
for a moment, then the new value is displayed and an event is issued.
The primary purpose of this compound widget is to serve as a full example of a realistic
compound widget for theIDL Users Guide.
The returned value of this function is the widget ID of the newly-created die widget.
cw_dice.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_DICE(Parent)
Arguments
Parent
Keywords
TUMBLE_CNT
The widget simulates the tumbling of a dice by changing the bitmap on the dice several
times before settling down to a nal value. The number of tumbles is specied by the
TUMBLE_CNT keyword. The default is 10.
TUMBLE_PERIOD
The amount of time in seconds between each tumble of the dice. The default is .05
seconds.
UVALUE
IDL Reference Guide CW_DICE
To get or set the value of a CW_DICE widget, use the GET_VALUE and SET_VALUE
keywordstoWIDGET_CONTROL. Thevalueof aCW_DICEwidget isan integer in the
range [ 1,6] .
If avalueoutsidetherange[ 1,6] isspeciedbytheSET_VALUEkeyword, thedietumbles
to a new value as if the user had pressed the button, but no event is issued.
WIDGET_INFO.
Widget Events Returned by the CW_DICE Widget
event = {CW_DICE_EVENT, ID: base, TOP: ev.top, HANDLER: 0L, VALUE:0}
The VALUE eld is the value of the die face. Such events are only sent when the user
presses the dice button.
Example
See Using CW_DICE in a Widget Program on page 323 of Building IDL Applications
for an example using CW_DICE.
CW_FIELD IDL Reference Guide
CW_FIELD
TheCW_FIELDfunctioncreatesawidget dataentryeld. Theeldconsistsof alabel and
a text widget. CW_FIELD can create string, integer, or oating-point elds. The default
is an editable string eld.
The returned value of this function is the widget ID of the newly-created eld widget.
cw_field.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_FIELD(Parent)
Arguments
Parent
Keywords
ALL_EVENTS
Like RETURN_EVENTS but return an event whenever the contents of a text eld have
changed.
COLUMN
Set thiskeywordtocenter thelabel abovethetext eld. Thedefault istoposition thelabel
to the left of the text eld.
FIELDFONT
A string containing the name of the font to use for the TEXT part of the eld.
FLOATING
Set thiskeywordtohavetheeldaccept onlyoating-point values. Anynumber or string
entered is converted to its oating-point equivalent.
FONT
A string containing the name of the font to use for the TITLE of the eld. The font
specied is a device font (an X Windows font on Motif systems; a TrueType or
PostScript font on Windows or Macintosh systems). See About Device Fonts on page
72for detailson specifyingnamesfor devicefonts. If thiskeyword isomitted, thedefault
font is used.
IDL Reference Guide CW_FIELD
FRAME
Thewidth, in pixels, of aframeto bedrawn around theentireeld cluster. Thedefault is
no frame.
INTEGER
Set thiskeywordtohavetheeldaccept onlyinteger values. Anynumber or stringentered
is converted to its integer equivalent (using FIX). For example, if 12.5 is entered in this
type of eld, it is converted to 12.
LONG
Set this keyword to have the eld accept only long integer values. Any number or string
entered is converted to its long integer equivalent (using LONG).
NOEDIT
Normally, thevaluein thetext eld can beedited. Set thiskeyword tomaketheeld non-
editable.
RETURN_EVENTS
Set this keyword to make CW_FIELD return an event when a carriage return is pressed
in a text eld. The default is not to return events. Note that the value of the text eld is
always returned when the command
WIDGET_CONTROL, field, GET_VALUE = X
is used.
ROW
Set this keyword to position the label to the left of the text eld. This is the default.
STRING
Set thiskeyword to havetheeld accept only stringvalues. Numbersentered in theeld
are converted to their string equivalents. This is the default.
TITLE
A string containing the text to be used as the label for the eld. The default is Input
Field.
UVALUE
VALUE
The initial value in the text widget. This value is automatically converted to the type set
by the STRING, INTEGER, and FLOATING keywords described below.
XSIZE
An explicit horizontal size(in characters) for thetext input area. Thedefault isto let the
window manager size the widget. Using the XSIZE keyword is not recommended.
CW_FIELD IDL Reference Guide
YSIZE
An explicit vertical size (in lines) for the text input area. The default is 1.
WIDGET_CONTROL to obtain or set the value of the eld. If one of the FLOATING,
INTEGER, LONG, or STRING keywords to CW_FIELD is set, values set with the
SET_VALUE keyword to WIDGET_CONTROL will be forced to the appropriate type.
Values returned by the GET_VALUE keyword to WIDGET_CONTROL will be of the
type specied when the eld widget is created. Note that if the eld contains string
information, returned valueswill becontained in astringarrayeven if theeld contains
only a single string.
See Compound Widgets on page 314 of Building IDL Applications for a more complete
discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.
Widget Events Returned by the CW_FIELD Widget
event = { ID:0L, TOP:0L, HANDLER: 0L, VALUE:'', TYPE:0 , UPDATE:0}
TheVALUEeld isthevalueof theeld. TYPEspeciesthetypeof datacontained in the
eld and can be any of the following: 0=string, 1=oating-point, 2=integer, 3=long
integer (the value of TYPE is determined by setting one of the STRING, FLOAT,
INTETER, or LONGkeywords). UPDATEcontainsazeroif theeldhasnot been altered
or a one if it has.
Example
Thecodebelowcreatesamain basewith aeld cluster attached to it. Thecluster accepts
string input, has the title Name, and has a frame around it:
base = WIDGET_BASE()
field = CW_FIELD(base, TITLE = "Name", /FRAME)
See Also
WIDGET_LABEL, WIDGET_TEXT
IDL Reference Guide CW_FORM
CW_FORM
The CW_FORM function is a compound widget that simplies creating small forms
which contain text, numeric elds, buttons, lists, and droplists. Event handling is also
simplied.
If the argument Parent is present, the returned value of this function is the widget ID of
the newly-created form widget. If Parent is omitted, the form realizes itself as a modal,
top-level widget and CW_FORM returnsastructurecontainingthevalueof each eld in
the form when the user nishes.
cw_form.pro in thelib subdirectory of the IDL distribution.
Using CW_FORM
The form has a value that is a structure with a tag/value pair for each eld in the form.
Use the command
WIDGET_CONTROL, id, GET_VALUE=v
to read the current value of the form. To set the value of one or more tags, use the
command
WIDGET_CONTROL, id, SET_VALUE={ Tag:value, ..., Tag:value}
Calling Sequence
Result = CW_FORM([Parent,] Desc)
Arguments
Parent
The widget ID of the parent widget. Omit this argument to created a modal, top-level
widget.
Desc
Astringarraydescribingtheform. Eachelement of thestringarraycontainstwoor more
comma-delimited elds. Each string has the following format:
'Depth, Item, Initial value, Keywords'
Usethebackslash character ( \ ) to escapecommasthat appear within elds. To include
the backslash character, escape it with another backslash.
The elds are dened as follows:
CW_FORM IDL Reference Guide
Depth
Adigit deningthelevel at which theelement will beplaced on theform. Nestingisused
primarily for layout, with row or column bases.
This eld must contain the digit 0, 1, or 2, with the following effects:
A 0 continues the current nesting level.
A 1 begins a new level under the current level.
A 2 denotes the last element at the current level.
Item
A label dening the type of element to be placed in the form. Itemmust be one of the
following: BASE, BUTTON, DROPLIST, FLOAT, INTEGER, LABEL, LIST, or TEXT.
BASEs and LABELs do not return a value in the widget value structure. The other items
return the following value types:
BUTTON
An integer or integer array. For singlebuttons, thevalueis1if thebutton isset, or 0if
it is not set. For exclusive button groups, the value is the index of the currently set
button. For non-exclusivebutton groups, thevalueisan array containingan element
for each button. Array elementsareset to1if thecorrespondingbutton isset, or 0if it
is not set.
DROPLIST
An integer. The value set in the widget value structure is the zero-based index of the
item is selected.
FLOAT
Aoating-point value. Thevalueset in thewidget valuestructureistheoating-point
value of the eld.
INTEGER
An integer. The value set in the widget value structure is the integer value of the eld.
LIST
An integer. The value set in the widget value structure is the zero-based index of the
item is selected.
TEXT
A string. The value set in the widget value structure is the string value of the eld.
Initial value
The initial value of the eld. TheInitial valueeld is left empty for BASEs.
For BUTTON, DROPLIST, and LIST items, the value eld contains one or more item
names, separated by the | character. Strings do not need to be enclosed in quotes. For
example, thefollowinglinedenesan exclusivebutton groupwithbuttonslabeledone,
two, and three.
'0, BUTTON, one|two|three, EXCLUSIVE'
For FLOAT, INTEGER, LABEL, and TEXT items, thevalueeld containstheinitial value
of the eld.
Keywords
TheKeyword eld contains one of the following keywords or keyword=valuepairs.
Keywords are used to specify optional attributes or options. Any number of Keyword
elds may be included in the description string.
Note that preceding keywords with a / character has no effect. Simply including a
keyword in theKeyword eld enables that option.
CENTER
Species alignment of LABEL items.
COLUMN
If present, species column layout in BASES or for BUTTON groups.
EXCLUSIVE
If present, makes an exclusive set of BUTTONs. The default is nonexclusive.
FONT=font name
If present, thefont for theitemisspecied. Thefont specied isadevicefont (an X
Windows font on Motif systems; a TrueType or PostScript font on Windows or
Macintosh systems). See About Device Fonts on page 72 for details on specifying
names for device fonts. If this keyword is omitted, the default font is used.
EVENT=function
Speciesthenameof auser-written event function that iscalledwhenever theelement
ischanged. Theevent function iscalledwiththewidget event structureasaparameter.
It may return an event structureor zero to indicatethat no further event processingis
desired.
FRAME
If present, a frame is drawn around the item. Valid only for BASEs.
LABEL_LEFT=label
Placealabel to theleft of theitem. Thiskeyword isvalid with BUTTON, DROPLIST,
FLOAT, INTEGER and TEXT items.
LABEL_TOP=label
Placealabel abovetheitem. ThiskeywordisvalidwithBUTTON, DROPLIST, FLOAT,
INTEGER and TEXT items.
LEFT
QUIT
If the form widget is created as a top-level, modal widget, when the user activates an
itemdened with thiskeyword, theformisdestroyed and itswidget valuereturned in
thewidget valuestructureof CW_FORM. For non-modal formwidgets, eventsgener-
ated by changing this item have their QUIT eld set to 1.
RIGHT
ROW
If present, species row layout in BASES or for BUTTON groups.
SET_VALUE=value
Sets the initial value of BUTTON groups or DROPLISTs. For droplists and exclusive
button groups, valueshould be the zero-based index of the item selected.
TAG=name
The tag name of this element in the widgets value structure. If not specied, the tag
name is TAGnnn, wherennn is the zero-based index of the item in theDesc array.
WIDTH=n
Species the width, in characters, of a TEXT, INTEGER, or FLOAT item.
Keywords
COLUMN
Set thiskeyword to maketheorientation of theformvertical. If COLUMN isnot set, the
form is laid out in a horizontal row.
IDS
Set this keyword equal to a named variable into which the widget id of each widget
corresponding to an element in theDesc array is stored.
NO_RELEASE
If set, button release events will not be returned.
TITLE
Set thiskeywordequal toascalar stringcontainingthetitleof thetoplevel base. TITLEis
not used if the form widget has a parent widget.
UVALUE
Set this keyword equal to the user value associated with the form widget.
WIDGET_CONTROL toobtain or set thevalueof theform. Theformhasavaluethat is
a structure with a tag/value pair for each eld in the form. Use the command
WIDGET_CONTROL, id, GET_VALUE=v
to read the current value of the form. To set the value of one or more tags, use the
command
WIDGET_CONTROL, id, SET_VALUE={ Tag:value, ..., Tag:value}
WIDGET_INFO.
Widget Events Returned by the CW_FORM Widget
This widget generates event structures each time the value of the form is changed. The
event structure has the following denition:
Event = { ID:0L, TOP:0L, HANDLER:0L, TAG:'', VALUE:0, QUIT:0}
The ID eld is the widget ID of the CW_FORM widget. The TOP eld is the widget ID
of thetop-level widget. TheTAGeldcontainsthetagnameof theeldthat changed. The
VALUEeld containsthenewvalueof thechanged eld. TheQUIT eld containsazero
if the quit ag is not set, or one if it is set.
Example
Dene a form with a label, two groups of vertical buttons (one non-exclusive and the
other exclusive), atext eld, an integer eld, and OK and Done buttons. If either the
OK or Done buttons are pressed, the form exits.
Begin by dening a string array describing the form:
desc = [ $
0, LABEL, Centered Label, CENTER, $
1, BASE,, ROW, FRAME, $
0, BUTTON, B1|B2|B3, LABEL_TOP=Nonexclusive:, $
+ COLUMN, TAG=bg1, $
2, BUTTON, E1|E2|E2, EXCLUSIVE,LABEL_TOP=Exclusive:, $
+ COLUMN,TAG=bg2, $
0, TEXT, , LABEL_LEFT=Enter File name:, WIDTH=12, $
+ TAG=fname, $
0, INTEGER, 0, LABEL_LEFT=File size:, WIDTH=6, TAG=fsize, $
1, BASE,, ROW, $
0, BUTTON, OK, QUIT, $
+ TAG=OK, $
2, BUTTON, Cancel, QUIT]
To use the form as a modal widget:
a = CW_FORM(desc, /COLUMN)
When theformisexited, (when theuser pressestheOKor Cancel buttons), astructureis
returned as the functions value. We can examine the structure by entering:
HELP, /STRUCTURE, a
IDL displays the following:
BG1 INT Array[3] Set buttons =1, unset =0.
BG2 INT 1 Second button of exclusivebutton
group was set.
FNAME STRING 'test.dat' Valueof thetext field.
FSIZE LONG 120 Valueof theinteger field.
OK LONG 1 This button was pressed.
TAG8 LONG 0 This button wasnt pressed.
Note that if the Cancel button is pressed, the OK eld is set to 0.
To use CW_FORM inside another widget:
a = WIDGET_BASE(TITLE='Testing')
b = CW_FORM(a, desc, /COLUMN)
WIDGET_CONTROL, a, /REALIZE
XMANAGER, 'Test', a
Theevent handlingprocedure(in thisexample, called TEST_EVENT), may usetheTAG
eld of the event structure to determine which eld changed and perform any data
validation or special actions required. It can also get and set the value of the widget by
calling WIDGET_CONTROL.
IDL Reference Guide CW_FSLIDER
CW_FSLIDER
The CW_FSLIDER function creates a slider that selects oating-point values.
The returned value of this function is the widget ID of the newly-created slider widget.
cw_fslider.pro in thelib subdirectory of the IDL distribution.
Using CW_FSLIDER
Toget or set thevalueof aCW_FSLIDERwidget, usetheGET_VALUEand SET_VALUE
keywords to WIDGET_CONTROL.
Note TheCW_FSLIDERwidget isbasedontheWIDGET_SLIDERroutine, whichaccepts
onlyinteger values. Becauseconversionbetweenintegersandoating-point numbers
necessarilyinvolvesround-off errors, theslider valuereturnedbyCW_FSLIDERmay
not exactly match theinput value, even when aoating-point number isentered in
thesliderstext eldasanASCII value. For moreinformationonoating-point issues,
see Accuracy & Floating-Point Operations on page 427 of Using IDL.
Calling Sequence
Result = CW_FSLIDER(Parent)
Arguments
Parent
Keywords
DRAG
Set thiskeyword tozeroif eventsshould onlybegenerated when themouseisreleased. If
DRAG is non-zero, events will be generated continuously when the slider is adjusted.
Note: On slowsystems, /DRAGperformancecan beinadequate. Thedefault isDRAG= 0.
EDIT
Set this keyword to make the slider label be editable. The default is EDIT = 0.
FORMAT
Provides the format in which the slider value is displayed. This should be a format as
accepted by the STRING procedure. The default FORMAT is'(G13.6)'
CW_FSLIDER IDL Reference Guide
FRAME
Set this keyword to have a frame drawn around the widget. The default is FRAME = 0.
MAXIMUM
The maximum value of the slider. The default is MAXIMUM = 100.
MINIMUM
The minimum value of the slider. The default is MINIMUM = 0.
SCROLL
Under the Motif window manager, the value provided for SCROLL species how many
units the scroll bar should move when the user clicks the left mouse button inside the
slider area, but not on the slider itself. This keyword has no effect under other window
systems.
SUPPRESS_VALUE
If true, the current slider value is not displayed. The default is SUPPRESS_VALUE = 0.
TITLE
The title of slider.
UVALUE
VALUE
The initial value of the slider
VERTICAL
If set, the slider will be oriented vertically. The default is horizontal.
XSIZE
For horizontal sliders, sets the length.
YSIZE
For vertical sliders, sets the height.
WIDGET_CONTROL to obtain or set the value of the slider. Note that the
SET_SLIDER_MAXandSET_SLIDER_MINkeywordstoWIDGET_CONTROLandthe
SLIDER_MIN_MAXkeywordtoWIDGET_INFOdonotwork withoatingpoint sliders
created with CW_FSLIDER.
IDL Reference Guide CW_FSLIDER
WIDGET_INFO.
Widget Events Returned by the CW_FSLIDER Widget
Event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0.0, DRAG:0}
TheVALUEeldistheoating-point valueselectedbytheslider. TheDRAGeldreports
on whether events are generated continuously (when the DRAG keyword is set) or only
when the mouse button is released (the default).
See Also
WIDGET_SLIDER
CW_ORIENT IDL Reference Guide
CW_ORIENT
The CW_ORIENT function creates a compound widget that provides a means to
interactively adjust the three-dimensional drawing transformation and resets the !P.T
system variable eld to reect the changed orientation.
The returned value of this function is the widget ID of the newly-created orientation-
adjustment widget.
cw_orient.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_ORIENT(Parent)
Arguments
Parent
Keywords
AX
The initial rotation in the X direction. The default is 30 degrees.
AZ
The initial rotation in the Z direction. The default is 30 degrees.
FRAME
Set this keyword to draw a frame around the widget.
TITLE
The title of the widget.
UVALUE
XSIZE
Determines the width of the widget. The default is 100.
YSIZE
Determines the height of the widget. The default is 100.
IDL Reference Guide CW_ORIENT
WIDGET_INFO.
Widget Events Returned by the CW_ORIENT Widget
CW_ORIENT only returns events when the three dimensional drawing transformation
hasbeen altered. The!P.Tsystemvariableeldisautomaticallyupdatedtoreect thenew
orientation.
See Also
CW_ARCBALL, T3D
CW_PDMENU IDL Reference Guide
CW_PDMENU
TheCW_PDMENUfunctionsimpliescreatingwidget pulldownmenus. It hasasimpler
interface than the XPDMENU procedure, which it replaces. Events for the individual
buttonsarehandled transparently, and aCW_PDMENU event returned. Thisevent can
return any one of the following:
the Index of the button within the base,
the widget ID of the button,
the name of the button.
thefullyqualiednameof thebutton. Thisallowsdifferent sub-menustocontainbuttons
with the same name in an unambiguous way.
Onlybuttonswithtextual namesarehandledbythiswidget. Bitmapsarenot understood.
Thereturnedvalueof thisfunction isthewidget IDof thenewly-createdpulldown menu
widget.
cw_pdmenu.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = CW_PDMENU(Parent, Desc)
Arguments
Parent
Desc
An array of stringsor structures. If Descisan array of strings, each element containsthe
ag eld, followed by a backslash character, followed by the name of the menu item,
optionally followed by another backslash character and thenameof an event-processing
procedure for that element. A string element of theDesc array would look like:
'n\item_name'
or
'n\item_name\event_proc'
wheren istheageld and item_name isthenameof themenu item. Theageld isa
bitmask that controls how the button is interpreted; appropriate values for the ag eld
are shown in Table 9-5. If theevent_proc eld is present, it is the name of an event-
handling procedure for the menu element and all of its children.
IDL Reference Guide CW_PDMENU
If Desc is an array of structures, each structure has the following denition:
{CW_PDMENU_S, flags:0, name:''}
The name tag is a string eld with the following components:
'item_name'
or
'item_name\event_proc'
whereitem_name isthenameof themenu item. If theevent_proc eldispresent, it is
the name of an event-handling procedure for the menu element and all of its children
Theagseldisabitmask that controlshowthebutton isinterpreted; appropriatevalues
for the ag eld are shown in Table 9-5. Note that if Desc is an array of structures, you
cannot specify individual event-handling procedures for each element.
Keywords
DELIMITER
Thecharacter used toseparatethepartsof afully qualied namein returned events. The
default is to use the . character.
FONT
Thenameof thefont to beused for thebutton titles. Thefont specied isadevicefont
(an X Windows font on Motif systems; a TrueType or PostScript font on Windows or
Macintoshsystems). SeeAbout DeviceFonts onpage72for detailsonspecifyingnames
Value Meaning
0 This button is neither the beginning nor the end of a pull-
down level.
1 This button is the root of a sub-pulldown menu. The sub-
buttons start with the next button.
2 This button is the last button at the current pulldown level.
The next button belongs to the same level as the current par-
ent button. If the name eld is not specied (or is an empty
string), no button is created, and the next button is created
one level up in the hierarchy.
3 Thisbutton istheroot of asub-pulldown menu, but it isalso
the last entry of the current level.
Table 9-5: Button Flag Bit Meanings.
HELP
If theMBARkeyword isset, and oneof thebuttonson themenubar hasthelabel help
(caseinsensitive) thenthat buttoniscreatedwiththe/HELPkeywordtogiveit anyspecial
appearanceit issupposedtohaveon amenubar. For example, Motif expectshelpbuttons
to be on the right.
IDS
A named variable in which the button IDs will be stored as a longword vector.
MBAR
Set this keyword to create a menubar pulldown. If MBAR is set, Parent must be the
menubar of a top-level base. (See the MBAR keyword to WIDGET_BASE for details.)
RETURN_ID
If thiskeywordisset, theVALUEfieldof returnedeventswill containthewidget IDof thebutton.
RETURN_INDEX
If thiskeywordisset, theVALUEeldof returnedeventswill containthezero-basedindex
of the button within the base. THIS IS THE DEFAULT.
RETURN_NAME
If thiskeywordisset, theVALUEfieldof returnedeventswill bethenameof theselectedbutton.
RETURN_FULL_NAME
Set thiskeyword and theVALUEeld of returned eventswill bethefully qualied name
of the selected button. This means that the names of all the buttons from the topmost
button of the pulldown menu to the selected one are concatenated with the delimiter
specied by the DELIMITER keyword. For example, if the top button was named
COLORS, thesecond level button wasnamed BLUE, and theselected button wasnamed
LIGHT, the returned value would be
COLORS.BLUE.LIGHT
This allows different submenus to have buttons with the same name (e.g.,
COLORS.RED.LIGHT).
UVALUE
XOFFSET
The X offset of the widget relative to its parent.
YOFFSET
The Y offset of the widget relative to its parent.
IDL Reference Guide CW_PDMENU
WIDGET_INFO.
Widget Events Returned by the CW_PDMENU Widget
event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }
VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button, depending on
how the widget was created.
Example
The following is the description of a menu bar with two buttons, Colors and Quit.
Colorsisapulldown containingthecolorsRed, Green, Blue, Cyan, and Magenta.
Blue is a sub-pulldown containing Light, Medium, Dark, Navy, and Royal.
The following small program can be used with the above description to create the
specied menu:
PRO PD_EXAMPLE
desc = [ '1\Colors' , $
'0\Red' , $
'0\Green' , $
'1\Blue' , $
'0\Light' , $
'0\Medium' , $
'0\Dark' , $
'0\Navy' , $
'2\Royal' , $
'0\Cyan' , $
'2\Magenta' , $
'2\Quit' ]
Create the widget:
base = WIDGET_BASE()
menu = CW_PDMENU(base, desc, /RETURN_FULL_NAME)
WIDGET_CONTROL, /REALIZE, base
Provide a simple event handler:
REPEAT BEGIN
ev = WIDGET_EVENT(base)
PRINT, ev.value
END UNTIL ev.value EQ 'Quit'
WIDGET_CONTROL, /DESTROY, base
END
END
TheDesc array could also have been dened using a structure for each element. The
followingarray of structurescreatesthesamemenu asthearray of stringsshown above.
Note, however, that if theDesc array is composed of structures, you cannot specify
individual event-handling routines.
First, make sure CW_PDMENU_S structure is dened:
junk = {CW_PDMENU_S, flags:0, name:'' }
Dene the menu:
desc = [ { CW_PDMENU_S, 1, 'Colors' }, $
{ CW_PDMENU_S, 0, 'Red' }, $
{ CW_PDMENU_S, 0, 'Green' }, $
{ CW_PDMENU_S, 1, 'Blue' }, $
{ CW_PDMENU_S, 0, 'Light' }, $
{ CW_PDMENU_S, 0, 'Medium' }, $
{ CW_PDMENU_S, 0, 'Dark' }, $
{ CW_PDMENU_S, 0, 'Navy' }, $
{ CW_PDMENU_S, 2, 'Royal' }, $
{ CW_PDMENU_S, 0, 'Cyan' }, $
{ CW_PDMENU_S, 2, 'Magenta' }, $
{ CW_PDMENU_S, 2, 'Quit' } ]
See Also
CW_BGROUP, WIDGET_DROPLIST
IDL Reference Guide CW_RGBSLIDER
CW_RGBSLIDER
The CW_RGBSLIDER function creates a compound widget that provides three sliders
for adjusting color values. The RGB, CMY, HSV, and HLS color systems can all be used.
No matter which color system is in use, the resulting color is always supplied in RGB,
which is the base system for IDL.
The returned value of this function is the widget ID of the newly-created color
adjustment widget.
cw_rgbslider.pro in thelib subdirectory of the IDL distribution.
Using CW_RGBSLIDER
The CW_RGBSLIDER widget consists of a pulldown menu which allows the user to
changebetweenthesupportedcolor systems, andthreecolor adjustment sliders, allowing
the user to select a new color value.
Calling Sequence
Result = CW_RGBSLIDER(Parent)
Arguments
Parent
Keywords
CMY
If set, the initial color system used is CMY.
COLOR_INDEX
If set, display asmall rectanglewith theselected color, usingthegiven index. Thecolor is
updated as the values are changed.
DRAG
Set thiskeywordandeventswill begeneratedcontinuouslywhen theslidersareadjusted.
If not set, eventswill onlybegeneratedwhen themousebutton isreleased. Note: On slow
systems, /DRAG performance can be inadequate. The default is DRAG = 0.
FRAME
If set, a frame will be drawn around the widget. The default is FRAME = 0.
CW_RGBSLIDER IDL Reference Guide
HSV
If set, the initial color system used is HSV.
HLS
If set, the initial color system used is HLS.
LENGTH
The length of the sliders. The default = 256.
RGB
If set, the initial color system used is RGB. This is the default.
UVALUE
VERTICAL
If set, the sliders will be oriented vertically. The default is VERTICAL = 0.
WIDGET_INFO.
Widget Events Returned by the CW_RGBSLIDER Widget
event = {ID:0L, TOP:0L, HANDLER:0L, R:0B, G:0B, B:0B }
The R, G, and B elds contain the Red, Green and Blue components of the selected
color. Note that CW_RGBSLIDER reports back the Red, Green, and Blue values no
matter which color system is selected.
See Also
CW_CLR_INDEX, XLOADCT, XPALETTE
IDL Reference Guide CW_TMPL
CW_TMPL
The CW_TMPL procedure is a template for compound widgets that use the
XMANAGER. Use this template instead of writing your compound widgets from
scratch. This template can be found in the lecw_tmpl.pro in thelib subdirectory
of the IDL distribution.
Calling Sequence
Result = CW_TMPL(Parent)
Arguments
Parent
The widget ID of the parent widget of the new compound widget.
Keywords
UVALUE
A user-specied value for the compound widget.
See Also
XMNG_TMPL
CW_ZOOM IDL Reference Guide
CW_ZOOM
The CW_ZOOM function creates a compound widget that displays two images: an
original image in one window and a portion of the original image in another. The user
can select thecenter of thezoomregion, thezoomscale, theinterpolation style, and the
method of indicating the zoom center.
The returned value of this function is the widget ID of the newly-created zoom widget.
cw_zoom.pro in thelib subdirectory of the IDL distribution.
Using CW_ZOOM
Thevalueof theCW_ZOOM widget istheoriginal, un-zoomed imagetobedisplayed (a
two-dimensional array). To change the contents of the CW_ZOOM widget, use the
command:
WIDGET_CONTROL, id, SET_VALUE = array
whereid isthewidget ID of theCW_ZOOM widget and array istheimagearray. The
valueof CW_ZOOM cannot beset until thewidget hasbeen realized. Notethat thesize
of theoriginal window, set withtheXSIZEandYSIZEkeywordstoCW_ZOOM, must be
the size of the input array.
To return thecurrent zoomed imageasdisplayed by CW_ZOOM in thevariablearray,
use the command:
WIDGET_CONTROL, id, GET_VALUE = array
Calling Sequence
Result = CW_ZOOM(Parent)
Arguments
Parent
Keywords
FRAME
If set, a frame will be drawn around the widget. The default is FRAME = 0.
MAX
The maximum zoom scale, which must be greater than or equal to 1. The default is 20.
IDL Reference Guide CW_ZOOM
MIN
The minimum zoom scale, which must be greater than or equal to 1. The default is 1.
RETAIN
bothwindows. RETAIN=0speciesnobackingstore. RETAIN=1requeststhat theserver
or windowsystemprovidebackingstore. RETAIN=2speciesthat IDL providebacking
store directly. See Backing Store on page 144for details.
SAMPLE
Set to zero for bilinear interpolation, or to a non-zero value for nearest neighbor
interpolation. Bilinear interpolation giveshigher quality results, but requiresmoretime.
The default is 0.
SCALE
Theinitial integer scalefactor tousefor thezoomedimage. Thedefault isSCALE= 4. The
scale must be greater than or equal to 1.
TRACK
Set thiskeyword and eventswill begenerated continuously asthecursor ismoved across
the original image. If not set, events will only be generated when the mouse button is
released. Note: On slowsystems, /TRACKperformancecan beinadequate. Thedefault is
0.
UVALUE
XSIZE
The width of the window (in pixels) for the original image. The default is XSIZE = 500.
Note that XSIZEmust be set to the width of the original image array for the image to
display properly.
X_SCROLL_SIZE
The width of the visible part of the original image. This may be smaller than the actual
width controlled by the XSIZE keyword. The default is 0, for no scroll bar.
X_ZSIZE
The width of the window for the zoomed image. The default is 250.
YSIZE
Theheight of thewindow(in pixels) for theoriginal image. Thedefault is500. Notethat
YSIZEmust be set to the height of the original image array for the image to display
properly.
Y_SCROLL_SIZE
The height of the visible part of the original image. This may be smaller than the actual
height controlled by the YSIZE keyword. The default is 0, for no scroll bar.
CW_ZOOM IDL Reference Guide
Y_ZSIZE
The height of the window for the zoomed image. The default is 250.
WIDGET_CONTROL to obtain or set the value of the zoom widget. The value of the
CW_ZOOMwidget istheoriginal, un-zoomedimagetobedisplayed(atwo-dimensional
array). To change the contents of the CW_ZOOM widget, use the command:
WIDGET_CONTROL, id, SET_VALUE = array
whereid isthewidget ID of theCW_ZOOM widget and array istheimagearray. The
valueof CW_ZOOM cannot beset until thewidget hasbeen realized. Notethat thesize
of theoriginal window, set withtheXSIZEandYSIZEkeywordstoCW_ZOOM, must be
the size of the input array.
To return thecurrent zoomed imageasdisplayed by CW_ZOOM in thevariablearray,
use the command:
WIDGET_CONTROL, id, GET_VALUE = array
WIDGET_INFO.
Widget Events Returned by the CW_ZOOM Widget
When the Report Zoom to Parent button is pressed, this widget generates event
structures with the following denition:
event = {ZOOM_EVENT, ID:0L, TOP:0L, HANDLER:0L, $
XSIZE:0L, YSIZE:0L, X0:0L, Y0:0L, X1:0L, Y1:0L }
The XSIZE and YSIZE elds contain the dimensions of the zoomed image. The X0 and
Y0eldscontain thecoordinatesof thelower left corner of theoriginal image, andtheX1
and Y1 elds contain the coordinates of the upper right corner of the original image.
Example
The following code samples illustrate a use of the CW_ZOOM widget.
IDL Reference Guide CW_ZOOM
First, createan event-handler. Notethat clickingon thewidgets Zoom button displays
IDLs help output on the console.
PRO widzoom_event, event
WIDGET_CONTROL, event.id, GET_UVALUE=uvalue
CASE uvalue OF
'ZOOM': HELP, /STRUCT, event
'DONE': WIDGET_CONTROL, event.top, /DESTROY
ENDCASE
END
Next, create the widget program:
PRO widzoom
OPENR, lun, FILEPATH('people.dat', SUBDIR = ['examples','data']), $
/GET_LUN
image=BYTARR(192,192)
READU, lun, image
FREE_LUN, lun
sz = SIZE(image)
base=WIDGET_BASE(/COLUMN)
zoom=CW_ZOOM(base, XSIZE=sz[1], YSIZE=sz[2], UVALUE='ZOOM')
done=WIDGET_BUTTON(base, VALUE='Done', UVALUE='DONE')
WIDGET_CONTROL, zoom, SET_VALUE=image
XMANAGER, 'widzoom', base
END
Onceyou haveenteredtheseprograms, type widzoom at theIDL commandprompt to
run the widget application.
See Also
ZOOM, ZOOM_24
DBLARR IDL Reference Guide
DBLARR
The DBLARR function returns a double-precision, oating-point vector or array.
Calling Sequence
Result = DBLARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, DBLARRsetseveryelement of theresult tozero. If NOZEROisset, thiszeroing
is not performed and DBLARR executes faster.
Example
TocreateD, an3-element by3-element, double-precision, oating-point arraywithevery
element set to 0.0, enter:
D = DBLARR(3, 3)
See Also
COMPLEXARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR,
IDL Reference Guide DCINDGEN
DCINDGEN
The DCINDGEN function returns a complex, double-precision, oating-point array
with thespecied dimensions. Each element of thearray hasitsreal part set to thevalue
of its one-dimensional subscript. The imaginary part is set to zero.
Calling Sequence
Result = DCINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
To createDC, a4-element vector of complex valueswith thereal partsset to thevalueof
their subscripts, enter:
DC = DCINDGEN(4)
See Also
BINDGEN, CINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, LINDGEN,
DCOMPLEX IDL Reference Guide
DCOMPLEX
TheDCOMPLEXfunction returnsdouble-precision complex scalarsor arraysgiven one
or twoscalarsor arrays. If onlyoneparameter issupplied, theimaginarypart of theresult
is zero, otherwise it is set to the value of theImaginary parameter. Parameters are rst
converted to double-precision oating-point. If either or both of the parameters are
arrays, theresult isan array, followingthesamerulesasstandard IDL operators. If three
parameters are supplied, DCOMPLEX extracts elds of data fromExpression.
Calling Sequence
Result = DCOMPLEX(Real [, Imaginary])
or
Result = DCOMPLEX(Expression, Offset, Dim
1
[, ..., Dim
n
])
Arguments
Real
Scalar or array to be used as the real part of the complex result.
Imaginary
Scalar or array to be used as the imaginary part of the complex result.
Expression
The expression from which data is to be extracted.
Offset
of data extracted fromExpression to be treated as complex data. See the description in
D
i
i
Example
Create a complex array from two integer arrays by entering the following commands:
IDL Reference Guide DCOMPLEX
A = [1,2,3] Createthefirst integer array.
B = [4,5,6] Createthesecond integer array.
C = DCOMPLEX(A, B) MakeA thereal parts and B the
imaginary parts of thenew com-
plex array.
PRINT, C Seehowthetwoarrayswerecom-
bined.
IDL prints:
( 1.0000000, 4.0000000)( 2.0000000, 5.0000000)
( 3.0000000, 6.0000000)
See Also
BYTE, CONJ, COMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT,
ULONG, ULONG64
DCOMPLEXARR IDL Reference Guide
DCOMPLEXARR
The DCOMPLEXARR function returns a complex, double-precision, oating-point
vector or array.
Calling Sequence
Result = DCOMPLEXARR(D
1
, ..., D
n
)
Arguments
D
i
Up to eight dimensions can be specied.
Keywords
NOZERO
Normally, DCOMPLEXARR sets every element of the result to zero. If the NOZERO
keyword is set, this zeroing is not performed, and DCOMPLEXARR executes faster.
Example
To create an empty, 5-element by 5-element, complex array DC, enter:
DC = DCOMPLEXARR(5, 5)
See Also
COMPLEXARR, DBLARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY,
STRARR, UINTARR, ULON64ARR, ULONARR
IDL Reference Guide DEFINE_KEY
DEFINE_KEY
TheDEFINE_KEYprocedureprogramsthekeyboardfunction KeywiththestringValue,
or with one of the actions specied by the available keywords.
DEFINE_KEYisprimarilyintendedfor usewithIDLscommandlineinterface(available
under UNIX and VMS). IDLs graphical interface (IDLDE), which is available under all
operating systems supported by IDL, uses different system-specic mechanisms.
Calling Sequence
DEFINE_KEY, Key [, Value]
Arguments
Key
Ascalar stringcontainingthenameof afunction key to beprogrammed. IDL maintains
an internal list of function key names and the escape sequences they send.
UNIX:Under UNIX, DEFINE_KEYallowsyoutoset thevaluesof twodistinctlydifferent
types of keys:
Control characters: Any of the 26 control characters (CTRL+A through CTRL+Z) can
be associated with specic actions by specifying the CONTROL keyword. Control
charactersaretheunprintableASCII charactersat thebeginningof theASCII character
set. TheyareusuallyenteredbyholdingdowntheControl keywhilethecorresponding
letter key is pressed.
Function keys: Most terminals(and terminal emulators) send escapesequenceswhen
a function key is pressed. An escape sequence is a sequence of characters starting the
ASCII Escape character. Escape sequences follow strict rules that allow applications
such as IDL to determine when the sequence is complete. For instance, the left arrow
key on most machines sends the sequence<ESC>[ D. The available function keys and
the escape sequences they send vary from keyboard to keyboard; IDL cannot be built
to recognize all of the different keyboards in existence. The ESCAPE keyword allows
you toprogramIDLwith theescapesequencesfor your keyboard. When you pressthe
function key, IDL will recognize the sequence and take the appropriate action.
UNIX:Under Unix, if Keyisnot alreadyon IDLsinternal list, you must usetheESCAPE
keyword to specify the escape sequence, otherwise, Key alone will sufce. The available
function keys and the escape sequences they send vary from keyboard to keyboard. The
SETUP_KEYSprocedureshouldbeusedonceat thebeginningof thesession toenter the
keys for the current keyboard. Table 9-6 describes the standard key denitions.
VMS: Under VMS, the key names are those dened by the Screen Management utility
(SMG). Table 9-7 describes some of these keys. For a complete description, refer to the
VMS RTL Screen Management (SMG$) Manual.
DEFINE_KEY IDL Reference Guide
Editing Key Function
Ctrl+A Move cursor to start of line
Ctrl+B Move cursor left one word
Ctrl+D EOFif current lineisempty, EOL other-
wise
Ctrl+E Move to end of line
Ctrl+F Move cursor right one word
Ctrl+K Erase from the cursor to the end of the
line
Ctrl+N Move back one line in the recall buffer
Ctrl+R Retype current line
Ctrl+U Delete from current position to start of
line
Ctrl+W Delete previous word
Ctrl+X Delete current character
Backspace, Delete Delete previous character
ESC-I Overstrike/insert toggle
ESC-Delete Delete previous word
Up Arrow Move back one line in the recall buffer
Down Arrow Move forward one line in the recall
buffer
Left Arrow Move left one character
Right Arrow Move right one character
R13 Move cursor left one word (Sun key-
boards)
R15 Move cursor right one word (Sun key-
boards)
^ text Recall the rst line containingtext. If
text is blank, recall the previous line
Other Characters Insert character at the current cursor
position
Table 9-6: Standard Key Denitions for Unix
Windows: Under Windows, function keys F2, F4, F11, and F12 can be customized.
In IDL for Windows, three special variables can be used to expand the current
mouse selection, the current line, or the current lename into the output of
dened keys.
For example, to dene F2 as a key that executes an IDL PRINT command with
the current mouse selection as its argument, use the command:
Key Name Description
DELETE Delete previous character.
PF1 Recall most recent command that matches supplied
string.
PF2PF4 Top row of keypad.
KP0KP9 Keypad keys 0 through 9
ENTER Keypad ENTER key
MINUS Keypad - key
COMMA Keypad , key
PERIOD Keypad . key
FIND Editing keypad FIND key
INSERT_HERE Editing keypad INSERT HERE key
REMOVE Editing keypad REMOVE key
SELECT Editing keypad SELECT key
PREV_SCREEN Editing keypad PREV_SCREEN key
NEXT_SCREEN Editing keypad NEXT_SCREEN key
Table 9-7: VMS Line Editing Keys
Variable Expansion
%f lename of the currently-selected IDL Editor window
%l number of the current line in an IDL Editor window
%s Currently-selected text from an IDL Output Log or Editor win-
dow
Table 9-8: Variable expansions for dened keys
DEFINE_KEY, 'F2', 'PRINT, "%S"'
Dragging the mouse over any text in an IDL Editor or Output Log window and
pressingF1causestheselected text to beprinted. The%l and %f variablescan be
used in a similar fashion.
Macintosh: DEFINE_KEY does not currently work with IDL for Macintosh.
Value
The scalar string that will be printed (as if it had been typed manually at the keyboard)
when Keyispressed. If Valueisnot present, and no function isspecied for thekey with
one of the keywords, the key is cleared so that nothing happens when it is pressed.
Keywords
MATCH_PREVIOUS
Set thiskeywordtoprogramKeytoprompt theuser for astring, andthensearchthesaved
command buffer for the most recently issued command that contains that string. If a
match is found, the matching command becomes the current command, otherwise the
last command entered isused. Under Unix, thedefault match key istheup caret ^ key
when pressed in column 1. Under VMS, the default match key is PF1.
NOECHO
Set this keyword to enter the Value assigned to Key when pressed, without echoing the
string to the screen. This feature is useful for dening keys that perform such actions as
erasing the screen. If NOECHO is set, TERMINATE is also assumed to be set.
TERMINATE
If this keyword is set, and Valueis present, pressingKey terminates the current input
operation after its assigned value is entered. Essentially, an implicit carriage return is
added to the end of Value.
Unix Keywords
BACK_CHARACTER
Set this keyword to programKey to move the current cursor position left one character.
BACK_WORD
Set this keyword to programKey to move the current cursor position left one word.
CONTROL
Set thiskeywordtoindicatethat Keyisthenameof acontrol key. Thedefault isfor Keyto
dene a function key escape sequence. To view the names used by IDL for the control
keys, type the following at the Command Input Line:
HELP, /ALL_KEYS
Caution TheCONTROL and ESCAPEkeywordsaremutually exclusiveand cannot bespeci-
ed together.
DELETE_CHARACTER
Set this keyword to programKey to delete the character to the left of the cursor.
DELETE_CURRENT
Set this keyword to programKey to delete the character directly underneath the cursor.
DELETE_EOL
Set thiskeyword to programKeyto deletefromthecursor position to theend of theline.
DELETE_LINE
Set this keyword to programKey to delete all characters to the left of the cursor.
DELETE_WORD
Set this keyword to programsKey to delete the word to the left of the cursor.
END_OF_LINE
Set this keyword to programKey to move the cursor to the end of the line.
END_OF_FILE
Set this keyword to programKey to exit IDL if the current line is empty, and to end the
current input line if the current line is not empty.
ENTER_LINE
Set this keyword to programKey to enter the current line (i.e., the action normally
performed by the Return key).
ESCAPE
A scalar string that species the escape sequence that corresponds to Key. See Dening
New Function Keys on page 405 for further details.
Caution TheCONTROL and ESCAPEkeywordsaremutually exclusiveand cannot bespeci-
ed together.
FORWARD_CHARACTER
Set thiskeyword toprogramKeytomovethecurrent cursor position right onecharacter.
FORWARD_WORD
Set this keyword to programKey to move the current cursor position right one word.
INSERT_OVERSTRIKE_TOGGLE
Set thiskeywordtoprogramKeytotogglebetween insert andoverstrike mode. When
characters are typed into the middle of a line, insert mode causes the trailing characters
tobemovedtotheright tomakeroomfor thenewones. Overstrikemodecausesthenew
characters to overwrite the existing ones.
NEXT_LINE
Set thiskeyword to programKeyto moveforward onecommand in thesaved command
buffer and make that command the current one.
PREVIOUS_LINE
Set this keyword to programKey to move back one command in the saved command
buffer and make that command the current one.
RECALL
Set thiskeyword to programKeyto prompt theuser for acommand number. Thesaved
command corresponding to the entered number becomes the current command. In
order to view the currently saved commands and the number currently associated with
each, enter the IDL command:
HELP, /RECALL COMMANDS
Example The RECALL operation remembers the last command number entered, and if the
user simplypressesreturn, it recallsthecommandcurrentlyassociatedwiththat saved
number. Since the number associated with a given command increases by one each
time a new command is saved, this feature can be used to quickly replay a sequence
of commands.
IDL> PRINT, 1
1
IDL> PRINT, 2
2
IDL> HELP, /RECALL_COMMANDS
Recall buffer length: 20
1 PRINT, 2
2 PRINT, 1
IDL> User presses key tied to RECALL.
Recall Line #: 2 Line2 is requested.
IDL> PRINT, 1 Saved command 2 is recalled.
1
Recall Line #: User presses return.
IDL> PRINT, 2 Saved command 2 is recalled
again.
2
REDRAW
Set this keyword to programKey to retype the current line.
START_OF_LINE
Set this keyword to programKey to move the cursor to the start of the line.
Dening New Function Keys
Under VMS, IDL uses the SMG screen management package, which ensures that IDL
command editingbehavesin thestandard VMSway. Hence, it isnot possibletouseakey
SMG does not understand.
Under Unix, IDL can handle arbitrary function keys. When adding a denition for a
function key that is not built into IDLs default list of recognized keys, you must use the
ESCAPEkeyword to specify theescapesequenceit sends. For example, toadd afunction
key named HELP which sends the escape sequence <Escape>[ 28~, use the command:
DEFINE_KEY, 'HELP', ESCAPE = '\033[28~'
This command adds the HELP key to the list of keys understood by IDL. Since only the
keynameandescapesequencewerespecied, pressingtheHELPkeywill donothing. The
Value argument, or one of the keywords provided to specify command line editing
functions, could havebeen included in theabovestatement to programit with an action.
Once a key is dened using the ESCAPE keyword, it is contained in the internal list of
function keys. It can then be subsequently redened without specifying the escape
sequence.
It is convenient to include commonly used key denitions in a startup le, so that they
will always be available. See Startup File on page 33 of Using IDL.
Usually, the SETUP_KEYS procedure is used to dene the function keys found on the
keyboard, soit isnot necessarytospecifytheESCAPEkeyword. For example, toprogram
key F2 on a Sun keyboard to redraw the current line:
SETUP_KEYS
DEFINE_KEY, 'F2', /REDRAW
The CONTROL keyword alters the action that IDL takes when it sees the specied
characters dening the control keys. IDL may not be able to alter the behavior of some
control characters. For example, CTRL+S and CTRL+Q are usually reserved by the
operating system for ow control . Similarly, CTRL+Z is usually The UNIX suspend
character.
Example CTRL+D is the UNIX end-of-le character. It is a common UNIX convention (fol-
lowed by IDL) for programsto quit upon encounteringCTRL+D.However, CTRL+D
isalsousedbysometext editorstodeletecharacters. TodisableIDLdefault handling
of CTRL+D, type the following:
DEFINE_KEY, /CONTROL, '^D'
To print a reminder of how to exit IDL properly, type the following:
DEFINE_KEY, /CONTROL, '^D', "print, 'Enter EXIT to quit IDL'", $
/NOECHO, /TERMINATE
To use CTRL+D to delete characters, type the following:
DEFINE_KEY, /CONTROL, '^D', /DELETE_CURRENT
See Also
GET_KBRD
IDL Reference Guide DEFROI
DEFROI
TheDEFROI function denesan irregular region of interest of an imageusingtheimage
displaysystemand thecursor and mouse. Theresult isavector of subscriptsof thepixels
inside the region. The lowest bit in which the write mask is enabled is changed.
DEFROI only worksfor interactive, pixel oriented deviceswith acursor and an exclusive
or writing mode. Regions may have at most 1000 vertices.
Caution DEFROI does not function correctly when used with draw widgets. See
CW_DEFROI on page 362.
defroi.pro in thelib subdirectory of the IDL distribution.
Using DEFROI
After callingDEFROI, click intheimagewiththeleft mousebuttontomark pointsonthe
boundary of the region of interest. The points are connected in sequence. Alternatively,
pressand hold theleft mousebutton and dragto drawacurved region. Click themiddle
mouse button to erase points. The most recently-placed point is erased rst. Click the
right mouse button to close the region. The function returns after the region has been
closed.
Calling Sequence
Result = DEFROI(Sx, Sy [, Xverts, Yverts])
Arguments
Sx, Sy
Integers specifying the horizontal and vertical size of image, in pixels.
Xverts, Yverts
Named vectors that will contain the vertices of the enclosed region.
Keywords
NOREGION
Set this keyword to inhibit the return of the pixel subscripts.
NOFILL
Set this keyword to inhibit lling of the dened region on completion.
DEFROI IDL Reference Guide
RESTORE
Set this keyword to restore the display to its original state upon completion.
X0, Y0
Set thesekeywordsequal tothecoordinatesof thelower left corner of thedisplayedimage
(in device coordinates). If omitted, the default value (0,0) is used.
ZOOM
Set this keyword equal to the zoom factor. If not specied, a value of 1 is assumed.
Example
TVSCL, DIST(200,200) Createan image.
X = DEFROI(200, 200) CallDEFROI.Thecursorbecomes
activeinthegraphicswindow.De-
finea region and click theright
mousebutton.
PRINT, X Printsubscriptsofpointsincluded
in thedefined region.
See Also
CW_DEFROI
IDL Reference Guide DEFSYSV
DEFSYSV
The DEFSYSV procedure creates a new system variable called Nameinitialized to Value.
Calling Sequence
DEFSYSV, Name, Value[, Read_Only]
Arguments
Name
A scalar string containing the name of the system variable to be created. All system
variable names must begin with the character !.
Value
An expressionfromwhichthetype, structure, andinitial valueof thenewsystemvariable
is taken. Valuecan be a scalar, array, or structure.
Read_Only
If theRead_Onlyargument ispresent andnonzero, thevalueof thenewly-createdsystem
variable cannot be changed (i.e., the system variable is read-only, like the !PI system
variable). Otherwise, the value of the new system variable can be modied.
Keywords
EXISTS
Set this keyword to a named variable that returns 1 if the system variable specied by
Nameexists. If thiskeywordisspecied, Valuecanbeomitted. For example, thefollowing
commands could be used to check that the system variable XYZ exists:
DEFSYSV, '!XYZ', EXISTS = i
IF i EQ 1 THEN PRINT, '!XYZ exists' ELSE PRINT, '!XYZ does not exist'
Example
To create a new, oating-point, scalar system variable called !NEWVAR with an initial
value of 2.0, enter:
DEFSYSV, '!NEWVAR', 2.0
You can both dene and use a system variable within a single procedure:
PRO foo
DEFSYSV, !foo, Rocky, watch me pull a squirrel out of my hat!
PRINT, !foo Print!foo after definingit.
END
DEFSYSV IDL Reference Guide
See Also
System Variables on page 37.
IDL Reference Guide DELETE_SYMBOL (VMS Only)
DELETE_SYMBOL (VMS Only)
The DELETE_SYMBOL procedure deletes a DCL (Digital Command Language)
interpreter symbol for the current process.
Calling Sequence
DELETE_SYMBOL, Name
Arguments
Name
A scalar string containing the name of the symbol to be deleted.
Keywords
TYPE
Indicates the table from which Namewill be deleted. Set TYPE to 1 to specify the local
symbol table. Set TYPEto2tospecifytheglobal symbol table. Thedefault istosearchthe
local table.
See Also
DELLOG (VMS Only), SET_SYMBOL, SETLOG (VMS Only)
DELLOG (VMS Only) IDL Reference Guide
DELLOG (VMS Only)
The DELLOG procedure deletes a VMS logical name.
Calling Sequence
DELLOG, Lognam
Arguments
Lognam
A scalar string containing the name of the logical to be deleted.
Keywords
TABLE
Ascalar stringgivingthenameof thelogical tablefromwhichtodeleteLognam. If TABLE
is not specied, LNM$PROCESS_TABLE is used.
See Also
DELETE_SYMBOL (VMS Only), SET_SYMBOL, SETENV (Unix and Windows Only),
SETLOG (VMS Only)
IDL Reference Guide DELVAR
DELVAR
The DELVAR procedure deletes variables from the main IDL program level. DELVAR
frees any memory used by the variable and removes it from the main programs symbol
table. The following restrictions apply:
DELVAR can only be called from the main program level.
Each time DELVAR is called, the main program is erased. Variables that are not deleted
remain unchanged.
Calling Sequence
DELVAR, V
1
, ..., V
n
Arguments
V
i
One or more named variables to be deleted.
Example
Suppose that the variable Q is dened at the main program level. Q can be deleted by
entering:
DELVAR, Q
See Also
TEMPORARY
DEMO_MODE IDL Reference Guide
DEMO_MODE
The DEMO_MODE function returns True if IDL is running in the timed demo mode
(i.e., a license manager is not running). Calling this function causes aFLUSH, -1
command to be issued.
demo_mode.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = DEMO_MODE()
IDL Reference Guide DERIV
DERIV
The DERIV function performs numerical differentiation using 3-point, Lagrangian
interpolation and returns the derivative.
Calling Sequence
Result = DERIV([X,] Y)
Arguments
X
Thevariableto differentiatewith respect to. If omitted, unit spacingfor Y(i.e., X
i
= i) is
assumed.
Y
The variable to be differentiated.
Example
X = [ 0.1, 0.3, 0.4, 0.7, 0.9]
Y = [ 1.2, 2.3, 3.2, 4.4, 6.6]
PRINT, DERIV(Y)
IDL prints:
1.20000 1.00000 1.05000 1.70000 2.70000
PRINT, DERIV(X,Y)
IDL prints:
8.00000 6.66667 5.25000 6.80000 10.800
See Also
DERIVSIG
DERIVSIG IDL Reference Guide
DERIVSIG
TheDERIVSIGfunction computesthestandarddeviation of aderivativeasfoundbythe
DERIVfunction, usingtheinput variablesof DERIVandthestandarddeviationsof those
input variables.
Calling Sequence
Result = DERIVSIG([X, Y, Sigx,] Sigy)
Arguments
X
Thevariableto differentiatewith respect to. If omitted, unit spacingfor Y(i.e., X
i
= i) is
assumed.
Y
The variable to be differentiated. Omit if X is omitted.
Sigx
Thestandard deviation of X(either vector or constant). Use 0.0 if theabscissaisexact;
omit if X is omitted.
Sigy
Thestandarddeviation of Y. Sigymust beavector if theother argumentsareomitted, but
may be either a vector or a constant if X, Y, and Sigx are supplied.
See Also
DERIV
IDL Reference Guide DETERM
DETERM
TheDETERM function computesthedeterminant of an nbynarray. LUdecomposition
isusedtorepresent theinput arrayintriangular form. Thedeterminant isthencomputed
astheproduct of diagonal elementsof thetriangular form. Rowinterchangesaretracked
during the LU decomposition to ensure the correct sign.
determ.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = DETERM(A)
Arguments
A
An n by n single- or double-precision oating-point array.
Keywords
CHECK
Set this keyword to check A for singularity. The determinant of a singular array is
returned aszeroif thiskeyword isset. Run-timeerrorsmayresult if Aissingular and this
keyword is not set.
DOUBLE
ZERO
Usethiskeywordtoset theabsolutevalueof theoating-point zero. Aoating-point zero
on the main diagonal of a triangular array results in a zero determinant. For single-
precision inputs, the default value is 1.0 10
-6
. For double-precision inputs, the default
valueis1.0 10
-12
. Settingthiskeyword to avaluelessthan thedefault may improvethe
precision of the result.
Example
Dene an array A:
A = [[ 2.0, 1.0, 1.0], $
[ 4.0, -6.0, 0.0], $
[-2.0, 7.0, 2.0]]
DETERM IDL Reference Guide
PRINT, DETERM(A) Computethedeterminant.
IDL prints:
-16.0000
See Also
COND, INVERT
IDL Reference Guide DEVICE
DEVICE
The DEVICE procedure provides device-dependent control over the current graphics
device(asset bytheSET_PLOTroutine). TheIDLgraphicsproceduresandfunctionsare
device-independent. That is, IDL presents the user with a consistent interface to all
devices. However, most deviceshaveextraabilitiesthat arenot directlyavailablethrough
thisinterface. DEVICEisused toaccessand control such abilities. It isused byspecifying
various keywords that differ from device to device.
See IDL Graphics Devices on page 111 for a description of the keywords available for
each graphics device.
Calling Sequence
DEVICE
Keywords
See Keywords Accepted by the IDL Devices on page 112.
Example
The following example retains the name of the current graphics device, sets plotting to
the PostScript device, makes a PostScript le, then resets plotting to the original device:
mydevice = !D.NAME ;TheNAME field of the!D system
variablecontainsthenameofthecur-
rent plottingdevice.
SET_PLOT, 'PS' ;Set plottingto PostScript.
DEVICE, FILENAME='myfile.ps', /LANDSCAPE
;UseDEVICE to set somePostScript
deviceoptions.
PLOT, FINDGEN(10) ;Makea simpleplot to thePostScript
file.
DEVICE, /CLOSE ;DEVICE closes thePostScript file.
SET_PLOT, mydevice ;Returnplottingtotheoriginaldevice.
DFPMIN IDL Reference Guide
DFPMIN
The DFPMIN procedure minimizes a user-written function Func of two or more
independent variables using the Broyden-Fletcher-Goldfarb-Shanno variant of the
Davidon-Fletcher-Powell method, using its gradient as calculated by a user-written
function Dfunc.
DFPMIN isbased on theroutinedfpmin described in section 10.7of Numerical Recipes
Calling Sequence
DFPMIN, X, Gtol, Fmin, Func, Dfunc
Arguments
X
On input, Xisan n-element vector specifyingthestartingpoint. On output, it isreplaced
with the location of the minimum.
Gtol
An input value specifying the convergence requirement on zeroing the gradient.
Fmin
On output, Fmin contains the value at the minimum-point X of the user-supplied
function specied by Func.
Func
A scalar string specifying the name of a user-supplied IDL function of two or more
independent variables to be minimized. This function must accept a vector argument X
and return a scalar result.
For example, suppose we wish to nd the minimum value of the function
y = (x
0
3)
4
+ (x
1
2)
2
To evaluate this expression, we dene an IDL function named MINIMUM:
FUNCTION minimum, X
RETURN, (X[0] - 3.0)^4 + (X[1] - 2.0)^2
END
Dfunc
A scalar string specifying the name of a user-supplied IDL function that calculates the
gradient of thefunction specied by Func. Thisfunction must accept avector argument
X and return a vector result.
IDL Reference Guide DFPMIN
For example, the gradient of the above function is dened by the partial derivatives:
We can write a function GRAD to express these relationships in the IDL language:
FUNCTION grad, X
RETURN, [4.0*(X[0] - 3.0)^3, 2.0*(X[1] - 2.0)]
END
Keywords
DOUBLE
EPS
Usethiskeywordtospecifyanumber closetothemachineprecision. For single-precision
calculations, thedefault valueis3.0 10
-8
. For double-precision calculations, thedefault
value is 3.0 10
-16
.
ITER
Use this keyword to specify a named variable which returns the number of iterations
performed.
ITMAX
Use this keyword to specify the maximum number of iterations allowed. The default
value is 200.
STEPMAX
Usethiskeywordtospecifythescaledmaximumsteplengthallowedin linesearches. The
default value is 100.0
TOLX
Usethiskeyword to specify theconvergencecriterion on Xvalues. Thedefault valueis4
x EPS.
Example
To minimize the function MINIMUM (shown above):
X = [1.0, 1.0] Makean initial guess (thealgo-
rithms startingpoint).
Gtol = 1.0e-7 Set theconvergencerequirement
on thegradient.
DFPMIN, X, Gtol, Fmin, 'minimum', 'grad'
y
x
0
-------- 4 x
0
3 ( )
3 y
x
1
-------- , 2 x
1
2 ( ) = =
DFPMIN IDL Reference Guide
Find theminimizingvalue.
PRINT, X Print theminimizingvalue.
IDL prints:
3.00175 2.00000
See Also
POWELL
IDL Reference Guide DIALOG_MESSAGE
DIALOG_MESSAGE
The DIALOG_MESSAGE function creates a modal (blocking) dialog box that can be
usedtodisplayinformationfor theuser. Thedialogmust bedismissed, byclickingonone
of its option buttons, before execution of the widget program can continue.
Thisfunction differsfromwidgetsin anumber of ways. TheDIALOG_MESSAGEdialog
does not exist as part of a widget tree, has no children, does not exist in an unrealized
state, and generates no events. Instead, the dialog is displayed whenever this function is
called. While the DIALOG_MESSAGE dialog is displayed, widget activity is limited
becausethedialogismodal. Thefunctiondoesnot returntoitscaller until theuser selects
one of the dialogs buttons. Once a button has been selected, the dialog disappears.
DIALOG_MESSAGE returns a string containing the text of the label that the user
selected.
There are four basic dialogs that can be displayed. The default type is Warning. Other
types can be selected by setting one of the keywords described below. Each dialog type
displays different buttons. Additionally any dialog can be made to show a Cancel
button by setting the CANCEL keyword. The four types of dialogs are described in the
table below:
Calling Sequence
Result = DIALOG_MESSAGE(Message_Text)
Arguments
Message_Text
Ascalar stringor stringarray that containsthetext of themessageto bedisplayed. If this
argument isset to an array of strings, each array element isdisplayed asaseparatelineof
text.
Dialog Type DefaultButtons
Error OK
Warning OK
Question Yes, No
Information OK
Table 9-9: Types of DIALOG_MESSAGE Dialogs
DIALOG_MESSAGE IDL Reference Guide
Keywords
CANCEL
Set this keyword to add a Cancel button to the dialog.
DEFAULT_CANCEL
Set this keyword to make the Cancel button the default selection for the dialog. The
default selection isthebutton that isselected when theuser pressesthedefault keystroke
(usually Space or Return depending on the platform). Setting DEFAULT_CANCEL
implies that the CANCEL keyword is also set.
DEFAULT_NO
Set this keyword to make the No button the default selection for Question dialogs.
Normally, the default is Yes.
DIALOG_PARENT
Set this keyword to the widget ID of a widget over which the message dialog should be
positioned. When displayed, theDIALOG_MESSAGEdialogwill bepositioned over the
specied widget. Dialogs are often related to a non-dialog widget tree. The ID of the
widget in that tree to which the dialog is most closely related should be specied.
Note In IDL for Windowsthe message dialog is centered on the screen rather than posi-
tioned over the specied widget.
This keyword is ignored on Macintosh platforms.
DISPLAY_NAME
Set thiskeywordequal toastringindicatingthenameof theXWindowsdisplayonwhich
the dialog is to appear. This keyword is ignored if the DIALOG_PARENT keyword is
specied. Thiskeyword isalso ignored on Microsoft Windowsand Macintosh platforms.
ERROR
Set this keyword to create an Error dialog. The default dialog type is Warning.
INFORMATION
Set thiskeyword to createan Information dialog. Thedefault dialogtypeisWarning.
QUESTION
Set this keyword to create a Question dialog. The default dialog type is Warning.
RESOURCE_NAME
A stringcontainingan X WindowSystemresourcenameto beapplied to thedialog. See
RESOURCE_NAME on page 1211 for a complete discussion of this keyword.
TITLE
Set this keyword to a scalar string that contains the text of a title to be displayed in the
dialog frame. If this keyword is not specied, the dialog has the dialog type as its title as
shown in Table 9-9. This keyword is ignored on Macintosh platforms.
IDL Reference Guide DIALOG_MESSAGE
See Also
XDISPLAYFILE
DIALOG_PICKFILE IDL Reference Guide
DIALOG_PICKFILE
TheDIALOG_PICKFILEfunction allowstheuser to interactively pick ale, or multiple
les, using the platforms own native graphical le-selection dialog. The user can also
enter the name of a le that does not exist (see the description of the WRITE keyword,
below). DIALOG_PICKFILEreturnsastringor an array of stringsthat containsthefull
path nameof theselected leor les. If no leisselected, DIALOG_PICKFILEreturnsa
null string.
Calling Sequence
Result = DIALOG_PICKFILE()
Keywords
DIALOG_PARENT
Set thiskeywordequal toastringthat speciesthenameof theparent directoryof thele.
DIRECTORY
Set this keyword to display only the existing directories in the current directory.
Individual les are not displayed.
DISPLAY_NAME
Set this keyword equal to a string that species the name of the X Windows display on
which the dialog should be displayed. This keyword is ignored on Microsoft Windows
and Macintosh platforms.
FILE
Set thiskeyword to ascalar stringthat containsthenameof theinitial leselection. This
keyword is useful for specifying a default lename.
FILTER
A string value for ltering the les in the le list. This keyword is used to reduce the
number of les to choose from. The user can modify the lter unless the FIX_FILTER
keyword isset. Examplelter valuescould be'*.pro' or '*.dat'. Only asinglelter
condition is allowed.
Under Microsoft Windows, the user cannot modify the lter. (The user can, however,
enter a lter string in the lename eld to lter the les displayed.)
On the Macintosh, the lter is not displayed if the WRITE keyword is set.
FIX_FILTER
When thiskeyword isset, only lesthat satisfy thelter can beselected. Theuser hasno
ability to modify the lter and the lter is not shown.
IDL Reference Guide DIALOG_PICKFILE
Under Microsoft Windows, the user cannot modify the lter even if FIX_FILTER isnot
set. Notethat theuser can enter alter stringin thelenameeld of thedialogtochange
the lter condition even if FIX_FILTERisset.
GET_PATH
Set this keyword to a named variable in which the path of the selection is returned.
GROUP
The widget ID of a widget that calls DIALOG_PICKFILE. When this ID is specied, a
death of the caller results in the death of the DIALOG_PICKFILE dialog.
MULTIPLE_FILES
Set thiskeyword toallowfor multipleleselection in thele-selection dialog. When you
set this keyword, the user can select multiple les using the platform- specic selection
method. The currently selected les appear in the selection text eld of the dialog as a
comma-separated list. With thiskeyword set, DIALOG_PICKFILEcan return astringor
an array of strings that contains the full path name of the selected le or les.
MUST_EXIST
Set this keyword to allow only les that already exist to be selected.
PATH
Set thiskeyword to astringthat containstheinitial path fromwhich to select les. If this
keyword is not set, the current working directory is used.
READ
Set this keyword to make the title of the dialog Select File to Read.
TITLE
Set this keyword to a scalar string to be used for the dialog title. If it is not specied, the
default title is Select File. This keyword is ignored on Macintosh platforms.
WRITE
Set this keyword to make the title of the dialog Select File to Write.
Note On theMacintosh, you mustset theWRITEkeyword in order to beableto enter the
nameof alethat doesnot exist. Asaresult, theFILTERand FIX_FILTERkeywords
are ignored when the WRITE keyword is specied on a Macintosh.
Example
Create a DIALOG_PICKFILE dialog that lets users select only les with the extension
pro. UsetheSelect FiletoRead titleandstorethenameof theselectedleinthevariable
file. Enter:
file = DIALOG_PICKFILE(/READ, FILTER = '*.pro')
DIALOG_PICKFILE IDL Reference Guide
See Also
FILEPATH
IDL Reference Guide DIALOG_PRINTJOB
DIALOG_PRINTJOB
The DIALOG_PRINTJOB function opens a native dialog that allows you to set
parameters for a printing job (number of copies to print, for example).
DIALOG_PRINTJOBreturnsanonzero valueif theuser pressed theOK button in the
dialog, or zero otherwise. You can use the result of this function to programmatically
begin printing.
Calling Sequence
Result = DIALOG_PRINTJOB([PrintDestination])
Arguments
PrintDestination
An instance of the IDLgrPrinter object for which a printing job is to be initiated. If no
PrintDestinationisspecied, theprinter usedbytheIDLDirect Graphicsprinterdevice
is modied.
Keywords
DIALOG_PARENT
Set this keyword to the widget ID of a widget to be used as the parent of this dialog.
DISPLAY_NAME
RESOURCE_NAME
Set this keyword equal to a string containing an X Window System resource name to be
applied to the dialog.
TITLE
Set this keyword equal to a string to be displayed on the dialog frame. This keyword is
ignored on Windows and Macintosh platforms.
See Also
DIALOG_PRINTERSETUP, The Printer Device on page 156
DIALOG_PRINTERSETUP IDL Reference Guide
DIALOG_PRINTERSETUP
TheDIALOG_PRINTERSETUPfunction opensanativedialogfor settingtheapplicable
properties for a particular printer.
DIALOG_PRINTERSETUPreturnsanonzerovalueif theuser pressedtheOK button in
the dialog, or zero otherwise. You can use the result of this function to programmatically
begin printing.
Calling Sequence
Result = DIALOG_PRINTERSETUP([PrintDestination])
Arguments
PrintDestination
An instance of the IDLgrPrinter object for which setup properties are to be set. If no
PrintDestinationisspecied, theprinter usedbytheIDLDirect Graphicsprinterdevice
is modied.
Keywords
DIALOG_PARENT
Set this keyword to the widget ID of a widget to be used as the parent of this dialog.
DISPLAY_NAME
RESOURCE_NAME
Set this keyword equal to a string containing an X Window System resource name to be
applied to the dialog.
TITLE
Set this keyword equal to a string to be displayed on the dialog frame. This keyword is
ignored on Windows and Macintosh platforms.
See Also
DIALOG_PRINTJOB, The Printer Device on page 156
IDL Reference Guide DIGITAL_FILTER
DIGITAL_FILTER
The DIGITAL_FILTER function returns the coefcients of a non-recursive, digital lter
for evenly spaced data points. Frequencies are expressed in terms of the Nyquist
frequency, 1/2T, whereT isthetimebetween datasamples. Highpass, lowpass, bandpass
and bandstop lters may be constructed with this function. The resulting vector of
coefcients has (2 Nterms+ 1) elements.
digital_filter.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = DIGITAL_FILTER(Flow, Fhigh, A, Nterms)
Arguments
Flow
The lower frequency of the lter as a fraction of the Nyquist frequency
Fhigh
The upper frequency of the lter as a fraction of the Nyquist frequency. The following
conditions are necessary for various types of lters:
No Filtering:Flow = 0, Fhigh = 1
Low Pass:Flow = 0, 0 < Fhigh < 1
High Pass:0 < Flow < 1, Fhigh =1
Band Pass:0 < Flow < Fhigh < 1
Band Stop:0 < Fhigh < Flow < 1
A
The size of Gibbs phenomenon wiggles in -db. 50 is a good choice.
Nterms
The number of terms in the lter formula. The order of lter.
Example
Coeff = DIGITAL_FILTER(Flow, Fhigh, A, Nterms)To get coefficients.
Followed by:
Yout = CONVOL(Yin, Coeff) To apply thefilter.
See Also
CONVOL, LEEFILT, MEDIAN, SMOOTH
DILATE IDL Reference Guide
DILATE
TheDILATEfunctionimplementsthemorphologicdilationoperator onbothbinaryand
grayscale images.
Mathematical morphologyisamethodof processingdigital imageson thebasisof shape.
A discussion of this topic is beyond the scope of this manual. A suggested reference is:
Haralick, Sternberg, and Zhuang, Image Analysis Using Mathematical Morphology,
IEEETransactionsonPatternAnalysisandMachineIntelligence, Vol. PAMI-9, No. 4, July,
1987, pp. 532-550. Much of this discussion is taken from that article.
Briey, the DILATE function returns the dilation of Imageby the structuring element
Structure. Thisoperator iscommonly known asll, expand, or grow. It can beused
to ll holes of a size equal to or smaller than the structuring element.
Used with binary images, where each pixel is either 1 or 0, dilation is similar to
convolution. Over each pixel of the image, the origin of the structuring element is
overlaid. If the image pixel is nonzero, each pixel of the structuring element is added to
the result using the or operator.
LettingABrepresent thedilation of an imageAbystructuringelement B, dilation can
be dened as:
where(A)
b
representsthetranslation of Aby b. Intuitively, for each nonzero element b
i,j
of B, A is translated by i,j and summed into C using the or operator. For example:
In this example, the origin of the structuring element is at (0,0).
Used with grayscale images, which are always converted to byte type, the DILATE
function is accomplished by taking the maximum of a set of sums. It can be used to
conveniently implement the neighborhood maximum operator with the shape of the
neighborhood given by the structuring element.
C A B A ( )
b
b B
= =
0100
0100
0110
1000
0000
11
0110
0110
0111
1100
0000
=
IDL Reference Guide DILATE
Openings and Closings
Theopeningof imageBby structuringelement K isdened as(BK) K. Theclosing
of imageB by K is dened as (BK) K where the o times symbol represents the
erosion operator implemented by the IDL ERODE function.
As stated by Haralick et al, the result of iteratively applied dilations and erosions is an
elimination of specic image detail smaller than the structuring element without the
global geometric distortion of unsuppressed features. For example, opening an image
with a disk structuring element smooths the contour, breaks narrow isthmuses, and
eliminates small islands and sharp peaks or capes.
Closing an image with a disk structuring element smooths the contours, fuses narrow
breaks and long thin gulfs, eliminates small holes, and lls gaps on the contours.
Calling Sequence
Result = DILATE(Image, Structure[, X
0
[, Y
0
[, Z
0
]]])
Arguments
Image
A one-, two-, or three-dimensional array upon which the dilation is to be performed. If
the parameter is not of byte type, a temporary byte copy is obtained. If neither of the
keywords GRAY or VALUES is present, the image is treated as a binary image with all
nonzero pixels considered as 1.
Structure
A one-, two-, or three-dimensional array that represents the structuring element.
Elementsareinterpretedasbinary: valuesareeither zeroor nonzero. Thisargument must
have the same number of dimensions asImage.
X
0
, Y
0
, Z
0
Optional parameters specifying the one-, two-, or three-dimensional coordinate of the
structuring elements origin. If omitted, the origin is set to the center, ([ N
x
/2] , [ N
y
/2] ,
[ N
z
/2] ), whereN
x
, N
y
, and N
z
are the dimensions of the structuring element array. The
origin need not be within the structuring element.
Keywords
GRAY
Set thiskeywordtoperformgrayscale, rather thanbinary, dilation. Thenonzeroelements
of the Structure parameter determine the shape of the structuring element
(neighborhood). If VALUESisnot present, all elementsof thestructuringelement are0,
yielding the neighborhood maximum operator.
DILATE IDL Reference Guide
VALUES
An array with the same dimensions asStructureproviding the values of the structuring
element. Thepresenceof thisparameter impliesgrayscaledilation. Eachpixel of theresult
isthemaximumof thesumof thecorrespondingelementsof VALUEandtheImagepixel
value. If the resulting sum is greater than 255, the return value is 255.
Example
The following example thresholds a gray scale image at the value of 100, producing a
binaryimage. Theresult isthen opened with a3pixel by3pixel squareshapeoperator,
using the DILATE and ERODE operators. The effect is to remove holes, islands, and
peninsula smaller than the shape operator:
B = A GE 100 Threshold and makebinary im-
age.
S = REPLICATE(1, 3, 3) Createtheshapeoperator.
C = DILATE(ERODE(B, S), S) Opening operator.
TVSCL, C Show theresult.
See Also
ERODE
IDL Reference Guide DINDGEN
DINDGEN
The DINDGEN function returns a double-precision, oating-point array with the
specied dimensions. Each element of thearray isset to thevalueof itsone-dimensional
subscript.
Calling Sequence
Result = DINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Up to eight dimensions may be specied. If the dimension arguments are not integer
values, IDL will convert them to integer values before creating the new array.
Example
To createD, a100-element, double-precision, oating-point array with each element set
to the value of its subscript, enter:
D = DINDGEN(100)
See Also
BINDGEN, CINDGEN, DCINDGEN, FINDGEN, INDGEN, LINDGEN, LINDGEN,
DISSOLVE IDL Reference Guide
DISSOLVE
The DISSOLVE procedure provides a digital dissolve effect for images. The routine
copiespixelsfromtheimage(arrangedintosquaretiles) tothedisplayinpseudo-random
order.
dissolve.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
DISSOLVE, Image
Arguments
Image
The image to be displayed. It is assumed that the image is already scaled. Byte-valued
images display most rapidly.
Keywords
DELAY
The wait between displaying tiles. The default is 0.01 second.
ORDER
The Image display order: 0 = bottom up (the default), 1 = top-down.
SIZ
Size of square tile. The default is 32 x 32 pixels.
X0, Y0
The X and Y offsets of the lower-left corner of the image on screen, in pixels.
Example
DISSOLVE, DIST(200), SIZ=16 Display an imageusing16 x 16
pixel tiles.
See Also
ERASE, TV
IDL Reference Guide DIST
DIST
The DIST function creates a rectangular array in which the value of each element is
proportional toitsfrequency. Thisarraymaybeused for avarietyof purposes, including
frequency-domain ltering and making pretty pictures.
dist.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = DIST(N [, M])
Arguments
N
The number of columns in the resulting array.
M
The number of rows in the resulting array. If M is omitted, the resulting array will beN
by N.
Example
TVSCL, DIST(100) Display theresults of DIST as an
image.
See Also
FFT
DO_APPLE_SCRIPT IDL Reference Guide
DO_APPLE_SCRIPT
The DO_APPLE_SCRIPT procedure compiles and executes an AppleScript script,
possibly returning a result. DO_APPLE_SCRIPT is only available in IDL for Macintosh.
Calling Sequence
DO_APPLE_SCRIPT, Script
Arguments
Script
A string or array of strings to be compiled and executed by AppleScript.
Keywords
AS_STRING
Set this keyword to cause the result to be returned as a decompiled string. Decompiled
strings have the same format as the The Result window of Apples Script Editor.
RESULT
Set this keyword equal to a named variable that will contain the results of the script.
Example
Supposeyou wish toretrievearangeof cell datafromaMicrosoft Excel spreadsheet. The
followingAppleScript script andcommandretrievetherst throughfthrowsof therst
two columnsof aspreadsheet titled Worksheet 1, storingtheresult in theIDL variable
A:
script = [ 'tell application "Microsoft Excel"', $
'get Value of Range "R1C1:R5C2" of Worksheet 1', $
'end tell' ]
DO_APPLE_SCRIPT, script, RESULT = a
Similarly, the following lines would copy the contents of the IDL variable A to a range
within the spreadsheet:
A = [ 1, 2, 3, 4, 5 ]
script = [ 'tell application "IDL" to copy variable "A"', $
'into aVariable', $
'tell application "Excel" to copy aVariable to', $
IDL Reference Guide DO_APPLE_SCRIPT
'value of range "R1C1:R5C1" of worksheet 1' ]
DO_APPLE_SCRIPT, script
See Also
Chapter 5, Apple Script Support, in the IDL External Development Guideor
Chapter 5, The IDL for Macintosh Interface , in theIDL Users Guide.
DOC_LIBRARY IDL Reference Guide
DOC_LIBRARY
The DOC_LIBRARY procedure extracts documentation headers from one or more IDL
programs(proceduresor functions). Thiscommand providesastandard interfacetothe
operating-system specic DL_DOS, DL_UNIX, and DL_VMS procedures.
The documentation header of the.pro le in question must have the following format:
The rst line of the documentation block contains only the characters;+, starting in
column 1.
The last line of the documentation block contains only the characters;-, starting in
column 1.
All other lines in the documentation block contain a; in column 1.
Theletemplate.pro in thegeneral subdirectory of theexamples subdirectory of
the IDL distribution contains a template for creating your own documentation headers.
This routine is supplied for users to view online documentation from their own IDL
programs. Though it could be used to view documentation headers from thelib
subdirectory of the IDL distribution, we do not recommend doing so. The
documentation headers on the les in thelib directory are used for historical
purposesmost do not contain the most current or accurate documentation for those
routines. The most current documentation for IDLs built-in and library routines is
found in IDLs online help system (enter ? at the IDL prompt).
doc_library.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
DOC_LIBRARY[, Name]
Arguments
Name
A string containing the name of the IDL routine in question. Under Windows or Unix,
Namecan be"*" to get information on all routines.
Keywords (All Platforms)
PRINT
Set this keyword to send the output of DOC_LIBRARY to the default printer. Under
Unix, if PRINT is a string, it is interpreted as a shell command used for output with the
IDL Reference Guide DOC_LIBRARY
documentation from DOC_LIBRARY providing standard input (i.e., PRINT="cat >
junk").
Unix Keywords
DIRECTORY
Astringcontainingthenameof thedirectory to search. If omitted, thecurrent directory
and !PATH are used.
MULTI
Set thiskeyword to allowprintingof morethan oneleif therequested moduleexistsin
more than one directory.
VMS Keywords
FILE
If thiskeyword isset, theoutput isleft in theleuserlib.doc, in thecurrent directory.
PATH
A string that describes an optional directory/library search path. This keyword uses the
same format and semantics as !PATH. If omitted, !PATH is used.
OUTPUTS
If this keyword is set, documentation is sent to the standard output unless the PRINT
keyword is set.
Example
To view the documentation header for the library function DIST, enter:
DOC_LIBRARY, 'DIST'
See Also
MK_HTML_HELP
DOUBLE IDL Reference Guide
DOUBLE
TheDOUBLEfunctionreturnsaresult equal toExpressionconvertedtodouble-precision
oating-point.
Calling Sequence
Result = DOUBLE(Expression[ , Offset [ , Dim
1
, ..., Dim
n
] ] )
Arguments
Expression
The expression to be converted to double-precision oating-point.
Offset
of data extracted fromExpression to be treated as double-precision oating-point data.
SeethedescriptioninConstantsandVariables onpage11of BuildingIDLApplications
for details.
D
i
i
Example
Supposethat Acontainstheinteger value45. Adouble-precision, oating-point version
of A can be stored in B by entering:
B = DOUBLE(A)
See Also
BYTE, COMPLEX, DCOMPLEX, FIX, FLOAT, LONG, LONG64, STRING, UINT,
ULONG, ULONG64
IDL Reference Guide EFONT
EFONT
The EFONT procedure provides a simple widget-based vector font editor and display.
Usethisproceduretoread and/or modifyalocal copyof thelehersh1.chr, located in
the main IDL directory, which contains the vector fonts used by IDL in plotting. This is
avery rudimentary editor. Click theHelp button on theEFONT main menu for more
information.
efont.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
EFONT, Init_Font
Arguments
Init_Font
The initial font index, from 3 to 29. The default is 3.
Keyword
BLOCK
Set this keyword to have XMANAGERblock when this application is registered. By
default, BLOCK is set equal to zero, providing access to the command line if active
command line processing is available. Note that setting BLOCK=1 will causeall widget
applications to block, not just this application. For more information, see the
documentation for the NO_BLOCK keyword to XMANAGER.
GROUP
The widget ID of the widget that calls EFONT. If GROUP is set, the death of the caller
results in the death of EFONT.
See Also
SHOWFONT, XFONT
EIGENQL IDL Reference Guide
EIGENQL
The EIGENQL function computes the eigenvalues and eigenvectors of an n by n real,
symmetricarray usingHouseholder reductionsand theQL method with implicit shifts.
The result is an n-element vector containing the eigenvalues.
Calling Sequence
Result = EIGENQL(A)
Arguments
A
An n by n symmetric single- or double-precision oating-point array.
Keywords
ABSOLUTE
Set thiskeyword to sort theeigenvaluesby their absolutevalue(their magnitude) rather
than by their signed value.
ASCENDING
Set this keyword to return eigenvalues in ascending order (smallest to largest). If not set
or set to zero, eigenvalues are returned in descending order (largest to smallest). The
eigenvectors are correspondingly reordered.
DOUBLE
EIGENVECTORS
Set this keyword equal to a named variable that will contain the computed eigenvectors
in an n by n array. Thei
th
row of the returned array contains thei
th
eigenvalue. This
keyword must be initialized to a nonzero value before calling EIGENQL if the
eigenvectors are desired. If no variable is supplied, the array will not be computed.
OVERWRITE
Set this keyword to use the input array for internal storage and to overwrite its previous
contents.
RESIDUAL
Use this keyword to specify a named variable that will contain the residuals for each
eigenvalue/eigenvector (/x) pair. Theresidual isbasedonthedenitionAx-()x=0and
is an array of the same size as A and the same type as Result. The rows of this array
correspond to the residuals for each eigenvalue/eigenvector pair. This keyword must be
initialized to a nonzero value before calling EIGENQL if the residuals are desired.
IDL Reference Guide EIGENQL
NoteIf the OVERWRITE keyword is set, the RESIDUAL keyword has no effect.
Example
Dene an n by n real, symmetric array:
A = [[ 5.0, 4.0, 0.0, -3.0], $
[ 4.0, 5.0, 0.0, -3.0], $
[ 0.0, 0.0, 5.0, -3.0], $
[-3.0, -3.0, -3.0, 5.0]]
residual = 1 & evecs = 1 Thevariablesthatwill containthe
residualsandeigenvectorsmustbe
initializedasnonzerovaluesprior
to callingEIGENQL.
eigenvalues = EIGENQL(A, EIGENVECTORS = evecs, RESIDUAL = residual)
Computetheeigenvalues and
eigenvectors.
PRINT, eigenvalues Print theeigenvalues/.
IDL prints:
12.0915 6.18661 1.00000 0.721870
Print the eigenvectors:
PRINT, evecs
IDL prints:
-0.554531 -0.554531 -0.241745 0.571446
0.342981 0.342981 -0.813186 0.321646
0.707107 -0.707107 -2.58096e-08 0.00000
0.273605 0.273605 0.529422 0.754979
The accuracy of each eigenvalue/eigenvector (/x) pair may be checked by printing the
residual array:
PRINT, residual
The RESIDUAL array has the same dimensions as the input array and the same type as
the result. The residuals are contained in the rows of the RESIDUAL array. All residual
values should be oating-point zeros.
See Also
EIGENVEC, TRIQL
EIGENVEC IDL Reference Guide
EIGENVEC
The EIGENVEC function computes the eigenvectors of an n by n real, non-symmetric
array using Inverse Subspace Iteration. The result is a complex array with a column
dimension equal to n and a row dimension equal to the number of eigenvalues. Use
ELMHES and HQR to nd the eigenvalues of an n by n real, nonsymmetric array.
eigenvec.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = EIGENVEC(A, Eval)
Arguments
A
An n by n nonsymmetric, single- or double-precision oating-point array.
EVAL
An n-element complex vector of eigenvalues.
Keywords
DOUBLE
ITMAX
Themaximumnumber of iterationsallowedin thecomputation of eacheigenvector. The
default value is 4.
RESIDUAL
Use this keyword to specify a named variable that will contain the residuals for each
eigenvalue/eigenvector (/x) pair. Theresidual isbased on thedenition Ax- x= 0and
is an array of the same size and type as that returned by the function. The rows of this
array correspond to the residuals for each eigenvalue/eigenvector pair.
Note Thiskeywordmust beinitializedtoanon-zerovaluebeforecallingEIGENVECif the
residuals are desired.
Example
Dene an n by n real, nonsymmetric array.
A = [[1.0, -2.0, -4.0, 1.0], $
IDL Reference Guide EIGENVEC
[0.0, -2.0, 3.0, 4.0], $
[2.0, -6.0, -1.0, 4.0], $
[3.0, -3.0, 1.0, -2.0]]
Computetheeigenvaluesof A usingdouble-precision complex arithmeticand print the
result:
eval = HQR(ELMHES(A), /DOUBLE)
PRINT, eval
IDL prints:
( 0.26366255, -6.1925899)( 0.26366255, 6.1925899)
( -4.9384492, 0.0000000)( 0.41112406, 0.0000000)
Computetheeigenvectorsof A. Theeigenvectorsarereturnedin therowsof theresulting
array.
residual = 1 Notethat theRESIDUAL array
must beinitialized to a nonzero
value.
evec = EIGENVEC(A, eval, RESIDUAL = residual)
Print the eigenvectors.
PRINT, evec[*,0], evec[*,1], evec[*,2], evec[*,3]
IDL prints:
( 0.0076733129, -0.42912489)( 0.40651652, 0.32973069)
( 0.54537624, -0.28856257)( 0.33149359, -0.22632585)
( -0.42145884, -0.081113711)( 0.23867007, 0.46584824)
( -0.39497143, 0.47402647)( -0.28990600, 0.27760747)
( -0.54965842, 0.0000000)( -0.18401243, 0.0000000)
( -0.58124548, 0.0000000)( 0.57111192, 0.0000000)
( 0.79297048, 0.0000000)( 0.50289130, 0.0000000)
( -0.049618509, 0.0000000)( 0.34034720, 0.0000000)
You can check the accuracy of each eigenvalue/eigenvector (/x) pair by printing the
residual array. All residual values should be oating-point zeros.
See Also
ELMHES, HQR, TRIQL, TRIRED
ELMHES IDL Reference Guide
ELMHES
TheELMHESfunction reducesareal, nonsymmetricnbynarrayAtoupper Hessenberg
form. Theresult isan upper Hessenbergarraywith eigenvaluesthat areidentical tothose
of the original array A. The Hessenberg array is stored in elements (j, i) with i j + 1.
Elementswith i > j + 1areto bethought of aszero, but arereturned with randomvalues.
ELMHESisbased on theroutineelmhes described in section 11.5of Numerical Recipes
Calling Sequence
Result = ELMHES(A)
Arguments
A
An n by n real, nonsymmetric array.
Keywords
DOUBLE
COLUMN
Set this keyword if the input array A is in column-major format (composed of column
vectors) rather than in row-major format (composed of row vectors).
NO_BALANCE
Set this keyword to disable balancing. By default, a balancing algorithm is applied to A.
Balancinganonsymmetricarrayisrecommendedtoreducethesensitivityof eigenvalues
to rounding errors.
Example
See the description of HQR for an example using this function.
See Also
EIGENVEC, HQR, TRIQL, TRIRED
IDL Reference Guide EMPTY
EMPTY
The EMPTY procedure causes all buffered output for the current graphics device to be
written. IDL usesbuffered output on many display devicesfor reasonsof efciency. This
buffering leads to rare occasions where a program needs to be certain that data are not
waitingin abuffer, but haveactuallybeen output. EMPTYisalow-level graphicsroutine.
IDLgraphicsroutinesgenerallyhandleushingof buffereddatatransparentlytotheuser,
so the need for EMPTY is very rare.
Calling Sequence
EMPTY
See Also
FLUSH
EOF IDL Reference Guide
EOF
The EOF function tests the specied le unit for the end-of-le condition. If the le
pointer is positioned at the end of the le, EOF returns true (1), otherwise false (0) is
returned.
Note that the EOF function cannot be used with les opened with the NOSTDIO
keyword to the OPEN routines. Many of the devices commonly used with NOSTDIO
signal their end-of-le by returning a zero transfer count to the I/O operation that
encounters the end-of-le.
Calling Sequence
Result = EOF(Unit)
Arguments
Unit
The le unit to test for end-of-le.
Using EOF with VMS Files
Under VMS, theEOFfunction doesnot work with lesaccessed viaDECNET or that do
not havesequential organization (i.e., relativeor indexed). TheEOFprocedurecannot be
used with such les as it will always return false. Instead, use the ON_IOERROR
procedure to detect when the end-of-le occurs.
Examples
If leunit number 1isopen, theend-of-lecondition can bechecked by examiningthe
value of the expression EOF(1). For example, the following IDL code reads and prints a
text le:
OPENR, 1, 'test.lis' Open thefiletest.lis.
A = '' Definea stringvariable.
WHILE NOT EOF(1) DO BEGIN Loop until EOF is found.
READF, 1, A Read a lineof text.
PRINT, Print theline.
ENDWHILE
CLOSE, 1 Closethefile.
See Also
POINT_LUN
IDL Reference Guide ERASE
ERASE
TheERASEprocedureerasesthescreenof thecurrentlyselectedgraphicsdevice(or starts
a new page if the device is a printer). The device is reset to alphanumeric mode if it has
such a mode (e.g., Tektronix terminals).
Calling Sequence
ERASE[, Background_Color]
Arguments
Background_Color
The color index for the screen to be erased to. If this argument is omitted ERASE resets
the screen to the default background color (normally 0), stored in the system variable
!P.BACKGROUND. Providing a value for Background_Color overrides the default.
Warning: Not all devices support this feature.
Keywords
CHANNEL
The channel or channel mask for the erase operation. This parameter has meaning only
whenusedwithdevicesthat support true-color or multiple-displaychannels. Thedefault
value is !P.CHANNEL.
COLOR
Species the background color. Using this keyword is analogous to using the
Background_Color argument.
Example
TV, DIST(255) Displayasimpleimageinthecur-
rent window.
ERASE Erasetheimagefromthewindow.
See Also
SET_PLOT, WINDOW, WSET
ERODE IDL Reference Guide
ERODE
The ERODE function implements the erosion operator on binary and grayscale images
and vectors.
Seethedescription of theDILATEfunction for backgroundon morphological operators.
Erosion is the dual of dilation. It does to the background what dilation does to the
foreground.
Briey, the ERODE function returns the erosion of Imageby the structuring element
Structure. This operator is commonly known as shrink or reduce. It can be used to
remove islands smaller than the structuring element.
Over each pixel of the image, the origin of the structuring element is overlaid. If each
nonzeroelement of thestructuringelement iscontained in theimage, theoutput pixel is
set to one. LettingA B represent the erosion of an imageA by structuring element B,
erosion can be dened as:
where(A)
-b
represents the translation of A by b. The structuring element B can be
visualized as a probe that slides across imageA, testing the spatial nature of A at each
point. If B translated by i,j can be contained in A (by placing the origin of B at i,j), then
i,j belongs to the erosion of A by B. For example:
In this example, the origin of the structuring element is at (0, 0).
Used with grayscale images, which are always converted to byte type, the ERODE
function isaccomplished by takingtheminimumof aset of differences. It can beused to
conveniently implement the neighborhood minimum operator with the shape of the
neighborhood given by the structuring element.
Calling Sequence
Result = ERODE(Image, Structure[, X
0
[, Y
0
[, Z
0
]]])
C A B A ( )
b
b B
= =
0100
0100
1110
1000
0000
11
0000
0000
1100
0000
0000
=
IDL Reference Guide ERODE
Arguments
Image
A one-, two-, or three-dimensional array upon which the erosion is to be performed. If
this parameter is not of byte type, a temporary byte copy is obtained. If neither of the
keywords GRAY or VALUES is present, the image is treated as a binary image with all
nonzero pixels considered as 1.
Structure
A one-, two-, or three-dimensional array to be used as the structuring element. The
elements are interpreted as binary valueseither zero or nonzero. The structuring
element must have the same number of dimensions asImage.
X
0
, Y
0
, Z
0
Optional parameters specifying the one-, two-, or three-dimensional coordinate of the
structuring elements origin. If omitted, the origin is set to the center, ([ N
x
/2] , [ N
y
/2] ,
[ N
z
/2] ), whereN
x
, N
y
, and N
z
are the dimensions of the structuring element array. The
origin need not be within the structuring element.
Keywords
GRAY
Set thiskeyword to performgrayscale, rather than binary, erosion. Nonzero elementsof
theStructureparameter determinetheshapeof thestructuringelement (neighborhood).
If VALUES is not present, all elements of the structuring element are 0, yielding the
neighborhood minimum operator.
VALUES
An array of the same dimensions asStructureproviding the values of the structuring
element. Thepresenceof thiskeyword impliesgrayscaleerosion. Each pixel of theresult
is the minimum of Image less the corresponding elements of VALUE. If the resulting
difference is less than zero, the return value will be zero.
Example
The following example thresholds a gray scale image at the value of 100, producing a
binaryimage. Theresult isthen opened with a3pixel by3pixel squareshapeoperator,
using the ERODE and DILATE operators. The effect is to remove holes, islands, and
peninsula smaller than the shape operator:
B = A GE 100 Threshold and makebinary im-
age.
S = REPLICATE(1, 3, 3) Createtheshapeoperator.
C = DILATE(ERODE(B, S), S) Opening operator.
TVSCL, C Show theresult.
ERODE IDL Reference Guide
See Also
DILATE
IDL Reference Guide ERRORF
ERRORF
The ERRORF function returns the value of the error function:
The result is a double-precision if the argument is double-precision. If the argument is
oating-point, theresult isoating-point. Theresult alwayshasthesamestructureasX.
The ERRORF function does not work with complex arguments.
Calling Sequence
Result = ERRORF(X)
Arguments
X
The expression for which the error function is to be evaluated.
Example
To nd the error function of 0.4 and print the result, enter:
PRINT, ERRORF(0.4)
IDL prints:
0.428392
See Also
GAMMA, IGAMMA, EXPINT
erf x ( ) 2 e
t
2
t d
0
x
=
ERRPLOT IDL Reference Guide
ERRPLOT
The ERRPLOT procedure plots error bars over a previously drawn plot.
errplot.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
ERRPLOT, [ X, ] Low, High
Arguments
X
A vector containing the abscissa values at which the error bars are to be plotted. X only
needs to be provided if the abscissa values are not the same as the index numbers of the
plotted points.
Low
A vector of lower estimates, equal to data - error.
High
A vector of upper estimates, equal to data + error.
Keywords
WIDTH
The width of the error bars. The default is 1% of plot width.
Examples
Toplot symmetrical error barswhereYisavector of datavaluesandERRisasymmetrical
error estimate, enter:
PLOT, Y Plot data.
ERRPLOT, Y-ERR, Y+ERR Overplot error bars.
If error estimates are non-symmetrical, provide actual error estimates in theupper and
lower arguments.
PLOT,Y Plot data.
ERRPLOT, lower, upper Providecustomlowwerandupper
bounds.
To plot versus a vector of abscissas:
IDL Reference Guide ERRPLOT
PLOT, X, Y Plot data (X versus Y).
ERRPLOT, X, Y-ERR, Y+ERR Overplot error estimates.
See Also
OPLOTERR, PLOT, PLOTERR
EXECUTE IDL Reference Guide
EXECUTE
TheEXECUTEfunction compilesandexecutesoneor moreIDLstatementscontainedin
a string at run-time. It also returns true(1) if the string was successfully compiled and
executed. If an error occurs during either phase, the result isfalse(0).
LiketheCALL_PROCEDUREand CALL_FUNCTION routines, callsto EXECUTEcan
be nested. However, compiling the string at run-time is inefcient. CALL_FUNCTION
and CALL_PROCEDURE provide much of the functionality of EXECUTE without
imposing this limitation, and should be used instead of EXECUTE whenever possible.
Calling Sequence
Result = EXECUTE(String [, QuietCompile])
Arguments
String
A string containing the command(s) to be compiled and executed.
QuietCompile
If this argument is set to a non-zero value, EXECUTE will not print the compiler
generated error messages(such assyntax errors). If QuietCompileisomitted or set to 0,
EXECUTE will output such errors.
Example
Create a string that holds a valid IDL command by entering:
com = 'PLOT, [0,1]'
Execute the contents of the string by entering:
R = EXECUTE(com)
A plot should appear. You can conrm that the string was successfully compiled and
executed by checking that the value of R is 1.
See Also
CALL_FUNCTION, CALL_PROCEDURE
IDL Reference Guide EXIT
EXIT
The EXIT procedure quits IDL and exits back to the operating system. All buffers are
ushed and open les are closed. The values of all variables that were not saved are lost.
Calling Sequence
EXIT
Keywords
NO_CONFIRM
Set thiskeyword to suppressany conrmation dialogthat would otherwisebedisplayed
in a GUI version of IDL such as the IDL Development Environment.
STATUS
Set this keyword equal to an exit status code that will be returned when IDL exits. For
example, on a Unix system using the Bourne shell:
$ idl Start IDL
IDL> exit, status=45 Exit, specifyingexit status 45
$ echo $? Display last exit status code
45
See Also
CLOSE, FLUSH, STOP, WAIT
EXP IDL Reference Guide
EXP
The EXP function returns the natural exponential function of Expression.
Calling Sequence
Result = EXP(Expression)
Arguments
Expression
Theexpression tobeevaluated. If Expressionisdouble-precision oatingor complex, the
result isof thesametype. All other typesareconverted tosingle-precision oating-point
and yield oating-point results. The denition of the exponential function for complex
arguments is:
EXP(x) = COMPLEX(e
R
cosI, e
R
sin I)
where:
R= real part of x, and I = imaginary part of x. If Expressionisan array, theresult hasthe
samestructure, witheachelement containingtheresult for thecorrespondingelement of
Expression.
Example
Plot a Gaussian with a 1/e width of 10 and a center of 50 by entering:
PLOT, EXP(-(FINDGEN(100)/10. - 5.0)^2)
See Also
ALOG
IDL Reference Guide EXPAND
EXPAND
The EXPAND procedure shrinks or expands a two-dimensional array, using bilinear
interpolation. It is similar to the CONGRID and REBIN routines.
expand.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
EXPAND, A, Nx, Ny, Result
Arguments
A
A two-dimensional array to be magnied.
Nx
Desired size of the X dimension, in pixels.
Ny
Desired size of the Y dimension, in pixels.
Result
A named variable that will contain the magnied array.
Keywords
MAXVAL
Set this keyword equal to the largest good value. Elements greater than this value are set
equal to the value of the FILLVAL keyword.
FILLVAL
Set this keyword equal to the value to use when elements larger than MAXVAL are
encountered. The default is -1.
See Also
CONGRID, REBIN
EXPAND_PATH IDL Reference Guide
EXPAND_PATH
TheEXPAND_PATHfunctionisusedtoexpandasimplepath-denitionstringintoafull
path name for use with the !PATH system variable.
!PATH is a list of locations where IDL searches for currently undened procedures and
functions.
The Path Denition String
EXPAND_PATH accepts a single argument, a scalar string that contains a simple path-
denition string, that thefunction expandsinto alist of directoriesthat can beassigned
to !PATH. This string uses the same format as the IDL_PATH environment variable
(Unix, Windows) or logical name(VMS). Thisformat isalsousedin thepathpreferences
dialog (Windows, Macintosh).
Thepath-denition stringisascalar stringcontainingalist of directories(andin thecase
of VMS, text library lesthat areprexed with the @ character), separated by aspecial
character ( : for Unix andMacintosh, , for VMS, and ; for Windows). Prepending
a + character to a directory name causes all of its subdirectories to be searched.
If a directory specied in the string doesnot have a + character prepended to it, it is
copied to the output string verbatim. However, if it does have a leading + then
EXPAND_PATH performs the following steps, searching each subdirectory of the
specieddirectoryrecursivelyfor other subdirectories. All directoriesfoundthat contain
at least one le of the desired type are added to the search path.
A Note on Order within !PATH
IDL ensuresonly that all directoriescontainingIDL lesareplaced in !PATH. Theorder
in which they appear is completely unspecied, and does not necessarily correspond to
anyspecicorder (suchastop-downalphabetized). ThisallowsIDLtoconstruct thepath
in thefastest possiblewayandspeedsstartup. Thisisonlyaproblemif twosubdirectories
in such a hierarchy contain a le with the same name. Such hierarchies usually are a
collection of cooperative routines designed to work together, so such duplication is rare.
If the order in which + expands directories is a problem for your application, you
shouldaddthedirectoriestothepathexplicitlyandnot use +. Onlytheorder of theles
withinagiven+ entryaredeterminedbyIDL. It never reorders!PATHinanyother way.
You can therefore obtain any search order you desire by writing the path explicitly.
Unix: The directory name is expanded to remove wildcards (~ and *). This avoids
overheadIDLwouldotherwiseincur asit searchesfor libraryroutines. It isdiscardedfrom
the search path if any of the following is true:
It is not a directory.
The directory it names does not exist or cannot be accessed.
The directory does not contain any .pro or .sav les.
IDL Reference Guide EXPAND_PATH
VMS:Thedirectorynameisdiscardedfromthesearchpathif anyof thefollowingistrue:
The directory does not contain any .PRO or .SAV les).
In addition, any text library (.TLB) les are added to the result.
Windows:Thedirectory nameisexpanded to removewildcards(*). Thisavoidsover-
head IDL would otherwise incur as it searches for library routines. It is discarded from
the search path if any of the following is true:
The directory does not contain any .PRO or .SAV les.
Macintosh:Thefolder nameisexpandedtoremovewildcards(*). Thisavoidsoverhead
IDL would otherwise incur as it searches for library routines. It is discarded from the
search path if any of the following is true:
It is not a folder.
The folder it names does not exist or cannot be accessed.
The folder does not contain any .pro or .sav les.
Calling Sequence
Result = EXPAND_PATH(String)
Arguments
String
A scalar string containing the path-denition string to be expanded. See The Path
Denition String, above, for details.
Keywords
ARRAY
Set this keyword to return the result as a string array with each element containing one
pathsegment. In thiscase, thereisnoneedfor aseparator character andnoneissupplied.
Normally, the result is a string array with the various path segments separated with the
correct special delimiter character for the current operating system.
COUNT
Set this keyword to a named variable which returns the number of path segments
contained in the result.
EXPAND_PATH IDL Reference Guide
Example
Under the Unix operating system, the default value of !PATH is specied as
+/usr/local/rsi/idl/lib, unlessthisdefault ischangedbysettingtheIDL_PATH
environment variable. WhenIDLstarts, oneof therst thingsit doesistorunthisdefault
value through the EXPAND_PATH function to obtain the actual value for the !PATH
system variable. The following statement shows how this expansion might look
(assuming that your IDL is installed in /usr/local/rsi/idl):
PRINT, EXPAND_PATH('+/usr/local/rsi/idl/lib')
IDL prints:
/usr/local/rsi/idl/lib
See Also
Executing Program Files on page 29 of Using IDL and IDL Environment System
Variables on page 42 of the IDL Reference Guide.
IDL Reference Guide EXPINT
EXPINT
The EXPINT function returns the value of the exponential integral E
n
(x).
EXPINT isbased on theroutineexpint described in section 6.3of Numerical Recipesin
C: TheArt of ScienticComputing(Second Edition), published by CambridgeUniversity
Press, and is used by permission.
Calling Sequence
Result = EXPINT(N, X)
Arguments
N
An integer specifying the order of E
n
(x). N can be either a scalar or an array.
X
The value at which E
n
(x) is evaluated. X can be either a scalar or an array.
Note: If an array isspecied for both Nand X, then EXPINT evaluatesE
n
(x) for each N
i
and X
i
. If either N or X is a scalar and the other an array, the scalar is paired with each
array element in turn.
Keywords
DOUBLE
ITMAX
An input integer specifying the maximum allowed number of iterations. The default
value is 100.
EPS
Use this keyword to specify a number close to the desired relative error. For single-
precision calculations, the default value is 1.0 10
-7
. For double-precision calculations,
the default value is 1.0 10
-14
.
Example
To compute the value of the exponential integral at the following X values:
X = [1.00, 1.05, 1.27, 1.34, 1.38, 1.50]
Definetheparametric X values.
EXPINT IDL Reference Guide
result = EXPINT(1, X) Computetheexponential integral
of order 1.
IDL prints:
0.219384 0.201873 0.141911 0.127354 0.119803 0.100020
This is the exact solution vector to six-decimal accuracy.
See Also
ERRORF
IDL Reference Guide EXTRAC
EXTRAC
TheEXTRACfunction returnsasitsresult any rectangular sub-matrix or portion of the
parameter array. Note that it is usually more efcient to use the array subscript ranges
(the : operator; see Subscript Ranges on page 64 of Building IDL Applications) to
perform such operations. The main advantage to EXTRAC is that, when parts of the
specied subsection lie outside the bounds of the array, zeros are entered into these
outlying elements.
EXTRAC was originally a built-in system procedure in the PDP-11 version of IDL, and
was retained in that form in the original VAX/VMS IDL for compatibility. Most
applications of the EXTRAC function are more concisely written using subscript ranges
(e.g., X(10:15)). EXTRAChasbeen rewritten asalibraryfunction that providesthesame
interface as the previous versions.
Note If you knowthat thesubarray will never liebeyond theedgesof thearray, it ismore
efcient tousearraysubscript ranges(the : operator) toextract thedatainsteadof
EXTRAC.
extrac.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = EXTRAC(Array, C
1
, C
2
, ..., C
n
, S
1
, S
2
, ..., S
n
)
Arguments
Array
The array from which the subarray will be copied.
C
i
The starting subscript in Array for the subarray. There should be oneC
i
for each
dimension of Array. These arguments must be integers.
S
i
The size of each dimension. The result will have dimensions of (S
1
, S
2
, ..., S
n
). There
should be oneS
i
for each dimension of Array. These arguments must be non-negative.
Examples
Extracting elements from a vector:
A = FINDGEN(1000) Createa 1000 element floating-
pointvectorwitheachelementset
to thevalueof its subscript.
EXTRAC IDL Reference Guide
B = EXTRAC(A, 200, 300) Extract 300 points startingat
A[200] and extendingto A[499].
In the next example, the rst 49 points extractedB[0] to B[49]lie outside the
bounds of the vector and are set to 0. B[50] is gets the value of A[0], B[51] gets the
value of A[1]which is 1. Enter:
A = FINDGEN(1000) Createa 1000 element vector.
B = EXTRAC(A, -50, 100) Extract 50 elements, 49 of which
lieoutsidethebounds of A.
The following commands illustrate the use of EXTRAC with multi-dimensional arrays.
Enter:
A = INTARR(64,64) Makea 64 by 64 array.
B = EXTRAC(A, 20, 30, 32, 32) Extracta32by32portionstarting
at A(20,30).
As suggested in the discussion above, a better way to perform the same operation as the
previous line is:
B = A(20:51, 30:61) Usethearray subscript operator
instead of EXTRAC.
Extract the 20th column and 32nd row of A:
B = EXTRAC(A, 19, 0, 1, 64) Extract 20th column of A.
B = EXTRAC(A, 0, 31, 64, 1) Extract 32nd row of A.
Take a 32 BY 32 matrix from A starting at A(40,50):
B = EXTRAC(A, 40, 50, 32, 32) Notethatthosepointsbeyondthe
boundaries of A areset to 0.
See Also
Subscript Ranges on page 64 of Building IDL Applications.
IDL Reference Guide EXTRACT_SLICE
EXTRACT_SLICE
This EXTRACT_SLICE function returns a two-dimensional planar slice extracted from
3D volumetricdata. Theslicingplanecan beoriented at any angleand passthrough any
desired location in the volume.
extract_slice.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = EXTRACT_SLICE(Vol, Xsize, Ysize, Xcenter, Ycenter, Zcenter, Xrot, Yrot, Zrot)
Arguments
Vol
Thevolumeof datatoslice. Thisargument isathree-dimensional arrayof anytypeexcept
stringor structure. Theplanar slicereturnedbyEXTRACT_SLICEhasthesamedatatype
asVol.
Xsize
ThedesiredXsize(dimension0) of thereturnedslice. Topreservethecorrect aspect ratio
of thedata, Xsizeshouldequal Ysize. For optimal results, set XsizeandYsizetobegreater
than or equal to the largest of the three dimensions of Vol.
Ysize
ThedesiredYsize(dimension 1) of thereturnedslice. Topreservethecorrect aspect ratio
of thedata, Ysizeshouldequal Xsize. For optimal results, set XsizeandYsizetobegreater
than or equal to the largest of the three dimensions of Vol.
Xcenter
The X coordinate (index) of the point within the volume that the slicing plane passes
through. The center of the slicing plane passes through Vol at the coordinate (Xcenter,
YCenter, Zcenter).
Ycenter
The Y coordinate (index) of the point within the volume that the slicing plane passes
YCenter, Zcenter).
Zcenter
The Z coordinate (index) of the point within the volume that the slicing plane passes
YCenter, Zcenter).
EXTRACT_SLICE IDL Reference Guide
Xrot
The X-axis rotation of the slicing plane, in degrees. Before transformation, the slicing
planeisparallel totheX-Yplane. Theslicingplanetransformationsareperformedin the
following order:
Rotate Z_rot degrees about the Z axis.
Rotate Y_rot degrees about the Y axis.
Rotate X_rot degrees about the X axis.
Translate the center of the plane to Xcenter, Ycenter, Zcenter.
Yrot
The Y-axis rotation of the slicing plane, in degrees.
Zrot
The orientation Z-axis rotation of the slicing plane, in degrees.
Keywords
RADIANS
Set this keyword to indicate that Xrot, Yrot, and Zrot are in radians. The default is
degrees.
OUT_VAL
Set this keyword to a value that will be assigned to elements of the returned slice that lie
outside of the original volume.
SAMPLE
Set this keyword to perform nearest neighbor sampling when computing the returned
slice. The default is to use bilinear interpolation. A small reduction in execution time
results when SAMPLE is set and the OUT_VAL keyword isnot used.
Example
Display an oblique slice through volumetric data:
vol = RANDOMU(s, 40, 40, 40) Createsomedata.
FOR i=0, 10 DO vol = SMOOTH(vol, 3) Smooth thedata.
vol = BYTSCL(vol(3:37, 3:37, 3:37)) Scalethesmoothed part into the
rangeof bytes
slice = EXTRACT_SLICE(vol, 40, 40, 17, 17, 17, 30.0, 30.0, 0.0, $
OUT_VAL=0B) Extract a slice.
TVSCL, REBIN(slice, 400, 400) Displaythe2Dsliceasamagni-
ed image.
See Also
SLICER3
IDL Reference Guide F_CVF
F_CVF
TheF_CVFfunction computesthecutoff valueVin an Fdistribution with Dfnand Dfd
degreesof freedomsuch that theprobabilitythat arandomvariableXisgreater than Vis
equal to a user-supplied probability P.
f_cvf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = F_CVF(P, Dfn, Dfd)
Arguments
P
Dfn
number of degrees of freedom of the F distribution numerator.
Dfd
number of degrees of freedom of the F distribution denominator.
Example
Use the following command to compute the cutoff value in an F distribution with ten
degreesof freedomin thenumerator andsixdegreesof freedomin thedenominator such
that theprobability that arandomvariableX isgreater than thecutoff valueis0.01. The
PRINT, F_CVF(0.01, 10, 6)
IDL prints:
7.87413
See Also
CHISQR_CVF, F_PDF, GAUSS_CVF, T_CVF
F_PDF IDL Reference Guide
F_PDF
TheF_PDFfunction computestheprobability Pthat, in an Fdistribution with Dfnand
Dfddegreesof freedom, arandomvariableXislessthanor equal toauser-speciedcutoff
valueV.
f_pdf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = F_PDF(V, Dfn, Dfd)
Arguments
V
value.
Dfn
number of degrees of freedom of the F distribution numerator.
Dfd
number of degrees of freedom of the F distribution denominator.
Example
the F distribution with ve degrees of freedom in the numerator and 24 degrees of
freedomin thedenominator, islessthan or equal to 3.90. Theresult should be0.990059.
PRINT, F_PDF(3.90, 5, 24
IDL prints:
0.990059
See Also
BINOMIAL, CHISQR_PDF, F_CVF, GAUSS_PDF, T_PDF
IDL Reference Guide FACTORIAL
FACTORIAL
The FACTORIAL function computes the factorial N! as the double-precision product,
(N) (N-1) (N-2) ... 3 2 1.
factorial.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = FACTORIAL(N)
Arguments
N
A non-negative integer or long integer.
Note:largevaluesof Nwill causeoating-point overowerrors. Themaximumsizeof N
varies with machine architecture. On machines that support the IEEE standard for
oating-point arithmetic, themaximumvalueof Nis170. SeeMACHARfor adiscussion
of machine-specic parameters affecting oating-point arithmetic.
Keywords
STIRLING
Set this keyword to use Stirlings asymptotic formula to approximateN!:
whereeis the base of the natural logarithm.
Example
Compute 20!.
PRINT, FACTORIAL(20)
IDL prints:
2.4329020e+18
See Also
BINOMIAL, TOTAL
N! 2N
N
e
----
N
=
FFT IDL Reference Guide
FFT
The FFT function returns a result equal to the complex, discrete Fourier transform of
Array. The result of this function is a single- or double-precision complex array.
The discrete Fourier transform, F(u), of an N-element, one-dimensional function, f(x),
is dened as:
And the inverse transform, (Direction > 0), is dened as:
If the keyword OVERWRITE is set, the transform is performed in-place, and the result
overwrites the original contents of the array.
Theresult returned by FFT isacomplex array that hasthesamedimensionsastheinput
array. The output array is ordered in the same manner as almost all discrete Fourier
transforms. Element 0 contains the zero frequency component, F
0
. F
1
contains the
smallest nonzero positive frequency, which is equal to 1/(N
i
T
i
), where N
i
and T
i
are the
number of elements and the sampling interval of the i
th
dimension, respectively. F
2
corresponds to a frequency of 2/(N
i
T
i
). Negative frequencies are stored in the reverse
order of positivefrequencies, rangingfromthehighest tolowest negativefrequencies(see
storage scheme below).
Note The FFT can be performed on functions of up to eight (8) dimensions in size. If a
function hasndimensions, IDL performsatransformin each dimension separately,
starting with the rst dimension and progressing sequentially to dimension n. For
example, if thefunction hastwodimensions, IDL rst doestheFFT rowbyrow, and
then column by column.
For an even number of points in the i
th
dimension, the storage scheme of returned
complex values is as follows:
F
0
1/ (N
i
T
i
) ... (N
i
-2)/ 2N
i
T
i
1/ (2T
i
)
(Nyquist)
-(N
i
-2)/ 2N
i
T
i
... -1/ (N
i
T
i
)
Real, Imag Real, Imag Real, Imag Real, Imag Real, Imag Real, Imag
F u ( )
1
N
---- f x ( )exp j2ux N [ ]
x 0 =
N 1
=
f x ( ) F u ( )exp j2ux N [ ]
u 0 =
N 1
=
IDL Reference Guide FFT
For an odd number of points in the i
th
dimension, the storage scheme of returned
complex values is as follows:
Calling Sequence
Result = FFT(Array [, Direction])
Arguments
Array
The array to which the Fast Fourier Transform should be applied. If Array is not of
complex type, it isconverted to complex type. Thedimensionsof theresult areidentical
to those of Array. The size of each dimension may be any integer value and does not
necessarily haveto bean integer power of 2, although powersof 2arecertainly themost
efcient.
Direction
Direction is a scalar indicating the direction of the transform, which is negative by
convention for theforwardtransform, andpositivefor theinversetransform. If Direction
is not specied, the forward transform is performed.
A normalization factor of 1/N, whereN is the number of points, is applied during the
forward transform.
Note When transformingfromareal vector tocomplex and back, it isslightly faster toset
Direction to 1 in the real to complex FFT.
Note also that the value of Direction is ignored if the INVERSE keyword is set.
Keywords
DOUBLE
Set thiskeywordtoavalueother than zerotoforcethecomputation tobedonein double-
precision arithmetic, and to givearesult of double-precision complex type. If DOUBLE
is set equal to zero, computation is done in single-precision arithmetic and the result is
single-precision complex. If DOUBLE is not specied, the data type of the result will
match the data type of Array.
INVERSE
Set this keyword to perform an inverse transform. Setting this keyword is equivalent to
setting theDirection argument to a positive value. Note, however, that setting INVERSE
results in an inverse transform even if Direction is specied as negative.
F
0
1/ (N
i
T
i
) ... (N
i
-1)/ 2N
i
T
i
-(N
i
-1)/ 2N
i
T
i
... -1/ (N
i
T
i
)
Real, Imag Real, Imag Real, Imag Real, Imag Real, Imag
FFT IDL Reference Guide
OVERWRITE
If thiskeywordisset, andtheArrayparameter isavariableof complextype, thetransform
is done in-place. The result overwrites the previous contents of the variable. For
example, to perform a forward, in-place FFT on the variable a:
a = FFT(a, -1, /OVERWRITE)
Running Time
For aone-dimensional FFT, runningtimeisroughlyproportional tothetotal number of
pointsin Arraytimesthesumof itsprimefactors. Let Nbethetotal number of elements
in Array, and decomposeN into its prime factors:
Running time is proportional to:
whereT
3
~ 4T
2
. For example, the running time of a 263 point FFT is approximately 10
times longer than that of a 264 point FFT, even though there are fewer points. The sum
of the prime factors of 263 is 264 (1 + 263), while the sum of the prime factors of 264 is
20 (2 + 2 + 2 + 3 + 11).
Example
Display the log of the power spectrum of a 100-element index array by entering:
PLOT, /YLOG, ABS(FFT(FINDGEN(100), -1))
As a more complex example, display the power spectrum of a 100-element vector
sampledat arateof 0.1secondsper point. Showthe0frequencycomponent at thecenter
of the plot and label the abscissa with frequency:
N = 100 Definethenumber of points.
T = 0.1 Definetheinterval.
N21 = N/2 + 1 Midpoint+1 is themost negative
frequency subscript.
F = INDGEN(N) Thearray of subscripts.
F[N21] = N21 -N + FINDGEN(N21-2) Insert negativefrequencies in ele-
ments F(N/2 +1), ..., F(N-1).
F = F/(N*T) ComputeT
0
frequency.
PLOT, /YLOG, SHIFT(F, -N21), SHIFT(ABS(FFT(F, -1)), -N21)
Shiftsothatthemostnegativefre-
quency is plotted first.
N 2
K
2
3
K
3
5
K
5
... =
T
0
N T
1
2K
2
T
2
T
3
3K
3
5K
5
... + + ( ) + + ( ) +
IDL Reference Guide FFT
See Also
HILBERT
FILEPATH IDL Reference Guide
FILEPATH
The FILEPATH function returns the fully-qualied path to a le found in the IDL
distribution. Operating system dependencies are taken into consideration. This routine
isused byResearch Systemstomakethelibraryroutinesportable. Thisroutineiswritten
in the IDL language. Its source code can be found in the lefilepath.pro in thelib
subdirectory of the IDL distribution.
Calling Sequence
Result = FILEPATH(Filename)
Arguments
Filename
A string containing the name of the le to be found. The le should be specied in all
lowercase characters. No device or directory information should be included.
Keywords
ROOT_DIR
A string containing the name of the directory from which the resulting path should be
based. If not present, thevalueof !DIRisused. Thiskeyword isignored if TERMINAL or
TMP are specied.
SUBDIRECTORY
The name of the subdirectory in which the le should be found. If this keyword is
omitted, the main IDL directory is used. This variable can be either a scalar string or a
stringarray with thenameof each level of subdirectory depth represented asan element
of the array.
For example, to get a path to the lefilepath.pro in IDLslib subdirectory, enter:
path = FILEPATH('filepath.pro',SUBDIR=['lib'])
TERMINAL
Set this keyword to return the lename of the users terminal.
TMP
Set this keyword to indicate that the specied le is a scratch le. Returns a path to the
proper place for temporary les under the current operating system.
Note On theMacintosh, useof thiskeyword returnsthedirectory nameIDL_DIR:IDL
Temp File.
IDL Reference Guide FILEPATH
Under Microsoft Windows, FILEPATH checks to see if the following environment
variablesaresetTMP, TEMP, WINDIRandusesthevalueof therst oneit nds.
If none of these environment variables exists, \TMP is used as the temporary direc-
tory.
Example
Open the IDL distribution lepeople.dat, found in theimages subdirectory:
OPENR, 1, FILEPATH('people.dat', SUBDIRECTORY='images')
See Also
FINDFILE
FINDFILE IDL Reference Guide
FINDFILE
TheFINDFILEfunction returnsastringarray containingthenamesof all lesmatching
File_Specication.
All matched lenames are returned in a string array, one le name per array element. If
no les exist with names matching theFile_Specication a null scalar string is returned
instead of a string array. Except for VMS, described below, FINDFILE returns the full
path only if the path itself is specied in File_Specication. See the Examples section
below for details.
Note Platform specic differences are described below:
Under Macintosh, FINDFILEfunction bracketsthereturnedlenamein colonsif thele
is a folder (e.g., :lib:)
Under UNIX, to refer to all of the les in a directory only, use
FINDFILE(/File_Specication/*.*). To include all the les in any subdirectories, use
FINDFILE(/File_Specication/*)
Under VMS, FINDFILE returns thefull path specication for any le it nds.
Under Windows, FINDFILEappendsa \ character totheend of thereturned lename
if the le is a directory. To refer to all the les in a specic directory only, use FIND-
FILE(\File_Specication\*).
Calling Sequence
Result = FINDFILE(File_Specication)
Arguments
File_Specication
A scalar string used to nd les. The string can contain any valid command-interpreter
wildcard characters. If File_Specication contains path information, that path
information isincluded in thereturned value. If File_Specicationisomitted, thenames
of all les in the current directory are returned.
Keywords
COUNT
A named variable into which the number of les found is placed. If no les are found, a
value of 0 is returned.
IDL Reference Guide FINDFILE
Examples
To print thelenamesof all theUnix leswith dat extensionsin thecurrent directory,
use the command:
PRINT, FINDFILE('*.dat')
Toprint thefull path namesof all .pro lesin theIDL lib directorythat begin with the
letter x, use the command:
PRINT, FINDFILE('/usr/local/rsi/idl/lib/x*.pro')
To print the path names of all .pro les in theprofiles subdirectory of the current
directory (a relative path), use the command:
PRINT, FINDFILE('profiles/*.pro')
Note that the values returned are (like theFile_Specication) relative path names. Use
caution when comparing values against this type of relative path specication.
See Also
FILEPATH
FINDGEN IDL Reference Guide
FINDGEN
The FINDGEN function returns a single-precision, oating-point array with the
specied dimensions. Each element of thearray isset to thevalueof itsone-dimensional
subscript.
Calling Sequence
Result = FINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
To create F, a 6-element vector of single-precision, oating-point values where each
element is set to the value of its subscript, enter:
F = FINDGEN(6)
The value of F[ 0] is 0.0, F[ 1] is 1.0, et cetera.
See Also
BINDGEN, CINDGEN, DCINDGEN, DINDGEN, INDGEN, LINDGEN, LINDGEN,
IDL Reference Guide FINITE
FINITE
TheFINITEfunction returns1(True) if itsargument isnite. If theargument isinnite
or not a dened number (NaN), 0 (False) is returned. (See Special Floating-Point
Values on page 152 of Building IDL Applications for more information on IEEE
oating-point values.) The result is a byte expression of the same structure as the
argument X.
Calling Sequence
Result = FINITE(X)
Arguments
X
Aoating-point, double-precision, or complexscalar or arrayexpression. Stringsarerst
converted to oating-point. This function is meaningless for byte, integer, or longword
arguments.
Keywords
INFINITY
If INFINITYisset, FINITEreturnsTrueif Xispositiveor negativeinnity, andit returns
False otherwise.
NAN
If NAN is set, FINITE returns True if X is Not A Number (NaN), and it returns False
otherwise.
Example
To nd out if the logarithm of 5.0 is nite, enter:
PRINT, FINITE(ALOG(5.0))
IDL prints 1 because the argument is nite.
See Also
CHECK_MATH, MACHAR, and !VALUES on page 38.
FIX IDL Reference Guide
FIX
The FIX function returns a result equal to Expression converted to integer type.
Calling Sequence
Result = FIX(Expression [, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to integer.
Offset
of data extracted fromExpression to be treated as integer data. See the description in
Dim
i
i
valid integer and no conversion is possible. The default action in such cases is to print a
warningmessageand return 0. TheON_IOERRORprocedurecan beused to establish a
statement to be jumped to in case of such errors.
Example
Convert theoating-point array [ 2.2, 3.0, 4.5] to integer typeand storethenewarray in
the variable I by entering:
I = FIX([2.2, 3.0, 4.5])
See Also
BYTE, COMPLEX, DCOMPLEX, DOUBLE, FLOAT, LONG, LONG64, STRING, UINT,
ULONG, ULONG64
IDL Reference Guide FLICK
FLICK
TheFLICK procedurecausesthedisplay to icker between two output imagesat agiven
rate.
flick.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
FLICK, A, B [, Rate]
Arguments
A
Byte image number 1, scaled from 0 to 255.
B
Byte image number 2, scaled from 0 to 255.
Rate
The icker rate. The default is 1.0 sec/frame
See Also
CW_ANIMATE, XINTERANIMATE
FLOAT IDL Reference Guide
FLOAT
The FLOAT function returns a result equal to Expression converted to single-precision
oating-point. If Expression is a complex number, FLOAT returns the real part.
Calling Sequence
Result = FLOAT(Expression [, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to single-precision oating-point.
Offset
of dataextracted fromExpressiontobetreated assingleprecision oatingpoint data. See
thedescription in ConstantsandVariables on page11of BuildingIDLApplicationsfor
details.
D
i
i
Example
If A contains the integer value 6, it can be converted to oating-point and stored in the
variable B by entering:
B = FLOAT(A)
See Also
BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, LONG, LONG64, STRING, UINT,
ULONG, ULONG64
IDL Reference Guide FLOOR
FLOOR
The FLOOR function returns the closest integer less than or equal to its argument. This
value is returned as a longword integer with the same structure as the input argument.
Calling Sequence
Result = FLOOR(X)
Arguments
X
Thevaluefor which theFLOORfunction isto beevaluated. Thisvaluecan besingle- or
double-precision, real or complex oating-point. FLOOR returns a longword integer
with the same structure asX.
Example
To print the oor function of 5.9, enter:
PRINT, FLOOR(5.9)
IDL prints:
5
See Also
CEIL, COMPLEXROUND, ROUND
FLOW3 IDL Reference Guide
FLOW3
TheFLOW3proceduredrawslinesrepresentinga3Dow/velocityeld. Notethat the3D
scalingsystemmust bein placebeforecallingFLOW3. Thisprocedureworksbest with Z
buffer output device.
flow3.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
FLOW3, Vx, Vy, Vz
Arguments
Vx, Vy, Vz
3D arrays containing X, Y, and Z components of the eld.
Keywords
ARROWSIZE
Size of arrowheads (default = 0.05).
BLOB
Set thiskeywordtodrawablobat thebeginningof eachowlineandsuppressthearrows.
LEN
Length of each step used to followowlines(default = 2.0). Expressed in unitsof largest
eld vector (i.e., the length of the longest step is set to len times the grid spacing.
NSTEPS
Number of steps used to follow the ow lines (default = largest dimension of Vx / 5).
NVECS
Number of random ow lines to draw (default = 200). Only used if Sx, Sy, Sz are not
present.
SX, SY, SZ
Optional vectorscontainingthestartingcoordinatesof theowlines. If omitted random
starting points are chosen.
Example
Create a set of random three-dimensional arrays to represent the eld:
IDL Reference Guide FLOW3
vx = RANDOMU(seed, 5, 5, 5)
vy = RANDOMU(seed, 5, 5, 5)
vz = RANDOMU(seed, 5, 5, 5)
Set up the 3D scaling system:
SCALE3, xr=[0,4], yr=[0,4], zr = [0,4]
Plot the vector eld:
FLOW3, vx, vy, vz
See Also
VEL, VELOVECT
FLTARR IDL Reference Guide
FLTARR
The FLTARR function returns a single-precision, oating-point vector or array.
Calling Sequence
Result = FLTARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, FLTARR sets every element of the result to zero. Set this keyword to inhibit
zeroing of the array elements and cause FLTARR to execute faster.
Example
Create F, a 3-element by 3-element oating-point array with each element set to 0.0 by
entering:
F = FLTARR(3, 3)
See Also
BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, INTARR, LON64ARR,
LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR
IDL Reference Guide FLUSH
FLUSH
TheFLUSH procedurecausesall buffered output on thespecied leunitstobewritten.
IDL usesbuffered output for reasonsof efciency. Thisbufferingleadsto rareoccasions
whereaprogramneedstobecertain that output dataarenot waitingin abuffer, but have
actually been output.
Calling Sequence
FLUSH, Unit
1
, ..., Unit
n
Arguments
Unit
i
The le units (logical unit numbers) to ush.
See Also
CLOSE, EMPTY, EXIT
FORMAT_AXIS_VALUES IDL Reference Guide
FORMAT_AXIS_VALUES
The FORMAT_AXIS_VALUES function accepts a vector of numeric values as an input
argument, and returns a vector of formatted strings values. This routine uses the same
rulesfor formattingasdo theaxisroutinesthat label tick marksgiven aset of tick values.
Calling Sequence
Result = FORMAT_AXIS_VALUES( Values)
Arguments
Values
Set this argument to a vector of numeric values to be formatted.
Keywords
None.
Example
Suppose we have a vector of axis values:
axis_values = [7.9, 12.1, 15.3, 19.0]
Convert these values into an array of strings:
new_values = FORMAT_AXIS_VALUES(axis_values)
HELP, new_values
PRINT, new_values
PRINT, axis_values
IDL prints:
NEW_VALUES STRING = Array[4]
7.9 12.1 15.3 19.0
7.90000 12.1000 15.3000 19.0000
IDL Reference Guide FREE_LUN
FREE_LUN
The FREE_LUN procedure deallocates previously-allocated le units. This routine is
usually used with le units allocated with GET_LUN, but it will also close any other
specied le unit. If the specied le units are open, they are closed prior to the
deallocation.
Calling Sequence
FREE_LUN, Unit
1
, ..., Unit
n
Arguments
Unit
i
The IDL le units (logical unit numbers) to deallocate.
Example
See the example for the GET_LUN procedure.
See Also
CLOSE, GET_LUN
FSTAT IDL Reference Guide
FSTAT
TheFSTATfunctionreturnsastructureexpressionof typeFSTAT(or FSTAT64inthecase
of lesthat arelonger than 2^ 31-1bytesin length) containingstatusinformation about
a specied le unit. The contents of this structure are documented in The FSTAT
Function on page 207 of Building IDL Applications.
Calling Sequence
Result = FSTAT(Unit)
Arguments
Unit
Theleunit about whichinformation isrequired. Thisparameter can bean integer or an
associated variable, in which case information about the variables associated le is
returned.
Fields of the FSTAT Structure
Thefollowingdescriptionsareof eldsin thestructurereturned by theFSTAT function.
They arenot keywords to FSTAT.
UNIT
The IDL logical unit number (LUN).
NAME
The name of the le.
OPEN
Nonzero if the le unit is open. If OPEN is zero, the remaining elds in FSTAT will not
contain useful information.
ISATTY
Nonzero if the le is actually a terminal instead of a normal le. For example, if you are
using an xterm window on a Unix system and you invoke FSTAT on logical unit 0
(standard input), ISATTY will be set to 1.
ISAGUI
Nonzero if the le is actually a Graphical User Interface (for example, a logical unit
associated with the IDL Development Environment). Thus, if you are using the IDLDE
and you invoke FSTAT on logical unit 0 (standard input), ISAGUI will be set to 1.
INTERACTIVE
Nonzero if either ISATTY or ISAGUI is nonzero.
IDL Reference Guide FSTAT
READ
Nonzero if the le is open for read access.
WRITE
Nonzero if the le is open for write access.
TRANSFER_COUNT
The number of scalar IDL data items transferred in the last input/output operation on
the unit. This is set by the following IDL routines: READU, WRITEU, PRINT, PRINTF,
READ, and READF. TRANSFER_COUNT is useful when attempting to recover from
input/output errors.
CUR_PTR
The current position of the le pointer, given in bytes from the start of the le. If the
deviceisaterminal (ISATTYisnonzero), thevalueof CUR_PTRwill not contain useful
information.
SIZE
Thecurrent length of thelein bytes. If thedeviceisaterminal (ISATTYisnonzero), the
value of SIZE will not contain useful information.
Caution VMSvariablelength recordshavea2-byterecord-length descriptor at thebeginning
of each record. Because the SIZE eld contains the length of the data leincluding
the record descriptors, reading a le with VMS variable length records into a byte
array of the size returned by FSTAT will result in an RMS EOF error.
REC_LEN
If the le is record-oriented (VMS), this eld contains the record length; otherwise, it is
zero.
Examples
If leunit number 1isopen, theFSTAT information on that unit can beseen byentering:
PRINT, FSTAT(1)
Specic information can be obtained by referring to single elds within the structure
returned by FSTAT. The following code prints the name and length of the le open on
unit 1:
A = FSTAT(1) Put FSTAT information in vari-
ableA.
PRINT, 'File: ', A.NAME, ' is ', A.SIZE, ' bytes long.'
Print thenameand sizefields.
See Also
ASSOC, OPEN
FULSTR IDL Reference Guide
FULSTR
TheFULSTRrestoresarow-indexed sparsearray tofull storagemode. If thesparsearray
was created with the SPRSIN function using the THRESH keyword, any values in the
original array that were below the specied threshold are replaced with zeros.
Calling Sequence
Result = FULSTR(A)
Arguments
A
A row-indexed sparse array created by the SPRSIN function.
Example
Suppose we have converted an array to sparse storage format with the following
commands:
A = [[ 5.0, -0.2, 0.1], $
[ 3.0, -2.0, 0.3], $
[ 4.0, -1.0, 0.0]]
sparse = SPRSIN(A, THRESH=0.5)
Convert to sparsestoragemode.
All elements of thearray A that
haveabsolutevalues less than
THRESH areset to zero.
ThevariableSPARSEnowcontainsarepresentation of thearray A in structureform. To
restore the array from the sparse-format structure, type:
result = FULSTR(sparse) Restorethearray.
IDL prints:
5.00000 0.00000 0.00000
3.00000 -2.00000 0.00000
4.00000 -1.00000 0.00000
Notethat theelementswith an absolutevaluelessthan thespecied threshold havebeen
set to zero.
See Also
LINBCG, SPRSAB, SPRSAX, SPRSIN, READ_SPR, WRITE_SPR
IDL Reference Guide FUNCT
FUNCT
TheFUNCTprocedureevaluatesthesumof aGaussian anda2nd-order polynomial and
optionally returns the value of its partial derivatives. Normally, this function is used by
CURVEFIT to t the sum of a line and a varying background to actual data.
funct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
FUNCT, X, A, F [, Pder]
Arguments
X
A vector of values for the independent variable.
A
A vector of coefcients for the equations:
F
A named variable that will contain the value of the function at each X
i
.
Pder
A named variable that will contain an array of the size (N_ELEMENTS(X),6) that
contains the partial derivatives. Pder(i,j) represents the derivative at thei
th
point with
respect to j
th
parameter.
See Also
CURVEFIT
F A
0
e
Z
2
2
A
3
A
4
X A
5
X
2
+ + + =
Z X A
1
( ) A
2
=
FV_TEST IDL Reference Guide
FV_TEST
The FV_TEST function computes the F-statistic and the probability that two sample
populationsX and Y have signicantly different variances. X and Y may be of different
lengths. Theresult isatwo-element vector containingtheF-statisticand itssignicance.
Thesignicanceisavaluein theinterval [ 0.0, 1.0] ; asmall value(0.05or 0.01) indicates
that Xand Yhavesignicantly different variances. Thistypeof test isoften referred to as
the F-variance test.
TheF-statisticformulafor samplepopulationsxandywithmeansxandyisdenedas:
wherex = (x
0
, x
1
, x
2
, ..., x
N-1
) and y = (y
0
, y
1
, y
2
..., y
M-1
)
fv_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = FV_TEST(X, Y)
Arguments
X
An n-element integer, single- or double-precision oating-point vector.
Y
An m-element integer, single- or double-precision oating-point vector.
Example
X = [257, 208, 296, 324, 240, 246, 267, 311, 324, 323, 263, $
305, 270, 260, 251, 275, 288, 242, 304, 267]
Y = [201, 56, 185, 221, 165, 161, 182, 239, 278, 243, 197, $
271, 214, 216, 175, 192, 208, 150, 281, 196]
F
M 1
N 1
--------------
,
_
x
j
x ( )
2
1
N
---- x
j
x ( )
j 0 =
N 1
j 0 =
N 1
y
j
y ( )
2
1
M
----- y
j
y ( )
j 0 =
M 1
j 0 =
M 1
---------------------------------------------------------------------------------------- =
IDL Reference Guide FV_TEST
Compute the F-statistic (of X and Y) and its signicance.
PRINT, FV_TEST(X, Y)
IDL prints:
2.48578 0.0540116
The result indicates that X and Y have signicantly different variances.
See Also
KW_TEST, MOMENT, RS_TEST, S_TEST, TM_TEST
FX_ROOT IDL Reference Guide
FX_ROOT
The FX_ROOT function computes real and complex roots of a univariate nonlinear
function using an optimal Mllers method.
fx_root.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = FX_ROOT(X, Func)
Arguments
X
A3-element real or complex initial guessvector. Real initial guessesmay result in real or
complex roots. Complex initial guesses will result in complex roots.
Func
univariate nonlinear function. This function must accept the vector argument X.
For example, suppose we wish to nd a root of the following function:
We write a function FUNC to express the function in the IDL language:
FUNCTION func, X
RETURN, EXP(SIN(X)^2 + COS(X)^2 - 1) - 1
END
Keywords
DOUBLE
ITMAX
The maximum allowed number of iterations. The default is 100.
STOP
Use this keyword to specify the stopping criterion used to judge the accuracy of a
computed root r(k). SettingSTOP= 0(thedefault) checkswhether theabsolutevalueof
the difference between two successively-computed roots, | r(k) - r(k+1) | is less than the
y e
x
2
x
2
1 cos + sin ( )
1 =
IDL Reference Guide FX_ROOT
stopping tolerance TOL. Setting STOP = 1 checks whether the absolute value of the
function FUNC at the current root, | FUNC(r(k)) |, is less than TOL.
TOL
Use this keyword to specify the stopping error tolerance. The default is 1.0 10
-4
.
Example
Tond therootsof thefunction FUNCdened above, rst deneareal 3-element initial
guess vector:
x = [0.0, -!pi/2, !pi]
Compute a root of the function using double-precision arithmetic.
root = FX_ROOT(X, 'FUNC', /DOUBLE)
Check the accuracy of the computed root.
PRINT, EXP(SIN(ROOT)^2 + COS(ROOT)^2 - 1) - 1
IDL prints:
0.0000000
We can also dene a complex 3-element initial guess vector:
X = [COMPLEX(-!PI/3, 0), COMPLEX(0, !PI), COMPLEX(0, -!PI/6)]
root = FX_ROOT(x, 'FUNC') Computetheroot of thefunction.
Check the accuracy of the computed complex root.
PRINT, EXP(SIN(ROOT)^2 + COS(ROOT)^2 - 1) - 1
IDL prints:
( 0.00000, 0.00000)
See Also
BROYDEN, NEWTON, FZ_ROOTS
FZ_ROOTS IDL Reference Guide
FZ_ROOTS
The FZ_ROOTS function is used to nd the roots of an m-degree complex polynomial,
using Laguerres method. The result is an m-element complex vector.
FZ_ROOTSisbasedon theroutinezroots describedin section 9.5of Numerical Recipes
Calling Sequence
Result = FZ_ROOTS(C)
Arguments
C
Avector of length m+1containingthecoefcientsof thepolynomial, in ascendingorder
(see example). The type can be real or complex.
Keywords
DOUBLE
EPS
The desired fractional accuracy. The default value is 2.0 10
-6
.
NO_POLISH
Set this keyword to suppress the usual polishing of the roots by Laguerres method.
Examples
EXAMPLE 1: Real coefcients yielding real roots.
P (x) = 6x
3
- 7x
2
- 9x - 2 (The exact roots are -1/2, -1/3, 2.0)
coeffs = [-2.0, -9.0, -7.0, 6.0]
roots = FZ_ROOTS(coeffs)
PRINT, roots
( -0.500000, 0.00000)( -0.333333, 0.00000)( 2.00000, 0.00000)
IDL Reference Guide FZ_ROOTS
EXAMPLE 2: Real coefcients yielding complex roots.
P (x) = x
4
+ 3x
2
+ 2
(The exact roots are:
, , ,
coeffs = [2.0, 0.0, 3.0, 0.0, 1.0]
PRINT, roots
(0.00000, -1.41421)(0.00000, 1.41421)
(0.00000, -1.00000)(0.00000, 1.00000)
EXAMPLE 3: Real and complex coefcients yielding real and complex roots.
P (x) = x
3
+ (4 i4)x
2
+s (3 + i4)x + (18 + i24)
(The exact roots are 2.0, 3.0, (3.0 + i4.0))
coeffs = [COMPLEX(18,24), COMPLEX(-3,4), COMPLEX(-4,-4), 1.0]
PRINT, roots
( -2.00000, 0.00000) ( 3.00000, 0.00000) ( 3.00000, 4.00000)
See Also
FX_ROOT, BROYDEN, NEWTON, POLY
0.0 i 2.0 0.0 i 2.0 + 0.0 i 0.0 i +
GAMMA IDL Reference Guide
GAMMA
TheGAMMAfunction returnsthegammafunction of X. Thedomain of thefunction is
0 < X < 34.5.
The gamma function is dened as:
If X is double-precision, the result is double-precision, otherwise the argument is
converted to oating-point and the result is oating-point.
Use the LNGAMMA function to obtain the natural logarithm of the gamma function
when there is a possibility of overow.
Calling Sequence
Result = GAMMA(X)
Arguments
X
The expression for which the gamma function will be evaluated.
Example
Plot the gamma function over the range 0.01 to 1.0 with a step size of 100 by entering:
X = FINDGEN(99)/100. + 0.01
PLOT, X, GAMMA(X)
See Also
BETA, IBETA, IGAMMA, LNGAMMA
x ( ) t
x 1
e
t
t d
0

IDL Reference Guide GAMMA_CT
GAMMA_CT
The GAMMA_CT procedure applies gamma correction to a color table.
gamma_ct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
GAMMA_CT, Gamma
Arguments
Gamma
The value of gamma correction. A value of 1.0 indicates a linear ramp (i.e., no gamma
correction). Higher valuesof Gammagivemorecontrast. Valueslessthan 1.0yield lower
contrast.
Keywords
CURRENT
Set this keyword to apply correction from the current color table (i.e., the values
R_CURR, G_CURR, and B_CURR in the COLORS common block). Otherwise,
correction is applied from the original color table (i.e., the values R_ORIG, G_ORIG,
andB_ORIGintheCOLORScommonblock). Thegammacorrectedcolor tableisalways
saved in thecurrent table(R_CURR, G_CURR, B_CURR) and thenewtableisloaded.
INTENSITY
Set this keyword to correct the individual intensities of each color in the colortable.
Otherwise, the colors are shifted according to the gamma function.
See Also
PSEUDO, STRETCH, XLOADCT
GAUSS_CVF IDL Reference Guide
GAUSS_CVF
TheGAUSS_CVFfunction computesthecutoff valueVin astandardGaussian (normal)
distribution with a mean of 0.0 and a variance of 1.0 such that the probability that a
random variableX is greater than V is equal to a user-supplied probability P.
gauss_cvf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = GAUSS_CVF(P)
Arguments
P
Example
Usethefollowingcommand to computethecutoff valuein aGaussian distribution such
that theprobabilitythat arandomvariableXisgreater than thecutoff valueis0.025. The
PRINT, GAUSS_CVF(0.025)
IDL prints:
1.95997
See Also
CHISQR_CVF, F_CVF, GAUSS_PDF, T_CVF
IDL Reference Guide GAUSS_PDF
GAUSS_PDF
The GAUSS_PDF function computes the probability P that, in a standard Gaussian
(normal) distributionwithameanof 0.0andavarianceof 1.0, arandomvariableXisless
than or equal to a user-specied cutoff valueV.
gauss_pdf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = GAUSS_PDF(V)
Arguments
V
value.
Examples
Computetheprobabilitythat arandomvariableX, fromthestandardGaussian (normal)
distribution, is less than or equal to 2.44. The result should be 0.992656.
result = GAUSS_PDF(2.44)
Computetheprobabilitythat arandomvariableX, fromthestandardGaussian (normal)
distribution, is less than or equal to 10.0 and greater than or equal to 2.0. The result
should be 0.0227501.
result = GAUSS_PDF(10.0) - GAUSS_PDF(2.0)
Compute the probability that a random variable X, from the Gaussian (Normal)
distribution with a mean of 0.8 and a variance of 4.0, is less than or equal to 2.44. The
result = GAUSS_PDF( (2.44 - 0.80)/SQRT(4.0) )
See Also
BINOMIAL, CHISQR_PDF, F_PDF, GAUSS_CVF, T_PDF
GAUSS2DFIT IDL Reference Guide
GAUSS2DFIT
The GAUSS2DFIT function ts a two-dimensional, elliptical Gaussian equation to
rectilinearly gridded data.
Z = F(x, y)
where:
And the elliptical function is:
The parameters of the ellipseU are:
Axis lengths are 2a and 2b, in the unrotated X and Y axes, respectively.
Center is at (h, k).
Rotation of T radians from the X axis, in theclockwisedirection.
The rotated coordinate system is dened as:
Therotation isoptional, and can beforced to 0, makingthemajor and minor axesof the
ellipse parallel to the X and Y axes.
Coefcients of the computed t are returned in argument A.
Procedure Used and Other Notes
The peak/valley is found by rst smoothingZ and then nding the maximum or
minimum, respectively. GAUSSFIT is then applied to the row and column running
through the peak/valley to estimate the parameters of the Gaussian in X and Y. Finally,
CURVEFIT is used to t the 2D Gaussian to the data.
Besurethat the2Darraytobet containstheentirepeak/valleyout toat least 5to8half-
widths, or the curve-tter may not converge.
This computationally-intensive routine takes approximately 4 seconds for a 128 by 128-
element array on a Sun SPARC LX. The time required is roughly proportional to the
number of elements in Z.
gauss2dfit.pro in thelib subdirectory of the IDL distribution.
F x y , ( ) A
0
A
1
e
U 2
+ =
U x' a ( )
2
y' b ( )
2
+ =
x' x h ( ) T y k ( ) T sin cos =
y' x h ( ) T y k ( ) T cos + sin =
IDL Reference Guide GAUSS2DFIT
Calling Sequence
Result = GAUSS2DFIT(Z, A [,X, Y])
Arguments
Z
Thedependent variable. Zshould beatwo-dimensional arraywith dimensions(N
x
, N
y
).
Gridding in the array must be rectilinear.
A
Anamed variablein which thecoefcientsof thet arereturned. Aisreturned asaseven
element vector thecoefcientsof thettedfunction. Themeaningsof theseven elements
in relation to the discussion above is:
A[ 0] = A
0
= constant term
A[ 1] = A
1
= scale factor
A[ 2] = a = width of Gaussian in the X direction
A[ 3] = b = width of Gaussian in the Y direction
A[ 4] = h = center X location
A[ 5] = k = center Y location.
A[ 6] = T= Theta, therotationof theellipsefromtheXaxisinradians, counter-clockwise.
X
An optional vector with N
x
elementsthat containstheXvaluesof Z(i.e., X
i
istheXvalue
for Z
i,j
. If thisargument isomitted, aregular grid in X isassumed, and theX location of
Z
i,j
= i.
Y
An optional vector with N
y
elementsthat containstheYvaluesof Z (i.e., Y
j
istheYvalue
for Z
i,j
. If this argument is omitted, a regular grid in Y is assumed, and the Y location of
Z
i,j
= j.
Keywords
NEGATIVE
Set thiskeywordtoindicatethat theGaussiantobettedisavalley(suchasanabsorption
line). By default, a peak is t.
TILT
Set thiskeyword to allowtheorientation of themajor and minor axesof theellipseto be
unrestricted. Thedefault isthat theaxesof theellipsemust beparallel totheXandYaxes.
Therefore, in the default case, A[ 6] is always returned as 0.
GAUSS2DFIT IDL Reference Guide
Example
This example creates a 2D gaussian, adds random noise and then applies GAUSS2DFIT.
nx = 128 & ny = 100 Definearray dimensions.
A = [ 5., 10., nx/6., ny/10., nx/2., .6*ny]
Defineinputfunctionparameters.
X = FINDGEN(nx) # REPLICATE(1.0, ny)
Y = REPLICATE(1.0, nx) # FINDGEN(ny)
CreateX and Y arrays.
U = ((X-A[4])/A[2])^2 + ((Y-A[5])/A[3])^2
Createan ellipse.
Z = A[0] + A[1] * EXP(-U/2) Creategaussian Z.
Z = Z + RANDOMN(seed, nx, ny) Add random noise, SD =1.
yfit = GAUSS2DFIT(Z, B) Fit thefunction, no rotation.
PRINT, 'Should be: ', STRING(A, FORMAT='(6f10.4)')
PRINT, 'Is: ', STRING(B(0:5), FORMAT='(6f10.4)')
Report results.
See Also
COMFIT, GAUSSFIT, POLY_FIT, POLYFITW, REGRESS, SFIT, SVDFIT
IDL Reference Guide GAUSSFIT
GAUSSFIT
TheGAUSSFIT function computesanon-linear least-squarest to afunction f (x) with
fromthreeto six unknown parameters. f (x) isalinear combination of aGaussian and a
quadratic; the number of terms is controlled by the keyword parameter NTERMS.
gaussfit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = GAUSSFIT(X, Y [, A])
Arguments
X
Y
A
A named variable that will contain the coefcientsA of the t.
Keywords
ESTIMATES
Set thiskeywordequal toanarrayof startingestimatesfor theparametersof theequation.
If the NTERMS keyword is specied, the ESTIMATES array should have NTERMS
elements. If NTERMSisnot specied, theESTIMATESarrayshouldhavesix elements. If
theESTIMATESarrayisnot specied, estimatesarecalculatedbytheGAUSSFIT routine.
NTERMS
Set this keyword to an integer value between three and six to specify the function to be
used for the t. The values correspond to the functions shown below. In all cases:
NTERMS=6
z
x A
1
A
2
--------------- =
f x ( ) A
0
e
z
2
2
--------
A
3
A
4
x A
5
x
2
+ + + =
GAUSSFIT IDL Reference Guide
NTERMS=6isthedefault setting. Here, A
0
istheheight of theGaussian, A
1
isthecenter
of theGaussian, A
2
isthewidth of theGaussian, A
3
istheconstant term, A
4
isthelinear
term, and A
5
is the quadratic term.
NTERMS=5
NTERMS=4
NTERMS=3
Example
X = FINDGEN(13)/5 - 1.2 Definetheindependent variables.
Y = [0.0, 0.1, 0.2, 0.5, 0.8, 0.9, $
0.99, 0.9, 0.8, 0.5, 0.2, 0.1, 0.0] Definethedependent variables.
yfit = GAUSSFIT(X, Y, A) Fitthedatatothedefaultfunction,
storingcoefficients in A.
PRINT, A Print thecoefficients.
IDL prints:
2.25642 -1.62041e-07 0.703372 -1.25634 3.04487e-07 0.513596
We can compare original and tted data by plotting one on top of the other:
LOADCT, 30 Load an appropriatecolor table.
PLOT, X, Y Plot theoriginal data.
OPLOT, X, yfit, COLOR = 100 Overplotthefitteddatainadiffer-
ent color.
See Also
COMFIT, CURVEFIT, GAUSS2DFIT, POLY_FIT, POLYFITW, REGRESS, SFIT,
SVDFIT
f x ( ) A
0
e
z
2
2
--------
A
3
A
4
x + + =
f x ( ) A
0
e
z
2
2
--------
A
3
+ =
f x ( ) A
0
e
z
2
2
--------
=
IDL Reference Guide GAUSSINT
GAUSSINT
TheGAUSSINT function evaluatestheintegral of theGaussian probability function and
returns the result.
The Gaussian integral is dened as:
If X is double-precision, the result is double-precision, otherwise the argument is
converted to oating-point and the result is oating-point. The result has the same
structure as the input argument, X.
Calling Sequence
Result = GAUSSINT(X)
Arguments
X
The expression for which the Gaussian integral is to be evaluated.
Example
Plot the Gaussian probability function over the range -5 to 5 with a step size of 0.1by
entering:
X = FINDGEN(101)/10. - 5.
PLOT, X, GAUSSINT(X)
See Also
GAUSS_CVF, GAUSS_PDF
Gaussint x ( )
1
2
---------- e
t
2
2
t d

x

GET_KBRD IDL Reference Guide
GET_KBRD
The GET_KBRD function returns the next character available from the standard input
(IDL le unit 0) as a one-character string.
Calling Sequence
Result = GET_KBRD(Wait)
Arguments
Wait
If Wait is zero, GET_KBRD returns the null string if there are no characters in the
terminal type-ahead buffer. If it isnonzero, thefunction waitsfor acharacter tobetyped
before returning.
Examples
To wait for keyboard input and store one character in the variable R, enter:
R = GET_KBRD(1)
Press any key to return to the IDL prompt. To see the character that was typed, enter:
PRINT, R
The following code fragment reads one character at a time and echoes that characters
numeric code. It quits when a q is entered:
REPEAT BEGIN
A = GET_KBRD(1)
PRINT, BYTE(A)
ENDREP UNTIL A EQ 'q'
Note The GET_KBRD function can be used to return Windows special characters (in
addition to standard keyboard characters), created by holdingdown theAlt key and
entering the characters ANSI equivalent.
For example, to return the paragraph marker (), ANSI number 0182, enter:
C = GET_KBRD(1)
WhileGET_KBRDiswaiting, pressandholdtheAlt keyandtype0182onthenumeric
keypad. When the IDL prompt returns, enter:
PRINT, C
IDL should print the paragraph marker, .
IDL Reference Guide GET_KBRD
GET_KBRD cannot be used to return control characters, the Return key, or other
editing keys (e.g., Delete, Backspace, etc.). These characters are used for keyboard
shortcuts and command line editing only.
See Also
READ/READF
GET_LUN IDL Reference Guide
GET_LUN
TheGET_LUNprocedureallocatesaleunit fromapool of freeunits. Insteadof writing
routinestoassumetheuseof certain leunits, IDL functionsand proceduresshould use
GET_LUN to reserve unit numbers in order to avoid conicts with other routines. Use
FREE_LUN to free the le units when nished.
Calling Sequence
GET_LUN, Unit
Arguments
Unit
The named variable into which GET_LUN should place the le unit number. Unit is
converted into alongword integer in theprocess. Theleunit number obtained isin the
range 100 to 128.
Example
Insteadof explicitlyspecifyingaleunit number that mayalreadybeused, useGET_LUN
to obtain a free one and store the result in the variable U by entering:
GET_LUN, U
Now U can be used in opening a le, for Example
OPENR, U, 'file.dat'
Oncethedatafromle.dat hasbeen read, thelecan beclosed and theleunit can be
freed with the command:
FREE_LUN, U
Notealsothat OPENRhasaGET_LUNkeywordthat allowsyoutosimultaneouslyobtain
a free le unit and open a le. The following command performs the same tasks as the
rst two commands above:
OPENR, U, 'file.dat', /GET_LUN
See Also
FREE_LUN, OPEN
IDL Reference Guide GET_SCREEN_SIZE
GET_SCREEN_SIZE
The GET_SCREEN_SIZE function returns a two-element vector of the form [width,
height] that represents the dimensions, measured in device units, of the screen.
Calling Sequence
Result = GET_SCREEN_SIZE([Display_name])
Arguments
Display_name (X Only)
Astringindicatingthenameof theXWIndowsdisplaythat should beused todetermine
the screen size.
Keywords
DISPLAY_NAME (X Only)
Set this keyword equal to a string indicating the name of the X WIndows display that
should beused to determinethescreen size. Settingthiskeyword isequivalent to setting
the optional Display_nameargument.
RESOLUTION
Set this keyword equal to a named variable that will contain a two-element vector,
[ xres, yres] , specifying the screen resolution in cm/pixel.
Example
You can nd the dimensions and screen resolution of your screen by entering the
following:
dimensions = GET_SCREEN_SIZE(RESOLUTION=resolution)
PRINT, dimensions, resolution
For the screen on which this was tested, IDL prints:
1280.00 1024.00
0.0282031 0.0281250
GET_SYMBOL (VMS Only) IDL Reference Guide
GET_SYMBOL (VMS Only)
The GET_SYMBOL function returns the value of a VMS DCL (Digital Command
Language) interpreter symbol asascalar string. If thesymbol isundened, thenull string
is returned.
Calling Sequence
Result = GET_SYMBOL(Name)
Arguments
Name
A scalar string containing the name of the symbol to be translated.
Keywords
TYPE
Thetablefromwhich Nameistranslated. Set TYPEto1tospecifythelocal symbol table.
A value of 2 species the global symbol table. The default is to search the local table.
See Also
GETENV
IDL Reference Guide GETENV
GETENV
TheGETENVfunction returnstheequivalencestringfor Namefromtheenvironment of
the IDL process. If Namedoes not exist in the environment, a null string is returned.
Calling Sequence
Result = GETENV(Name)
Arguments
Name
The scalar string for which an equivalence string from the environment is desired.
Environment Variables Under VMS
VMS does not directly support the concept of environment variables. Instead, it is
emulated (by using the standard C getenv() function) as described below, enabling you
to use GETENV portably between Unix and VMS:
If Nameisoneof HOME, TERM, PATH, or USER, an appropriateresponseisgenerated.
This mimics the most common Unix environment variables.
An attempt ismadeto translateNameasalogical name. All four logical nametablesare
searched in the standard order.
An attempt is made to translateNameas a command-language interpreter symbol.
Example
To print the name of the current Unix shell, enter the command:
PRINT, 'The current shell is: ', GETENV('SHELL')
See Also
GET_SYMBOL (VMS Only), SETENV (Unix and Windows Only), TRNLOG
The Unix Environment
Every Unix process has an environment. The environment consists of
environment variables, eachof whichhasastringvalueassociatedwithit. Some
environment variablesalwaysexist, suchasPATHthat tellstheshell wheretolook
for programsor TERM that speciesthekindof terminal beingused. Otherscan
GETENV IDL Reference Guide
be added by the user, usually from an interactive shell and often from the
.login le that is executed when you log in.
When a process is created, it is given a copy of the environment from its parent
process. IDL isnoexception tothis; when started, it inheritsacopyof itsparents
environment. The parent process to IDL is usually the interactive shell from
whichit wasstarted. Inturn, anychildprocesscreatedbyIDL(suchasthosefrom
the SPAWN procedure) inherits a copy of IDLs current environment.
Note It is important to realize that environment variables are not an IDL feature;
theyarepart of everyUnixprocess. Althoughtheycanserveasaformof global
memory, it isbest toavoidusingtheminthat way. Instead, IDLheapvariables
(pointers or object references), IDL system variables, or common blocks
should be used in that role. This will make your IDL code portable to non-
Unix-based IDL systems. Environment variablesshould beused for commu-
nicatingwith child processes. Oneexampleissettingthevalueof theSHELL
environment variableprior tocallingSPAWNtochangetheshell executedby
SPAWN.
IDL provides two routines for manipulating the environment:
GETENV
TheGETENV function returns the equivalence string from the environment of
the IDL process. It has the form:
GETENV(Name)
whereNameisthenameof theenvironment variablefor which thetranslation is
desired. If Namedoesnot exist in theenvironment, anull stringisreturned. For
example, to determine the type of terminal being used, you can enter the IDL
statement:
PRINT, 'The terminal type is: ', GETENV('TERM')
Executing this statement on a Sun workstation give the following result:
The terminal type is: sun
SETENV
TheSETENV function addsanewenvironment variableor changesthevalueof
an existing environment variable in the IDL process. It has the form:
SETENV, Environment_Expression
whereEnvironment_Expressionis a scalar string containing an environment
expression to be added to the environment.
IDL Reference Guide GETENV
For example, you can changetheshell used by SPAWN by changingthevalueof
the SHELL environment variable. An IDL statement to change to using the
Bourne shell /bin/sh would be:
SETENV, 'shell=/bin/sh'
GRID3 IDL Reference Guide
GRID3
TheGRID3function tsasmooth function to aset of 3D scattered nodes(x
i
, y
i
, z
i
) with
associateddatavalues(f
i
). Thefunctioncanbesampledover aset of user-speciedpoints,
or over an arbitrary 3D grid which can then be viewed using the SLICER procedure.
GRID3 uses the method described in Renka, R. J., Multivariate Interpolation of Large
Setsof Scattered Data, ACMTransactionsonMathematical Software, Vol. 14, No. 2, June
1988, Pages139-148, which hasbeen referred to astheModied ShepardsMethod. The
function described bythismethod hastheadvantagesof beingequal tothevaluesof f
i
, at
each (x
i
, y
i
, z
i
), and being smooth (having continuous rst partial derivatives).
If nooptional or keywordparametersaresupplied, GRID3producesaregularly-sampled
volume with dimensions of (25, 25, 25), made up of single-precision, oating-point
values, enclosing the original data points.
Calling Sequence
Result = GRID3(X, Y, Z, F, G
x
, G
y
, G
z
)
Arguments
X, Y, Z and F
Arrays containing the locations of the data points, and the value of the variable to be
interpolated at that point. X, Y, Z, and Fmust havethesamenumber of elements(with a
minimum of 10 elements per array) and are converted to oating-point if necessary.
Note: For the greatest possible accuracy, the arraysX, Y, and Z should be scaled to t in
the range [ 0,1] .
G
x
, G
y
, and G
z
Optional arrays containing the locations within the volume to be sampled (if the GRID
keyword is not set), or the locations along each axis of the sampling grid (if the GRID
keyword is set). If these parameters are supplied, the keywords DELTA, NGRID, and
START are ignored.
If thekeyword GRIDisnotset, theresult hasthesamenumber of elementsasG
x
, G
y
, and
G
z
. Theithelement of theresult containsthevalueof theinterpolateat (G
xi
, G
yi
, G
zi
). The
result has the same dimensions asG
x
.
If theGRID keyword isset, theresult of GRID3isathree-dimensional, single-precision,
oating-point array with dimensions of (N
x
, N
y
, N
z
), whereN
x
, N
y
, and N
z
are the
number of elements in G
x
, G
y
, and G
z
, respectively.
IDL Reference Guide GRID3
Keywords
DELTA
Set thiskeywordtoathree-element vector or ascalar that speciesthegridspacingin the
X, Y, and Z dimensions. Thedefault spacingproducesNGRID sampleswithin therange
of each axis.
DTOL
The tolerance for detecting an ill-conditioned system of equations. The default value is
0.01, which isappropriatefor small rangesof X, Y, and Z. For largerangesof X, Y, or Z, it
maybenecessarytodecreasethevalueof DTOL. If youreceivetheerror messageGRID3:
Ill-conditioned matrix or all nodes co-planar, try decreasing the value of DTOL.
GRID
Thiskeywordspeciestheinterpretation of G
x
, G
y
, andG
z
. Thedefault valuefor GRIDis
zero if G
x
, G
y
, and G
z
are supplied, otherwise a regularly-gridded volume is produced.
NGRID
Thenumber of samplesalongeach axis. NGRIDcan beset toascalar, in which caseeach
axishasthesamenumber of samples, or toathree-element arraycontainingthenumber
of samples for each axis. The default value for NGRID is 25.
START
Athree-element arraythat speciesthestartingvaluefor each grid. Thedefault valuefor
START is the minimum value in the respective X, Y, and Z array.
Examples
Produce a set random points within the (0,1) unit cube and simulate a function:
N = 300 Number of irregular samples.
X = RANDOMU(SEED, N) Generaterandomvaluesbetween
0 and 1.
Y = RANDOMU(SEED, N)
Z = RANDOMU(SEED, N)
F = (X-.5)^2 + (Y-.5)^2 + Z Thefunction to simulate.
Return a cube with 25 equal-interval samples along each axis:
Result = GRID3(X, Y, Z, F)
Return acubewith11elementsalongeachdimension, whichsampleseachaxisat (0, 0.1,
..., 1.0):
Result = GRID3(X, Y, Z, F, START=[0., 0., 0], $
DELTA=0.1, NGRID=10)
The same result is produced by the statements:
GRID3 IDL Reference Guide
S = FINDGEN(11) / 10. Createsamplevalues
Result = GRID3(X, Y, Z, F, S, S, S, /GRID)
See Also
SLICER3
IDL Reference Guide GS_ITER
GS_ITER
The GS_ITER function solves an n by n linear system of equations using Gauss-Seidel
iteration with over- and under-relaxation to enhance convergence.
Note that the equations must be entered in diagonally dominant form to guarantee
convergence. A system is diagonally dominant if the diagonal element in a given row is
greater than the sum of the absolute values of the non-diagonal elements in that row.
gs_iter.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = GS_ITER(A, B)
Arguments
A
An n by n integer, single-, or double-precision oating-point array. On output, A is
divided by its diagonal elements. Integer input values are converted to single-precision
B
A vector containing the right-hand side of the linear systemAx=b. On output, B is
divided by the diagonal elements of A.
Keywords
CHECK
Set this keyword to check the array A for diagonal dominance. If A is not in diagonally
dominant form, GS_ITER reports the fact but continues processing on the chance that
the algorithm may converge.
LAMBDA
A scalar value in the range: [ 0.0, 2.0] . This value determines the amount of relaxation.
Relaxation is a weighting technique used to enhance convergence.
If LAMBDA = 1.0, no weighting is used. This is the default.
If 0.0 LAMBDA < 1.0, convergence improves in oscillatory and non-convergent
systems.
If 1.0< LAMBDA 2.0, convergenceimprovesin systemsalready known to converge.
MAX_ITER
The maximum allowed number of iterations. The default value is 30.
GS_ITER IDL Reference Guide
X_0
An n-element vector that providesthealgorithmsstartingpoint. Thedefault is[ 1.0, 1.0,
... , 1.0] .
TOL
The relative error tolerance between current and past iterates calculated as: (( (current-
past)/current )(. The default is 1.0 10
-4
.
Example
Dene an array A:
A = [[ 1.0, 7.0, -4.0], $
[ 4.0, -4.0, 9.0], $
[12.0, -1.0, 3.0]]
B = [12.0, 2.0, -9.0] Definetheright-hand sidevector
B.
RESULT = GS_ITER(A, B, /CHECK) Computethesolution to thesys-
tem.
IDL prints:
Input matrix is not in Diagonally Dominant form.
Algorithm may not converge.
% GS_ITER: Algorithm failed to converge within given parameters.
Since the A represents a system of linear equations, we can reorder it into diagonally
dominant form by rearranging the rows:
A = [[12.0, -1.0, 3.0], $
[ 1.0, 7.0, -4.0], $
[ 4.0, -4.0, 9.0]]
Make corresponding changes in the ordering of B.
B = [-9.0, 12.0, 2.0]
RESULT = GS_ITER(A, B, /CHECK) Computethesolution to thesys-
tem.
IDL prints:
-0.999982 2.99988 1.99994
See Also
CRAMER, LU_COMPLEX, CHOLSOL, LUSOL, SVSOL, TRISOL
IDL Reference Guide H_EQ_CT
H_EQ_CT
TheH_EQ_CT function histogram-equalizesthecolor tablesfor an imageor aregion of
the display. A pixel-distribution histogram is obtained, the cumulative integral is taken
and scaled, and the result is applied to the current color table.
h_eq_ct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
H_EQ_CT [, Image]
Arguments
Image
A two-dimensional byte array representing the image whose histogram is to be used in
determining the new color tables. If this value is omitted, the user is prompted to mark
thediagonal cornersof aregion of thedisplay. If Imageisspecied, it isassumed that the
image is loaded into the current IDL window. Imagemust be scaled the same way as the
image loaded to the display.
See Also
H_EQ_INT
H_EQ_INT IDL Reference Guide
H_EQ_INT
The H_EQ_INT function interactively histogram-equalizes the color tables of an image
or a region of the display. By moving the cursor across the screen, the amount of
histogram-equalization can be varied.
Either theimageparameter or aregion of thedisplaymarkedbytheuser isusedtoobtain
apixel-distribution histogram. Thecumulativeintegral istaken andscaledandtheresult
is applied to the current color tables.
h_eq_int.pro in thelib subdirectory of the IDL distribution.
Using the H_EQ_INT Interface
Awindowiscreated and thehistogramequalization function isplotted. Alinear ramp is
overplotted. Move the cursor from left to right to vary the amount of histogram
equalization applied to thecolor tablesfrom0to 100%. Presstheright mousebutton to
exit.
Calling Sequence
H_EQ_INT [, Image]
Arguments
Image
A two-dimensional byte array representing the image whose histogram is to be used in
determining the new color tables. If this value is omitted, the user is prompted to mark
thediagonal cornersof aregion of thedisplay. If Imageisspecied, it isassumed that the
image is loaded into the current IDL window. Imagemust be scaled the same way as the
image loaded to the display.
See Also
H_EQ_CT
IDL Reference Guide HANNING
HANNING
TheHANNINGfunction isused tocreateawindow for Fourier Transformltering. It
can be used to create both Hanning and Hamming windows.
hanning.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = HANNING(N
1
[, N
2
])
Arguments
N
1
The number of columns in the resulting array.
N
2
The number of rows in the resulting array.
Keywords
ALPHA
Set this keyword equal to the width parameter of a generalized Hamming window.
ALPHA must be in the range of 0.5 to 1.0. If ALPHA = 0.5 (the default) the function is
called a Hanning window. If ALPHA= 0.54, theresult iscalled a Hamming window.
See Also
FFT
HDF_BROWSER IDL Reference Guide
HDF_BROWSER
TheHDF_BROWSERfunction presentsagraphical user interface(GUI) that allowsthe
user to view the contents of a Hierarchical Data Format (HDF), HDF-EOS, or NetCDF
le, and prepare a template for the extraction of HDF data and metadata into IDL. The
output template is an IDL structure that may be used when reading HDF les with the
HDF_READ routine. If you have several HDF les of identical form, the returned
template from HDF_BROWSER may be reused to extract data from these les with
HDF_READ. If you donot need amulti-usetemplate, you maycall HDF_READdirectly.
Calling Sequence
Template = HDF_BROWSER([Filename])
Arguments
Filename
Astringcontainingthenameof aHDFletobrowse. If Filenameisnot specied, adialog
allows you to choose a le.
Keywords
CANCEL
Set this keyword to a named variable that will contain the byte value 1 (one) if the user
clicked the Cancel button or the byte value 0 (zero) otherwise.
PREFIX
When HDF_BROWSER reviews the contents of an HDF le, it creates default output
names for the various data elements. By default these default names begin with a prex
derived from the lename. Set this keyword to a string value to be used in place of the
default prex.
IDL Reference Guide HDF_BROWSER
Graphical User Interface Menu Options
The following options are available from the graphical user interface menus.
Pulldown Menu
The following table shows the options available with the pulldown menu.
Preview Button
If you have selected an image from the pulldown menu, click on this button to view the
image. If youhaveselectedadataitemthat canbeplottedintwodimensions, click onthis
button to view a 2D plot of the data (the default) or click on the Surface radio button
todisplayasurfaceplot, or click on theContour radiobutton todisplayacontour plot.
You can also select the Fit to Window checkbox to t the image to the window.
Read Checkbox
Select this checkbox to extract the current data or metadata item from the HDF le.
Extract As
Specify a name for the extracted data or metadata item
Note TheRead Checkbox must beselected for theitemtobeextracted. Default namesare
generated for all data items, but may be changed at any time by the user.
Menu Selection Description
HDF/NetCDF Summary Overview of HDF le contents
DFR8 (8-bit Images) 8-bit images, palettes, and their attributes
DF24 (24-bit Images) 24-bit images and their attributes
DFP (Palettes) Image palettes
SD (Variables/Attributes) Scientic Datasets and attributes
AN (Annotations) Annotations
GR (Generic Raster) Images
GR Global Attributes
HDF-EOS Summary Overview of HDF-EOS le contents
Point
Swath
Grid
Table 9-10: HDF_BROWSER Pulldown Menu Options
HDF_BROWSER IDL Reference Guide
Example
template = HDF_BROWSER(test.hdf)
output_structure = HDF_READ(TEMPLATE=template)
or,
output_structure = HDF_READ(test.hdf, TEMPLATE=template)
Note VgroupsandVdatasarenot currentlysupported. HDFleswritten with HDF4.1or
greater maynot bereadablewiththisbrowser. Becauseof abuginHDF4.0r2, multiple
useof HDF_BROWSERon lescontainingboth DFR8and DF24imagesmay cause
theDFR8andDF24interfacestobecomeunusable. In thesecases, HDF_BROWSER
will improperlyindicatethat therearenoDFR8or DF24imagesin theHDFle, and
all access to these interfaces will fail for the duration of the IDL session. Restarting
IDLwill allowyoutoagainuseHDF_BROWSERtoviewthefull contentsof theHDF
le.
See Also
HDF_READ, Scientic Data Formats
IDL Reference Guide HDF_READ
HDF_READ
The HDF_READ function allows extraction of Hierarchical Data Format (HDF),
HDF-EOS, and NetCDF data and metadata into an output structure based upon
information provided through a graphical user interface or through a le template
generated by HDF_BROWSER. The output structure is a single level structure
corresponding to the data elements and names specied by HDF_BROWSER or its
output template. Templatesgenerated byHDF_BROWSERmaybere-used for HDFles
of identical format.
Calling Sequence
Result = HDF_READ([Filename])
Arguments
Filename
A string containing the name of a HDF le to extract data from. If Filename is not
specied, a dialog allows you to specify a le. Note that if a template is specied, the
template must match the HDF le selected.
Keywords
DFR8
Set this keyword to a named variable that will contain a 2 x n string array of extracted
DFR8imagesand their palettes. Therst column will contain theextracted DFR8image
names, whilethesecondcolumnwill containtheextractednameof theassociatedpalette.
If nopaletteisassociatedwithaDFR8imagethepalettenamewill beset tothenull string.
If no DFR8imageswereextracted fromtheHDFle, thisreturned stringwill bethenull
string array [ '', ''] .
DF24
Set this keyword to a named variable that will contain a string array of the names of all
the extracted DF24 24-bit images. This is useful in determining whether a (3,n,m)
extracteddataelement isa24-bit imageor another typeof data. If noDF2424-bit images
were extracted from the HDF le, the returned string will be the null string ('').
TEMPLATE
Set this keyword to specify the HDF le template (generated by the function
HDF_BROWSER), that denes which data elements to extract from the selected HDF
le. Templatesmaybeusedonanylesthat haveaformat identical tothelethetemplate
was created from.
HDF_READ IDL Reference Guide
PREFIX
When HDF_READ is called without a template, it calls HDF_BROWSER to review the
contentsof anHDFleandcreatethedefault output namesfor thevariousdataelements.
By default, these names begin with a prex derived from the lename. Set this keyword
to a string value to be used in place of the default prex.
Graphical User Interface Menu Options
The following options are available from the graphical user interface menus.
Pulldown Menu
The following table shows the options available with the pulldown menu.
Preview Button
If you have selected an image from the pulldown menu, click on this button to view the
image. If youhaveselectedadataitemthat canbeplottedintwodimensions, click onthis
button to view a 2D plot of the data (the default) or click on the Surface radio button
todisplayasurfaceplot, or click on theContour radiobutton todisplayacontour plot.
You can also select the Fit to Window checkbox to t the image to the window.
Read Checkbox
Select this checkbox to extract the current data or metadata item from the HDF le.
Menu Selection Description
HDF/NetCDF Summary Overview of HDF le contents
DFR8 (8-bit Images) 8-bit images, palettes, and their attributes
DF24 (24-bit Images) 24-bit images and their attributes
DFP (Palettes) Image palettes
SD (Variables/Attributes) Scientic Datasets and attributes
AN (Annotations) Annotations
GR (Generic Raster) Images
GR Global Attributes
HDF-EOS Summary Overview of HDF-EOS le contents
Point
Swath
Grid
Table 9-11: HDF_BROWSER Pulldown Menu Options
IDL Reference Guide HDF_READ
Extract As
Specify a name for the extracted data or metadata item
Note TheRead Checkbox must beselected for theitemtobeextracted. Default namesare
generated for all data items, but may be changed at any time by the user.
Example
template = HDF_BROWSER(my.hdf)
output_structure = HDF_READ(TEMPLATE=template)
or,
output_structure = HDF_READ(my.hdf)
or,
output_structure = HDF_READ() Selectmy.hdf withthefilelocator
or,
output_structure = HDF_READ(just_like_my.hdf, TEMPLATE=template)
Note VgroupsandVdatasarenot currentlysupported. HDFleswritten with HDF4.1or
greater may not be readable. Because of a bug in HDF4.0r2, multiple use of
HDF_READ or HDF_BROWSER on les containing both DFR8 and DF24 images
may cause the DFR8 and DF24 interfaces to become unusable. In these cases,
HDF_READ will not be able to extract DFR8 or DF24 images, and access to these
interfaceswill fail for theduration of theIDL session. RestartingIDL will allowyou
to again use HDF_READ to extract the contents of the HDF le.
See Also
HDF_BROWSER, Scientic Data Formats
HEAP_GC IDL Reference Guide
HEAP_GC
The HEAP_GC procedure performsgarbagecollection on heap variables. It searches all
current IDL variables (including common blocks, widget user values, etc.) for pointers
and object references and determines which heap variables have become inaccessible.
Pointer heap variables are freed (via PTR_FREE) and all memory used by the heap
variable is released. Object heap variables are destroyed (via OBJ_DESTROY), also
freeing all used memory.
The default action is to perform garbage collection on all heap variables regardless of
type. Use the POINTER and OBJECT keywords to remove only specic types.
Note Garbagecollection isan expensiveoperation. When possible, applicationsshouldbe
written to avoid losingpointer and object referencesand avoid theneed for garbage
collection.
Caution HEAP_GC uses a recursive algorithm to search for unreferenced heap variables. If
HEAP_GC is used to manage certain data structures, such as large linked lists, a
potentially large number of operations may be pushed onto the system stack. If so
many operations are pushed that the stack runs out of room, IDL will crash.
Calling Sequence
HEAP_GC
Keywords
PTR
Set this keyword to perform garbage collection on pointer heap variables only.
OBJ
Set this keyword to perform garbage collection on object heap variables only.
Note Settingboth the PTR and OBJ keywords is the same a setting neither.
VERBOSE
If this keyword is set, HEAP_GC writes a one line description of each heap variable, in
theformat used by theHELPprocedure, asthevariableisdestroyed. Thisisadebugging
aid that can beused by programdevelopersto check for heap variableleaksthat need to
be located and eliminated.
IDL Reference Guide HELP
HELP
The HELP procedure gives the user information on many aspects of the current IDL
session. The specic area for which help is desired is selected by specifying the
appropriate keyword. If no arguments or keywords are specied, the default is to show
the current nesting of procedures and functions, all current variables at the current
program level, and open les. Only one keyword can be specied at a time.
Calling Sequence
HELP, Expression
1
, ..., Expression
n
Arguments
Expression(s)
The arguments are interpreted differently depending on the keyword selected. If no
keyword isselected, HELPdisplaysbasicinformation for itsparameters. For example, to
see the type and structure of the variable A, enter:
HELP, A
Keywords
Notethat theuseof someof thefollowingkeywordscausesanyargumentstoHELPtobe
ignored and HELPprovidesother typesof information instead. If thedescription of the
keyword does not explicitly mention the arguments, the arguments are ignored.
ALL_KEYS
Set this keyword to show current function-key denitions as set by DEFINE_KEY. If no
arguments are supplied, information on all function keys is displayed. If arguments are
provided, they must be scalar strings containing the names of function keys, and
information on the specied keys is given. Under Unix, this keyword is different from
KEYS because every key is displayed, no matter what its current programming. Under
VMS and Windows, the two keywords mean the same thing. On the Macintosh, keys
cannot be dened via DEFINE_KEY.
BREAKPOINTS
Set this keyword to display the breakpoint table which shows the program module and
location for each breakpoint.
CALLS
Set this keyword to a named variable in which to store the procedure call stack. Each
string element contains the name of the program module, source le name, and line
number. Array element zero containstheinformation about thecaller of HELP, element
HELP IDL Reference Guide
one contains information about its caller, etc. This keyword is useful for programs that
require traceback information.
DEVICE
Set this keyword to show information about the currently selected graphics device. This
informationisdependent ontheabilitiesof thecurrent device, but thenameof thedevice
is always given. Arguments to HELP are ignored when DEVICE is specied.
DLM
Set this keyword to display all known dynamically loadable modules and their state
(loaded or not loaded).
FILES
Set thiskeyword to display information about leunits. If no argumentsaresupplied in
thecall toHELP, information on all open leunits(except thespecial units0, -1, and -2)
isdisplayed. If argumentsareprovided, theyaretakentobeinteger leunit numbers, and
information on the specied le units is given.
For example, the command:
HELP, /FILES, -2, -1, 0
gives information below about the default le units:
Unit Attributes Name
-2 Write, Truncate, Tty, Reserved <stderr>
-1 Write, Truncate, Tty, Reserved <stdout>
0 Read, Tty, Reserved <stdin>
The attributes column tells about the characteristics of the le. For instance, the le
connected tological leunit 2iscalled stderr and isthestandard error le. It isopened
for writeaccess(Write), isanewle(Truncate), isaterminal (Tty), andcannot beclosed
by the CLOSE command (Reserved).
HEAP_VARIABLES
Set this keyword to display help information for all the current heap variables.
KEYS
Set this keyword to show current function key denitions as set by DEFINE_ KEY, for
those function keys that are currently programmed to perform a function. Under Unix,
this keyword is different from ALL_KEYS because that keyword displays every key, no
matter what its current programming. Under VMS and Windows, the two keywords
mean thesamething. On theMacintosh, keyscannot bedened viaDEFINE_KEY. If no
arguments are supplied, information on all function keys is displayed. If arguments are
provided, they must be scalar strings containing the names of function keys, and
information on the specied keys is given.
LAST_MESSAGE
Set this keyword to display the last error message issued by IDL.
IDL Reference Guide HELP
MEMORY
Set thiskeyword to seeareport on theamount of dynamicmemory (in bytes) currently
in useby theIDL session, and thenumber of timesdynamicmemory hasbeen allocated
and deallocated. Arguments to HELP are ignored when MEMORY is specied.
MESSAGES
Set thiskeywordtodisplayall knownmessageblocksandtheerror spacerangeintowhich
they are loaded.
NAMES
Astringof thenamesof variableswhosevaluesaretobeprinted. Thisstring, which must
be enclosed in quotes, can contain the standard wildcard matching characters, * and
?. For example, to print only the values of variables beginning with A, use the
command HELP, NAME='a*'. Similarly, HELP, NAME='?', prints the values of all
variables with a single-character name.
OBJECTS
Set this keyword to display information on dened object classes. If no arguments are
provided, all currently-dened object classes are shown. If arguments are provided, the
denition of the object class for the heap variables referred to is displayed.
Information is provided on inherited superclasses and all known methods. A method is
knowntoIDLonlyif it hasbeencompiledinthecurrent IDLsessionandcalledbyitsown
classor asubclass. Methodsthat havenot been compiledyet will not beshown. Thus, the
list of methodsdisplayedbyHELPisnot necessarilyacompletelist of all possiblemethod
for the object class.
If called within aclass method, theOBJECTSkeyword also displaystheinstancedataof
the object on which it was called.
OUTPUT
Set thiskeyword equal toanamed variablethat will contain astringarray containingthe
formattedoutput of theHELPcommand. Eachlineof formattedoutput becomesasingle
element in the string array.
Caution The OUTPUT keyword is primarily for use in capturing HELP output in order to
displayit someplaceelse, such asin atext widget. Thiskeyword isnotintended tobe
usedinobtainingprogrammaticinformationabout theIDLsession, andisformatted
to behuman readable. Research Systemsreservestheright to changetheformat and
content of thistext atanytime, withoutwarning. If you ndyourself usingOUTPUT
for anon-displaypurpose, you should consider submittingan enhancement request
for a function that will provide the information you require in a safe form.
RECALL_COMMANDS
Set thiskeywordtodisplaythesavedcommandsinthecommandinput buffer. Bydefault,
IDL saves the last 20 lines of input in a buffer from which they can be recalled for
command line editing. Arguments to HELP are ignored when RECALL is specied.
HELP IDL Reference Guide
Thenumber of linessavedcan bechangedbyassigningthedesirednumber of linestothe
environment variable !EDIT_INPUT in the IDL startup le. See !EDIT_INPUT on
page 42 of theIDL ReferenceGuidefor details.
ROUTINES
Set this keyword to show a list of all compiled procedures and functions with their
parameter names. Keyword parameters accepted by each module are shown to the right
of the routine name.
SOURCE_FILES
Set thiskeyword to display information on proceduresand functionswritten in theIDL
language that have been compiled during the current IDL session. Full path names
(relative to the current directory) of compiled .pro les are displayed.
STRUCTURES
Set thiskeyword to display information on structure-typevariables. If no argumentsare
provided, all currently-dened structures are shown. If arguments are provided, the
structuredenition for thoseexpressionsisdisplayed. It isoften moreconvenient to use
HELP, /STRUCTURES instead of PRINT to look at the contents of a structure variable
because it shows the names of the elds as well as the data.
SYSTEM_VARIABLES
Set this keyword to display information on all system variables. Arguments are ignored.
TRACEBACK
Set this keyword to display the current nesting of procedures and functions.
Example
To see general information on the current IDL session, enter:
HELP
To see information on the structure denition of the system variable !D, enter:
HELP, !D, /STRUCTURES
See Also
Getting Help with IDL on page 241 of Using IDL.
IDL Reference Guide HILBERT
HILBERT
The HILBERT function returns a series that has all periodic terms phase-shifted by 90
degrees. The output is a complex-valued vector with the same size as the input vector.
This transform has the interesting property that the correlation between a series and its
own Hilbert transform is mathematically zero.
HILBERTgeneratesthefast Fourier transformusingtheFFTfunction, andshiftstherst
half of the transform products by +90 degrees and the second half by -90 degrees. The
constant elements in the transform are not changed. Angle shifting is accomplished by
multiplyingor dividingby thecomplex number, i = (0.0000, 1.0000). Theshifted vector
isthen submittedtoFFT for transformation back tothetime domain andtheoutput is
dividedbythenumber elementsin thevector tocorrect for multiplication effect peculiar
to the FFT algorithm.
Note: Because HILBERT uses FFT, it exhibits the same side effects with respect to input
arguments as that function.
hilbert.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = HILBERT(X [, D])
Arguments
X
An n-element oating-point or complex-valued vector.
D
A ag for rotation direction. Set D = +1 for a positive rotation (the default). Set D = -1
for a negative rotation.
See Also
FFT
HIST_2D IDL Reference Guide
HIST_2D
TheHIST_2Dfunction returnsthetwodimensional densityfunction (histogram) of two
variables, a longword array of dimensions (MAX(V1)+1, MAX(V2)+1). Result(i,j) is
equal to the number of simultaneous occurrences of V1 = i and V2 = j at the specied
element.
hist_2d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = HIST_2D(V1, V2)
Arguments
V1, V2
Arrays containing the variables. V1 and V2 must be of byte, integer, or longword type,
and must contain no negative elements.
Keywords
BIN1
Thesizeof each bin in theV1direction (column width). If thiskeyword isnot specied,
the size is set to 1.
BIN2
Thesizeof each bin in theV2direction (rowheight). If thiskeyword isnot specied, the
size is set to 1.
MAX1
MAX1 is the maximumV1 value to consider. If this keyword is not specied, then V1 is
searched for its largest value.
MAX2
MAX2 is the maximumV2 value to consider. If this keyword is not specied, then V2 is
searched for its largest value.
MIN1
MIN1istheminimumV1valueto consider. If thiskeyword isnot specied, then it isset
to 0.
MIN2
MIN2istheminimumV2valueto consider. If thiskeyword isnot specied, then it isset
to 0.
IDL Reference Guide HIST_2D
Example
To return the 2D histogram of two byte images:
R = HIST_2D(image1, image2)
Toreturn the2Dhistogrammadefromtwooatingpoint imageswith rangeof -1to+1,
and with 100 bins:
R = HIST_2D(LONG((F1+1) * 50), LONG((F2+1) * 50))
See Also
H_EQ_CT, H_EQ_INT, HIST_EQUAL, HISTOGRAM
HIST_EQUAL IDL Reference Guide
HIST_EQUAL
The HIST_EQUAL function returns a histogram-equalized byte array. The
HISTOGRAM function isused to obtain thedensity distribution of theinput array. The
histogramisintegrated toobtain thecumulativedensity-probabilityfunction and nally
the lookup function is used to transform to the output image.
Theresultingarray isalwaysof bytetypeand isscaled from0to thevalueset by theTOP
keyword.
Note: Floating-point arrays should not have small ranges, (e.g., less than around 255)
unless a binsize is specied.
hist_equal.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = HIST_EQUAL(A)
Arguments
A
The array to be histogram-equalized.
Keywords
MINV
Theminimumvalueto consider. If thiskeyword isomitted, zero isused. Input elements
lessthan or equal toMINVareoutput aszero. MINVshouldbegreater than or equal to0.
MAXV
The maximum value to consider. If this keyword is omitted, the maximum element is
used. Input elements greater than or equal to MAXV are output as 255.
BINSIZE
Sizeof bin touse. If thiskeywordisomitted, thevalue1isused. Thisparameter isignored
for byte type data.
TOP
The maximum value to scale the output array. If this keyword is omitted, 255 is used.
Example
Create a sample image using the DIST function and display it by entering:
IDL Reference Guide HIST_EQUAL
image = DIST(100)
TV, image
Create a histogram-equalized version of the byte array, image, and display the new
version. Useaminimuminput valueof 10, amaximuminput valueof 200, and limit the
top value of the output array to 220. Enter:
new = HIST_EQUAL(image, MINV = 10, MAXV = 200, TOP = 220)
TV, new
See Also
H_EQ_CT, H_EQ_INT, HIST_2D, HISTOGRAM
HISTOGRAM IDL Reference Guide
HISTOGRAM
The HISTOGRAM function returns a longword vector equal to the density function of
Array. In the simplest case, the density function, at subscript i, is the number of Array
elements in the argument with a value of i.
Let F
i
= thevalueof element i, 0 i < n. Let H
v
= result of histogramfunction, alongword
vector. The denition of the histogram function becomes:
Caution There may not always be enough virtual memory available to nd the density
functions of arrays that contain a large number of bins.
For bivariate probability distributions, use the HIST_2D function.
HISTOGRAM can optionally return an array containing a list of the original array
subscriptsthat contributed toeach histogrambin. Thislist, commonly called thereverse
(or backwards) indexlist, efcientlydetermineswhicharrayelementsareaccumulatedin
aset of histogrambins. Atypical application of thereverseindex list isreversehistogram
or scatter plot interrogationahistogrambin or 2Dscatter plot location ismarked with
the cursor and the original data items within that bin are highlighted.
Calling Sequence
Result = HISTOGRAM(Array)
Arguments
Array
The vector or array for which the density function is to be computed.
Keywords
BINSIZE
The size of the bin to use. If this keyword is not specied, a bin size of 1 is used.
H
v
P F
i
v , ( ),
i 0 =
n 1
= v 0 1 2 ...
Max Min
Binsize
-------------------------- -
, , , , =
P F
i
v , ( )
1, v F
i
Min ( ) Binsize v 1 + <
0, Otherwise
'
=
IDL Reference Guide HISTOGRAM
INPUT
Set thiskeyword to anamed variablethat containsan array to beadded to theoutput of
HISTOGRAM. Thedensityfunction of Arrayisadded totheexistingcontentsof INPUT
and returned astheresult. Thearrayisconverted tolongword typeif necessaryand must
have at least as many elements as are required to form the histogram.
Multiple histograms can be efciently accumulated by specifying partial sums via this
keyword.
MAX
MAXisthemaximumvaluetoconsider. Notethat thedatatypeof thevaluespeciedfor
MAX should match the data type of the input array; specifying mismatched data types
may produce undesired results. If this keyword is not specied, Array is searched for its
largest value.
MIN
MIN istheminimumvalueto consider. Notethat thedatatypeof thevaluespecied for
MIN should match the data type of the input array; specifying mismatched data types
may produceundesired results. If thiskeyword isnot specied, and Arrayisof typebyte,
0 is used. If this keyword is not specied and Array is not of byte type, Array is searched
for its smallest value.
NAN
OMAX
Anamedvariablethat, upon exit, containsthemaximumdatavalueusedin constructing
the histogram.
OMIN
Anamedvariablethat, upon exit, containstheminimumdatavalueusedin constructing
the histogram.
REVERSE_INDICES
Set thiskeyword to anamed variablein which thelist of reverseindicesisreturned. This
list isreturned asalongword vector whosenumber of elementsisthesumof thenumber
of elements in the histogram, N, and the number of array elements included in the
histogram, plus one.
Thesubscriptsof theoriginal array elementsfallingin theith bin, 0 i < N, aregiven by
the expression: R(R[ i] : R(i+1)-1), where R is the reverse index list. If R[ i] is equal to
R[ i+1] , no elements are present in theith bin.
Example Make the histogram of array A:
H = HISTOGRAM(A, REVERSE_INDICES = R)
HISTOGRAM IDL Reference Guide
IF R(i) NE R(i+1) THEN A(R(R(I) : R(i+1)-1)) = 0
Setall elementsofAthatareinthe
ith bin of H to 0.
The above is usually more efcient than the following:
bini = WHERE(A EQ i, count)
IF count NE 0 THEN A(bini) = 0
Examples
Create a simple, two-dimensional dataset with the DIST function by entering:
D = DIST(200)
Plot thehistogramof D with abin sizeof 1and thedefault minimumand maximumby
entering:
PLOT, HISTOGRAM(D)
To plot a histogram considering only those values from 10 to 50 using a bin size of 4,
enter:
PLOT, HISTOGRAM(D, MIN = 10, MAX = 50, BINSIZE = 4)
The HISTOGRAM function can also be used to increment the elements of one vector
whosesubscriptsarecontained in another vector. To increment thoseelementsof vector
A indicated by vector B, use the command:
A = HISTOGRAM(B, INPUT=A, MIN=0, MAX=N_ELEMENTS(A)-1)
This method works for duplicate subscripts, whereas the statement:
A[B] = A[B]+1
never addsmorethan 1toanyelement, even if that element isduplicated in vector B. For
example, the following commands:
A = LONARR(5)
B = [2,2,3]
PRINT, HISTOGRAM(B, INPUT=A, MIN=0, MAX=4)
print:
0 0 2 1 0
while the commands:
A = LONARR(5)
A[B] = A[B]+1
PRINT, A
gives the result:
IDL Reference Guide HISTOGRAM
0 0 1 1 0
The following example demonstrates how to use HISTOGRAM.
PRO t_histogram
data = [[-5, 4, 2, -8, 1], $
[ 3, 0, 5, -5, 1], $
[ 6, -7, 4, -4, -8], $
[-1, -5, -14, 2, 1]]
hist = HISTOGRAM(data)
bins = FINDGEN(N_ELEMENTS(h)) + MIN(data)
PRINT, MIN(hist)
PRINT, bins
PLOT, bins, hist, YRANGE = [MIN(hist)-1, MAX(hist)+1], PSYM = 10, $
XTITLE = Bin Number, YTITLE = Density per Bin
END
IDL prints:
0
-14.0000 -13.0000 -12.0000 -11.0000 -10.0000 -9.00000
-8.00000 -7.00000 -6.00000 -5.00000 -4.00000 -3.00000
-2.00000 -1.00000 0.00000 1.00000 2.00000 3.00000
4.00000 5.00000 6.00000
See Also
H_EQ_CT, H_EQ_INT, HIST_2D, HIST_EQUAL
HLS IDL Reference Guide
HLS
The HLS procedure creates a color table based on the HLS (Hue, Lightness, Saturation)
color system.
Usingtheinput parameters, aspiral throughthedouble-endedHLSconeistraced. Points
alongtheconeareconvertedfromHLStoRGB. Thecurrent colortable(andtheCOLORS
common block) contains the new colortable on exit.
hls.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
HLS, Litlo, Lithi, Satlo, Sathi, Hue, Loops [, Colr]
Arguments
Litlo
Starting lightness, from 0 to 100%.
Lithi
Ending lightness, from 0 to 100%.
Satlo
Starting saturation, from 0 to 100%.
Sathi
Ending saturation, from 0 to 100%.
Hue
Starting Hue, from 0 to 360 degrees. Red = 0 degs, green = 120, blue = 240.
Loops
The number of loops through the color spiral. This parameter does not have to be an
integer. A negative value causes the loops to traverse the spiral in the opposite direction.
Colr
An optional (256,3) integer array in which thenewR, G, and Bvaluesarereturned. Red
= Colr[ *,0] , green = Colr[ *,1] , blue = Colr[ *,2] .
See Also
COLOR_CONVERT, HSV, PSEUDO
IDL Reference Guide HQR
HQR
TheHQRfunctionreturnsall eigenvaluesof anupper Hessenbergarray. Usingtheoutput
producedbytheELMHESfunction, thisfunctionndsall eigenvaluesof theoriginal real,
nonsymmetric array. The result is an n-element complex vector.
HQRisbasedon theroutinehqr describedin section 11.6of Numerical RecipesinC:The
Art of Scientic Computing(Second Edition), published by Cambridge University Press,
and is used by permission.
Calling Sequence
Result = HQR(A)
Arguments
A
An n by n upper Hessenberg array. Typically, A would be an array resulting from an
application of ELMHES.
Keywords
DOUBLE
COLUMN
Example
To compute the eigenvalues of a real, non-symmetric unbalanced array, rst dene the
array A:
A = [[ 1.0, 2.0, 0.0, 0.0, 0.0], $
[-2.0, 3.0, 0.0, 0.0, 0.0], $
[ 3.0, 4.0, 50.0, 0.0, 0.0], $
[-4.0, 5.0, -60.0, 7.0, 0.0], $
[-5.0, 6.0, -70.0, 8.0, -9.0]]
hes = ELMHES(A) Computetheupper Hessenberg
form of thearray.
evals = HQR(hes) Computetheeigenvalues.
HQR IDL Reference Guide
Sort the eigenvalues into ascending order based on their real components:
evals = evals(SORT(FLOAT(evals)))
PRINT, evals Print theresult.
IDL prints:
( -9.00000, 0.00000)( 2.00000, -1.73205)
( 2.00000, 1.73205)( 7.00000, 0.00000)
( 50.0000, 0.00000)
This is the exact solution vector to ve-decimal accuracy.
See Also
EIGENVEC, ELMHES, TRIQL, TRIRED
IDL Reference Guide HSV
HSV
TheHSV procedurecreatesacolor tablebased on theHSV (Hue, Saturation, and Value)
color system.
Usingtheinput parameters, aspiral through thesingle-endedHSVconeistraced. Points
alongtheconeareconvertedfromHLStoRGB. Thecurrent colortable(andtheCOLORS
common block) contains the new colortable on exit.
hsv.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
HLS, Vlo, Vhi, Satlo, Sathi, Hue, Loops [, Colr]
Arguments
Vlo
Starting value, from 0 to 100%.
Vhi
Ending value, from 0 to 100%.
Satlo
Sathi
Hue
Starting Hue, from 0 to 360 degrees. Red = 0 degs, green = 120, blue = 240.
Loops
The number of loops through the color spiral. This parameter does not have to be an
integer. A negative value causes the loops to traverse the spiral in the opposite direction.
Colr
An optional (256,3) integer array in which thenewR, G, and Bvaluesarereturned. Red
= Colr[ *,0] , green = Colr[ *,1] , blue = Colr[ *,2] .
See Also
COLOR_CONVERT, HLS, PSEUDO
IBETA IDL Reference Guide
IBETA
The IBETA function computes the incomplete beta function.
ibeta.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = IBETA(A, B, X)
Arguments
A
A positive integer, single-, or double-precision oating-point scalar that species the
parametric exponent of the integrand.
B
X
An integer, single-, or double-precision oating-point scalar, in the interval [ 0, 1] , that
species the upper limit of integration.
Example
Compute the incomplete beta function for the corresponding elements of A, B, and X.
Dene an array of parametric exponents.
A = [0.5, 0.5, 1.0, 5.0, 10.0, 20.0]
B = [0.5, 0.5, 0.5, 5.0, 5.0, 10.0]
Dene the upper limits of integration.
X = [0.01, 0.1, 0.1, 0.5, 1.0, 0.8]
Allocate an array to store the results.
result = FLTARR(N_ELEMENTS(A))
I
x
a b , ( )
t
a 1
1 t ( )
b 1
t d
0
x
t
a 1
1 t ( )
b 1
t d
0
1
------------------------------------------------
IDL Reference Guide IBETA
Computetheincompletebetafunctions. Notethat theresult for eachelement intheinput
arrays must be computed individually.
FOR K = 0, N_ELEMENTS(A)-1 DO $
result[K] = IBETA(A[K], B[K], X[K])
PRINT, result
IDL prints:
[0.0637686, 0.204833, 0.0513167, 0.500000, 1.00000, 0.950736]
See Also
BETA, GAMMA, IGAMMA, LNGAMMA
IDENTITY IDL Reference Guide
IDENTITY
The IDENTITY function returns an n by n identity array (an array with ones along the
main diagonal and zeros elsewhere).
identity.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = IDENTITY(N)
Argument
N
The desired column and row dimensions.
Keyword
DOUBLE
Set this keyword to return a double-precision identity array.
Example
Dene an array, A.
A = [[ 2.0, 1.0, 1.0, 1.5], $
[ 4.0, -6.0, 0.0, 0.0], $
[-2.0, 7.0, 2.0, 2.5], $
[ 1.0, 0.5, 0.0, 5.0]]
inverse = INVERT(A) ComputetheinverseofAusingthe
INVERT function
Verifytheaccuracyof thecomputedinverseusingthemathematical identity, AxA
-1
- I(4)
= 0; whereA
-1
istheinverseof A, I(4) isthe4by 4identity array and 0isa4by 4array of
zeros.
PRINT, A ## inverse - IDENTITY(4)
See Also
FINDGEN, FLTARR
IDL Reference Guide IGAMMA
IGAMMA
The IGAMMA function computes the incomplete gamma function.
IGAMMAuseseither apower seriesrepresentation or acontinuedfractionsmethod. If X
islessthan or equal toA+1, apower seriesrepresentation isused. If Xisgreater than A+1,
a continued fractions method is used.
igamma.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = IGAMMA(A, X)
Arguments
A
X
Aninteger, single-, or double-precisionoating-point scalar that speciestheupper limit
of integration.
Keywords
METHOD
Set this keyword to a named variable that will contain the method used to compute the
incompletegammafunction. Avalueof 0indicatesthat apower seriesrepresentationwas
used. A value of 1 indicates that a continued fractions method was used.
Example
Compute the incomplete gamma function for the corresponding elements of A and X.
Dene an array of parametric exponents.
A = [0.10, 0.50, 1.00, 1.10, 6.00, 26.00]
P
x
a ( )
e
t
t
a 1
t d
0
x
e
t
t
a 1
t d
0
-------------------------------
IGAMMA IDL Reference Guide
Dene the upper limits of integration.
X = [0.0316228, 0.0707107, 5.00000, 1.04881, 2.44949, 25.4951]
Allocate an array to store the results.
result = FLTARR(N_ELEMENTS(A))
Compute the incomplete gamma functions. Note that the result for each element in the
input arrays must be computed individually.
FOR K = 0, N_ELEMENTS(A)-1 DO $
result[K] = IGAMMA(A[K], X[K])
PRINT, result
IDL prints:
[0.742026, 0.293128, 0.993262, 0.607646, 0.0387318, 0.486387]
See Also
BETA, GAMMA, IBETA, LNGAMMA
IDL Reference Guide IMAGE_CONT
IMAGE_CONT
The IMAGE_CONT procedure overlays an image with a contour plot.
image_cont.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
IMAGE_CONT, A
Arguments
A
The two-dimensional array to display and overlay.
Keywords
ASPECT
Set this keyword to retain the images aspect ratio. Square pixels are assumed. If
WINDOW_SCALE is set, the aspect ratio is automatically retained.
INTERP
If this keyword is set, bilinear interpolation is used if the image is resized.
WINDOW_SCALE
Set this keyword to scale the window size to the image size. Otherwise, the image size is
scaled to the window size. This keyword is ignored when outputting to devices with
scalable pixels (e.g., PostScript).
Example
A = BYTSCL(DIST(356)) Createan imageto display.
IMAGE_CONT, A, /WINDOW Display imageand overplot con-
tour lines.
See Also
CONTOUR, TV
IMAGINARY IDL Reference Guide
IMAGINARY
TheIMAGINARYfunction returnstheimaginary part of itscomplex-valued argument.
If thecomplex-valued argument isdouble-precision, theresult will bedouble-precision,
otherwise the result will be single-precision oating-point.
Calling Sequence
Result = IMAGINARY(Complex_Expression)
Arguments
Complex_Expression
The complex-valued expression for which the imaginary part is desired.
Example
Create an array of complex values by entering:
C = COMPLEX([1,2,3],[4,5,6])
Print just the imaginary parts of each element in C by entering:
PRINT, IMAGINARY(C)
IDL prints:
4.00000 5.00000 6.00000
See Also
COMPLEX, DCOMPLEX
IDL Reference Guide INDGEN
INDGEN
The INDGEN function returns an integer array with the specied dimensions. Each
element of the array is set to the value of its one-dimensional subscript.
Calling Sequence
Result = INDGEN(D
1
, ..., D
n
)
Arguments
D
i
Keywords
BYTE
Set this keyword to create a byte array.
COMPLEX
Set this keyword to create a complex, single-precision, oating-point array.
DCOMPLEX
Set this keyword to create a complex, double-precision, oating-point array.
DOUBLE
Set this keyword to create a double-precision, oating-point array.
FLOAT
Set this keyword to create a single-precision, oating-point array.
L64
Set this keyword to create a 64-bit integer array.
LONG
Set this keyword to create a longword integer array.
STRING
Set this keyword to create a string array.
TYPE
list of IDL type codes.
INDGEN IDL Reference Guide
UINT
Set this keyword to create an unsigned integer array.
UL64
Set this keyword to create an unsigned 64-bit integer array.
ULONG
Set this keyword to create an unsigned longword integer array.
Example
Create I, a 5-element vector of integer values with each element set to the value of its
subscript by entering:
I = INDGEN(5)
See Also
BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, LINDGEN, LINDGEN,
IDL Reference Guide INT_2D
INT_2D
TheINT_2Dfunction computesthedoubleintegral of abivariatefunction usingiterated
Gaussian quadrature. Thealgorithmstransformation dataisprovided in tabulated form
with 15 decimal accuracy.
int_2d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = INT_2D(Fxy, AB_Limits, PQ_Limits, Pts)
Arguments
Fxy
bivariatefunction tobeintegrated. Thefunction must accept XandYandreturn ascalar
result.
For example, if we wish to integrate the following function:
We dene a function FXY to express this relationship in the IDL language:
FUNCTION fxy, X, Y
RETURN, EXP(-X^2. -Y^2.)
END
AB_Limits
A two-element vector containing the lower (A) and upper (B) limits of integration with
respect to the variablex.
PQ_Limits
Ascalar stringspecifyingthenameof auser-suppliedIDLfunction that denesthelower
(P(x)) and upper (Q(x)) limitsof integration with respect tothevariabley. Thefunction
must accept x and return a two-element vector result.
For example, we might write the following IDL function to represent the limits of
integration with respect to y:
FUNCTION PQ_limits, X
RETURN, [-SQRT(16.0 - X^2), SQRT(16.0 - X^2)]
END
f x y , ( ) e
x
2
y
2
=
INT_2D IDL Reference Guide
Pts
Thenumber of transformation pointsusedin thecomputation. Possiblevaluesare: 6, 10,
20, 48, or 96.
Keywords
DOUBLE
ORDER
A scalar valueof either 0or 1. If set to 0, theintegral iscomputed usingadx-dy order of
integration. If set to 1, the integral is computed using a dx-dy order of integration.
Example
Compute the double integral of the bivariate function.
function PQ_Limits, x
return, [0.0, x^2]
end Definethelimitsofintegrationfor
y as a function of x.
AB_Limits = [0.0, 2.0] Definelimits of integration for x.
Using the function and limits dened above, integrate with 48 and 96 point formulas
using a dy-dx order of integration and double-precision arithmetic:
PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 48, /DOUBLE)
PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 96, /DOUBLE)
INT_2D with 48 transformation points yields: 0.055142668
INT_2D with 96transformation points yields: 0.055142668
Compute the double integral of the bivariate function.
function PQ_Limits, y
return, [sqrt(y), 2.0]
I y x
5
( ) cos y d x d
y 0.0 =
y x
2
=
x 0.0 =
x 2.0 =
=
I y x
5
( ) cos x d y d
y 0.0 =
y x
2
=
x 0.0 =
x 2.0 =
=
end Definethelimitsofintegrationfor
y as a function of x.
AB_Limits = [0.0, 4.0] Definelimits of integration for x.
Using the function and limits dened above, integrate with 48 and 96 point formulas
using a dy-dx order of integration and double-precision arithmetic:
PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 48, /DOUBLE, /ORDER)
PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 96, /DOUBLE, ORDER)
The exact solution (7 decimal accuracy) is:0.055142668
See Also
INT_3D, INT_TABULATED, QROMB, QROMO, QSIMP
INT_3D IDL Reference Guide
INT_3D
TheINT_3D function computesthetripleintegral of atrivariatefunction usingiterated
Gaussian quadrature. Thealgorithmstransformation dataisprovided in tabulated form
with 15 decimal accuracy.
int_3d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = INT_3D(Fxyz, AB_Limits, PQ_Limits, UV_Limits, Pts)
Arguments
Fxyz
trivariate function to be integrated. The function must accept X, Y, and Z, and return a
scalar result.
For example, if we wish to integrate the following function:
We dene a function FXY to express this relationship in the IDL language:
FUNCTION fxyz, X, Y, Z
RETURN, z*(x^2+y^2+z^2)^1.5
END
AB_Limits
A two-element vector containing the lower (A) and upper (B) limits of integration with
respect to the variablex.
PQ_Limits
(P(x)) and upper (Q(x)) limitsof integration with respect tothevariabley. Thefunction
must accept x and return a two-element vector result.
integration with respect to y:
FUNCTION PQ_limits, X
RETURN, [-SQRT(4.0 - X^2), SQRT(4.0 - X^2)]
END
f x y z , , ( ) z x
2
y
2
z
2
+ + ( )
3 2 /
=
UV_Limits
(U(x,y)) and upper (V(x,y)) limits of integration with respect to the variablez. The
function must accept xand yand return a two-element vector result.
integration with respect to z:
FUNCTION UV_limits, X, Y
RETURN, [0, SQRT(4.0 - X^2 - Y^2)]
END
Pts
Thenumber of transformation pointsusedin thecomputation. Possiblevaluesare: 6, 10,
20, 48, or 96.
Keywords
DOUBLE
Example
Compute the triple integral of the trivariate function
Using the functions and limits dened above, integrate with 10, 20, 48, and 96 point
formulas (using double-precision arithmetic):
PRINT, INT_3D('Fxyz', [-2.0, 2.0], 'PQ_Limits', 'UV_Limits', 10, /D)
INT_3D with 96transformation points yields: 57.446266
The exact solution (6 decimal accuracy) is: 57.446267
See Also
INT_2D, INT_TABULATED, QROMB, QROMO, QSIMP
I z x
2
y
2
z
2
+ + ( )
3 2 /
z d y d x d
z 0 =
z 4 x
2
y
2
=
y 4 x
2
=
y 4 x
2
=
x 2 =
x 2 =
=
INT_TABULATED IDL Reference Guide
INT_TABULATED
TheINT_TABULATED function integratesatabulated set of data{ x
i
, f
i
} on theclosed
interval [ MIN(x) , MAX(x)] , using a ve-point Newton-Cotes integration formula.
CautionDatathat ishighly oscillatory requiresasufcient number of samplesfor an accurate
integral approximation.
int_tabulated.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = INT_TABULATED(X, F)
Arguments
X
The tabulated single- or double-precision oating-point x-value data. Data may be
irregularly gridded and in randomorder. (If thedataisrandomly ordered, set theSORT
keyword.)
Caution Each Xvaluemust beunique; if duplicateXvaluesaredetected, theroutinewill exit
and display a warning message.
F
Thetabulated single- or double-precision oating-point f-valuedata. Upon input to the
function, x
i
and f
i
must have corresponding indices for all values of i. If xis reordered, f
is also reordered.
Keywords
SORT
Set this keyword to sort the tabulated x-value data into ascending order. If SORT is set,
both x and f values are sorted.
Example
Dene 11x-values on the closed interval [ 0.0 , 0.8] :
X = [0.0, .12, .22, .32, .36, .40, .44, .54, .64, .70, .80]
Dene 11f-values corresponding to x
i
:
F = [0.200000, 1.30973, 1.30524, 1.74339, 2.07490, 2.45600, $
2.84299, 3.50730, 3.18194, 2.36302, 0.231964]
IDL Reference Guide INT_TABULATED
result = INT_TABULATED(X, F) Integrate.
In this example, the f-values are generated from a known function
f = 0.2 + 25x - 200x
2
+ 675x
3
- 900x
4
+ 400x
5
whichallowsthedetermination of an exact solution. Acomparison of methodsyieldsthe
following results:
The Multiple Application Trapezoid Method yields: 1.5648
The Multiple Application Simpsons Method yields: 1.6036
INT_TABULATED yields: 1.6271
The exact solution (4 decimal accuracy) is: 1.6405
See Also
INT_2D, INT_3D, QROMB, QROMO, QSIMP
INTARR IDL Reference Guide
INTARR
The INTARR function returns an integer vector or array.
Calling Sequence
Result = INTARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, INTARR sets every element of the result to zero. If NOZERO is nonzero, this
zeroing is not performed and INTARR executes faster.
Example
Create I, a 3-element by 3-element integer array with each element set to 0 by entering:
I = INTARR(3, 3)
See Also
BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, LON64ARR,
LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR
IDL Reference Guide INTERPOL
INTERPOL
The INTERPOL function performs linear interpolation on vectors with a regular or
irregular grid. The result is a single- or double-precision oating-point vector, or a
complex vector if the input vector is complex.
interpol.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
For regular grids: Result = INTERPOL(V, N)
For irregular grids:Result = INTERPOL(V, X, U)
Arguments
V
An input vector of any type except string.
N
The number of points in the result when both input and output grids are regular. The
abscissa values for the output grid will contain the same endpoints as the input.
X
Theabscissavaluesfor V, in theirregularly-gridded case. Xmust havethesamenumber
of elements asV, and the valuesmust be monotonically ascending or descending.
U
Theabscissavaluesfor theresult. Theresult will havethesamenumber of elementsasU.
U does not need to be monotonic.
Example
Create a oating-point vector of 61 elements in the range [ -3, 3] .
X = FINDGEN(61)/10 - 3
V = SIN(X) EvaluateV[x] at each point.
U = [-2.50, -2.25, -1.85, -1.55, -1.20, -0.85, -0.50, -0.10, $
0.30, 0.40, 0.75, 0.85, 1.05, 1.45, 1.85, 2.00, 2.25, 2.75 ]
DefineX-values whereinterpo-
lates aredesired.
result = INTERPOL(V, X, U) Interpolate.
PLOT, X, V Plot thefunction.
OPLOT, U, result Plot theinterpolated values.
INTERPOL IDL Reference Guide
See Also
BILINEAR, INTERPOLATE, KRIG2D
IDL Reference Guide INTERPOLATE
INTERPOLATE
TheINTERPOLATEfunction returnsan arrayof linear, bilinear or trilinear interpolates,
dependingon thedimensionsof theinput array P. Linear interpolatesarereturnedin the
one-dimensional case, bilinear in the two-dimensional case and trilinear interpolates in
thethree-dimensional case. ThereturnedarrayhasthesametypeasPanditsdimensions
depend on those of the location parametersX, Y, and Z, as explained below.
Interpolates outside the bounds of P can be set to a user-specied value by using the
MISSING keyword.
Calling Sequence
Result = INTERPOLATE(P, X [, Y [, Z]])
Arguments
P
Thearray of datavalues. Pmust beaone-, two-, or three-dimensional array of numeric
type.
X, Y, Z
Arrays of numeric type containing the locations for which interpolates are desired. For
linear interpolation (P is a vector), the result has the same dimensions as X. Thei-th
element of the result isP interpolated at location X
i
. TheY and Z parameters should be
omitted.
For bilinear interpolation Z should not be present.
Note INTERPOLATE considers location points with values between zero and n, wheren
isthenumber of valuesin theinput array P, to bevalid. Location pointsoutsidethis
rangeareconsidered missingdata. Location pointsxin therangen-1 x< nreturn
the last data value in the array P.
If the keyword GRID is not set, all location arrays must have the same number of
elements. See the description of the GRID keyword below for more details on how
interpolates are computed fromP and these arrays.
Keywords
CUBIC
INTERPOLATE IDL Reference Guide
improves the reconstruction properties of this algorithm.
0
, and f is sampled
0
CA, July 1974.
GRID
The GRID keyword controls how the location arrays specify where interpolates are
desired. This keyword has no effect in the case of linear interpolation.
IfGRIDisnotset:Thelocationarrays, X, Y, and, if present, Zmust havethesamenumber
of elements. The result has the same structure and number of elements asX.
In thecaseof bilinear interpolation, theresult isobtained asfollows: Let l = X
i
] and k=
Y
i
] . Element i of theresult iscomputed by interpolatingbetween P(l, k), P(l+1, k), P(l,
k+1), and P(l+1, k+1). to obtain theestimated valueat (X
i
, Y
i
). Trilinear interpolation is
a direct extension of the above.
IfGRIDisset:Let N
x
bethenumber of elementsin X, let N
y
bethenumber of elements
in Y, and N
z
be the number of elements in Z. The result has dimensions (N
x
, N
y
) for
bilinear interpolation, and (N
x
, N
y
, N
z
) for trilinear interpolation. For bilinear
interpolation, element (i,j) of the result contains the value of P interpolated at position
(X
i
, Y
i
). For trilinear interpolation, element (i, j, k) of the result isP interpolated at (X
i
,
Y
i
, Z
i
).
MISSING
Thevaluetoreturn for elementsoutsidetheboundsof P. If thiskeyword isnot specied,
interpolatedpositionsthat fall outsidetheboundsof thearrayPthat is, elementsof the
X, Y, or Zargumentsthat areeither lessthan zero or greater than thelargest subscript in
thecorrespondingdimension of Pareset equal to thevalueof thenearest element of P.
IDL Reference Guide INTERPOLATE
Examples
The example below computes bilinear interpolates with the keyword GRID set:
p = FINDGEN(4,4)
PRINT, INTERPOLATE(p, [.5, 1.5, 2.5], [.5, 1.5, 2.5], /GRID)
and prints the 3 by 3 array:
2.50000 3.50000 4.50000
6.50000 7.50000 8.50000
10.5000 11.5000 12.5000
corresponding to the locations:
(.5,.5), (1.5, .5), (2.5, .5),
(.5,1.5), (1.5, 1.5), (2.5, 1.5),
(.5,2.5), (1.5, 2.5), (2.5, 2.5)
Another examplecomputesinterpolates, with GRIDnot set and aparameter outsidethe
bounds of P:
PRINT, INTERPOLATE(p, [.5, 1.5, 2.5, 3.1], [.5, 1.5, 2.5, 2])
prints the result:
2.50000 7.50000 12.5000 11.0000
corresponding to the locations (.5,.5), (1.5, 1.5), (2.5, 2.5) and (3.1, 2.0). Note that the
last location is outside the bounds of P and is set from the value of the last column. The
following command uses the MISSING keyword to set such values to -1:
PRINT, INTERPOLATE(p, [.5, 1.5, 2.5, 3.1], [.5, 1.5, 2.5, 2], $
MISSING = -1)
and gives the result:
2.50000 7.50000 12.5000 -1.00000
See Also
BILINEAR, INTERPOL, KRIG2D
INVERT IDL Reference Guide
INVERT
The INVERT function uses the Gaussian elimination method to compute the inverse of
asquarearray. Theresult isasingle- or double-precisionoating-point array. Errorsfrom
singular or near-singular arrays are accumulated in the optional Status.
Calling Sequence
Result = INVERT(Array [, Status])
Arguments
Array
The array to be inverted. Arraymust have two dimensions of equal size (i.e., a square
array) andcanbeof anytypeexcept string. Notethat theresultingarraywill becomposed
of single- or double-precisionoating-point values, dependingonwhether theDOUBLE
keyword is set.
Status
A named variable to receive the status of the operation. Possible status values are: 0 for
successful completion, 1 for a singular array (which indicates that the inversion is
invalid), and2whichisawarningthat asmall pivot element wasusedandthat signicant
accuracy was probably lost.
Keywords
DOUBLE
Example
Begin with an array A:
A = [[ 5.0, -1.0, 3.0], $
[ 2.0, 0.0, 1.0], $
[ 3.0, 2.0, 1.0]]
result = INVERT(A) Invert.
We can check the accuracy of the inversion by multiplying the inverted array by the
original array. The result should be a 3 x 3 identity array.
PRINT, result # A
IDL prints:
IDL Reference Guide INVERT
1.00000 0.00000 0.00000
0.00000 1.00000 0.00000
0.00000 9.53674e-07 1.00000
See Also
COND, DETERM, INVERT, REVERSE, ROTATE, TRANSPOSE
IOCTL IDL Reference Guide
IOCTL
The IOCTL function provides a thin wrapper over the Unix ioctl(2) system call.
IOTCL performs special functions on the specied le. The set of functions actually
available depends on your version of Unix and the type of le (tty, tape, disk le, etc.)
referred to.
To use IOCTL, read the C programmers documentation describing theioctl(2)
function for the desired device and convert all constants and data to their IDL
equivalents.
The value returned by the systemioctl function is returned as the value of the IDL
IOCTL function.
Calling Sequence
Result = IOCTL(File_Unit [, Request, Arg])
Arguments
File_Unit
The IDL logical le unit (LUN) for the open le on which theioctl request is made.
Request
Alongwordinteger that speciestheioctl request code. Thesecodesareusuallycontained
in C language header les provided by the operating system, and are not generally
portablebetween Unix versions. If oneof the MT keywordsisused, thisargument can
be omitted.
Arg
Anamedvariablethroughwhichdataif passedtoandfromioctl. IOCTLrequestsusually
request datafromthesystemor supplythesystemwithinformation. Theuser must make
Argthe correct type and size. Errors in typing or sizingArgcan corrupt the IDL address
space and/or make IDL crash. If one of the MT keywords is used, this argument can be
omitted.
Keywords
Note that the keyword below that start with MT can be used to issue commonly used
magnetictapeioctl() calls. Whenthesekeywordsareused, theRequestandArgarguments
areignoredandanbeomitted. Magnetictapeoperationsnot availableviathesekeywords
can still be executed by supplying the appropriateRequest and Argvalues. When issuing
magnetictapeIOCTL calls, beawarethat different deviceshavedifferent rulesfor which
ioctl callsareallowed, and when. Thedocumentation for your computer systemexplains
those rules.
IDL Reference Guide IOCTL
BY_VALUE
If thiskeywordisset, Argisconvertedtoascalar longwordandthislongwordispassedby
value. Normally, Argis passed to ioctl by reference (i.e., by address).
MT_OFFLINE
Set this keyword to rewind and unload a tape.
MT_REWIND
Set this keyword to rewind a tape.
MT_SKIP_FILE
Use this keyword to skip les on a tape. A positive value skips forward that number of
les. A negative value skips backward.
MT_SKIP_RECORD
Use this keyword to skip records on tape. A positive value skips forward that number of
les. A negative value skips backward.
MT_WEOF
Set thiskeyword to writean end of le(tapemark ) on thetapeat thecurrent location.
SUPPRESS_ERROR
Set this keyword to log errors quietly and cause a value of -1 to be returned. The default
is for IDL to notice any failures associated with the use of ioctl and issue the
appropriate IDL error and halt execution.
Example
The following example prints the size of the terminal being used by the current IDL
session. It is known to work under SunOS 4.1.2. Changes may be necessary for other
operating systems or even other versions of SunOS.
winsize = { row:0, col:0, xpixel:0, ypixel:0 }
Variableto receiveresult. This
structureisdescribedinSection4
oftheSunOSmanualpagesunder
termios(4).
TIOCGWINSZ = 1074295912L Therequestcodeforobtainingthe
ttysize, asdeterminedbyreading
thetermios(4) documentation,
and readingthesystem include
files in the/usr/include/sys direc-
tory.
ret = ioctl(-1, TIOCGWINSZ, winsize)
Maketheinformationrequest. -1
is theIDL logical fileunit for the
standard output.
IOCTL IDL Reference Guide
print,winsize.row, winsize.col, $
format=("TTY has ", I0," rows and ", I0," columns.")
Output theresults.
The following points should be noted in this example:
Even though we only want the number of rows and columns, we must include all the
eldsrequired by theTIOCGWINSIZ ioctl in thewinsizevariable(asdocumented
in thetermio(4) manual page). Not providing a large enough result buffer would
cause IDLs memory to be corrupted.
The value of TIOCGWINSZ was determined by examining the system header les
provided in the/usr/include/sys directory. Such values are not always portable
between major operating system releases.
See Also
OPEN
IDL Reference Guide ISHFT
ISHFT
TheISHFT function performsthebit shift operation on bytes, integersandlongwords. If
P
2
ispositive, P
1
isleft shifted P
2
bit positionswith 0bitsllingvacated positions. If P
2
is
negative, P
1
is right shifted with 0 bits lling vacated positions.
Calling Sequence
Result = ISHFT(P
1
, P
2
)
Arguments
P
1
The scalar or array to be shifted.
P
2
The scalar or array containing the number of bit positions and direction of the shift.
Example
Bit shift each element of theinteger array [ 1, 2, 3, 4, 5] threebitsto theleft and storethe
result in B by entering:
B = ISHFT([1,2,3,4,5], 3)
The resulting array B is [ 8, 16, 24, 32, 40] .
See Also
SHIFT
JOURNAL IDL Reference Guide
JOURNAL
The JOURNAL procedure provides a record of an interactive session by saving, in a le,
all text entered from the terminal in response to the IDL prompt. The rst call to
JOURNAL startstheloggingprocess. Theread-only systemvariable!JOURNAL isset to
the le unit used. To stop saving commands and close the le, call JOURNAL with no
parameters. If loggingisineffect andJOURNALiscalledwithaparameter, theparameter
is simply written to the journal le.
Calling Sequence
JOURNAL [, Arg]
Arguments
Arg
A string containing the name of the journal le to be opened or text to be written to an
open journal le. If Argis not supplied, and a journal le is not already open, the le
idlsave.pro isused. Oncejournalingisenabled, acall toJOURNALwith Argsupplied
causesArgto be written into the journal le. Calling JOURNAL without Argwhile
journaling is in progress closes the journal le and ends the logging process.
Example
To begin journaling to the lemyjournal.pro, enter:
JOURNAL, 'myjournal.pro'
Any commands entered at the IDL prompt are recorded in the le until IDL is exited or
the JOURNAL command is entered without an argument.
See Also
RESTORE, SAVE
IDL Reference Guide JULDAY
JULDAY
TheJULDAYfunction calculatestheJulian DayNumber for agiven month, day, andyear.
This is the inverse of the CALDAT procedure. JULDAY returns the Julian Day Number
(which begins at noon) of the specied calendar date.
Note TheJulian calendar, establishedbyJuliusCaesar in theyear 45BCE, wascorrectedby
Pope Gregory XIII in 1582, excising ten days from the calendar. The CALDAT
procedure reects the adjustment for dates after October 4, 1582. See the example
below for an illustration.
julday.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = JULDAY(Month, Day, Year, Hour, Minute, Second)
Arguments
Month
Number of the desired month (1 = January, ..., 12 = December).
Day
Number of the day of the month (1-31).
Year
Number of the desired year (e.g., 1994).
Hour
Number of the hour of the day (0-23) .
Minute
Number of the minute of the day (0-1439).
Second
Number of the second of the day (0-86399).
Example
In 1582, Pope Gregory XIII adjusted the Julian calendar to correct for its inaccuracy of
slightlymorethan 11minutesper year. Asaresult, thedayfollowingOctober 4, 1582was
October 15, 1582. JULDAY follows this convention, as illustrated by the following
commands:
PRINT, JULDAY(10,4,1582), JULDAY(10,5,1582), JULDAY(10,15,1582)
JULDAY IDL Reference Guide
IDL prints:
2299160 2299161 2299161
If you are using JULDAY to calculate an absolute number of days elapsed, be sure to
account for the Gregorian adjustment.
See Also
BIN_DATE, CALDAT, SYSTIME
IDL Reference Guide KEYWORD_SET
KEYWORD_SET
The KEYWORD_SET function returns a nonzero value if Expression is dened and
nonzero or an array, otherwisezero isreturned. Thisfunction isespecially useful in user-
written procedures and functions that process keywords that are interpreted as being
either true (keyword is present and nonzero) or false (keyword was not used, or was set
to zero).
Calling Sequence
Result = KEYWORD_SET(Expression)
Arguments
Expression
The expression to be tested. Expression is usually a named variable.
Example
Suppose that you are writing an IDL procedure that has the following procedure
denition line:
PRO myproc, KEYW1 = keyw1, KEYW2 = keyw2
Thefollowingcommand could beused toexecuteaset of commandsonlyif thekeyword
KEYW1 is set (i.e., it is present and nonzero):
IF KEYWORD_SET(keyw1) THEN BEGIN
The commands to be executed only if KEYW1 is set would follow.
See Also
N_ELEMENTS, N_PARAMS
KRIG2D IDL Reference Guide
KRIG2D
The KRIG2D function interpolates a regularly- or irregularly-gridded set of points z= f
(x, y) using kriging. It returns a two dimensional oating-point array containing the
interpolated surface, sampled at the grid points.
The parameters of the data model the range, nugget, and sill are highly dependent
upon the degree and type of spatial variation of your data, and should be determined
statistically. Experimentation, or preferably rigorous analysis, is required.
For ndatapoints, asystemof n+1simultaneousequationsaresolved for thecoefcients
of the surface. For any interpolation point, the interpolated value is:
The following formulas are used to model the variogram functions:
d(i,j) = the distance from point i to point j.
V = the variance of the samples.
C(i,j) = the covariance of sample i with sample j.
C(x
0
,y
0
,x
1
,y
1
) = the covariance of point (x
0
,y
0
) with point (x
1
,y
1
).
Exponential covariance:
Spherical covariance:
Note The accuracy of this function is limited by the single-precision oating-point accu-
racy of the machine.
krig2d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = KRIG2D(Z [, X, Y])
f x y , ( ) w
i
C x
i
y
i
x y , , , ( )
=
C d ( )
C
1
e
3 d A ( )
if d 0
C
1
C
0
if d = 0 +
=
C d ( )
1.0 1.5 d A ( ) 0.5 d A ( )
3
( ) if d < a +
C
1
C
0
if d = 0 +
0 if d > a
=
IDL Reference Guide KRIG2D
Arguments
Z, X, Y
Arrays containing theZ, X, and Y coordinates of the data points on the surface. Points
neednot beregularlygridded. For regularlygriddedinput data, XandYarenot used: the
grid spacing is specied via the XGRID and YGRID (or XVALUES and YVALUES)
keywords, and Z must be a two dimensional array. For irregular grids, all three
parameters must be present and have the same number of elements.
Keywords
Model Parameters:
EXPONENTIAL
Set this keyword to a two- or three-element vector of model parameters to use an
exponential semivariogrammodel. Themodel parameters(A, CO, andC1) areexplained
below.
SPHERICAL
Set thiskeywordtoatwo- or three-element vector of model parameterstouseaspherical
semivariogram model. The model parameters (A, CO, and C1) are explained below.
A
Therange. At distances beyond A, the semivariogram or covariance remains essentially
constant.
C0
Thenugget, which provides a discontinuity at the origin.
C1
If specied, C1isthecovariancevaluefor azerodistance, andthevarianceof therandom
samplezvariable. If onlyatwoelement vector issupplied, C1isset tothesamplevariance.
(C0 + C1) = thesill, which is the variogram value for very large distances.
Input Grid Description:
REGULAR
If set, theZ parameter is a two dimensional array of dimensions (n,m), containing
measurementsover aregular grid. If any of XGRID, YGRID, XVALUES, or YVALUESare
specied, REGULARisimplied. REGULARisalsoimpliedif thereisonlyoneparameter,
Z. If REGULARisset, and nogrid specicationsarepresent, thegrid isset to(0, 1, 2, ...).
XGRID
Atwo-element array, [ xstart, xspacing] , deningtheinput grid in thexdirection. Donot
specify both XGRID and XVALUES.
KRIG2D IDL Reference Guide
XVALUES
An n-element array dening thex locations of Z[ i,j] . Do not specify both XGRID and
XVALUES.
YGRID
Atwo-element array, [ ystart, yspacing] , deningtheinput grid in theydirection. Donot
specify both YGRID and YVALUES.
YVALUES
An n-element array dening they locations of Z[ i,j] . Do not specify both YGRID and
YVALUES.
Output Grid Description:ENVI
GS
Theoutput grid spacing. If present, GSmust beatwo-element vector [ xs, ys] , wherexsis
the horizontal spacing between grid points and ysis the vertical spacing. The default is
based on the extents of x and y. If the grid starts at x valuexmin and ends at xmax, then
thedefault horizontal spacingis(xmax- xmin)/(NX-1). ysiscomputed in thesameway.
The default grid size, if neither NX or NY are specied, is 26 by 26.
BOUNDS
If present, BOUNDS must be a four-element array containing the grid limits in x and y
of the output grid: [ xmin, ymin, xmax, ymax] . If not specied, the grid limits are set to
the extent of x and y.
NX
Theoutput gridsizein thexdirection. NXneednot bespeciedif thesizecan beinferred
from GS and BOUNDS. The default value is 26.
NY
Theoutput gridsizein theydirection. NYneednot bespeciedif thesizecan beinferred
Examples
Make a random set of points that lie on a Gaussian:
N = 15 Number of random points.
X = RANDOMU(seed, N)
Y = RANDOMU(seed, N)
Z = EXP(-2 * ((X-.5)^2 + (Y-.5)^2)) TheGaussian.
Get a 26 by 26 grid over the rectangle bounding x and y:
E = [ 0.25, 0.0] Rangeis 0.25 and nugget is 0.
Thesenumbersaredependenton
your data model.
IDL Reference Guide KRIG2D
R = KRIG2D(Z, X, Y, EXPON = E) Get thesurface.
Alternatively, get a surface over the unit square, with spacing of 0.05:
R = KRIG2D(Z, X, Y, EXPON=E, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
See Also
BILINEAR, INTERPOLATE
KURTOSIS IDL Reference Guide
KURTOSIS
The KURTOSIS function computes the statistical kurtosis of an n-element vector. If the
variance of the vector is zero, the kurtosis is not dened, and KURTOSIS returns
!VALUES.F_NAN as the result. KURTOSIS calls the IDL function MOMENT.
Calling sequence
Result = KURTOSIS(X)
Arguments
X
An n-element, oating-point or double-precision vector.
Keywords
DOUBLE
If this keyword is set, computations are performed in double precision arithmetic.
NAN
Example
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
Definethen-element vector of
sampledata.
result = KURTOSIS(x) Computethekurtosis.
IDL prints
-1.18258
See Also
MEAN, MEANABSDEV, MOMENT, STDDEV, SKEWNESS, VARIANCE
IDL Reference Guide KW_TEST
KW_TEST
TheKW_TEST function teststhehypothesisthat threeor moresamplepopulationshave
the same mean of distribution against the hypothesis that they differ. The populations
maybeof equal or unequal lengths. Theresult isatwo-element vector containingthetest
statisticH and theone-tailed probability of obtainingavalueof H or greater fromaChi-
square distribution.
This test is an extension of the Rank Sum Test implemented in the RS_TEST function.
When each sample population contains at least ve observations, the H test statistic is
approximated very well by a Chi-square distribution with DF degrees of freedom. The
hypothesisthat threeof moresamplepopulationshavethesamemean of distribution is
rejected if two or morepopulationsdiffer with statistical signicance. Thistypeof test is
often referred to as the Kruskal-Wallis H-Test.
The test statistic H is dened as follows:
whereN
i
is the number of observations in thei
th
sample population, N
T
is the total
number of observations in all sample populations, and R
i
is the overall rank sum of the
i
th
sample population.
kw_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = KW_TEST(X)
Arguments
X
An integer, single-, or double-precision oating-point array of m-columns(with m 3)
and n-rows. The columns of this two dimensional array correspond to the sample
populations.
If the sample populations are of unequal length, any columns of X that are shorter than
thelongest column must belled in by appendingauser-specied missingdatavalue.
This method requires the use of the MISSING keyword. See theExamplesection below
for an example of this case.
H
12
N
T
N
T
1 + ( )
-------------------------------
R
i
2
N
i
------
i 0 =
M 1
= 3 N
T
1 + ( )
KW_TEST IDL Reference Guide
Keywords
DF
Use this keyword to specify a named variable that will contain the number of degrees of
freedom used to compute the probability of obtaining a value of H or greater from the
corresponding Chi-square distribution
MISSING
Set this keyword equal to a non-zero numeric value that has been appended to some
columns of X to make them all a common length of n.
Example
Test the hypothesis that three sample populations have the same mean of distribution
against the hypothesis that they differ at the 0.05 signicance level. Assume we have the
following sample populations:
sp0 = [ 24.0, 16.7, 22.8, 19.8, 18.9]
sp1 = [ 23.2, 19.8, 18.1, 17.6, 20.2, 17.8]
sp2 = [ 18.2, 19.1, 17.3, 17.3, 19.7, 18.9, 18.8, 19.3]
Since the sample populations are of unequal lengths, a missing value must be appended
to sp0 and sp1. In this example the missing value is -1.0 and the 3-column, 8-row input
array X is dened as:
X = [[24.0, 23.2, 18.2], $
[16.7, 19.8, 19.1], $
[22.8, 18.1, 17.3], $
[19.8, 17.6, 17.3], $
[18.9, 20.2, 19.7], $
[-1.0, 17.8, 18.9], $
[-1.0, -1.0, 18.8], $
[-1.0, -1.0, 19.3]]
PRINT, KW_TEST(X, MISSING = -1)
IDL prints:
[1.65862, 0.436351]
The computed probability (0.436351) is greater than the 0.05 signicance level and
thereforewedonot reject thehypothesisthat thethreesamplepopulationssp0, sp1, and
sp2 have the same mean of distribution.
See Also
FV_TEST, RS_TEST, S_TEST, TM_TEST
IDL Reference Guide L64INDGEN
L64INDGEN
The L64INDGEN function returns a 64-bit integer array with the specied dimensions.
Each element of the array is set to the value of its one-dimensional subscript.
Calling Sequence
Result = L64INDGEN(D
1
, ..., D
n
)
Arguments
D
i
The dimensions of the result. These parameters can be any scalar expression, and up to
eight dimensionscanbespecied. If thedimensionargumentsarenot integer values, IDL
converts them to integer values before creating the new array.
Example
TocreateL, a10-element by10-element 64-bit arraywhereeachelement isset tothevalue
of its one-dimensional subscript, enter:
L = L64INDGEN(10, 10)
See Also
BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN,
LABEL_DATE IDL Reference Guide
LABEL_DATE
TheLABEL_DATEfunction can beused, in conjunction with the[ XYZ] TICKFORMAT
keyword to IDL plotting routines, to easily label axes with dates.
label_date.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = LABEL_DATE(DATE_FORMAT = String)
PLOT, x, y, XTICKFORMAT = 'LABEL_DATE'
Arguments
LABEL_DATE has no explicit inputs. When called from the plotting routines, the input
parameters are (Axis, Index, Value)
Keywords
DATE_FORMAT
Set this keyword to a format string that can contain any of the following variables:
%M for month (3 character abbreviations)
%N for month (2 digit abbreviations)
%D for day of month
%Y for 4 digit year
%Z for last two digits of year
%H for hours (2 digits)
%I for minutes (2 digits)
%S for seconds (2 digits)
%% to represent the % character
Any vector font positioning and font change commands
Other characters are passed directly through
For example, '%M %D, %Y' results in labels of the formDEC 11, 1993. '%M %2Y'
yieldsDEC 93. '%D-%M' yields11-DEC. '%D/%N/%Y' yields11/12/1993. '%M!C%Y'
yieldsDEC on the top line, 1993 on the bottom (!C is the newline graphics command).
IDL Reference Guide LABEL_DATE
MONTHS
Atwelveelement stringarray that containsthenamesto beused for months. If omitted,
three-letter abbreviations are used (i.e., Jan, Feb, ..., Dec).
Example
Thefollowingcommandscreateasampleplot that hasadateaxisfromJan 1, 1993toJuly
12, 1994:
start_date = JULDAY(1, 1, 1993)
end_date = JULDAY(7, 12, 1994)
dummy = LABEL_DATE(DATE_FORMAT = '%N/%D')Simplemm/dd
x = FINDGEN(end_date+1 - start_date) + start_date
Timeaxis
PLOT, x, sqrt(x), XTICKFORMAT = 'LABEL_DATE', XSTYLE=1
PICKFILE
This routine is obsolete and should not be used in new IDL code.
The PICKFILE function has been renamed but retains the same functionality it had in
previous releases. See DIALOG_PICKFILE in theIDL ReferenceGuide.
LABEL_REGION IDL Reference Guide
LABEL_REGION
The LABEL_REGION function consecutively labels all of the regions, or blobs, of a bi-
level imagewith auniqueregion index. Thisprocessissometimescalled blobcoloring.
A region is a set of non-zero pixels within either a four-neighbor region (the default) or
an eight-neighbor region (if the EIGHT keyword is specied) around the pixel under
examination. The four-neighbor region around a pixel consists of two adjacent
horizontal andtwoadjacent vertical neighbors. Theeight-neighbor regionaroundapixel
consists of all the immediately adjacent pixels.
The argument for LABEL_REGION is a two-dimensional bi-level integer type array
only zero and non-zero values are considered. The result of the function is a two-
dimensional integer array of the same dimensions with each pixel containing its region
index. Aregion index of zero indicatesthat theoriginal pixel waszero and belongsto no
region. Output values range from 0 to the number of regions.
Statisticsoneachof theregionsmaybeeasilycalculatedusingtheHISTOGRAMfunction
as shown in the examples below.
Calling Sequence
Result = LABEL_REGION(Image)
Arguments
Image
Thetwo-dimensional imagetobelabeled. Imageisconverted tointeger typeif necessary.
Pixels at the edges of Imageare considered to be zero.
Keywords
EIGHT
If thiskeywordisset, LABEL_REGIONsearchestheeight-neighbor regionaroundapixel
rather than the four-neighbor region. The four-neighbor region around a pixel consists
of two adjacent horizontal and two adjacent vertical neighbors. The eight-neighbor
region around a pixel consists of all the immediately adjacent pixels.
Example
Count the number of distinct regions within an image, and their population:
b = LABEL_REGION(image) Get blob indices.
h = HISTOGRAM(b) Get population of each blob.
FOR i=0, N_ELEMENTS(h)-1 DO PRINT 'Region ',i, $
IDL Reference Guide LABEL_REGION
', Population = ', h(i)
Note that region 0 is the set of zero pixels that are not within a region.
As above, but also print the average value and standard deviation of each region:
b = LABEL_REGION(image) Get blob indices.
h = HISTOGRAM(b, REVERSE_INDICES=r) Get population and members of
each blob.
FOR i=0, N_ELEMENTS(h)-1 DO BEGIN Each region
p = r(r[i]:r[i+1]-1) Find subscripts of members of re-
gion i.
q = image[p] Pixels of region i
PRINT 'Region ', i, $
', Population = ', h[i], $
', Standard Deviation = ', STDEV(q, mean), $
', Mean = ', mean
ENDFOR
See Also
ANNOTATE, DEFROI, HISTOGRAM, SEARCH2D
LADFIT IDL Reference Guide
LADFIT
TheLADFIT function tsthepaired data{x
i
, y
i
} to thelinear model, y=A+Bx, usinga
robust least absolute deviation method. The result is a two-element vector containing
the model parameters, A and B.
ladfit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = LADFIT(X, Y)
Arguments
X
An n-element integer, single-, or double-precision oating-point vector. Notethat theX
vector must be sorted into ascending order.
Y
An n-element integer, single-, or double-precision oating-point vector. Note that the
elements of theY vector must be paired with the appropriate elements of X.
Keywords
ABSDEV
Set this keyword to a named variable that will contain the mean absolute deviation for
each data-point in the y-direction.
DOUBLE
Example
X = [-3.20, 4.49, -1.66, 0.64, -2.43, -0.89, -0.12, 1.41, $
2.95, 2.18, 3.72, 5.26]
Y = [-7.14, -1.30, -4.26, -1.90, -6.19, -3.98, -2.87, -1.66, $
-0.78, -2.61, 0.31, 1.74]
Sort the X values into ascending order, and sort the Y values to match the new order of
the elements in X:
IDL Reference Guide LADFIT
XX = X(SORT(X))
YY = Y(SORT(X))
Compute the model parameters, A and B.
PRINT, LADFIT(XX, YY)
IDL prints:
-3.15301 0.930440
See Also
COMFIT, CURVEFIT, LINFIT, SORT
Figure9-4: Atwo-dimensional distributionfittedtothemodel y=a +bx, usinga minimizedChi-square
error criterion(left) anda robust least absolutedeviationtechnique(right). Theuseof theChi-square
error statistic can result in a poor fit due to an undesired sensitivity to outlying data.
LEEFILT IDL Reference Guide
LEEFILT
TheLEEFILT function performstheLeelter algorithmon an imagearrayusingabox of
size2N+1. Thisfunctioncanalsobeusedonvectors. TheLeetechniquesmoothsadditive
imagenoiseby generatingstatisticsin alocal neighborhood and comparingthemto the
expected values.
Thisroutineiswritten in theIDL language. It isbased upon thealgorithmpublished by
Lee(Optical Engineering25(5), 636-646, May 1986). Itssourcecodecan befound in the
leleefilt.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = LEEFILT(A [, N [, Sig]])
Arguments
A
The input image array or one-dimensional vector.
N
The size of the lter box is 2N+1. The default value is 5.
Sig
Estimate of the standard deviation. The default is 5. If Sigis negative, IDL interactively
promptsfor avalueof sigma, and displaystheresultingimageusingTVSCL (for arrays)
or PLOT (for vectors). To end this cycle, enter a value of 0 (zero) for sigma.
Keywords
EXACT
Set this keyword to apply a more accurate (but slower) implementation of the Lee lter.
See Also
DIGITAL_FILTER, MEDIAN, SMOOTH, VOIGT
IDL Reference Guide LINBCG
LINBCG
The LINBCG function is used in conjunction with SPRSIN to solve a set of n linear
equations with n unknowns using the iterative biconjugate gradient method. The result
is an n-element vector.
LINBCGisbased on theroutinelinbcg described in section 2.7of Numerical Recipesin
Note: Numerical Recipesrecommendsusingdouble-precision arithmeticto performthis
computation.
Calling Sequence
Result = LINBCG(A, B, X)
Arguments
A
B
An n-element vector containing the right-hand side of the linear systemAx=b.
X
An n-element vector containing the initial solution of the linear system.
Keywords
DOUBLE
ITOL
Usethiskeywordtospecifywhichconvergencetest shouldbeused. Set ITOLtooneof the
following:
1. Iteration stops when (A x- b(/(b( is less than the value specied by TOL.
2. Iteration stops when (
-1
(A x- b)(/(
-1
b( (where is a preconditioning
matrix close to A) is less than the value specied by TOL.
3. The routine uses its own estimate of error in x. Iteration stops when the magnitude
of the error divided by the magnitude of x is less than the value specied by TOL.
This is the default setting.
LINBCG IDL Reference Guide
4. Thesameas3, except that theroutineusesthelargest (in absolutevalue) component
of the error and the largest component of x rather than the vector magnitudes.
TOL
Use this keyword to specify the desired convergence tolerance. For single-precision
calculations, the default value is 1.0 10
-7
. For double-precision values, the default is
1.0 10
-14
.
ITER
Usethiskeyword tospecifyan output variablethat will beset tothenumber of iterations
performed.
ITMAX
The maximum allowed number of iterations. The default isn
2
.
Example
Begin with an array A:
A = [[ 5.0, 0.0, 0.0, 1.0, -2.0], $
[ 3.0, -2.0, 0.0, 1.0, 0.0], $
[ 4.0, -1.0, 0.0, 2.0, 0.0], $
[ 0.0, 3.0, 3.0, 1.0, 0.0], $
[-2.0, 0.0, 0.0, -1.0, 2.0]]
B = [7.0, 1.0, 3.0, 3.0, -4.0] Definearight-handsidevector B.
X = REPLICATE(1.0, N_ELEMENTS(B)) Start with an initial guess at the
solution.
result = LINBCG(SPRSIN(A), B, X)
Solvethelinear system Ax=b.
IDL prints:
1.00000 1.00000 -5.53459e-08 3.02525e-07 -1.00000
The exact solution is [ 1, 1, 0, 0, -1] .
See Also
FULSTR, READ_SPR, SPRSAB, SPRSAX, SPRSIN, WRITE_SPR
IDL Reference Guide LINDGEN
LINDGEN
TheLINDGENfunction returnsalongword integer arraywith thespecied dimensions.
Each element of the array is set to the value of its one-dimensional subscript.
Calling Sequence
Result = LINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
To createL, a10-element by 10-element longword array whereeach element isset to the
value of its one-dimensional subscript, enter:
L = LINDGEN(10, 10)
See Also
LINFIT IDL Reference Guide
LINFIT
The LINFIT function ts the paired data {x
i
, y
i
} to the linear model, y = A + Bx, by
minimizing the Chi-square error statistic. The result is a two-element vector containing
the model parameters [ A, B] .
linfit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = LINFIT(X, Y)
Arguments
X
Y
Keywords
CHISQ
Set thiskeywordtoanamedvariablethat will contain theChi-squareerror statisticasthe
sum of squared errors between y
i
and A + Bx
i
. If individual standard deviations are
supplied, then the Chi-square error statistic is computed as the sum of squared errors
divided by the standard deviations.
DOUBLE
PROB
Set thiskeyword to anamed variablethat will contain theprobability that thecomputed
t would have a value of CHISQ or greater. If PROB is greater than 0.1, the model
parameters are believable. If PROB is less than 0.1, the accuracy of the model
parameters is questionable.
SDEV
An n-element integer, single-, or double-precision oating-point vector that speciesthe
individual standard deviationsfor {x
i
, y
i
} used for weighting, wheretheweight isdened
as 1/SDEV
2
. If SDEV is not set, no weighting is used.
IDL Reference Guide LINFIT
SIGMA
Set this keyword to a named variable that will contain a two-element vector of probable
uncertainties for the model parameters.
Example
X = [-3.20, 4.49, -1.66, 0.64, -2.43, -0.89, -0.12, 1.41, $
2.95, 2.18, 3.72, 5.26]
Y = [-7.14, -1.30, -4.26, -1.90, -6.19, -3.98, -2.87, -1.66, $
-0.78, -2.61, 0.31, 1.74]
Dene an n-element vector of standard deviations with a constant value of 0.85
sdev = REPLICATE(0.85, N_ELEMENTS(X))
Compute the model parameters, A and B.
PRINT, LINFIT(X, Y, SDEV=sdev)
IDL prints:
[-3.44596, 0.867329]
See Also
COMFIT, CURVEFIT, GAUSSFIT, LADFIT, LMFIT, POLY_FIT, POLYFITW,
REGRESS, SFIT, SVDFIT
LINKIMAGE IDL Reference Guide
LINKIMAGE
LINKIMAGEmergesroutineswritten in other languageswith IDL at run-time. Each call
to LINKIMAGE denes a new system procedure or function by specifying the routines
name, the name of the le containing the code, and the entry point name. The name of
your routine is added to IDLs internal system routine table, making it available in the
same manner as any other IDL built-in routine. LINKIMAGE can also be used to add
graphics device drivers.
Caution Using LINKIMAGE requires intimate knowledge of the internals of IDL, and is not
for use by the novice user. We recommend use of CALL_EXTERNAL, which has a
simpler interface, instead of LINKIMAGE unless your application specically re-
quires it. To use LINKIMAGE, you should be familiar with the material in the IDL
Advanced Development Guide.
LINKIMAGEusesthedynamiclinkinginterfacesupportedbytheoperatingsystemtodo
itswork. Programmersshould befamiliar with theservicessupported by their systemin
order to better understand LINKIMAGE:
Under VMS, the LIB$FIND_IMAGE_SYMBOL run-time library routine is used to acti-
vate your sharable image and merge it into the IDL address space, as described in VMS
LINKIMAGE and LIB$FIND_IMAGE_SYMBOL, below.
Under Unix, LINKIMAGEusesthedlopen() interfacetothedynamiclinker in all cases
except for HP-UX (which usesshl_load()) and AIX (which usesload()).
Under Windows, LINKIMAGE usesLoadLibrary() to load a 32-bit, Win32 DLL.
On the PowerPC Macintosh, LINKIMAGE uses the Code Fragment Manager routines
GetDiskFragment() and FindSymbol() to load shared libraries.
Note Modules must be merged via LINKIMAGE before other procedures and functions
that call themarecompiled, or thecompilation of thoseroutineswill fail. Notethat
because routines merged via LINKIMAGE are considered built-in routines by IDL,
declaringtheroutinewiththeFORWARD_FUNCTIONstatement will not eliminate
this restriction.
Calling Sequence
LINKIMAGE, Name, Image[, Type[, Entry]]
Arguments
Name
A string containing the IDL name of the function, procedure or device routine which is
to bemerged. When loadingadevicedriver, Namecontainsthenameof theglobal (also
called universal under VMS) DEVICE_DEF structure in the driver. Upon successful
IDL Reference Guide LINKIMAGE
loadingof theroutine, anewprocedureor function with thegiven namewill exist, or the
new device driver will be loaded.
Image
A string that holds the name of the le containing the code to be dynamically linked.
Under VMS, thefull interpretation of thisargument isdiscussed in VMSLINKIMAGE
and LIB$FIND_IMAGE_SYMBOL on page 608. Under other operating systems, this
argument contains the full path specication of the dynamically loaded object le. See
your system documentation on sharable libraries or DLLs for details.
Type
An optional scalar integer parameter that contains0(zero) for aprocedure, 1(one) for a
function, and 2 for a device driver. The keyword parameters DEVICE and FUNCT can
also be used to indicate the type of routine being merged. The default value is 0, for
procedure.
Entry
An optional string that contains the name of the symbol which is the entry point of the
procedureor function. Withsomecompilersor operatingsystems, thisnamemayrequire
theaddition of leadingor trailingcharacters. For example, someUnix Ccompilersadd a
leading underscore to the beginning of a function name, and some Unix FORTRAN
compilers add a trailing underscore.
If Entryisnot supplied, LINKIMAGEwill provideadefault namebyconvertingthevalue
suppled for Nameto lower case and adding any special characters (leading or trailing
underscores) typical of the system.
Caution Under Microsoft Windowsoperatingsystems, onlycdeclfunctionscanbyusedwith
LINKIMAGE. Attempting to use routines with other calling conventions will yield
undened results, including memory corruption or even IDL crashing.
TheWindowsoperatingsystemhastwodistinct systemdenedstandardsthat govern
how routines pass arguments: stdcall, which is used by much of the operating
systemaswell aslanguagessuchasVisual Basic, andcdecl, whichisusedwidelyfor
programmingin theClanguage. Thesestandardsdiffer in howandwhen arguments
arepushedontothesystemstack. Thestandardusedbyagivenfunctionisdetermined
when thefunction iscompiled, and can becontrolled by theprogrammer. LINKIM-
AGEcan only beused with cdecl functions. Unfortunately, thereisnoway for IDL
to know which convention a given function uses, meaning that LINKIMAGE will
quietlyaccept anentrypoint of thewrongtype. TheLINKIMAGEuser isresponsible
for ensuring that Entry is acdecl function.
Keywords
DEFAULT
Thiskeywordisignoredon non-VMSplatforms. Under VMS, it isastringcontainingthe
default device, directory, lename, andletypeinformation for thelethat containsthe
sharable image. See VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL on page
608 for additional information.
DEVICE
Set this keyword to indicate that the module being loaded contains a device driver.
FUNCT
Set this keyword to indicate that the module being loaded contains a function.
KEYWORDS
Set thiskeywordtoindicatethat theprocedureor function beingloadedacceptskeyword
parameters.
MAX_ARGS
Set this keyword equal to the maximum number of non-keyword arguments the
procedure or function accepts. If this keyword is not present, the maximum number of
parameters is not checked when the routine is called.
Note It is a very good idea to specify a value for MAX_ARGS. Passing the wrong number
of argumentstoan external routinemaycauseunexpectedresults, includingcausing
IDL tocrash. ByforcingIDL tocheck thenumber of argumentsbeforepassingthem
to the linked routine, you will avoid parameter mismatch problems.
MIN_ARGS
Set thiskeyword equal totheminimumnumber of non-keyword argumentsaccepted by
the procedure or function.
VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL
Specifying The Library Name
The VMS implementation of LINKIMAGE uses the system runtime library function
LIB$FIND_IMAGE_SYMBOL to perform the dynamic linking. This function has a
complicated interface in which the name of the library to be linked is given in two
separate arguments. We encourage VMS users wishing to use LINKIMAGE to read and
fully understand the documentation for LIB$FIND_IMAGE_SYMBOL in order to
understandhowit isusedbyIDL. Thefollowingdiscussion assumesthat you haveacopy
of the LIB$FIND_IMAGE_SYMBOL documentation available to consult as you read.
LIB$FIND_IMAGE_SYMBOL uses an argument called lenameto specify the name of
thesharablelibraryor executabletobeloaded. Onlytheactual lenameitself isallowed,
meaning that none of the le specication punctuation characters (:, [, <, ;, .) are
allowed. Filename can also be a logical name, in which case its translated value is the
nameof theletobeloaded. Thetranslation of such alogical nameisallowed tocontain
additional le specication information. VMS uses this information to nd the le to
load, using SYS$SHARE as the default location if a location is not specied via a logical
name. Alternatively, the user can also supply the optional image-nameargument, which
is used as a default lespec to ll in the parts of the le specication not contained in
IDL Reference Guide LINKIMAGE
lename. IDL uses the following rules, in the order listed, to determine how to call
LIB$FIND_IMAGE_SYMBOL:
1. If LINKIMAGE is called with both the Image argument and DEFAULT keyword,
Image is passed to LIB$FIND_IMAGE_SYMBOL as lename, and DEFAULT is
passedasimage-name. Botharepasseddirectlytothefunction without anyinterpre-
tation.
2. If DEFAULT isnot present and Imagedoesnot contain alespecication character
(:, [, <, ;, .) then it is passed to LIB$CALL_IMAGE_SYMBOL as its lename
argument without any further interpretation.
3. If DEFAULTisnot present andImagecontainsalespecicationcharacter, thenIDL
examines it and locates the lename part. The lename part is passed to
LIB$FIND_IMAGE_SYMBOLaslenameandtheentirestringfromImageispassed
as image-name.
Thismeansthat althoughLIB$CALL_IMAGE_SYMBOLhasacomplicatedinterface, the
LINKIMAGEuser can supply asimplelespecication for Imageand it will beproperly
loaded by IDL. Full control of LIB$CALL_IMAGE_SYMBOL is still available for those
who require it.
Linking To The IDL Executable
LINKIMAGEroutinesinvariably need to call functionssupplied by theIDL program. In
order todothis, youmust link your sharablelibrarywithIDL. Thisrequiresyoutosupply
the linker with the path (le specication) of the IDL program. The VMS linker in turn
includesthepath you specify in theresultinglibrary. Thiscan beinconvenient becausea
librarylinkedthiswaycan onlyrun with theexact IDL executablethat it waslinkedwith.
Thismeansthat you cannot moveyour IDLinstallation or keepmultipleinstallationsfor
usewithyour library. ThestandardVMSsolution tothisproblemistousealogical name
instead of an actual path. For example, IDL users frequently use the logical name
IDL_EXE to point at their IDL executable. To make this process easier and less trouble
prone, IDL denes this logical name in the users process logical table when it starts
running. Therefore, you can always link with the IDL_EXE logical and know that it will
refer to theIDL executableyou areactually runningwhen theLINKIMAGEcall ismade.
Examples
To add a procedure called MY_PROC, whose entry symbol is also named MY_PROC,
and whose le is pointed to by the logical name MY_PROC_EXE:
LINKIMAGE, 'MY_PROC', 'MY_PROC_EXE'
Under VMS, to add a device driver contained in the leDRA0:[SMITH]XXDRIV.EXE:
LINKIMAGE, 'XX_DEV', 'XXDRIV', $
/DEVICE, DEFAULT=DRA0:[SMITH].EXE
The global symbol XX_DEV, which contains the device denition structure, must be
dened as universal within the sharable image.
See Also
CALL_EXTERNAL, SPAWN, and the IDL Advanced Development Guide.
IDL Reference Guide LIVE_Tools
LIVE_Tools
The LIVE tools are a subset of the IDL Insight application that allow you to create,
modify, and export Insight-like visualizations directly from the IDL command line.
In many cases, you can modify your visualizations using the LIVE tools graphical user
interface directly without ever needing to return the IDL command line. In some cases,
however, you may wish to alter your visualizations programmatically rather than using
the graphical user interface. Several LIVE routines allow you to do this easily.
Theprocessof usingtheLIVEtoolsbeginswith thecreation of aLIVEwindowviaoneof
the four main LIVE routines: LIVE_CONTOUR, LIVE_IMAGE, LIVE_PLOT, and
LIVE_SURFACE. When youuseoneof thesefour routinesat theIDLcommandline, you
specify somedatato bevisualized and aLIVEwindowappears. You can modify many of
thepropertiesof theitemsin your visualization bydouble-clickingon theitemtocall up
a Properties dialog.
If you nd that thegraphical user interfacedoesnot allowyou to performtheoperation
you wish to performsavingyour visualization asan imagele, say you can usethe
auxiliary LIVE routines. These routines can be divided into two groups:
OverplottingandAnnotationRoutinesthat allowyou toadd annotationstoan existing
LIVE window. These routines include LIVE_LINE, LIVE_OPLOT, LIVE_RECT, and
LIVE_TEXT. (Lines, rectangles, andtext can alsobeaddedtoLIVEwindowsusingthe
graphical user interface.)
Information and Control Routinesthat allow you to get information about an existing
LIVE window, alter its properties, or export visualizations. These routines include
LIVE_CONTROL, LIVE_DESTROY, LIVE_EXPORT, LIVE_INFO, LIVE_PRINT,
and LIVE_STYLE.
To use the auxiliary routines, you will need to know theNameof the LIVE window or
itemyou wish to alter. To createan IDL variablecontainingthenamesof theelementsof
aLIVEwindow, set theREFERENCE_OUTkeywordequal toanamedvariablewhenyou
rst createyour LIVEwindow. Thereturnedvariablewill beastructurethat containsthe
namesof all of theelementsin thevisualization you havecreated. Usethecontentsof this
structuretodeterminethevalueof theNameargument for theauxiliaryLIVEtools, or to
determine the name of the LIVE window you wish to alter.
If you nd that the LIVE tools do not provide the level of control you need over your
visualizations, consider using Insight itself. You can start the Insight application by
enteringinsight at the IDL command prompt.
Note The LIVE tools do not utilize the !X, !Y, and !Z conventions. Setting these system
variables will have no effect on LIVE tool display.
LIVE_CONTOUR IDL Reference Guide
LIVE_CONTOUR
The LIVE_CONTOUR procedure displays contour visualizations in an interactive
environment. Because the interactive environment requires extra system resources, this
routine is most suitable for relatively small data sets. If you nd that performance does
not meet your expectations, consider using the Direct Graphics CONTOUR routine or
the Object Graphics IDLgrContour class directly.
After LIVE_CONTOUR has been executed, you can double-click on a contour line to
displayapropertiesdialog. Aset of buttonsin theupper left corner of thewindowallows
you toprint, undothelast operation, redothelast undone operation, copy, drawaline,
draw a rectangle, or add text.
LIVE_CONTOURisactually asubset of theIDL Insight application. If you nd that the
LIVE_CONTOURgraphical user interfacedoesnot providethelevel of control youneed,
consider usingInsight itself. Youcan start theInsight application byenteringinsight at
the IDL command prompt.
You can control your LIVE window after it is created using any of several auxiliary
routines. See LIVE_Tools on page 611 for an explanation.
Calling Sequence
LIVE_CONTOUR, Z1, Z2,...
Argument
Zn
A two-dimensional array containing the values that make up the contour. Up to 25 of
these arguments may be specied.
Keywords
BUFFER
Set this keyword to bypass the creation of a LIVE window and send the visualization to
an offscreen buffer. The WINDOW eld of the reference structure returned by the
REFERENCE_OUT keyword will contain the name of the buffer.
Print Undo Redo Copy Line Rectangle Text
IDL Reference Guide LIVE_CONTOUR
DIMENSIONS
Set this keyword to a two-element, oating-point vector of the form [ width, height]
specifying the dimensions of the visualization in normalized coordinates. The default is
[ 1.0, 1.0] .
DRAW_DIMENSIONS
Set thiskeywordequal toavector of theform[ width, height] representingthedesiredsize
of the LIVE tools draw widget (in pixels). The default is [ 452, 452] .
Note This default value may be different depending on the Insight template project.
ERROR
Set this keyword to a named variable to contain the returned error message (string). An
emptystringisreturnedif noerrorsoccurredduringtheoperation. Bydefault, errorsare
reported via a GUI.
Note If anamed variableispassed in thiskeyword and an error occurs, theerror GUI will
not be displayed.
INDEXED_COLOR
If set, the indexed color mode will be used. The default is true color. (SeeUsingIDL for
more information on color modes.)
INSTANCING
Set thiskeyword to 1to instancedrawingon, or 0to turn it off. Thedefault (-1) isto use
instancingif andonlyif the"softwarerenderer" isbeingused(seeRENDERER). For more
information, see"Instancing" in theObjects and Object Graphicsmanual.
LOCATION
Set thiskeywordtoatwo-element, oating-point vector of theform[ X, Y] specifyingthe
locationof thevisualization(relativetothelower left handcorner withinthevisualization
window) in normalized coordinates. The default is [ 0.0, 0.0] .
Note LOCATION may be adjusted to take into account window decorations.
MANAGE_STYLE
Set thiskeywordtohavethepassedin styleitemdestroyedwhen theLIVEtool windowis
destroyed. Thiskeywordwill havenoeffect if theSTYLEkeywordisnot set toastyleitem.
NAME
Set this keyword to a structure containing suggested names for the data items to be
created for this visualization. See the REPLACE keyword for details on how they will be
used. The elds of the structure are as follows. (Any or all of the tags may be set.)
Tag Description
DATA Dependent Data Name(s)
Table 9-12: Fields of the NAME keyword.
The default for a eld is to use the given variable name. If the variable does not have a
name (i.e., is an expression), a default name is automatically generated. The dependent
data names will be used in a round-robin fashion if more data than names are input.
NO_DRAW
Set this keyword to inhibit the visualization window from drawing results of
LIVE_CONTOUR. Thisisuseful if multiplevisualizationsand/or annotationsarebeing
created viacallsto other LIVE_Toolsin order to reduceunwanted drawsand help speed
the display.
NO_STATUS
Set this keyword to prevent the creation of the status bar.
NO_TOOLBAR
Set this keyword to prevent the creation of the toolbar.
PARENT_BASE
Set this keyword to the widget ID of an existing base widget to bypass the creation of a
LIVE window and create the visualization within the specied base widget.
Note Thelocationof thedrawwidget isnot settable. It isexpectedthat theuser whowishes
toinsert atool intotheir own widget application will determinethesettingfromthe
parent base sent to the tool.
Note LIVE_DESTROYon awindowisrecommendedwhen usingPARENT_BASEsothat
proper memory cleanup isdone. Simply destroyingtheparent baseisnot sufcient.
Note When specifying a PARENT_BASE, that parent base must be running in a non-
blocking mode. Putting a LIVE tool into a realized base already controlled by
XMANAGERwill overridetheXMANAGERmodeto/NO_BLOCKeven if blocking
had been in effect.
IX Independent X Data Name
IY Independent Y Data Name
Tag Description
REFERENCE_OUT
Set this keyword to a variable to return a structure dening the names of the created
items. The elds of the structure are shown in the following table.
Note You can also determine the name of an item by opening its properties dialog and
checking the Name eld (or for Windows, by clicking the title bar).
RENDERER
Set thiskeyword to 1to usethesoftwarerenderer, or 0to usethe hardwarerenderer.
The default (-1) is to use the setting in the IDE (IDL Development Environment)
preferences; if the IDE is not running, however, the default is hardware rendering. For
more information, see Hardware vs. Software Rendering in theObjects and Object
Graphicsmanual.
REPLACE
Set this keyword to a structure containing tags as listed for the NAME keyword, with
scalar valuescorrespondingtothereplacement optionslistedbelow. (Anyor all of thetags
maybeset.) Thereplacement settingsareused todeterminewhat action totakewhen an
item(such asdata) beinginput would havethesamenameasonealready existingin the
given window or buffer (WINDOW_IN).
Tag Description
WIN Window Name
VIS Visualization Name
XAXIS X-Axis Name
YAXIS Y-Axis Name
GRAPHIC Graphic Name(s)
LEGEND Legend Name
Table 9-13: Fields of the LIVE_CONTOUR Reference Structure
Alternatively, this keyword may be set to a single scalar value, which is equivalent to
setting each tag of the structure to that choice.
STYLE
Set thiskeywordtoeither astringspecifyingastylename(or astylein theInsight template
project), or to a style reference created from LIVE_STYLE.
TITLE
Set this keyword to a string specifying the title to give the main window. It must not
already be in use. A default will be chosen if no title is specied.
TLB_LOCATION
Set thiskeywordtoatwo-element vector of theform[Xoffset, Yoffset] specifyingtheoffset
(in pixels) of theLIVEwindowfromtheupper left corner of thescreen. Thiskeywordhas
no effect if the PARENT_BASE keyword is set. The default is [ 0, 0] .
WINDOW_IN
Set thiskeywordequal toaname(string, case-sensitive) of aLIVEtool or Insight window,
or a LIVE tool buffer, in which to display the visualization. The WIN tag of the
REFERENCE_OUTstructurefromthecreationof theLIVEtool will providethewindow
or buffer name. Window names are also visible in visualization window titlebars. The
default is to create a new window.
[XY]INDEPENDENT
Set these keywords to a vector specifying X and Y values for LIVE_CONTOUR. The
default is the datas index values.
Setting Action Taken
0 New items will be given unique names.
1 Existingitemswill bereplacedbynewitems(i.e., the
old items will be deleted and new ones created).
2 User will be prompted for the action to take.
3 The values of existing items will be replaced. This
will cause dynamic updating to occur for any cur-
rent uses, e.g., avisualization would redrawto show
the new value.
4 Default. Option 0 will be used for items that do not
have names (e.g., data input as an expression rather
than a named variable, with no name provided via
the NAME keyword). Option 3 will be used for all
named items.
Table 9-14: REPLACE keyword Settings and Action Taken
Note Only oneindependent vector isallowed; all dependent vectorswill usetheindepen-
dent vector.
[XY]LOG
Set these keywords to make the specied axis a log axis. The default is 0.
[XY]RANGE
Set these keywords equal to a two-element array which denes the minimum and
maximumvaluesof theaxisrange. Thedefault equalsthevaluescomputedfromthedata
range.
[XY]_TICKNAME
Set thesekeywordsequal toan arrayof elements. Thevaluesof thestringswill beused to
label the tick mark for the given axis. The default equals the values computed from the
data range.
Example
Z=DIST(10) Createa dataset to display.
LIVE_CONTOUR, Z Display thecontour. To manipu-
latecontourlines,clickontheplot
toaccessagraphical userinterface.
Note Thisisa Live situation. When dataof thesamenameisusedmultipletimeswithin
the same window, it always represents the same internal data item. For example, if
one does the following:
Y=indgen(10)
LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc1
Y=indgen(20)
The rst plot will update to use the Y of the second plot when the second plot is drawn.
If theuser wantstodisplay2tweaks of thesamedata, adifferent variablenamemust be
used each time, or at least oneshould bean expression (thusnot anamed variable). For
example:
LIVE_PLOT, Y1,...
LIVE_PLOT, Y2,...
or;
LIVE_PLOT, Y,...
LIVE_PLOT, myFunc(Y),...
In last example, thedataof thesecond visualization will begiven adefault uniquename
since an expression rather than a named variable is input.
Note The above shows the default behavior for naming and replacing data, which can be
overridden using the NAME and REPLACE keywords.
See Also
CONTOUR, Using IDL Insight
IDL Reference Guide LIVE_CONTROL
LIVE_CONTROL
TheLIVE_CONTROLprocedureallowsyou toset thepropertiesof (or elementswithin)
avisualizationinaLIVEtool fromtheIDLcommandline. See LIVE_Tools onpage611
for additional discussion of the routines that control the LIVE_ tools.
Note The LIVE tools do not utilize the !X, !Y, and !Z conventions. Setting these system
variables will have no effect on LIVE tool display.
Calling Sequence
LIVE_CONTROL, [Name]
Arguments
Name
If keywords DIALOG and/or PROPERTIES are used, Nameis a string (case-insensitive)
containingthenameof awindowvisualization or graphicto operateon. WINDOW_IN
will default to the window or buffer, if only one is present in the IDL session.
If keyword UPDATE_DATA isused, Namemust bean IDL variablewith thesamename
as one already used in the given window or buffer (WINDOW_IN). In this case there is
no default. If UPDATE_DATA is not set, the parameter must be a name of a window,
visualization or visualization element.
Keywords
DIALOG
Set this keyword to have the editable properties dialog of the visualization or graphic
appear.
ERROR
reported via a GUI.
not be displayed.
NO_DRAW
Set this keyword to inhibit the visualization window from drawing. This is useful if
multiplevisualizationsand/or annotationsarebeingcreatedviacallstoother LIVE_Tools
in order to reduce unwanted draws and help speed the display.
LIVE_CONTROL IDL Reference Guide
PROPERTIES
Set thiskeywordtoapropertiesstructurewithwhichtomodifythegiven visualization or
graphic. The structure should contain one or more tags as returned from a LIVE_INFO
call on the same type of item.
UPDATE_DATA
Set this keyword to force the window to update all of its visualizations that contain the
given data passed in the parameter to LIVE_CONTROL.
WINDOW_IN
or aLIVEtool buffer. TheWINtagof theREFERENCE_OUTstructurefromthecreation
of theLIVEtool will providethewindowor buffer name. Windownamesarealsovisible
in visualization windowtitlebars. If only oneLIVEtool or Insight window(or buffer) is
present in the IDL session, this keyword will default to it.
Example
X=indgen(10) Createa dataset to display.
LIVE_PLOT, X Plot it.
X=X+2 Modify thedataset.
LIVE_CONTROL, X, /UPDATE_DATA Replaceold values of X.
See Also
LIVE_INFO, LIVE_STYLE, Using IDL Insight
IDL Reference Guide LIVE_DESTROY
LIVE_DESTROY
The LIVE_DESTROY procedure allows you to destroy a window visualization or an
element in a visualization.
Calling Sequence
LIVE_DESTROY, [Name1, Name2,...]
Argument
Name
A string containing the name of a valid LIVE or Insight visualization or element. If a
visualization issupplied, all componentsin thevisualization will bedestroyed. Up to 25
componentsmaybespeciedin asinglecall. If not specied, theentirewindowor buffer
(WINDOW_IN) and its contents will be destroyed.
Caution Using WIDGET_CONTROL to destroy the parent base of a LIVE tool before using
LIVE_DESTROY to clean up will leave hanging object references.
Keywords
ENVIRONMENT
Destroys the LIVE_ Tools or Insight environment (background processes).
ERROR
reported via a GUI.
not be displayed.
NO_DRAW
PURGE
Destroys LIVE_ Tools or Insight (use this keyword for cleaning up the system after fatal errors in
LIVE_ Tools or Insight). This keyword may cause the loss of data if not used correctly.
WINDOW_IN
LIVE_DESTROY IDL Reference Guide
Example
LIVE_DESTROY, Line Plot Visualization
LIVE_DESTROY
See Also
Using IDL Insight
IDL Reference Guide LIVE_EXPORT
LIVE_EXPORT
TheLIVE_EXPORT routineallowstheuser to export agiven visualization or windowto
an image le.
Calling Sequence
LIVE_EXPORT
Arguments
(None)
Keywords
APPEND
Species that the image should be added to the existing le, creating a multi-image TIFF le.
COMPRESSION
Creates a complex, single-precision, oating-point array.
DIALOG
Set this keyword to have a dialog appear allowing the user to choose the image type and
specications.
DIMENSIONS
Set this keyword to a two-element vector of the form [ width, height] to specify the
dimensions of the image in units specied by the UNITS keyword. The default is [ 640,
480] pixels.
ERROR
reported via a GUI.
not be displayed.
FILENAME
Set this keyword equal to a string specifying the desired name of the image le. The
default islive_export.extension, where extensionsare: .bmp, .gif, .jpg,
.jpeg, .pic, .pict, .srf, .tif, .tiff, .xwd, and. vrml.
ORDER (JPEG)
Set thiskeyword to havetheimagewritten fromtop to bottom. Default isbottomto top.
LIVE_EXPORT IDL Reference Guide
PROGRESSIVE (JPEG)
Set this keyword to write the image as a series of scans of increasing quality. When used
with a slow communications link, a decoder can generate a low-quality image very
quickly, and then improve its quality as more scans are received.
QUALITY
This keyword species the quality index of JPEG images only: 0=Low, 1=Medium,
2=High (default). This keyword has no effect on non-JPEG images.
RESOLUTION
Set thiskeyword to aoating-point valuespecifyingthedeviceresolution in centimeters
per pixel. The default is 72 DPI=2.54 (cm/in)/ 0.0352778 (cm/pixel).
Note It isimportant to match theeventual output devicesresolution so that text isscaled
properly.
TYPE
Set this keyword equal to a string specifying the image type to write. Valid strings are:
BMP, GIF, JPG, JPEG (default), PIC, PICT, SRF, TIF, TIFF, XWD, and VRML.
UNITS
Set this keyword to indicate the units of measure for the DIMENSIONS keyword. Valid
values are 0=Device (default), 1=Inches, 2=Centimeters.
VISUALIZATION_IN
Set this keyword equal to the name (string, case-insensitive) of a LIVE tool or Insight
visualization to export. The VIS eld from the REFERENCE_OUT keyword from the
creation of the LIVE tool will provide the visualization name. Visualization names are
also visible in Insight's Visualization Manager and visualization property dialogs. If
VISUALIZATION_INisnot specied, thewholewindowor buffer (WINDOW_IN) will
be exported.
WINDOW_IN
or aLIVEtool buffer, to export. TheWIN tagof theREFERENCE_OUT structurefrom
thecreation of theLIVEtool will providethewindowor buffer name. Windownamesare
alsovisiblein visualization windowtitlebars. If onlyoneLIVEtool or Insight window(or
buffer) is present in the IDL session, this keyword will default to it.
Example
LIVE_EXPORT, WINDOW_IN='Live Plot 2'
See Also
Using IDL Insight
IDL Reference Guide LIVE_IMAGE
LIVE_IMAGE
The LIVE_IMAGE procedure displays visualizations in an interactive environment.
Double-click on theimagetodisplayapropertiesdialog. Aset of buttonsin theupper left
corner of the image window allows you to print, undo the last operation, redo the last
undone operation, copy, draw a line, draw a rectangle, or add text..
LIVE_IMAGE is actually a subset of the IDL Insight application. If you nd that the
LIVE_IMAGE graphical user interface does not provide the level of control you need,
Calling Sequence
LIVE_IMAGE, Image
Argument
Image
A two- or three-dimensional array of image data. The three-dimensional array must be
for the form [ 3,X,Y] or [ X,3,Y] or [ X,Y,3] .
Keywords
BLUE
Set this keyword equal to a byte vector of blue values.
Note The BLUE, GREEN, and RED keywords are only used for 2D image data. They are
used to formthecolor table. The2D array isaset of valuesthat arejust indexesinto
this table.
BUFFER
LIVE_IMAGE IDL Reference Guide
DIMENSIONS
Set this keyword to a two-element vector of the form [width, height] to specify the
dimensionsof theimagein unitsspecified bytheUNITSkeyword. Thedefault is[1.0, 1.0].
DRAW_DIMENSIONS
Set thiskeywordtoatwo-element vector of theform[ width, height] tospecifythesizeof
the LIVE tools draw widget (in pixels). The default is [ 452, 452] .
Note This default value may be different depending on previous template projects.
ERROR
reported via a GUI.
not be displayed.
GREEN
Set this keyword equal to a byte vector of green values.
Note TheBLUE, GREEN, andREDkeywordsareonlyusedfor 2Dimagedata. Theyareusedto
form the color table. The 2D array is a set of values that are just indexes into this table.
INDEXED_COLOR
INSTANCING
LOCATION
MANAGE_STYLE
NAME
Set thiskeywordtoastructurecontainingsuggestednamesfor theitemstobecreatedfor
this visualization. See the REPLACE keyword for details on how they will be used. The
elds of the structure are as follows. (Any or all of the tags may be set.)
name (i.e., is an expression), a default name is automatically generated.
NO_DRAW
Set this keyword to inhibit the visualization window from drawing results of
LIVE_CONTOUR. Thisisuseful if multiplevisualizationsand/or annotationsarebeing
created viacallsto other LIVE_Toolsin order to reduceunwanted drawsand help speed
the display.
NO_STATUS
NO_TOOLBAR
PARENT_BASE
had been in effect.
RED
Set this keyword equal to a byte vector of red values.
Tag Description
CT Color Table Name
LIVE_IMAGE IDL Reference Guide
Note The BLUE, GREEN, and RED keywords are only used for 2D image data. They are
used to formthecolor table. The2D array isaset of valuesthat arejust indexesinto
this table.
REFERENCE_OUT
RENDERER
moreinformation, seeHardwarevs. SareRendering in theObjectsandObjectGraphics
manual.
REPLACE
Tag Description
WIN Window Name
GRAPHIC Graphic Name
CT Color Table Name
COLORBAR* Colorbar Name
DATA Data Name
Table 9-16: Fields of the LIVE_IMAGE Reference Structure
(Note: The COLORBAR* eld does not show
up with true color images).
STYLE
TITLE
TLB_LOCATION
WINDOW_IN
Example
LIVE_IMAGE, myImage
See Also
TV, TVSCL, Using IDL Insight
the new value.
named items.
LIVE_INFO IDL Reference Guide
LIVE_INFO
The LIVE_INFO procedure allows the user to get the properties of a LIVE tool.
Calling Sequence
LIVE_INFO, [ Name]
Argument
Name
Astringcontainingthenameof avisualization or element (case-insensitive). Thedefault
is to use the window or buffer (WINDOW_IN).
Keywords
ERROR
reported via a GUI.
not be displayed.
PROPERTIES
Set thiskeyword to anamed variableto contain thereturned propertiesstructure. For a
description of the structures, see Properties Structures below.
WINDOW_IN
Structure Tables for LIVE_INFO and LIVE CONTROL
The following tables describe the properties structures used by LIVE_INFO and
LIVE_CONTROL (via the PROPERTIES keyword) for:
Color Names
Line Annotations
Rectangle Annotations
IDL Reference Guide LIVE_INFO
Text Annotations
Axes
Colorbars
Images
Legends
Surfaces
Entire Visualizations
Windows
Color Names
The following color names are the possible values for color properties:
Line Annotations
The elds in the properties structure of Line Annotations are as follows:
Black Red Green Yellow
Blue Magenta Cyan Dark Gray
Light Gray Brown Light Red Light Green
Light Blue Light Cyan Light Magenta White
Table 9-18: Color Names
Tag Description
thick 1 to 10 pixels
arrow_start 1 = arrow head at line start, 0 = no arrowhead
arrow_end 1 = arrow head at line start, 0 = no arrowhead
arrow_size 0.0 to 0.3 normalized units
arrow_angle 1.0 to 179.0 degrees
linestyle 0 to 5 (solid, dotted, dashed, dash dot, dash dot dot dot, long dash)
hide 1 = hidden, 0 = visible
name scalar string (unique within all graphics)
color see Table 9-18
location [ x, y] normalized units
Table 9-19: Line Annotation Properties Structure
Rectangle Annotations
The elds in the properties structure of Rectangle Annotations are as follows:
Text Annotations
The elds in the properties structure of Text Annotations are as follows:
dimensions [ width, height] normalized units
uvalue any value of any type (only returned in structure if dened)
Tag Description
linestyle 0 to 5 (solid, dotted, dashed, dash dot, dash dot dot dot, long dash)
hide 1=hidden, 0=visible
Table 9-20: Rectangle Annotation Properties Structure
Tag Description
fontsize 9 to 72 points
fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a
valid name of a font on the local system)
textangle 0.0 to 360.0 degrees
alignment 0.0 to 1.0 where 0.0 = right justied and 1.0 = left justied
Table 9-21: Text Annotation Properties Structure.
Tag Description
Table 9-19: Line Annotation Properties Structure
Note Eachvector element of theannotationformula(see value tagabove) isparsedonce,
left to right, for vertical bars (|).
Twovertical barssurroundingadataitemnamewill bereplaced bythecorresponding
data value(s), possibly requiring multiple lines.
Two adjacent bars will be replaced by a single bar.
Two bars surrounding text that is not a data item name will be left as is.
Axes
The elds in the properties structure of Axes are as follows:
value string (scalar or vector) annotation formula (see note below)
enable_formatting set to allow "!" chars for font commands
Tag Description
title_FontSize 9 to 72 points
title_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a
title_Color see Table 9-18
tick_FontSize 9 to 72 points
tick_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a
tick_FontColor see Table 9-18
gridStyle see linestyle
location [ x, y] data units
minor number of minor ticks (minimum 0)
Table 9-22: Axis Properties Structure
Tag Description
fontsize 9 to 72 points
Table 9-21: Text Annotation Properties Structure.
Colorbars
The elds in the properties structure of Colorbars are as follows:
major number of major ticks (minimum 0)
default_minor set to compute default number of minor ticks
default_major set to compute default number of major ticks
tickLen normalized units * 100 = percent of visualization dimensions
subticklen normalized units * 100 = percent of ticklen
tickDir 0 = up (or right), 1 = down (or left)
textPos 0 = below (or left), 1 = above (or right)
tickFormat standard IDL FORMAT string (See STRING function) excluding
parentheses
exact set to use exact range specied
log set to display axis as log
compute_range set to compute axis range from data min/max
tickName if dened, vector of strings to use at major tick marks
Tag Description
title_Fontsize 9 to 72 points
tick_FontSize see fontsize
tick_Fontname see fontname
tick_FontColor see Table 9-18
Table 9-23: Colorbar Properties Structure.
Tag Description
Contours
The elds in the properties structure of Contours are as follows:
location [ x, y] ; where [ 0, 0] = lower left and [ 1, 1] = position where the
entire colorbar ts into the upper right of the visualization
tickFormat standard IDL FORMAT string (See STRING function) excluding
parentheses
show_axis set to display the colorbar axis
show_outline set to display the colorbar outline
axis_thick see thick
Tag Description
min_value minimum contour value to display
max_value maximum contour value to display
downhill set to display downhill tick marks
ll set to display contour levels as lled
Table 9-24: Contour Properties Structure
Tag Description
title_Fontsize 9 to 72 points
Table 9-23: Colorbar Properties Structure.
Note
*
TheMINandMAXvalueof thedataarereturnedascontour levelswhenN_LEVELS
is set. Because of this, when setting N_LEVELS, contour plots appear to have N-2
contour levels because the rst (MIN) and last (MAX) level is not shown. With
LIVE_CONTOUR, this results in a legend that contains unneccessary items in the
legend (the MIN and the MAX contour level).
Images
The elds in the properties structure of Images are as follows:
c_thick vector of thickness values (see thick)
c_linestyle vector of linestyle values (see linestyle)
c_color vector of color names (see Table 9-18)
default_n_levels set to default the number of levels
n_levels
*
specify a positive number for a specic number of levels
Tag Description
order set to draw from top to bottom
sizing_constraint [ 0|1|2] 0=Natural, 1=Aspect, 2=Unrestricted
dont_byte_scale set to inhibit byte scaling the image
palette name of managed colortable
uvalue any value of any type (only returned in LIVE_INFO structure if
dened)
Table 9-25: Image Properties Structure
Tag Description
min_value minimum contour value to display
Table 9-24: Contour Properties Structure
Legends
The elds in the properties structure of Legends are as follows:
Tag Description
item_fontSize see fontsize
item_fontName Helvetica, Courier, Times, Symbol, and Other (where Other is a
text_color color of item text (see Table 9-18)
border_gap normalized units * 100 = percent of item text height
columns number of columns to display the items in (minimum 0)
gap normalized units * 100 = percent of item text height
glyph_Width normalized units * 100 = percent of item text height
ll_color see Table 9-18
outline_color see Table 9-18
outline_thick see thick
location [ x, y] ; where [ 0, 0] = lower left and [ 1, 1] = position where the
entire legend ts into the upper right of the visualization
show_ll set to display the ll color
show_outline set to display the legend outline
title_text String to display in the legend title
item_format standard IDL FORMAT string (See STRING function) excluding
parentheses (contour legends only)
Table 9-26: Legend Properties Structure
Surfaces
The elds in the properties structure of Surfaces are as follows:
Entire Visualizations
The elds in the properties structure of Entire Visualizations are as follows:
Tag Description
min_value minimum plot line value to display
max_value maximum plot line value to display
lineStyle 0 to 5 (solid, dotted, dashed, dash dot, dash dot dot dot, long dash)
bottom see Table 9-18
style 0 to 5 0=point, 1=wire, 2=solid, 3=ruledXZ, 4=ruledYZ,5=lego
(wire), 6=lego (solid)
shading 0=at, 1=Gouraud
hidden_lines set to not display hidden lines or points
show_skirt set to display the surface skirt
skirt z value at which skirt is drawn (data units)
Table 9-27: Surface Properties Structure
Tag Description
transparent set to avoid erasing to the background color
color background color (see Table 9-18)
Windows
The elds in the properties structure of Windows are as follows:
Example
LIVE_INFO, 'x axis', PROPERTIES=myProps
See Also
LIVE_CONTROL, LIVE_STYLE, Using IDL Insight
Tag Description
dimensions 2-element integer vector (pixels)
hide boolean (0=show, 1=hide)
location 2-element integer vector (pixels) from
upper left corner of screen
title string
Table 9-29: Windows Properties Structure
Tag Description
Table 9-28: Visualization Properties Structure
LIVE_LINE IDL Reference Guide
LIVE_LINE
The LIVE_LINE procedure is an interface for line annotation.
Calling Sequence
LIVE_LINE
Arguments
(None)
Keywords
ARROW_ANGLE
Set thiskeywordtoaoating-point number between1.0and179.0degreestoindicatethe
angle of the arrowheads. The default is 30.0.
ARROW_END
Set thiskeywordtoindicatean arrowheadshouldbedrawn at theendof theline. It isnot
drawn by default.
ARROW_SIZE
Set this keyword to a oating-point number between 0.0 and 0.3 (normalized
coordinates) to indicate the size of the arrowheads. The default is 0.02.
ARROW_START
Set this keyword to indicate an arrowhead should be drawn at the start of the line. It is
not drawn by default.
COLOR
Set thiskeyword to astring(case-sensitive) of thecolor to beused for theline. Thecolor
must be specied as an Insight color. The default is Black. Available colors are listed in
the table below.
IDL Reference Guide LIVE_LINE
DIALOG
Set thiskeyword to havean Insight linepropertiesdialogappear. Thedialogwill haveall
known properties supplied by keywords lled in.
DIMENSIONS
Set thiskeyword toatwo-element vector of theform[ width, height] tospecifytheXand
Y components of the line in normalized coordinates. The default is [ 0.2, 0.2] .
ERROR
reported via a GUI.
not be displayed.
HIDE
Set this keyword to a boolean value indicating whether this item should be hidden.
0 = Visible (default)
1 = Hidden
LINESTYLE
Set this keyword to a pre-dened line style integer:
0 = solid line (default)
1 = dotted
2 = dashed
3 = dash dot
4 = dash dot dot dot
5 = long dash
LOCATION
NAME
Set thiskeywordequal toastringcontainingthenametobeassociatedwiththisitem. The
name must be unique within the given window or buffer (WINDOW_IN). If not
specied, a unique name will be assigned automatically.
LIVE_LINE IDL Reference Guide
NO_DRAW
REFERENCE_OUT
Set this keyword to a variable to return a structure dening names of the modied visu-
alizations properties. The elds of the structure are shown in the following table.
THICK
Set thiskeyword to an integer valuebetween 1and 10, specifyingthelinethicknessto be
used to draw the line, in pixels. The default is one pixel.
VISUALIZATION_IN
visualization. The VIS eld from the REFERENCE_OUT keyword from the creation of
theLIVEtool will providethevisualization name. Visualization namesarealso visiblein
Insight's Visualization Manager and visualization property dialogs. If only one
visualization is present in the window or buffer (WINDOW_IN), this keyword will
default to it.
WINDOW_IN
Example
LIVE_LINE, WINDOW_IN='Live Plot 2', $
VISUALIZATION_IN='line plot visualization'
;Units arein thevisualization
units ( based on axis ranges).
Tag Description
WIN Window Name
GRAPHIC Graphic Name the line created
Table 9-30: Fields of the LIVE_LINE Reference Structure
IDL Reference Guide LIVE_LINE
See Also
LIVE_RECT, LIVE_TEXT, Using IDL Insight
LIVE_LOAD IDL Reference Guide
LIVE_LOAD
TheLIVE_LOADprocedureloadsintomemorythecompleteset of routinesnecessaryto
runall LIVEtoolsandInsight. Bydefault, portionsof theset areloadedwhenrst needed
duringtheIDL session. If you expect tofrequently usethetoolsand/or Insight, you may
wish to call LIVE_LOAD from your IDL startup le.
Calling Sequence
LIVE_LOAD
Arguments
(None)
Keywords
(None)
See Also
Using IDL Insight
IDL Reference Guide LIVE_OPLOT
LIVE_OPLOT
The LIVE_OPLOT procedure allows the insertion of data into pre-existing plots.
Calling Sequence
LIVE_OPLOT, Yvector1, Yvector2,...
Argument
YVector
A vector argument of data. Up to 25 of these arguments may be specied.
Keywords
ERROR
reported via a GUI.
not be displayed.
INDEPENDENT
Set this keyword to an independent vector specifying the X-Values for LIVE_OPLOT.
NAME
Tag Description
I Independent Data Name
LIVE_OPLOT IDL Reference Guide
dent vector.
NEW_AXES
Set thiskeywordtogenerateanewset of axesfor thisplot line. If thiskeywordisspecied,
the [ XY] AXIS_IN keywords will not be used.
NO_DRAW
REFERENCE_OUT
Set this keyword to a variable to return a structure dening the names of the modied
REPLACE
Tag Description
WIN Window Name
XAXIS X-Axis Name
YAXIS Y-Axis Name
LEGEND Legend Name
DATA Dependent Data Names(s)
Table 9-32: Fields of the LIVE_OPLOT Reference Structure
IDL Reference Guide LIVE_OPLOT
SUBTYPE
Set this keyword to a string (case-insensitive) containing the desired type of plot.
SUBTYPEdefaultstowhatever isbeinginserted into, if the[ XY] AXIS_INkeyword isset.
If the keywords are not set, then the default is line plot. Valid strings are:
LinePlot (default)
ScatterPlot
Histogram
PolarPlot
Note If inserting into a group (dened by the set of axes) that is polar, SUBTYPE cannot
bedened asline, scatter, or histogram. Theoppositeisalso true: if insertinginto a
line, scatter, or histogram group, then SUBTYPE cannot be dened as polar.
VISUALIZATION_IN
default to it.
the new value.
named items.
LIVE_OPLOT IDL Reference Guide
WINDOW_IN
[XY]_TICKNAME
Set thesekeywordsequal toan array of elements. Thevaluesof thestringswill beused to
data range.
[XY]AXIS_IN
Set thesekeywordsequal tothestringnameof an existingaxis. Thenamecanbeobtained
fromtheREFERENCE_OUTkeyword, or visuallyfromtheGUI. Thedefault istousethe
rst set of axes in the plot.
Note If thekeywordsareset, theymust bothbeset, andtheymust beset toapair of axes.
The X and Y axes given must be associated with the same plot line.
Example
LIVE_OPLOT, tempData, pressureData
See Also
LIVE_PLOT, PLOT, OPLOT, Using IDL Insight
IDL Reference Guide LIVE_PLOT
LIVE_PLOT
The LIVE_PLOT procedure creates an interactive plotting environment.
Click on asection of theplot to display apropertiesdialog. Aset of buttonsin theupper
left corner of theimagewindowallowsyou toprint, undothelast operation, redothelast
undone operation, copy, draw a line, draw a rectangle, or add text..
LIVE_PLOT is actually a subset of the IDL Insight application. If you nd that the
LIVE_PLOT graphical user interface does not provide the level of control you need,
Calling Sequence
LIVE_PLOT, Yvector1, Yvector2,...
Argument
YVector
A vector of data. Up to 25 of these arguments may be specied.
Keywords
BUFFER
DIMENSIONS
Set thiskeywordtoatwo-element, oating-point vector specifyingthedimensionsof the
visualization in normalized coordinates. The default is [ 1.0, 1.0] .
DRAW_DIMENSIONS
LIVE_PLOT IDL Reference Guide
ERROR
reported via a GUI.
not be displayed.
HISTOGRAM
Set this keyword to represent plot values as a histogram.
INDEPENDENT
Set this keyword to an independent vector specifying X-values for LIVE_PLOT.
INDEXED_COLOR
INSTANCING
LINE
Set this keyword to represent plot values as a line plot. This is the default. Alternate
choices are provided by keywords HISTOGRAM, POLAR, and SCATTER.
LOCATION
MANAGE_STYLE
NAME
NO_DRAW
NO_STATUS
NO_TOOLBAR
PARENT_BASE
Note The location of the draw widget is not settable. To insert a tool into your widget
application, you must determine the setting from the parent base sent to the tool.
LIVE_DESTROYon awindowisrecommendedwhen usingPARENT_BASEsothat
proper memory cleanup is done. Destroying the parent base is not sufcient.
had been in effect.
POLAR
Set this keyword to represent plot values as a polar plot. In this case, the arguments to
LIVE_PLOT represent valuesof r (radius), whiletheINDEPENDENT keyword represents
the values of T (angle theta). If POLAR is set, you must specify INDEPENDENT .
Tag Description
REFERENCE_OUT
RENDERER
Graphicsmanual.
REPLACE
Tag Description
WIN Window Name
XAXIS X-Axis Name
YAXIS Y-Axis Name
LEGEND Legend Name
DATA Dependent Data Names(s)
Table 9-35: Fields of the LIVE_PLOT Reference Structure
SCATTER
Set this keyword to represent plot values as a scatter plot.
STYLE
Note If STYLE is not set, the default plot style will be used.
TITLE
TLB_LOCATION
WINDOW_IN
[XY]LOG
Set these keywords to make the specied axis a log axis. The default is 0 (linear axis).
the new value.
named items.
[XY]RANGE
range.
[XY]_TICKNAME
data range.
Example
LIVE_PLOT, tempdata, pressureData Plot two data sets simultaneously.
Note Thisisa"Live" situation. When dataof thesamenameisused multipletimeswithin
Y= indgen(10)
Y = indgen(20)
example:
LIVE_PLOT, Y1,...
LIVE_PLOT, Y2,...
or
LIVE_PLOT, Y,...
See Also
LIVE_OPLOT, PLOT, OPLOT, Using IDL Insight
IDL Reference Guide LIVE_PRINT
LIVE_PRINT
TheLIVE_PRINTprocedureallowstheuser toprint agivenwindowtotheprinter. It uses
Insights preferences for print scaling (stretch, aspect ratio, and no scaling).
Calling Sequence
LIVE_PRINT
Arguments
(None)
Keywords
DIALOG
Set this keyword to have a print dialog appear.
ERROR
reported via a GUI.
not be displayed.
SETUP
(Macintosh users only) Set this keyword to have a printer setup dialog appear. This
keyword allows the user to setup the page for printing.
WINDOW_IN
Example
LIVE_PRINT, WINDOW_IN='Live Plot 2'
See Also
DIALOG_PRINTJOB, DIALOG_PRINTERSETUP, Using IDL Insight
LIVE_RECT IDL Reference Guide
LIVE_RECT
The LIVE_RECT procedure is an interface for insertion of rectangles.
Calling Sequence
LIVE_RECT
Arguments
(None)
Keywords
COLOR
Set thiskeyword to astring(case-sensitive) of thecolor to beused for therectangle. The
color must bespeciedasanInsight color. Thedefault isBlack. Availablecolorsarelisted
in the table below.
DIALOG
Set thiskeyword tohavean Insight rectangledialogappear. Thisdialogwill ll in known
attributes from set keywords.
DIMENSIONS
Set this keyword to a two-element, oating-point vector of the form [ width, height] to
specify the dimensions of the rectangle in normalized coordinates. The default is [ 0.2,
0.2] .
ERROR
reported via a GUI.
not be displayed.
IDL Reference Guide LIVE_RECT
HIDE
Set this keyword to a boolean value indicating whether this item should be hidden.
0 = Visible (default)
1 = Hidden
LINESTYLE
Set this keyword to a pre-dened line style integer:
0 = Solid line (default)
1 = dotted
2 = dashed
3 = dash dot
4 = dash dot dot dot
5 = long dash
LOCATION
NAME
NO_DRAW
REFERENCE_OUT
Tag Description
WIN Window Name
GRAPHIC Graphic Name the rectangle created
Table 9-37: Fields of the LIVE_RECT Reference Structure
LIVE_RECT IDL Reference Guide
THICK
Set thiskeyword to an integer valuebetween 1and 10, specifyingthelinethicknessto be
used to draw the line, in pixels. The default is one pixel.
VISUALIZATION_IN
default to it.
WINDOW_IN
Example
LIVE_RECT, LOCATION=[0.1,0.1],DIMENSIONS=[0.2,0.2],$
WINDOW_IN='Live Plot 2',VISUALIZATION_IN='line plot'
See Also
LIVE_LINE, LIVE_TEXT, Using IDL Insight
IDL Reference Guide LIVE_STYLE
LIVE_STYLE
The LIVE_STYLE procedure allows the user to create a style.
Calling Sequence
Style = LIVE_STYLE (Type)
Arguments
Type
Astring(case-insensitive) specifyingthevisualization styletype. Availabletypesinclude:
plot, contour, image, and surface.
Keywords
BASE_STYLE
Set thiskeyword equal to astring(case-insensitive) containingthenameof apreviously
saved style held in the Insight template le. It will be used for defaulting unspecied
properties. If not specied, only those properties you provide will be put into the style.
The basic styles that will always exist include::
Visualization
Type
Style Name
plot Basic Plot
contour Basic Contour
image Basic Image
surface Basic Surface
Table 9-38: Base Style Strings
LIVE_STYLE IDL Reference Guide
COLORBAR_PROPERTIES
The table below lists the structure of the COLORBAR_PROPERTIES keyword.
GRAPHIC_PROPERTIES
Set this keyword equal to a scalar or vector of structures dening the graphic properties
to usein creatingthestyle. (Useavector if you want successivegraphicsto havedifferent
properties, e.g., different colored lines in a line plot. The structures are used in a round-
robin fashion.) Not all properties need be specied (see BASE_STYLE). The complete
structure denitions are listed in the following tables.
Tag Description
title_Color see color table
tick_FontSize see fontsize
tick_Fontname see fontname
tick_FontColor see color table
color see color table
tickFormat see format
show_axis set to display the colorbar axis
show_outline set to display the colorbar outline
axis_thick see thick
Table 9-39: Colorbar Properties Structure
Plots
Images
Contours
Tag Data Type/ Description
color string (see color table)
hide boolean (1=hidden, 0=visible)
linestyle integer (0to 5: solid, dotted, dashed, dash dot, dash dot dot dot, longdash)
nSum integer (1 to number of elements to average over)
symbol_size [ x,y] normalized units relative to the visualization
symbol_type integer (1-7)
thick integer (1 to 10 pixels)
Table 9-40: Plot Graphic Properties Structure
order boolean (set to draw from top to bottom)
sizing_constraint integer (0=natural, 1=aspect, 2=unrestricted)
Table 9-41: Image Graphic Properties Structure
downhill boolean (set to display downhill tick marks)
ll boolean (set to display contour levels as lled)
n_levels integer (number of levels)
c_thick vector of thickness values
c_linestyle vector of linestyle values
c_color vector of color names
default_n_levels integer (set to default number of levels)
Table 9-42: Contour Graphic Properties Structure
Surfaces
GROUP
Set this keyword to the widget ID of the group leader for error message display. This
keywordisusedonlywhentheERRORkeywordisnot set. If onlyoneLIVEtool or Insight
window is present in the IDL session, it will default to that.
LEGEND_PROPERTIES
Set thiskeyword equal to astructuredeningthelegend propertiesto usein creatingthe
style. Not all properties need be specied (see BASE_STYLE). The complete structure
denitions for different types of styles are listed in the following tables.
bottom string (see color table)
hidden_lines boolean (1=show, 0=dont show)
lineStyle integer (0 to 5 : solid, dotted, dashed, dash dot, dash
dot dot dot, long dash)
shading boolean (0=at, 1=Gouraud)
show_skirt boolean (1=show, 0=dont show)
skirt oat (z value at which skirt is drawn [ data units] )
style integer (0=point, 1=wire, 2=solid, 3=ruledXZ,
4=ruledYZ, 5=lego (wire), 6=lego (solid)
thick integer (1 to 10 pixels)
Table 9-43: Surface Graphic Properties Structure
Tag Description
title_Color see color table
item_fontSize see fontsize
item_fontName see fontname
NAME
Set thiskeywordtoastringcontaininganamefor thereturnedstyle. If theSAVEkeyword
is set, the name must be unique in the Insight template le. If not specied, a name will
be automatically generated.
SAVE
Set this keyword to save the style in the Insight style template le. The supplied Name
must not already exist in the template le or an error will be returned.
VISUALIZATION_PROPERTIES
Set this keyword equal to a structure dening the visualization properties to use in
creatingthestyle. Not all propertiesneed bespecied (seeBASE_STYLE). Thecomplete
structure denition is in the following table.
text_color see color
border_gap normalized units * 100 = percent of item text height
columns number of columns to display the items in (minimum 0)
gap normalized units * 100 = percent of item text height
glyph_Width normalized units * 100 = percent of item text height
ll_color see color table
outline_color see color table
outline_thick see thick
show_ll set to display the ll color
show_outline set to display the legend outline
Tag Data Type
color string (see color table) for background
hide boolean
transparent boolean
Table 9-45: Visualization Properties Structure
Tag Description
[XYZ]AXIS_PROPERTIES
Set thesekeywordsequal toascalar or vector of structuresdeningtheaxispropertiesto
usein creatingthestyle. (Useavector tospecifypropertystructuresfor successiveaxesof
the same direction have different properties. The structures are used in a round-robin
fashion.) Not all properties need be specied (see BASE_STYLE). The user need only
dene the elds of the structure they wish to be different from the BASE style. The
complete structure denition is shown in the following table.
Example
Style=LIVE_STYLE(plot,BASE_STYLE=basic plot, $
GRAPHIC_PROPERTIES={color:red})
See Also
LIVE_INFO, LIVE_CONTROL, Using IDL Insight
Tag Data Type
default_major integer
default_minor integer
exact boolean
gridstyle integer (0-5) (linestyle)
hide boolean
location 3-element oating vector (normalized units)
major integer (default=-1, computed by IDL)
minor integer (default=-1, computed by IDL)
thick integer (1-10)
tickDir integer
tickLen oat (normalized units)
tick_fontname string
tick_fontsize integer
IDL Reference Guide LIVE_SURFACE
LIVE_SURFACE
TheLIVE_SURFACEprocedurecreatesan interactiveplottingenvironment for multiple
surfaces. Because the interactive environment requires extra system resources, this
routine is most suitable for relatively small data sets. If you nd that performance does
not meet your expectations, consider usingtheDirect GraphicsSURFACEroutineor the
Object Graphics IDLgrSurface class directly.
After LIVE_SURFACEhasbeenexecuted, youcandouble-click onasectionof thesurface
to display a properties dialog. A set of buttons in the upper left corner of the image
window allows you to print, undo the last operation, redo the last undone operation,
copy, draw a line, draw a rectangle, or add text..
LIVE_SURFACE is actually a subset of the IDL Insight application. If you nd that the
LIVE_SURFACEgraphical user interfacedoesnot providethelevel of control you need,
Calling Sequence
LIVE_SURFACE, Data, Data2,...
Arguments
Data
A two-dimensional array of data. Up to 25 of these parameters may be specied.
Keywords
BUFFER
LIVE_SURFACE IDL Reference Guide
DIMENSIONS
Set this keyword to a two-element, oating-point vector of the form [ width, height]
specifying the dimensions of the visualization in normalized coordinates. The default is
[ 1.0, 1.0] .
DRAW_DIMENSIONS
ERROR
reported via a GUI.
not be displayed.
INDEXED_COLOR
INSTANCING
LOCATION
MANAGE_STYLE
NAME
Tag Description
NO_DRAW
in order to reduce unwanted draws and help speed the display
NO_STATUS
NO_TOOLBAR
PARENT_BASE
had been in effect.
REFERENCE_OUT
Tag Description
WIN Window Name
Table 9-48: Fields of the LIVE_SURFACE Reference Structure
Tag Description
RENDERER
Set thiskeyword to1tousethesoftwarerenderer, or 0tousethehardwarerenderer.
Graphicsmanual.
REPLACE
XAXIS X-Axis Name
YAXIS Y-Axis Name
LEGEND Legend Name
the new value.
Tag Description
Table 9-48: Fields of the LIVE_SURFACE Reference Structure
STYLE
TITLE
TLB_LOCATION
WINDOW_IN
[XY]INDEPENDENT
Set these keywords to a vector specifying X and Y values for LIVE_CONTOUR. The
default is the datas index values.
dent vector.
[XY]LOG
Set these keywords to make the specied axis a log axis. The default is 0.
[XY]RANGE
range.
named items.
[XY]_TICKNAME
data range.
Example
LIVE_SURFACE, tempData, pressureData Visualizetwo surfacerepresenta-
tions. To manipulateany part of
thesurface,doubleclickonsurface
toaccessagraphical userinterface.
Note Thisisa"Live" situation. When dataof thesamenameisused multipletimeswithin
Y = indgen(10)
Y = indgen(20)
example:
LIVE_PLOT, Y1,...
LIVE_PLOT, Y2,...
or;
LIVE_PLOT, Y,...
See Also
SURFACE, SHADE_SURF, Using IDL Insight
IDL Reference Guide LIVE_TEXT
LIVE_TEXT
The LIVE_TEXT procedure is an interface for text annotation.
Calling Sequence
LIVE_TEXT[ , Text]
Arguments
Text
The string to be used for the text annotation. The default is Text. If Text is an array of
strings, each element of the string array will appear on a separate line.
Keywords
ALIGNMENT
Set this keyword to a oating-point value between 0.0 and 1.0 to indicate the requested
alignment of the text baseline. The alignment scheme follows:
1.0---------0.5--------0.0
Left Middle Right
COLOR
Set thiskeywordtoastring(case-sensitive) of theforegroundcolor tobeusedfor thetext.
Thecolor must bespecied asan Insight color. Thedefault isBlack. Availablecolorsare
listed in the table below.
DIALOG
Set this keyword to have an Insight text annotation dialog appear. This dialog will ll in
known attributes from set keywords.
LIVE_TEXT IDL Reference Guide
ENABLE_FORMATTING
Set this keyword to have LIVE_TEXT interpret ! (exclamation mark) as font and
positioning commands.
ERROR
reported via a GUI.
not be displayed.
FONTNAME
Set this keyword to a string containing the name of the desired font. The default is
Helvetica.
FONTSIZE
Set thiskeyword toan integer scalar specifyingthefont point sizetobeused. Thedefault
is 12. Available point sizes are 9 through 72.
HIDE
Set this keyword to a boolean value indicating whether this item should be drawn:
0 = Draw (default)
1 = Do not draw
LOCATION
NAME
NO_DRAW
REFERENCE_OUT
IDL Reference Guide LIVE_TEXT
TEXTANGLE
Set this keyword to a oating-point value dening the angle of rotation of the text. The
valid range is from 0.0 to 360.0. The default is 0.0.
VISUALIZATION_IN
default to it.
WINDOW_IN
Example
LIVE_TEXT, My Annotation, WINDOW_IN='Live Plot 2', $
VISUALIZATION_IN='line plot visualization'
See Also
LIVE_LINE, LIVE_RECT, Using IDL Insight
Tag Description
WIN Window Name
GRAPHIC Graphic Name the text created
Table 9-50: Fields of the LIVE_TEXT Reference Structure
LJLCT IDL Reference Guide
LJLCT
TheLJLCTprocedureloadsstandardcolor tablesfor LJ-250/252printer. Thecolor tables
are modied only if the device is currently set to LJ.
The default color maps used are for the 90 dpi color palette. There are only 8 colors
available at 180 dpi.
If thecurrent deviceisLJ, the!D.N_COLORSsystemvariableisused to determinehow
many bit planesarein use(1to 4). Thestandard color map for that number of planesis
loaded. These maps are described in Chapter 7 of theLJ250/LJ252 Companion Color
Printer Programmer ReferenceManual, Table 7-5. That manual gives the values scaled
from 1 to 100, LJLCT scales them from 0 to 255.
ljlct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
LJLCT
Example
SET_PLOT, 'LJ' Set plottingto theLJ device.
LJLCT Load theLJ color tables.
See Also
SET_PLOT
IDL Reference Guide LL_ARC_DISTANCE
LL_ARC_DISTANCE
The LL_ARC_DISTANCE function returns a two-element vector containing the
longitude and latitude [ lon, lat] of a point a given arc distance (- Arc_Dist ), and
azimuth (Az), from a specied location Lon_lat0. Values are in radians unless the
keyword DEGREES is set.
ll_arc_distance.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = LL_ARC_DISTANCE(Lon_lat0, Arc_Dist, Az)
Arguments
Lon_lat0
A2-element vector containingthelongitudeandlatitudeof thestartingpoint. Valuesare
assumed to be in radians unless the keyword DEGREES is set.
Arc_Dist
The arc distance fromLon_lat0. The value must be between - and +. To express
distancesin arcunits, dividebytheradiusof theglobeexpressedin theoriginal units. For
example, if theradiusof theearthis6371km, dividethedistancein kmby6371toobtain
the arc distance.
Az
The azimuth fromLon_lat0. The value is assumed to be in radians unless the keyword
DEGREES is set.
Keywords
DEGREES
Set this keyword to express all measurements and results in degrees.
Example
Lon_lat0 = [1.0, 2.0] Initial point specified in radians
Arc_Dist = 2.0 Arc distancein radians
Az = 1.0 Azimuth in radians
Result = LL_ARC_DISTANCE(Lon_lat0, Arc_Dist, Az)
PRINT, Result
LL_ARC_DISTANCE IDL Reference Guide
IDL prints:
2.91415 -0.622234
See Also
MAP_SET
IDL Reference Guide LMFIT
LMFIT
The LMFIT function does a non-linear least squares t to a function with an arbitrary
number of parameters. LMFIT uses the Levenberg-Marquardt algorithm, which
combines the steepest descent and inverse-Hessian function tting methods. The
function may be any non-linear function.
Iterations are performed until three consecutive iterations fail to change the chi square
value by more than the specied tolerance amount, or until a maximum number of
iterations have been performed. The LMFIT function returns a vector of calculated
parameters, which are improvements upon the initial guesses.
Theinitial guessof theparameter valuesshouldbeasclosetotheactual valuesaspossible
or the solution may not converge. Test the value of the variable specied by the
CONVERGENCE keyword to determine whether the algorithm converged, failed to
converge, or encountered a singular matrix.
lmfit.pro in thelib subdirectory of the IDL distribution. LMFIT is based on the
routinemrqmin described in section 15.5of Numerical RecipesinC: TheArt of Scientic
Computing(Second Edition), published by Cambridge University Press, and is used by
permission.
Calling Sequence
Result = LMFIT(X, Y, A)
Arguments
X
Arowvector of independent variables. LMFIT doesnot manipulateor usevaluesin X, it
simply passesX to the user-written function.
Y
A row vector containing the dependent variables.
A
A vector that contains the initial estimate for each parameter.
Keywords
ALPHA
Set this keyword equal to a named variable that will contain the value of the curvature
matrix.
LMFIT IDL Reference Guide
CHISQ
Set this keyword equal to a named variable that will contain the value of chi-squared.
CONVERGENCE
Set this keyword equal to a named variable that will indicate whether the LMFIT
algorithm converged. The possible returned values are:
1 The algorithm converged.
0 The algorithm did not converge.
-1 The algorithm encountered a singular matrix and did not converge.
COVAR
Set this keyword equal to a named variable that will contain the value of the covariance
matrix.
DOUBLE
Set this keyword to force the computations to be performed in double precision.
FITA
Set thiskeyword equal to avector, with asmany elementsasA, which containsazero for
each xed parameter, and a non-zero value for elements of A to t. If FITA is not
specied, all parameters are taken to be non-xed.
FUNCTION_NAME
Use this keyword to specify the name of the function to t. If this keyword is omitted,
LMFITassumesthat theIDLprocedureLMFUNCT istobeused. If LMFUNCT isnot already
compiled, IDL compiles the function from the lelmfunct.pro, located in thelib
subdirectory of the IDL distribution. LMFUNCT is designed to t a quadratic equation.
Thefunction tobet must bewritten asan IDL procedureand compiled prior tocalling
LMFIT. Thefunction must accept avector X(theindependent variables) and avector A
containing the tted functions parameter values. It must return an A+1-element vector
in which the rst (zeroth) element is the evaluated function value and the remaining
elements are the partial derivatives with respect to each parameter in A.
Note The returned value must be of the same data type as the input X value.
ITER
Set this keyword equal to a named variable that will contain the actual number of
iterations which were performed
ITMAX
Set this keyword equal to the maximum number of iterations. The default is 20.
SIGMA
Set this keyword equal to a named variable that will contain a vector of standard
deviations for the returned parameters.
IDL Reference Guide LMFIT
TOL
Theconvergencetolerance. Theroutinereturnswhentherelativedecreaseinchi-squared
is less than TOL in an iteration. Default = 1.0 x10
-6
.
WEIGHTS
Set this keyword equal to a vector of tting weights for Y
i
. This vector must be the same
lengthasXandY. For instrumental (Gaussian) weighting(when themeasurement errors
or standard deviations () of Y are known), set WEIGHTS to 1/(
2
). For statistical
(Poisson) weighting, set WEIGHTS=1/Y. If WEIGHTS is not specied, WEIGHTS
i
is
assumed to be 1.0.
YFIT
Set thiskeyword equal toanamed variablethat will contain thetted function evaluated
at the input X values.
Example
Suppose we wish to t a function of the form:
f(x)=a[0] * exp(a[1]*x) + a[2] + a[3] * sin(x)
First, dene a return function for LMFIT:
FUNCTION myfunct, X, A
bx = A[0]*EXP(A[1]*X)
RETURN,[ [bx+A[2]+A[3]*SIN(X)], [EXP(A[1]*X)], [bx*X], $
[1.0] ,[SIN(X)] ]
END
Compute the t to the function we have just dened. First, dene the independent and
dependent variables:
X = FINDGEN(40)/20.0
Y = 8.8 * EXP(-9.9 * X) + 11.11 + 4.9 * SIN(X)
sig = 0.05 * Y
A = [10.0, -0.1, 2.0, 4.0] Providean initial guess for the
functions parameters.
fita = [1,1,1,1]
PLOTERR, X, Y, sig Plot theinitial data, with error
bars.
coefs = LMFIT(X, Y, A, WEIGHTS = (1/sig^2.0), FITA = fita, $
FUNCTION_NAME = 'myfunct')
OPLOT, X, coefs Overplot thefitted data.
See Also
CURVEFIT, GAUSSFIT, LMFIT, POLY_FIT, POLYFITW, REGRESS, SFIT, SVDFIT
LMGR IDL Reference Guide
LMGR
The LMGR function tests whether a particular licensing mode is in effect. The function
returns True (1) if the mode specied is in effect, or False (0) otherwise. Different
licensing modes are specied by keyword; see theKeywordssection below for a
description of each licensing mode.
The LMGR function can also force IDL into time demo mode or report the LMHostid
number for the machine in use.
For moreinformation on IDLslicensingmethods, consult theIDL LicenseManagement
Guide, which isincluded in AdobeAcrobat PortableDocument Format on your IDL CD-
ROM.
Calling Sequence
Result = LMGR()
Arguments
None.
Keywords
CLIENTSERVER
Set this keyword to test whether the current IDL session is using Client/Server licensing
(as opposed to Desktop licensing).
DEMO
Set thiskeywordtotest whether thecurrent IDLsession isrunningin timeddemomode.
Unlicensed copies of IDL and copies running directly from a CD-ROM run in timed
demo mode.
EMBEDDED
Set this keyword to test whether the current IDL session is running in embedded mode.
Embedded-modeapplicationscontain abuilt-in version of theIDL license. Examplesof
applications running in embedded mode are the IDL demo and the IDL registration
program.
FORCE_DEMO
Set this keyword to force the current session into timed demo mode. Forcing an IDL
session into demo mode can be useful if you are testing an application that will be run
with an unlicensed copy of IDL. Note that you must exit IDL and restart to return to
normal licensed mode after forcing IDL into demo mode.
IDL Reference Guide LMGR
LMHOSTID
Set thiskeywordequal toanamedvariablethat will contain astringvaluerepresetingthe
LMHostidfor themachinein use. TheLMHostidisusedwhen creatingclient/server IDL
licenses. This keyword returns the string "0" on machines which do not have a unique
LMHostid (Macintoshes and some Windows machines that use Desktop licensing.)
RUNTIME
Set this keyword to test whether the current IDL session is running in runtime mode.
Runtime-modeapplicationsdonot provideaccesstotheIDLcommandline. SeetheIDL
RuntimeGuidefor additional details on runtime applications.
STUDENT
Set thiskeyword totest whether thecurrent IDL session isrunningin student mode. The
IDL Student version, which provides a subset of IDLs full functionality, is currently the
only product that runs in student mode.
TRIAL
Set this keyword to test whether the current IDL session is running in trial mode. Trial
mode licenses allow IDL to operate for a limited time period (generally 30 days) but do
not otherwise restrict functionality.
Example
Usethefollowingcommandstotest whether thecurrent IDL session isrunningin timed
demo mode:
Result = LMGR(/DEMO)
IF (Result GT 0) THEN PRINT, "IDL is in Demo Mode"
Use the following commands to generate the LMHostid number for the machine in use:
Result = LMGR(LMHOSTID = myId)
PRINT, "LMHostid for this machine is: ", myId
LNGAMMA IDL Reference Guide
LNGAMMA
The LNGAMMA function returns the logarithm of the gamma function of X. This
functionisundenedfor negativeintegers. If theargument isdouble-precision, theresult
is double-precision. Otherwise, this function yields oating-point results.
Calling Sequence
Result = LNGAMMA(X)
Arguments
X
The expression for which the logarithm of the gamma function will be evaluated.
Example
To nd the logarithm of the gamma function of 0.5 and store the result in variable A,
enter:
A = LNGAMMA(0.5)
See Also
BETA, GAMMA, IBETA, IGAMMA
IDL Reference Guide LNP_TEST
LNP_TEST
The LNP_TEST function computes the Lomb Normalized Periodogram of two sample
populationsXand Yand teststhehypothesisthat thepopulationsrepresent asignicant
periodic signal against the hypothesis that they represent random noise. The result is a
two-element vector containing the maximum peak in the Lomb Normalized
Periodogram and its signicance. The signicance is a value in the interval [ 0.0, 1.0] ; a
small value indicates that a signicant periodic signal is present.
LNP_TESTisbasedontheroutinefasperdescribedinsection13.8of Numerical Recipes
Calling Sequence
Result = LNP_TEST(X, Y)
Arguments
X
An n-element integer, single-, or double-precision oating-point vector containing
equally or unequally spaced time samples.
Y
amplitudes corresponding to X
i
.
Keywords
HIFAC
Usethiskeyword to specify thescalefactor of theaverageNyquist frequency. Thedefault
value is 1.
JMAX
Usethiskeywordtospecifyanamedvariablethat will contain theindex of themaximum
peak in the Lomb Normalized Periodogram.
OFAC
Use this keyword to specify the oversampling factor. The default value is 4.
WK1
Usethiskeywordtospecifyanamedvariablethat will containavector of increasinglinear
frequencies.
LNP_TEST IDL Reference Guide
WK2
Usethiskeyword tospecifyanamed variablethat will contain avector of valuesfromthe
Lomb Normalized Periodogram corresponding to the frequencies in WK1.
Example
X = [ 1.0, 2.0, 5.0, 7.0, 8.0, 9.0, $
10.0, 11.0, 12.0, 13.0, 14.0, 15.0, $
16.0, 17.0, 18.0, 19.0, 20.0, 22.0, $
23.0, 24.0, 25.0, 26.0, 27.0, 28.0]
Y = [ 0.69502, -0.70425, 0.20632, 0.77206, -2.08339, 0.97806, $
1.77324, 2.34086, 0.91354, 2.04189, 0.53560, -2.05348, $
-0.76308, -0.84501, -0.06507, -0.12260, 1.83075, 1.41403, $
-0.26438, -0.48142, -0.50929, 0.01942, -1.29268, 0.29697]
Test the hypothesis that X and Y represent a signicant periodic signal against the
hypothesis that they represent random noise.
result = LNP_TEST(X, Y, WK1 = wk1, WK2 = wk2, JMAX = jmax)
PRINT, result
IDL prints:
4.69296 0.198157
The small value of the signicance represents the possibility of a signicant periodic
signal. A larger number of samplesfor Xand Y would produceamoreconclusiveresult.
WK1 and WK2 are both 48-element vectors containing linear frequencies and
correspondingLombvalues, respectively. JMAXistheindexed location of themaximum
Lomb value in WK2.
See Also
CTI_TEST, FV_TEST, KW_TEST, MD_TEST, R_TEST, RS_TEST, S_TEST, TM_TEST,
XSQ_TEST
IDL Reference Guide LOADCT
LOADCT
TheLOADCT procedureloadsoneof 41predened IDL color tables. Thesecolor tables
aredened in thelecolors1.tbl (located in themain IDL directory) unlesstheFILE
keyword isspecied. Theselected colortableisloaded into theCOLORScommon block
as both the current and original colortable. If the current device has fewer than 256
colors, the color table data is interpolated to cover the number of colors in the device.
loadct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
LOADCT [, Table]
Arguments
Table
The number of the pre-dened color table to load, from 0 to 40. If this value is omitted,
amenu of theavailabletablesisprintedandtheuser ispromptedtoenter atablenumber.
Keywords
BOTTOM
The rst color index to use. LOADCT will use color indices from BOTTOM to
BOTTOM+NCOLORS-1. The default is BOTTOM=0.
FILE
Set this keyword to the name of a colortable file to be used instead of the filecolors1.tbl
intheIDLdirectory. TheMODIFYCTprocedure(page754) canbeusedtocreateandmodify
colortable files.
GET_NAMES
Set thiskeyword to anamed variablein which thenamesof thecolor tablesarereturned
as a string array. No changes are made to the color table.
NCOLORS
The number of colors to use. The default is all available colors (this number is stored in
the system variable !D.TABLE_SIZE).
SILENT
If this keyword is set, the Color Table message is suppressed.
See Also
MODIFYCT, XLOADCT, TVLCT
LON64ARR IDL Reference Guide
LON64ARR
The LON64ARR function returns a 64-bit integer vector or array.
Calling Sequence
Result = LON64ARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, LON64ARR sets every element of the result to zero. If NOZERO is set, this
zeroing is not performed and LON64ARR executes faster.
Example
To create L, a 100-element, 64-bit vector with each element set to 0, enter:
L = LON64ARR(100)
See Also
BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LONARR,
IDL Reference Guide LONARR
LONARR
The LONARR function returns a longword integer vector or array.
Calling Sequence
Result = LONARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, LONARR sets every element of the result to zero. If NOZERO is set, this
zeroing is not performed and LONARR executes faster.
Example
To create L, a 100-element, longword vector with each element set to 0, enter:
L = LONARR(100)
See Also
BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR,
LON64ARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR
LONG IDL Reference Guide
LONG
The LONG function returns a result equal to Expression converted to longword integer
type.
Calling Sequence
Result = LONG(Expression[, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to longword integer.
Offset
of data extracted fromExpression to be treated as longword integer data. See the
description in Constants and Variables on page 11 of Building IDL Applications for
details.
D
i
i
valid longword integer and no conversion is possible. The default action in such cases is
to print a warning message and return 0. The ON_IOERROR procedure can be used to
Example
If Acontainstheoating-point value32000.0, it can convertedtoalongwordinteger and
stored in the variable B by entering:
B = LONG(A)
See Also
BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, ULONG64, STRING, UINT,
ULONG, ULONG64
IDL Reference Guide LONG64
LONG64
The LONG64 function returns a result equal to Expression converted to 64-bit integer
type.
Calling Sequence
Result = LONG64(Expression[, Offset [, D
1
, ..., D
n
]])
Arguments
Expression
The expression to be converted to 64-bit integer.
Offset
of dataextracted fromExpressionto betreated as64-bit integer data. Seethedescription
in Constants and Variables on page 11 of Building IDL Applications for details.
D
i
i
statement to be executed in case of such errors.
Example
If A contains the oating-point value 32000.0, it can converted to a 64-bit integer and
B = LONG64(A)
See Also
BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, STRING, UINT,
ULONG, ULONG64
LSODE IDL Reference Guide
LSODE
TheLSODEfunction usesadaptivenumerical methodstoadvanceasolution toasystem
of ordinarydifferential equationsonetime-step H, given valuesfor thevariablesYand X.
Calling Sequence
Result = LSODE(Y, X, H, Derivs[, Status])
Arguments
Y
A vector of values for Y at X
X
A scalar value for the initial condition.
H
A scalar value giving interval length or step size.
Derivs
values of the derivativesDydx at X. This function must accept two arguments: A scalar
oating valueX, and one n-element vector Y. It must return an n-element vector result.
Example Suppose the values of the derivatives are dened by the following relations:
dy
0
/ dx = 0.5y
0,
dy
1
/ dx = 4.0 0.3y
1
0.1y
0
Wecan writeafunction called differential to expresstheserelationshipsin the
IDL language:
FUNCTION differential, X, Y
RETURN, [-0.5 * Y[0], 4.0 - 0.3 * Y[1] - 0.1 * Y[0]]
END
Status
An index used for input and output tospecifythestateof thecalculation. Thisargument
contains a positive value if the function was successfully completed. Negative values
indicate different errors.
Input Value Description
1 This is the rst call for the problem; initializations will occur. This is
the default value.
Table 9-51: Input Values for Status
IDL Reference Guide LSODE
Note Apreliminarycall withtout = tisnot countedasarst call here, asnoinitialization
or checking of input is done. (Such a call is sometimes useful for the purpose of
outputting the initial condition s.) Thus, the rst call for which tout t requires
STATUS = 1 on input..
2 This is not the rst call. The calculation is to continue normally.
3 This is not the rst call. The calculation is to continue normally, but
with a change in input parameters.
OutputValue Description
1 Nothing occurred. (However, an internal counter was set to detect
and prevent repeated calls of this type.)
2 The integration was performed successfully, and no roots were found.
3 The integration was successful, and one or more roots were found.
-1 An excessiveamount of work wasdoneon thiscall, but theintegration
was otherwise successful. To continue, reset STATUS to a value greater
than1 and begin again (the excess work step counter will be reset to 0).
-2 The precision of the machine being used is insufcient for the
requested amount of accuracy. Integration wassuccessful. Tocontinue,
the tolerance parameters must be reset, and STATUS must be set to 3.
(If this condition is detected before taking any steps, then an illegal
input return (STATUS = -3) occurs instead.)
-3 Illegal input was detected, before processing any integration steps. If
the solver detects an innite loop of calls to the solver with illegal
input, it will cause the run to stop.
-4 There were repeated error test failures on one attempted step, before
completing the requested task, but the integration was successful. The
problem may have a singularity, or the input may be inappropriate.
-5 There were repeated convergence test failures on one attempted step,
before completing the requested task, but the integration was success-
ful. This may be caused by an inaccurate jacobian matrix, if one is
being used.
Table 9-52: Output Values for Status
Input Value Description
Table 9-51: Input Values for Status
LSODE IDL Reference Guide
Note Sincethenormal output valueof STATUSis2, it doesnot needtobereset for normal
continuation. Also, sinceanegativeinput valueof STATUSwill beregardedasillegal,
anegativeoutput valuerequirestheuser tochangeit, andpossiblyother inputs, before
calling the solver again.
Keywords
ATOL
A scalar or array value that species the absolute tolerance. The default value is 1.0e-7.
Use ATOL = 0.0 (or ATOL[ i] = 0.0) for pure relative error control, and use RTOL = 0.0
for pure absolute error control. For an explanation of how to use ATOL and RTOL
together, see RTOL below.
RTOL
A scalar value that specied the relative tolerance. The default value is 1.0e-7. Use
RTOL = 0.0 for pure absolute error control, and use ATOL = 0.0 (or ATOL[i] = 0.0) for
pure relative error control.
The estimated local error in the Y[ i] argument will be controlled to be less than
ewt[i] = RTOL*abs(Y[i]) + ATOL If ATOL is a scalar.
ewt[i] = RTOL*abs(Y[i]) + ATOL[i] If ATOL is an array.
Thus, thelocal error test passesif, ineachcomponent, either theabsoluteerror islessthan
ATOL (or ATOL[ i] ), or if the relative error is less than RTOL.
Caution Actual, or global, errors might exceed these local tolerances, so choose values for
ATOL and RTOL conservatively.
Example
To integrate the example system of differential equations for one time step, H:
H = 0.5 Definethestep size.
-6 ewt(i) became zero for some i during the integration. Pure relative
error control was requested on a variable which has now vanished.
Integration was successful.
-7 The length of rwork and/or iwork was too small to proceed, but the
integration was successful. This happens when LSODA chooses to
switch methods but other variables are too small for the new method.
OutputValue Description
Table 9-52: Output Values for Status
IDL Reference Guide LSODE
X = 0.0 Definean initial X value.
Y = [4.0, 6.0] Defineinitial Y values.
result = LSODE(Y, X, H, 'differential')
Integrateovertheinterval (0, 0.5).
IDL prints:
3.11523 6.85767
This is the exact solution vector to 5-decimal precision.
See Also
DERIV, DERIVSIG, RK4
References
1. Alan C. Hindmarsh, ODEPACK, ASystematizedCollection of ODESolvers, in Scientic
Computing, R. S. Stepleman et al. (eds.), North-Holland, Amsterdam, 1983,
pp. 55-64.
2. LindaR. Petzold, AutomaticSelection of Methodsfor SolvingStiff and Nonstiff Systems
of OrdinaryDifferential Equations, SIAMJ. SCI. STAT. COMPUT. 4(1983), pp. 136-148.
3. Kathie L. Hiebert and Lawrence F. Shampine, Implicitly Dened Output Points for
Solutions of ODEs, Sandia Report SAND80-0180, February, 1980.
LU_COMPLEX IDL Reference Guide
LU_COMPLEX
The LU_COMPLEX function solves an n by n complex linear systemAz = b using LU
decomposition. The result is an n-element complex vector z. Alternatively,
LU_COMPLEX computesthegeneralized inverseof an nby ncomplex array. Theresult
is an n by n complex array.
lu_complex.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = LU_COMPLEX(A, B)
Arguments
A
An n by n complex array.
B
An n-element right-hand side vector (real or complex).
Keywords
DOUBLE
INVERSE
Set this keyword to compute the generalized inverse of A. If INVERSE is specied, the
input argument B is ignored.
SPARSE
Set this keyword to convert the input array to row-indexed sparse storage format.
Computationsaredoneusingtheiterativebiconjugategradient method. Thiskeywordis
effective only when solving complex linear systems. This keyword has no effect when
calculating the generalized inverse.
Example
Dene a complex array A and right-side vector B:
A = [[COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3,1)], $
[COMPLEX(1,-2), COMPLEX(2, 2), COMPLEX(1, 0)], $
[COMPLEX(1, 1), COMPLEX(0, 1), COMPLEX(1, 5)]]
IDL Reference Guide LU_COMPLEX
B = [COMPLEX(1, 1), COMPLEX(3,-2), COMPLEX(1,-2)]
Solve the complex linear systemAz = b.
Z = LU_COMPLEX(A, B)
PRINT, Z
IDL prints:
( 0.552267, 1.22818)( -0.290371, -0.600974)
( -0.629824, -0.340952)
Computetheinverseof thecomplex array Aby supplyingascalar for B(in thisexample
-1).
inv = LU_COMPLEX(A, B, /INVERSE)
PRINT, inv
IDL prints:
( 0.261521, -0.0303485)( 0.0138629, 0.329337)
( -0.102660, -0.168602)
( 0.102660, 0.168602)( 0.0340952, -0.162982)
( 0.125890, -0.0633196)
( -0.0689397, 0.0108655)( -0.0666916, -0.0438366)
( 0.0614462, -0.161858)
See Also
CRAMER, CHOLSOL, GS_ITER, LUSOL, SVSOL, TRISOL, andSparseArrays onpage
464 of Using IDL.
LUDC IDL Reference Guide
LUDC
The LUDC procedure replaces an n by n array, A, with the LU decomposition of a row-
wise permutation of itself.
LUDCisbasedon theroutineludcmp describedin section 2.3of Numerical RecipesinC:
TheArt of Scientic Computing(Second Edition), published by Cambridge University
Calling Sequence
LUDC, A, Index
Arguments
A
An n by n array of any type except string. Upon output, A is replaced with its LU
decomposition.
Index
An output vector that recordstherowpermutationswhich occurred asaresult of partial
pivoting.
Keywords
COLUMN
DOUBLE
INTERCHANGES
An output variablethat isset topositive1if thenumber of rowinterchangeswaseven, or
to negative 1 if the number of interchanges was odd.
Example
See the description of LUSOL for an example using this function.
See Also
LUSOL
IDL Reference Guide LUMPROVE
LUMPROVE
TheLUMPROVEfunctionusesLUdecompositiontoiterativelyimproveanapproximate
solution X of a set of n linear equations in n unknownsAx = b. The result is a vector,
whose type and length are identical to X, containing the improved solution.
LUMPROVE is based on the routinemprove described in section 2.5 of Numerical
Recipes in C: TheArt of Scientic Computing(Second Edition), published by Cambridge
Calling Sequence
Result = LUMPROVE(A, Alud, Index, B, X)
Arguments
A
Then by n coefcient array of the linear systemAx = b.
Alud
Then by n LU decomposition of A created by the LUDC procedure.
Index
An input vector, created by the LUDC procedure, containing a record of the row
permutations which occurred as a result of partial pivoting.
B
An n-element vector containing the right-hand side of the linear system
Ax = b.
X
An n-element vector containing the approximate solution of the linear system
Ax = b.
Keywords
COLUMN
DOUBLE
LUMPROVE IDL Reference Guide
Example
Use LUMPROVE to improve an approximate solution X to the linear systemAx = B:
A = [[ 2.0, 1.0, 1.0], $ Createcoefficient array A.
[ 4.0, -6.0, 0.0], $
[-2.0, 7.0, 2.0]]
alud = A Createa duplicateof A.
B = [3.0, -8.0, 10.0] Definetheright-hand sidevector
B.
X = [.89, 1.78, -0.88] Begin with an estimated solution
X.
LUDC, alud, INDEX Decomposetheduplicateof A.
result = LUMPROVE(A, alud, INDEX, B, X)
Computean improved solution.
PRINT, result Print it.
IDL prints:
1.00000 2.00000 -1.00000
This is the exact solution vector.
See Also
GS_ITER, LUDC
IDL Reference Guide LUSOL
LUSOL
TheLUSOL function isused in conjunction with theLUDCprocedureto solveaset of n
linear equationsinnunknownsAx=b. Theparameter Aisinput not astheoriginal array,
but as its LU decomposition, created by the routine LUDC. The result is an n-element
vector whose type is identical to A.
LUSOL is based on the routinelubksb described in section 2.3 of Numerical Recipes in
Calling Sequence
Result = LUSOL(A, Index, B)
Arguments
A
Then by n LU decomposition of an array created by the LUDC procedure.
Index
An input vector, created by the LUDC procedure, containing a record of the row
permutations which occurred as a result of partial pivoting.
B
An n-element vector containing the right-hand side of the linear system
Ax = b.
Keywords
COLUMN
DOUBLE
Example
To solve the linear systemAx = b using LU decomposition and back substitution:
A = [[ 2.0, 1.0, 1.0], $ Definearray A.
[ 4.0, -6.0, 0.0], $
[-2.0, 7.0, 2.0]]
LUSOL IDL Reference Guide
B = [3.0, -8.0, 10.0] Defineright-hand sidevector B.
LUDC, A, INDEX DecomposeA.
result = LUSOL(A, INDEX, B) Computethesolution usingback
substitution.
IDL prints:
1.00000 2.00000 -1.00000
This is the exact solution vector.
See Also
CHOLSOL, CRAMER, GS_ITER, LU_COMPLEX, LUDC, SVSOL, TRISOL
IDL Reference Guide M_CORRELATE
M_CORRELATE
The M_CORRELATE function computes the multiple correlation coefcient of a
dependent variable and two or more independent variables.
m_correlate.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = M_CORRELATE(X, Y)
Arguments
X
An integer, single-, or double-precision oating-point array of m-columns and n-rows
that species the independent variable data. The columns of this two dimensional array
correspond to then-element vectors of independent variable data.
Y
dependent variable data.
Example
Dene the independent (X) and dependent (Y) data.
X = [[0.477121, 2.0, 13.0], $
[0.477121, 5.0, 6.0], $
[0.301030, 5.0, 9.0], $
[0.000000, 7.0, 5.5], $
[0.602060, 3.0, 7.0], $
[0.698970, 2.0, 9.5], $
[0.301030, 2.0, 17.0], $
[0.477121, 5.0, 12.5], $
[0.698970, 2.0, 13.5], $
[0.000000, 3.0, 12.5], $
[0.602060, 4.0, 13.0], $
[0.301030, 6.0, 7.5], $
[0.301030, 2.0, 7.5], $
M_CORRELATE IDL Reference Guide
[0.698970, 3.0, 12.0], $
[0.000000, 4.0, 14.0], $
[0.698970, 6.0, 11.5], $
[0.301030, 2.0, 15.0], $
[0.602060, 6.0, 8.5], $
[0.477121, 7.0, 14.5], $
[0.000000, 5.0, 9.5]]
Y = [97.682, 98.424, 101.435, 102.266, 97.067, 97.397, $
99.481, 99.613, 96.901, 100.152, 98.797, 100.796, $
98.750, 97.991, 100.007, 98.615, 100.225, 98.388, $
98.937, 100.617]
Compute the multiple correlation of Y on the rst column of X. The result should be
0.798816.
PRINT, M_CORRELATE(X[0,*], Y)
IDL prints:
0.798816
Compute the multiple correlation of Y on the rst two columns of X. The result should
be 0.875872.
PRINT, M_CORRELATE(X[0:1,*], Y)
IDL prints:
0.875872
Compute the multiple correlation of Y on all columns of X. The result should be
0.877197.
PRINT, M_CORRELATE(X, Y)
IDL prints:
0.877197
See Also
A_CORRELATE, CORRELATE, C_CORRELATE, P_CORRELATE, R_CORRELATE
IDL Reference Guide MACHAR
MACHAR
The MACHAR function determines and returns machine-specic parameters affecting
oating-point arithmetic. Information is returned in the form of a structure with the
following elds:
MACHARisbasedon theroutinemachar describedin section 20.1of Numerical Recipes
University Press, and is used by permission. See that section for more details on and
sample values of the various parameters returned.
Field Name Description
IBETA The radix in which numbers are represented. A longword integer.
IT The number of base-IBETA digits in the oating-point mantissa
M. A longword integer.
IRND A code in the range 0 5 giving information on what type of
roundingisdoneand howunderowishandled. Alongword inte-
ger.
NGRD The number of guard digits used when truncating the product
of two mantissas. A longword integer.
MACHEP The exponent of the smallest power of IBETA that, added to 1.0,
gives something different from 1.0. A longword integer.
NEGEP The exponent of the smallest power of IBETA that, subtracted
from 1.0, gives something different from 1.0. A longword integer.
IEXP The number of bits in the exponent. A longword integer.
MINEXP The smallest value of IBETA consistent with there being no lead-
ing zeros in the mantissa. A longword integer.
MAXEXP The smallest positive value of IBETA that causes overow. A long-
word integer.
EPS The oating-point number IBETA
MACHEP
, loosely referred to as
the oating-point precision.
EPSNEG Theoating-point number IBETA
NEGEP
, which isanother way of
determining oating-point precision.
XMIN The oating-point number IBETA
MINEXP
, generally the smallest
usable oating-point value.
XMAX The largest usable oating-point value, dened as the number (1-
EPSNEG)xIBETA
MAXEXP
MACHAR IDL Reference Guide
Calling Sequence
Result = MACHAR()
Keywords
DOUBLE
The information returned is normally for single-precision oating-point arithmetic.
Specify DOUBLE to see double-precision information.
See Also
CHECK_MATH, !VALUES on page 38 of theIDL ReferenceGuide, and Special
Floating-Point Values on page 152 of Building IDL Applications.
IDL Reference Guide MAKE_ARRAY
MAKE_ARRAY
The MAKE_ARRAY function returns an array of the specied type, dimensions, and
initialization. This function enables you to dynamically create an array whose
characteristics are not known until run time.
Calling Sequence
Result = MAKE_ARRAY([D
1
, ..., D
n
])
Arguments
D
i
Keywords
BYTE
Set this keyword to create a byte array.
COMPLEX
Set this keyword to create a complex, single-precision, oating-point array.
DCOMPLEX
Set this keyword to create a complex, double-precision, oating-point array.
DIMENSION
A vector of 1 to 8 elements specifying the dimensions of the result.
DOUBLE
Set this keyword to create a double-precision, oating-point array.
FLOAT
Set this keyword to create a single-precision, oating-point array.
L64
Set this keyword to create a 64-bit integer array.
INDEX
Set this keyword to initialize the array with each element set to the value of its one-
dimensional subscript.
INT
Set this keyword to create an integer array.
MAKE_ARRAY IDL Reference Guide
LONG
Set this keyword to create a longword integer array.
NOZERO
Set this keyword to prevent the initialization of the array. Normally, each element of the
resulting array is set to zero.
OBJ
Set this keyword to create an object reference array.
PTR
Set this keyword to create a pointer array.
SIZE
Asizevector specifyingthetypeand dimensionsof theresult. Theformat of asizevector
is given in the description of the SIZE function.
STRING
Set this keyword to create a string array.
TYPE
list of IDL type codes.
UINT
Set this keyword to create an unsigned integer array.
UL64
Set this keyword to create an unsigned 64-bit integer array.
ULONG
Set this keyword to create an unsigned longword integer array.
VALUE
The value to initialize each element of the resulting array. VALUE can be a scalar of any
type including structure types. The result type is taken from VALUE unless one of the
other keywordsthat specifyatypeisalsoset. In that case, VALUEisconverted tothetype
specied by the other keyword prior to initializing the resulting array.
Example
TocreateM, a3-element by4-element, integer arraywith each element set tothevalue5,
enter:
M = MAKE_ARRAY(3, 4, /INTEGER, VALUE = 5)
IDL Reference Guide MAKE_ARRAY
See Also
LON64ARR, LONARR, STRARR, UINTARR, ULON64ARR, ULONARR
MAP_CONTINENTS IDL Reference Guide
MAP_CONTINENTS
The MAP_CONTINENTS procedure draws continental boundaries, lled continents,
political boundaries, coastlines, and/or rivers, over anexistingmapprojectionestablished
by MAP_SET. Outlines can be drawn in low or high-resolution (if the optional high-
resolution CIA World Map database is installed). If MAP_CONTINENTS is called
without any keywords, it draws low-resolution, unlled continent outlines.
MAP_SET must be called before MAP_CONTINENTS to establish the projection type,
the center of the projection, polar rotation and geographic limits.
Calling Sequence
MAP_CONTINENTS
Keywords
COASTS
Set this keyword to draw coastlines, islands, and lakes instead of the default continent
outlines. Note that if you are using the low-resolution map database (if the HIRES
keywordisnotset), manyislandsaredrawnevenwhenCOASTSisnot set. If youareusing
the high-resolution map database (if the HIRES keyword isset), no islands are drawn
unless COASTS is set.
COLOR
The color index of the lines being drawn.
COUNTRIES
Set this keyword to draw political boundaries as of 1993.
FILL_CONTINENTS
Set thiskeywordto1toll continent boundarieswithasolidcolor. Thecolor isset bythe
COLOR keyword. Set this keyword to 2 to ll continent boundaries with a line ll. For
linelling, theCOLOR, MLINESTYLE, MLINETHICK, ORIENTATION, andSPACING
keywords can be used to control the type of line ll.
HIRES
Set this keyword to use high-resolution map data instead of the default low-resolution
data. Thisoption isonly availableif you haveinstalled theoptional high-resolution map
datasets. If the high-resolution data is not available, a warning is printed and the low-
resolution data is used instead.
This keyword can be used in conjunction with the COASTS, COUNTRIES,
FILL_CONTINENTS, and RIVERS keywords.
IDL Reference Guide MAP_CONTINENTS
MLINESTYLE
Thelinestyleof theboundariesbeingdrawn. Thedefault issolidlines. Validlinestylesare
shown in the table below:
MLINETHICK
The thickness of the boundary or ll lines. The default thickness is 1.
ORIENTATION
Set thiskeywordtothecounterclockwiseangleindegreesfromhorizontal that thelinell
should be drawn. The default is 0. This keyword only has effect if the
FILL_CONTINENTS keyword is set to 2.
RIVERS
Set this keyword to draw rivers.
SPACING
Set thiskeywordtothespacing, in centimeters, for alinell. Thiskeywordonlyhaseffect
if the FILL_CONTINENTS keyword is set to 2. The default is 0.5 centimeters.
USA
Set this keyword to draw borders for each state in the United States in addition to
continental boundaries.
Example
The following example demonstrates the use of the map outlines to embellish a map
projection:
tek_color Load discretecolor table.
black=0 & white=1 & red=2
green=3 & dk_blue=4 & lt_blue=5 Match color indices to colors we
want to use.
Index Linestyle
0 Solid
1 Dotted
2 Dashed
3 Dash Dot
4 Dash Dot Dot Dot
5 Long Dashes
MAP_CONTINENTS IDL Reference Guide
MAP_SET, /ORTHO, 40, -30, 23, /ISOTROPIC, $
Setupanorthographicprojection
centered over thenorth Atlantic.
/HORIZON, E_HORIZON={FILL:1, COLOR:dk_blue}, $
Fill thehemispherewith dark
blue.
/GRID, COLOR=black Specify black gridlines
MAP_CONTINENTS, /FILL_CONTINENTS, COLOR=white
Fill thecontinentboundarieswith
solid white.
MAP_CONTINENTS, /COASTS, COLOR=black Overplot coastlinedata.
MAP_CONTINENTS, /RIVERS, COLOR=lt_blue Add rivers, in light blue.
MAP_CONTINENTS, /COUNTRIES, COLOR=red, MLINETHICK=2
Show national borders.
See Also
MAP_GRID, MAP_IMAGE, MAP_PATCH, MAP_SET
IDL Reference Guide MAP_GRID
MAP_GRID
The MAP_GRID procedure draws the graticule of parallels and meridians, according to
the specications established by MAP_SET. MAP_SET must be called before
MAP_GRID to establish theprojection type, thecenter of theprojection, polar rotation
and geographical limits.
Calling Sequence
MAP_GRID
Keywords
BOX_AXES
Set this keyword to create box-style axes for map plots where the parallels intersect the
sides, and the meridians intersect the bottom and top edges of the box.
CHARSIZE
The size of the characters used for the labels. The default is 1.
CLIP_TEXT
Set this keyword to a zero value to turn off clipping of text labels.
COLOR
The color index for the grid lines.
GLINESTYLE
If set, thelinestyleused to drawthegrid of parallelsand meridians. SeeTable7-1, IDL
Linestyles, on page103for alist of availablelinestyles. Thedefault index is1, drawinga
dotted line.
GLINETHICK
The thickness of the grid lines. Default is 1.
LABEL
Set this keyword to label the parallels and meridians with their corresponding latitudes
and longitudes. Settingthiskeyword to an integer will causeevery LABEL gridlineto be
labeled (that is, if LABEL=3then every third gridlinewill belabeled). Thestartingpoint
for determining which gridlines are labeled is the minimum latitude or longitude (-180
to180), unlesstheLATSor LONSkeywordisset toasinglevalue. In thiscase, thestarting
point is the value of LATS or LONS.
LATALIGN
Thiskeyword controlsthealignment of thetext baselinefor latitudelabels. Avalueof 0.0
left justies the label, 1.0 right justies it, and 0.5 centers it.
MAP_GRID IDL Reference Guide
LATDEL
Set thiskeywordequal tothespacing(indegrees) betweenparallelsof latitudeinthegrid.
If thiskeyword isnot set, asuitablevalueisdetermined fromthecurrent map projection.
LATLAB
Thelongitudeat which to placelatitudelabels. Thedefault isthecenter longitudeon the
map.
LATNAMES
Set thiskeyword equal to an array specifyingthenamesto beused for thelatitudelabels.
By default, this array is automatically generated in units of degrees. The LATNAMES
array can be either type string or any single numeric type, but should not be of mixed
type.
When LATNAMESisspecied, theLATSkeywordmust alsobespecied. Thenumber of
elements in the two arrays need not be equal. If there are more elements in the
LATNAMESarray than in theLATSarray, theextraLATNAMESareignored. If thereare
moreelementsin theLATSarray than in theLATNAMESarray, labelsin degreeswill be
automatically provided for the missing latitude labels.
TheLATNAMESkeywordcanbealsousedwhentheLATSkeywordisset toasinglevalue.
It thiscase, therst label suppliedwill beusedat thespeciedlatitude; subsequent names
will be placed at the next latitude line to the north, wrapping around the globe if
appropriate. Caution should be used when using LATNAMES in conjunction with a
single LATS value, since the number of visible latitude gridlines is dependent on many
factors.
LATS
Set thiskeywordequal toaoneor moreelement vector of latitudesfor which lineswill be
drawn (and optionally labeled). If LATS is omitted, appropriate latitudes will be
generatedbasedon thevalueof the(optional) LATDELkeyword. If LATSisset toasingle
value, that latitude and a series of automatically generated latitudes will be drawn (and
optionally labeled). Automatically generated latitudes have the values:
[...,LATS-LATDEL,LATS,LATS+LATDEL,...]
over theextent of themap. If LATSisasinglevalue, that valueistaken to bethestarting
point for labelling (See the LABEL keyword).
LONALIGN
This keyword controls the alignment of the text baseline for longitude labels. A value of
0.0 left justies the label, 1.0 right justies it, and 0.5 centers it.
LONDEL
Set thiskeyword equal to thespacing(in degrees) between meridiansof longitudein the
grid. If this keyword is not set, a suitable value is determined from the current map
projection.
IDL Reference Guide MAP_GRID
LONLAB
The latitude at which to place longitude labels. The default is the center latitude on the
map.
LONNAMES
Set thiskeywordequal toanarrayspecifyingthenamestobeusedfor thelongitudelabels.
By default, this array is automatically generated in units of degrees. The LONNAMES
array can be either type string or any single numeric type, but should not be of mixed
type.
When LONNAMESisspecied, theLONSkeyword must also bespecied. Thenumber
of elements in the two arrays need not be equal. If there are more elements in the
LONNAMES array than in the LONS array, the extra LONNAMES are ignored. If there
aremoreelementsintheLONSarraythanintheLONNAMESarray, labelsindegreeswill
be automatically provided for the missing longitude labels.
The LONNAMES keyword can be also used when the LONS keyword is set to a single
value. It this case, the rst label supplied will be used at the specied longitude;
subsequent nameswill beplaced at thenext longitudelineto theeast, wrappingaround
theglobeif appropriate. CautionshouldbeusedwhenusingLONNAMESinconjunction
withasingleLONSvalue, sincethenumber of visiblelongitudegridlinesisdependent on
many factors.
LONS
Set thiskeyword equal to aoneor moreelement vector of longitudesfor which lineswill
be drawn (and optionally labeled). If LONS is omitted, appropriate longitudes will be
generated based on the value of the (optional) LONDEL keyword. If LONS is set to a
single value, that longitudes and a series of automatically generated longitudes will be
drawn (and optionally labeled). Automatically generated longitudes have the values:
[...,LONS-LONDEL,LONS,LONS+LONDEL,...]
over theextent of themap. If LONSisasinglevalue, that valueistaken to bethestarting
point for labelling (See the LABEL keyword).
ORIENTATION
Set thiskeywordequal toan anglein degreesfromhorizontal (in theclockwisedirection)
to rotate the labels.
Example
The following example creates an orthographic projection, denes which latitudes to
label, and provides text labels. Note that the text labels are rotated to match the
orientation of the map projection.
MAP_SET, /ORTHO, 10, 20, 30, /ISOTROPIC, /CONTINENTS, /HORIZON
Setupanorthographicprojection.
lats = [ -80, -45, -30, -20, 0, 15, 27, 35, 45, 55, 75]
Definelatitudes of interest.
MAP_GRID IDL Reference Guide
latnames = strtrim(lats, 2) Createstringequivalentsoflatitudes.
latnames(where(lats eq 0)) = Equator Label theequator.
MAP_GRID, LABEL=2, LATS=lats, LATNAMES=latnames, LATLAB=7, $
LONLAB=-2.5, LONDEL=20, LONS=-15, ORIENTATION=-30
Draw thegrid.
See Also
MAP_CONTINENTS, MAP_IMAGE, MAP_PATCH, MAP_SET
IDL Reference Guide MAP_IMAGE
MAP_IMAGE
TheMAP_IMAGEfunction returnsan image(or other dataset) warpedtot thecurrent
map projection. Thisfunction providesan easy method for displayinggeographical data
as an image on a map. The MAP_SET procedure should be called prior to calling
MAP_IMAGE.
MAP_IMAGE works in image (graphic) space. For each destination pixel (when
COMPRESSisset toone) MAP_IMAGEcalculatesthelatitudeandlongitudebyapplying
the inverse map projection. This latitude and longitude are then used to index and
interpolatetheImageargument, obtaininganinterpolatedvaluefor thedestinationpixel.
The time required by MAP_IMAGE depends mainly on the number of pixels in the
destination and the setting of the COMPRESS parameter.
MAP_IMAGE is more efcient than MAP_PATCH when the input data set is large
compared tothedestination area. If theconverseistrue, MAP_PATCH ismoreefcient.
For more information, see Image Display on page 381 of Using IDL.
Calling Sequence
Result = MAP_IMAGE(Image[, Startx, Starty [, Xsize, Ysize]])
Arguments
Image
A two-dimensional array containing the image to be overlaid on the map.
Startx
A named variable that, upon return, contains the X coordinate position where the left
edge of the image should be placed on the screen.
Starty
A named variable that, upon return, contains the Y coordinate position where the left
edge of the image should be placed on the screen.
Xsize
Anamedvariablethat, upon return, containsthewidthof theimageexpressedin graphic
coordinateunits. If thecurrent graphicsdeviceusesscalablepixels, thevaluesof Xsizeand
Ysizeshould be passed to the TV procedure.
Ysize
Anamedvariablethat, uponreturn, containstheheight of theimageexpressedingraphic
coordinateunits. If thecurrent graphicsdeviceusesscalablepixels, thevaluesof Xsizeand
Ysizeshould be passed to the TV procedure.
MAP_IMAGE IDL Reference Guide
Keywords
LATMIN
Thelatitudecorrespondingtotherst rowof Image. Thedefault is-90degrees. Notealso
that -90 LATMIN < LATMAX 90.
LATMAX
Thelatitudecorrespondingtothelast rowof Image. Thedefault valueis90degrees. Note
also that -90 LATMIN < LATMAX 90.
LONMIN
Thelongitudecorrespondingtotherst (leftmost) columnof theImageargument. Select
LONMIN so that -180 LONMIN 180. The default value is -180.
LONMAX
The longitude corresponding to the last (rightmost) column of theImageargument.
Select LONMAX so that it islarger than LONMIN. If thelongitudeof thelast column is
equal to (LONMIN - (360. /Nx)) MODULO 360, it is assumed that the image covers all
longitudes (Nx being the total number of columns in theImageargument).
BILINEAR
Set thisagtousebilinear interpolation tosoften edgesin thereturnedimage, otherwise,
nearest neighbor sampling is used.
COMPRESS
This keyword, the interpolation compression ag, controls the accuracy of the results
fromMAP_IMAGE. Thedefault is4for output deviceswith xedpixel sizes. Theinverse
projection transformation isappliedtoeach ith rowandcolumn. Settingthiskeywordto
ahigher number savestimewhilelower numbersproducemoreaccurateresults. Setting
this keyword to 1 solves the inverse map transformation for every pixel of the output
image.
SCALE
Set this keyword to the pixel/graphics scale factor for devices with scalable pixels (e.g.,
PostScript). The default is 0.02 pixels/graphic coordinate. This setting yields an
approximateoutput imagesizeof 350x250. Makethisnumber larger for moreresolution
(and larger PostScript les and images), or smaller for faster, smaller, and less accurate
images.
MAX_VALUE
Datapointswith valuesequal toor greater than thisvaluewill betreated asmissingdata,
and will be set to the value specied by the MISSING keyword.
MIN_VALUE
Datapointswithvaluesequal toor lessthan thisvaluewill betreatedasmissingdata, and
will be set to the value specied by the MISSING keyword.
IDL Reference Guide MAP_IMAGE
MISSING
Thepixel valueto set areasoutsidethevalid map coordinates. If thiskeyword isomitted,
areas outside the map are set to 255 (white) if the current graphics device is PostScript,
otherwise they are set to 0.
Example
The following lines of code set up an orthographic map projection and warp a simple
image to it.
image = BYTSCL(SIN(DIST(400)/10)) Createa simpleimageto be
warped.
TV, image Display theimageso wecan see
what it looks likebeforewarping.
latmin = -65
latmax = 65
lonmin = 160 Left edgeis 160 East
lonmax = -70 + 360 Right edgeis 70 West =+360.
MAP_SET, 0, -140, /ORTHOGRAPHIC, /ISOTROPIC, $
LIMIT=[latmin, lonmin, latmax, lonmax]
result = MAP_IMAGE(image,Startx,Starty, COMPRESS=1, $
LATMIN=latmin, LONMIN=lonmin, $
LATMAX=latmax, LONMAX=lonmax)
TV, result, Startx, Starty Display thewarped imageon the
map at theproper position.
MAP_GRID, latdel=10, londel=10, /LABEL, /HORIZON
Draw continent outlines.
MAP_CONTINENTS, /coasts Draw gridlines over themap and
image.
See Also
MAP_CONTINENTS, MAP_GRID, MAP_PATCH, MAP_SET
MAP_PATCH IDL Reference Guide
MAP_PATCH
TheMAP_PATCH function returnsan image(or other dataset) warped tot thecurrent
map projection. Mapping coordinates should be setup via a call to MAP_SET before
using MAP_PATCH.
MAP_PATCH worksin object (data) space. It dividestheinput dataset, Image_Orig, into
triangular patches, either directly fromtheimplicit rectangular grid, or by triangulating
thedatapointson thesurfaceof thesphereusingtheTRIANGULATEprocedure. These
triangular patches are then projected to the map plane in the image space of the
destination array and then interpolated. The time required by MAP_PATCH depends
mainly on the number of elements in the input array.
MAP_PATCH is more efcient than MAP_IMAGE when the destination area is large
compared to the input data set. If the converse is true, MAP_IMAGE is more efcient.
map_patch.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = MAP_PATCH(Image_Orig [, Lons, Lats])
Arguments
Image_Orig
Aone- or two-dimensional array that containsthedatato beoverlaid on themap. If the
TRIANGULATEkeyword isnot set, Image_Origmust beatwo-dimensional array. Rows
and columns must be arranged in increasing longitude and latitude order. Also, the
corner points of each cell must be contiguous. This means that the seam of a map must
lie on a cell boundary, not in its interior, splitting the cell.
Lons
An optional vector that contains the longitude value for each column in Image_Orig. If
Lonsis a one-dimensional vector, longitude(Image_Orig[ i,j] ) = Lons[ i] ; if Lonsis a two-
dimensional vector, longitude(Image_Orig[ i,j] ) = Lons[ i,j] .
Thisargument can beomittedif thelongitudesareequally-spacedandthebeginningand
ending longitudes are specied with the LON0 and LON1 keywords.
Lats
An optional vector that containsthelatitudevaluefor each rowin Image_Orig. If Latsis
a one-dimensional vector, latitude(Image_Orig[ i,j] ) = Lats[ i] ; if Latsis a two-
dimensional vector, latitude(Image_Orig[ i,j] ) = Lats[ i,j] .
This argument can be omitted if the latitudes are equally-spaced and the beginning and
ending latitudes are specied with the LAT0 and LAT1 keywords.
IDL Reference Guide MAP_PATCH
Keywords
LAT0
The latitude of the rst row of data. The default is -90.
LAT1
The latitude of the last row of data. The default is +90.
LON0
The longitude of the rst column of data. The default is -180.
LON1
The longitude of the last column of data. The default is 180 - (360/Number-of-Rows)
MISSING
Set thiskeywordtoavaluetobeusedfor areasoutsidethevalidmapcoordinates(i.e., the
background color ). If the current plotting device is PostScript, the default is 255
(white). Otherwise, the default is 0 (usually black).
MAX_VALUE
The largest data value to be warped. Values in Image_Origgreater than this value are
considered missing. Pixels in the output image that correspond to these missing values
are set to the value specied by the MISSING keyword.
TRIANGULATE
Set this keyword to convert the input data to device space and triangulate them. This
keyword must be specied if the connectivity of the data points is not rectangular and
monotonic in device space.
XSIZE
Set thiskeyword toanamed variablein which thewidth of theoutput imageisreturned,
in graphic coordinate units. If the current graphics device has scalable pixels (e.g.,
PostScript), the values returned by XSIZE and YSIZE should be passed to the TV
procedure.
XSTART
Set thiskeyword toanamed variablein which theXcoordinatewheretheleft edgeof the
image should be placed on the screen is returned.
YSIZE
Set thiskeywordtoanamedvariablein which theheight of theoutput imageisreturned,
in graphic coordinate units. If the current graphics device has scalable pixels (e.g.,
PostScript), the values returned by XSIZE and YSIZE should be passed to the TV
procedure.
YSTART
Set thiskeywordtoanamedvariablein whichtheYcoordinatewherethebottomedgeof
the image should be placed on the screen is returned.
MAP_PATCH IDL Reference Guide
Example
n = 24 Forma24x24datasetonasphere.
lat = replicate(180./(n-1),n) # findgen(n) - 90
Specify equally gridded latitudes.
lon = findgen(n) # replicate(360./(n-1), n)
Specify equally gridded longi-
tudes.
x = cos(lon * !dtor) * cos(lat * !dtor)
y = sin(lon * !dtor) * cos(lat * !dtor)
z = sin(lat * !dtor) Convert to Cartesian coordinates.
f = BYTSCL((x-1)^2 + (y-1)^2 + z^2) Set interpolation function to
scaled distancesquared from
(1,1,0).
MAP_SET, 90, 0, /STEREO, /ISOTROPIC, /HORIZ
Set up projection.
TV, MAP_PATCH(f, XSTART=x0, YSTART=y0), x0, y0
Grid and display thedata.
MAP_GRID Draw gridlines over themap and
image.
MAP_CONTINENTS Draw continent outlines.
MAP_HORIZON Draw a horizon line.
See Also
MAP_CONTINENTS, MAP_GRID, MAP_IMAGE, MAP_SET
IDL Reference Guide MAP_PROJ_INFO
MAP_PROJ_INFO
The MAP_PROJ_INFO routine returns information about the current map and/or the
availableprojection. Mappingparametersshould besetup viaacall to MAP_SET before
using MAP_PROJ_INFO.
Calling Sequence
Result = MAP_PROJ_INFO[, iproj]
Arguments
Iproj
Theprojection index. If theCURRENT keywordisset, then theindex of thecurrent map
projection is returned in Iproj.
Keywords
AZIMUTHAL
Set thiskeyword if theprojection isazimuthal. If theprojection isnot azimuthal, set this
keyword to zero (the default).
CIRCULAR
Set this keyword for a circular or elliptical projection.
CURRENT
Set this keyword to use the current projection index and return that index in Iproj.
CYLINDRICAL
Set this keyword for a cylindrical or pseudo-cylindrical projection.
LL_LIMITS
The geocoordinate rectangle of the current map in degrees (Lonmin, Latmin, Lonmax,
Latmax). Thisrangemaynot alwaysbeavailable, especiallyif theLIMITkeywordwasnot
specied in the call to MAP_SET. If either or both the longitude and latitude range are
not available, the minimum and maximum values will be set to zero.
NAME
Set this keyword to the name of the projection.
PROJ_NAMES
Set this keyword to a string array containing the names of the available projections,
ordered by their indices. The rst projection name is stored in element one.
MAP_PROJ_INFO IDL Reference Guide
UVRANGE
TheUVcoordinatelimitsof theselectedmapprojection (umin, vmin, umax, vmax). UV
coordinates are mapped to normalized coordinates using the system variables !X.S and
!Y.S. These limits are dependent upon the selected projection, but independent of the
current map.
UV_LIMITS
The UV bounding box of the current map (Umin, Vmin, Umax, Vmax).
See Also
MAP_SET
IDL Reference Guide MAP_SET
MAP_SET
TheMAP_SETprocedureestablishestheaxistypeandcoordinateconversionmechanism
for mapping points on the earths surface, expressed in latitude and longitude, to points
on a plane, according to one of several possible map projections.
The type of map projection, the map center, polar rotation and geographical limits can
all be customized. The system variable !MAP1 retains the information needed to effect
coordinateconversionstotheplaneand, inversely, fromtheprojection planetopointson
the earth in latitude and longitude. Users should not change the values of the elds in
!MAP directly.
MAP_SET can also be made to plot the grid of latitude and longitude lines and
continental boundaries by setting the keywords GRID and CONTINENTS. Many other
types of boundaries can be overplotted on maps using the MAP_CONTINENTS
procedure.
Note If thethegraphicsdeviceischanged, MAP_SET (and all other mappingcalls) must
be re-called for the projection to be set up properly for the new device.
Calling Sequence
MAP_SET [, P
0lat
, P
0lon
, Rot]
Arguments
P
0lat
The latitude of the point on the earths surface to be mapped to the center of the
projection plane. Latitudeismeasured in degreesNorth of theequator and P
0lat
must be
in the range: -90 P
0lat
90.
If P
0lat
is not set, the default value is 0.
P
0lon
The longitude of the point on the earths surface to be mapped to the center of the map
projection. Longitudeismeasured in degreeseast of theGreenwich meridian and P0lon
must be in the range: -180 P
0lon
180.
If P
0lon
is not set, the default value is zero.
Rot
Rot is the angle through which the North direction should be rotated around the lineL
between theearthscenter andthepoint (P
0lat
, P
0lon
). Rotismeasuredin degreeswiththe
positivedirection beingclockwiserotation around lineL. Rotcan havevaluesfrom-180
to 180.
MAP_SET IDL Reference Guide
If thecenter of themap isat theNorth pole, North isin thedirection P
0lon
+ 180. If the
origin is at the South pole, North is in the direction P
0lon
.
The default value of Rot is 0 degrees.
KeywordsProjection Types
AITOFF
Set this keyword to select the Aitoff projection.
ALBERS
Set this keyword to select the Albers equal-area conic projection. To specify the latitude
of the standard parallels, see STANDARD_PARALLELS on page 730.
AZIMUTHAL
Set this keyword to select the azimuthal equidistant projection.
CONIC
Set thiskeywordtoselect Lambertsconformal conicprojection withoneor twostandard
parallels. Tospecifythelatitudeof thestandardparallels, seeSTANDARD_PARALLELS
on page 730. This keyword can be used with the ELLIPSOID keyword.
CYLINDRICAL
Set thiskeyword toselect thecylindrical equidistant projection. Cylindrical isthedefault
map projection.
GOODESHOMOLOSINE
Set this keyword to select the Goodes Homolosine Projection. The central latitude for
thisprojection isxed on theequator, 0degreeslatitude. Thisprojection isinterrupted,
astheinventor originally intended, and isbest viewed with thecentral longitudeset to0.
GNOMIC
Set this keyword to select the gnomonic projection. If default clipping is enabled, this
projection will display amaximumof t 60 fromthecenter of theprojection areawhen
the center is at either the equator or one of the poles.
HAMMER
Set this keyword to select the Hammer-Aitoff equal area projection.
LAMBERT
Set this keyword to select Lamberts azimuthal equal area projection.
MERCATOR
Set this keyword to select the Mercator projection. Note that this projection will not
display regions within t 10 of the poles of projection.
MILLER
Set this keyword to select the Miller Cylindrical projection.
MOLLWEIDE
Set this keyword to select the Mollweide projection.
ORTHOGRAPHIC
Set this keyword to select the orthographic projection. Note that this projection will
display a maximum of t 90 from the center of the projection area.
ROBINSON
Set this keyword to select the Robinson pseudo-cylindrical projection.
SATELLITE
Set this keyword to select the satellite projection.
For thesatelliteprojection, P0LATandP0LONrepresent thelatitudeandlongitudeof the
sub-satellite point. Three additional parameters, P, Omega, and Gamma (supplied as a
three-element vector argument to the SAT_P keyword), are also required.
Note Since all meridians and parallels are oblique lines or arcs, the LIMIT keyword must
be supplied as an eight-element vector representing four points that delineate the
limitsof themap. Theextent of themaplimits, when expressedin latitude/longitude
is a complicated polygon, rather than a simple quadrilateral.
SINUSOIDAL
Set this keyword to select the sinusoidal projection.
STEREOGRAPHIC
Set this keyword to select the stereographic projection. Note that if default clipping is
enabled, thisprojectionwill displayamaximumof t 90 fromthecenter of theprojection
area.
TRANSVERSE_MERCATOR
Set this keyword to select the Transverse Mercator projection, also called the UTM or
Gauss-Krueger projection. This projection works well with the ellipsoid form. The
default ellipsoid is the Clarke 1866 ellipsoid. To change the default ellipsoid
characteristics, see ELLIPSOID on page 729.
KeywordsMap Characteristics
ADVANCE
Set this keyword to advance to the next frame when the screen is set to display multiple
plots. Otherwise the entire screen is erased.
CHARSIZE
The size of the characters used for the labels. The default is 1.
CLIP
Set this keyword to clip the map using the map-specic graphics technique. The default
is to perform map-specic clipping. Set CLIP=0 to disable clipping.
Note ClippingcontrolledbytheCLIPkeywordtoMAP_SETappliesonlytothemapitself.
In order todisablegeneral clippingwithin theplot window, you must set thesystem
variable!P.NOCLIP=1. For moreinformation, see NOCLIP on page51of theIDL
ReferenceGuide.
COLOR
The color index of the map border in the plotting window.
CONTINENTS
Set this keyword to plot the continental boundaries. Note that if you are using the low-
resolution map database (if the HIRES keyword isnot set), outlines for continents,
islands, and lakesaredrawn when theCONTINENTSkeyword isset. If you areusingthe
high-resolutionmapdatabase(if theHIRESkeywordisset), onlycontinental outlinesare
drawn when theCONTINENTSkeywordisset. Todrawislandsandlakeswhen usingthe
high-resolution map database, use the COASTS keyword to the MAP_CONTINENTS
procedure.
CON_COLOR
The color index for continent outlines if CONTINENTS is set.
E_CONTINENTS
Set this keyword to a structure containing extra keywords to be passed to
MAP_CONTINENTS. For example, to ll continents, the FILL keyword of
MAP_CONTINENTS is set to 1. To ll the continents with MAP_SET, specify
E_CONTINENTS={FILL:1}.
E_GRID
Set this keyword to a structure containing extra keywords to be passed to MAP_GRID.
For example, tolabel everyother gridlineon agridof parallelsandmeridians, theLABEL
keyword of MAP_GRID is set to 2. To do the same with MAP_SET, specify
E_GRID={LABEL:2}.
E_HORIZON
Set this keyword to a structure containing extra keywords to be set as modiers to the
HORIZON keyword.
Example To draw a Stereographic map, with the sphere lled in color index 3, enter:
MAP_SET, 0, 0, /STEREO, /HORIZON, /ISOTROPIC, $
E_HORIZON={FILL:1, COLOR:3}
GLINESTYLE
Set thiskeywordtoalinestyleindex used todrawthegridof parallelsandmeridians. See
Table9-53, IDL Linestyles, on page709for alist of availablelinestyles. Thedefault is1,
drawing a grid of dotted lines.
GLINETHICK
Set this keyword to the thickness of the gridlines drawn if the GRID keyword is set. The
default is 1.
GRID
Set this keyword to draw the grid of parallels and meridians.
HIRES
Set thiskeyword tousethehigh-resolution continent outlineswhen drawingcontinents.
This keyword only has effect if the CONTINENTS keyword is also set.
HORIZON
Set thiskeyword todrawahorizon line, when theprojection in usepermits. Thehorizon
delineates the boundary of the sphere. See E_HORIZON for more options.
LABEL
Set this keyword to label the parallels and meridians with their corresponding latitudes
and longitudes. Settingthiskeyword to an integer will causeevery LABEL gridlineto be
labeled (that is, if LABEL=3then every third gridlinewill belabeled). Thestartingpoint
for determining which gridlines are labeled is the minimum latitude or longitude (-180
to 180).
LATALIGN
Thealignment of thetext baselinefor latitudelabels. Avalueof 0.0left justiesthelabel,
1.0 right justies it, and 0.5 centers it.
LATLAB
Thelongitudeat whichtoplacelatitudelabels. Thedefault isthecenter longitudeof themap.
LATDEL
Set thiskeyword equal to thespacing(in degrees) between parallelsof latitudedrawn by
theMAP_GRIDprocedure. If thiskeywordisnot set, asuitablevalueisdeterminedfrom
the current map projection.
LONALIGN
The alignment of the text baseline for longitude labels. A value of 0.0 left justies the
label, 1.0 right justies it, and 0.5 centers it.
LONDEL
Set thiskeywordequal tothespacing(in degrees) between meridiansof longitudedrawn
by the MAP_GRID procedure. If this keyword is not set, a suitable value is determined
from the current map projection.
LONLAB
Thelatitudeat whichtoplacelongitudelabels. Thedefault isthecenter latitudeof themap.
MLINESTYLE
Thelinestyleindex used for continental boundaries. Linestylesaredescribed in thetable
below. The default is 0 for solid.
MLINETHICK
The line thickness used for continental boundaries. The default is 2.
NOBORDER
Set thiskeyword tonot drawaborder around themap. Themap will ll theextent of the
plotting region. If NOBORDER isnot specied, a margin equalling 1% of the plotting
region will be placed between the map and the border.
NOERASE
Set this keyword to have MAP_SET not erase the current plot window. The default is to
erase before drawing the map.
TITLE
A stringcontainingthemain titlefor themap. Thetitleappearscentered abovethemap
window.
USA
Set this keyword to draw borders for each state in the United States.
XMARGIN
A scalar or two-element vector that species the vertical margin between the map and
screen border in character units. If a scalar is specied, the same margin will be used on
both sides of the map.
YMARGIN
A scalar or two-element vector that species in the horizontal margin between the map
and screen border in character units. If ascalar isspecied, thesamemargin will beused
on the top and bottom of the map.
Index Linestyle
0 Solid
1 Dotted
2 Dashed
3 Dash Dot
4 Dash Dot Dot Dot
5 Long Dashes
KeywordsProjection Parameters
CENTRAL_AZIMUTH
Set this keyword to the angle of the central azimuth, in degrees east of North. This
keyword can be used with the following projections: Cylindrical, Mercator, Miller,
Mollweide, and Sinusoidal. The default is 0 degrees. The pole is placed at an azimuth of
CENTRAL_AZIMUTH degrees CCW of North, as specied by theRot argument.
ELLIPSOID
Set thiskeyword to a3-element array, [ a, e
2
, k
0
] , deningtheellipsoid for theTransverse
Mercator or Lambert Conic projections.
a: equatorial radius, in meters.
e
2
: eccentricity squared. e
2
= 2 * f - f
2
, where f = 1 - b/a (a: equatorial radius, b: polar
radius; in meters).
k
0
: scale on the central meridian.
The default is the Clarke 1866 ellipsoid, [ 6378206.4, 0.00676866, 0.9996] .
This keyword can be used with the CONIC keyword.
ISOTROPIC
Set this keyword to produce a map that has the same scale in the X and Y directions.
LIMIT
A four- or eight-element vector that species the limits of the map.
As a four-element vector, LIMIT has the form [Lat
min
, Lon
min
, Lat
max
, Lon
max
] that
species the boundaries of the region to be mapped. (Lat
min
, Lon
min
) and (Lat
max
,
Lon
max
) are the latitudes and longitudes of two points diagonal from each other on the
regions boundary.
Asan eight-element vector, LIMIT hastheform: [Lat
0
, Lon
0
, Lat
1
, Lon
1
, Lat
2
, Lon
2
, Lat
3
,
Lon
3
] . These four latitude/longitude pairs describe, respectively, four points on the left,
top, right, and bottom edges of the map extent.
ROBINSON
Set this keyword to select the Robinson pseudo-cylindrical projection.
SAT_P
Athree-element vector containingthreeparameters, P, Omega, andGamma,that must be
supplied when using the SATELLITE projection where:
P is the distance of the point of perspective (camera) from the center of the globe,
expressed in units of the radius of the globe.
Omegaisthedownward tilt of thecamera, in degreesfromthenewhorizontal. If both
Gamma and Omega are 0, a Vertical Perspective projection results.
Gammaistheangle, expressed in degreesclockwisefromnorth, of therotation of the
projection plane.
SCALE
Set this keyword to construct an isotropic map with the given scale, set to the
ratioof 1:scale. If SCALEisnot specied, themapist tothewindow. Thetypical
scale for global maps is in the ratio of between 1:100million and 1:200million.
For continents, thetypical scaleisin theratioof approximately1:50million. For
example, SCALE=100E6 sets the scale at the center of the map to 1:100million,
which is in the same ratio as 1 inch to 1578 miles (1 cm to 1000 km).
STANDARD_PARALLELS
Set this keyword to a one- or two-element array dening, respectively, one or two
standard parallels for conic projections.
SeeChapter 7, GraphicsKeywords , for descriptionsof graphicsand plottingkeywords
not listed above. POSITION T3D ZVALUE.
Examples
To draw a Stereographic map, with the sphere lled in color index 3:
MAP_SET, 0, 0, /STEREO, /HORIZON, /ISOTROPIC, E_HORIZON={FILL:1,
COLOR:3}
See Also
MAP_CONTINENTS, MAP_GRID, MAP_IMAGE
IDL Reference Guide MAX
MAX
TheMAXfunction returnsthevalueof thelargest element of Array. Thetypeof theresult
is the same as the type of Array.
Calling Sequence
Result = MAX(Array [, Max_Subscript])
Arguments
Array
The array to be searched.
Max_Subscript
A named variable that, if supplied, is converted to a long integer containing the one-
dimensional subscript of themaximumelement. Otherwise, thesystemvariable!Cisset
to the one-dimensional subscript of the maximum element.
Keywords
MIN
Anamed variableto receivethevalueof theminimumarray element. If you need to nd
both the minimum and maximum array values, use this keyword to avoid scanning the
array twice with separate calls to MAX and MIN.
NAN
Example
Create a simple two-dimensional array by entering:
D = DIST(100)
Print the maximum value in array D and its linear subscript by entering:
PRINT, MAX(D, I), I
IDL prints:
70.7107 5050
MAX IDL Reference Guide
To convert I to a two-dimensional subscript, use the commands:
IX = I MOD 100
IY = I/100
PRINT, IX, IY
The maximum value of D is at location (50, 50) in the original array.
See Also
MIN
IDL Reference Guide MD_TEST
MD_TEST
TheMD_TEST function teststhehypothesisthat asamplepopulation israndomagainst
the hypothesis that it is not random. The result is a two-element vector containing the
nearly-normal test statistic Z and its associated probability. This two-tailed is an
extension of theRunsTest for Randomness andisoften referredtoastheMedian Delta
Test.
md_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = MD_TEST(X)
Arguments
X
An n-element integer, single- or double-precision oating-point vector.
Keywords
ABOVE
Use this keyword to specify a named variable that will contain the number of sample
population values greater than the median of X.
BELOW
Use this keyword to specify a named variable that will contain the number of sample
population values less than the median of X.
MDC
Use this keyword to specify a named variable that will contain the number of Median
Delta Clusters (sequential values of X above and below the median).
Example
Dene a sample population.
X = [ 2.00, 0.90, -1.44, -0.88, -0.24, 0.83, -0.84, -0.74, $
0.99, -0.82, -0.59, -1.88, -1.96, 0.77, -1.89, -0.56, $
-0.62, -0.36, -1.01, -1.36]
Test thehypothesisthat Xrepresentsarandompopulation against thehypothesisthat it
does not represent a random population at the 0.05 signicance level.
MD_TEST IDL Reference Guide
result = MD_TEST(X, MDC = mdc)
PRINT, result
IDL prints:
0.459468 0.322949
therefore we do not reject the hypothesis that X represents a random population.
See Also
CTI_TEST, FV_TEST, KW_TEST, LNP_TEST,R_TEST, RS_TEST, S_TEST, TM_TEST,
XSQ_TEST
IDL Reference Guide MEAN
MEAN
The MEAN function computes the mean of a numeric vector. MEAN calls the IDL
function MOMENT.
Calling sequence
Result = MEAN(X)
Arguments
X
An n-element, integer, double-precision or oating-point vector.
Keywords
DOUBLE
If this keyword is set, computations are done in double precision arithmetic.
NAN
Example
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
Definethen-element vector of
sampledata.
result = MEAN(x) Computethestandard deviation.
IDL prints:
66.7333
See Also
KURTOSIS, MEANABSDEV, MOMENT, STDDEV, SKEWNESS, VARIANCE
MEANABSDEV IDL Reference Guide
MEANABSDEV
TheMEANABSDEVfunctioncomputesthemeanabsolutedeviation(averagedeviation)
of an n-element vector.
Calling sequence
Result = MEANABSDEV(X)
Arguments
X
Keywords
DOUBLE
Set thiskeyword to forcecomputationsto bedonein doubleprecision arithmeticand to
return a double precision result. If this keyword is not set, the computations and result
depend upon thetypeof theinput data(integer and oat datareturn oat results, while
double data returns double results). This has no effect if the MEDIAN keyword is set.
MEDIAN
Set thiskeywordtoreturntheaveragedeviationfromthemedian. Bydefault, if MEDIAN
is not set, MEANABSDEV will return the average deviation from the mean.
NAN
Example
x = [1, 1, 1, 2, 5] Definean n-element vector.
result = MEANABSDEV(x) Computeaveragedeviation from
themean.
IDL prints:
1.20000
IDL Reference Guide MEANABSDEV
See Also
KURTOSIS, MEAN, MOMENT, STDDEV, SKEWNESS, VARIANCE
MEDIAN IDL Reference Guide
MEDIAN
TheMEDIANfunction returnsthemedian value(element n/2) of Arrayif oneparameter
is present, or applies a one- or two-dimensional median lter of the specied width to
Array and returns the result. In an ordered set of values, the median is a value with an
equal number of valuesaboveand belowit. Median smoothingreplaceseach point with
the median of the one- or two-dimensional neighborhood of a given width. It is similar
to smoothing with a boxcar or average lter but does not blur edges larger than the
neighborhood.
In addition, median ltering is effective in removing salt and pepper noise, (isolated
high or low values). The scalar median is simply the middle value, which should not be
confused with the average value (e.g., the median of the array [ 1,10,4] is 4, while the
average is 5.)
Calling Sequence
Result = MEDIAN(Array [, Width])
Arguments
Array
Thearraytobeprocessed. If Widthisalsosupplied, and Arrayisof bytetype, theresult is
of byte type. All other types are converted to single-precision oating-point, and the
result is oating-point. Array can have only one or two dimensions.
If Width is not given, Array can have any valid number of dimensions. The array is
converted to single-precision oating-point, and the median value is returned as a
oating-point value.
Width
The size of the one or two-dimensional neighborhood to be used for the median lter.
The neighborhood has the same number of dimensions asArray.
Keywords
EVEN
If the EVEN keyword is set when Array contains an even number of points (i.e. there is
no middle number), MEDIAN returns the average of the two middle numbers. The
returned value may not be an element of Array. If Array contains an odd number of
points, MEDIANreturnsthemedian value. Thereturnedvaluewill alwaysbean element
of Arrayeven if the EVEN keyword is setsince an odd number of points will always
have a single middle value.
IDL Reference Guide MEDIAN
Example
Create a simple image and display it by entering:
D = SIN(DIST(200)^0.8) & TVSCL, D
Display D median-ltered with a width of 9 by entering:
TVSCL, MEDIAN(D, 9)
Print the median of a six-element array, with and without the EVEN keyword:
PRINT, MEDIAN([1, 2, 3, 4], /EVEN)
PRINT, MEDIAN([1, 2, 3, 4])
IDL prints:
2.50000
3.00000
See Also
DIGITAL_FILTER, LEEFILT, MOMENT, SMOOTH
MESH_OBJ IDL Reference Guide
MESH_OBJ
The MESH_OBJ procedure generates a polygon mesh (vertex list and polygon list) that
represent the desired primitive object. The available primitive objects are: triangulated
surface, rectangular surface, polar surface, cylindrical surface, spherical surface, surface
of extrusion, surface of revolution, and ruled surface.
mesh_obj.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MESH_OBJ, Type, Vertex_List, Polygon_List, Array1 [, Array2]
Arguments
Type
An integer which species what type of object to create. The various surface types are
described in the table below.
Vertex_List
Anamed variablethat will contain themesh vertices. Vertex_List hasthesameformat as
the lists returned by the SHADE_VOLUME procedure.
Type Surface Type
0 Triangulated
1 Rectangular
2 Polar
3 Cylindrical
4 Spherical
5 Extrusion
6 Revolution
7 Ruled
Other values None
Table 9.55 Surface Types
IDL Reference Guide MESH_OBJ
Polygon_List
Anamedvariablethat will contain themeshindexes. Polygon_Listhasthesameformat as
the lists returned by the SHADE_VOLUME procedure.
Array1
An array whose use depends on the type of object being created. The table below
describes the differences.
Surface
Type
Array1 Type
Triangulated A (3, n) array containing random [ x, y, z] points to build a triangulated surface
from. Theresultingpolygon mesh will havenvertices. When shadingatriangulated
mesh, the shading array should have (n) elements.
Rectangular A two dimensional (n, m) array containingz values. The resulting polygon mesh
will havenx mvertices. When shadingarectangular mesh, theshadingarray should
have (n, m) elements.
Polar A two dimensional (n, m) array containingz values. The resulting polygon mesh
will haven x mvertices. Then dimension of the array is mapped to the polar angle,
and themdimension is mapped to the polar radius. When shading a polar mesh,
the shading array should have (n, m) elements.
Cylindrical A two dimensional (n, m) array containing radius values. The resulting polygon
mesh will haven x mvertices. Then dimension of the array is mapped to the polar
angle, and the m dimension is mapped to the Z axis. When shading a cylindrical
mesh, the shading array should have (n, m) elements.
Spherical A two dimensional (n, m) array containing radius values. The resulting polygon
mesh will haven x mvertices. Then dimension of the array is mapped to the longi-
tude(0.0to 360.0degrees), and themdimension ismapped to thelatitude(-90.0to
+90.0 degrees). When shading a spherical mesh, the shading array should have (n,
m) elements.
Extrusion A (3, n) array of connected 3D pointswhich denetheshapeto extrude. Theresult-
ing polygon mesh will haven x (steps+1) vertices (where steps is the number of
segments in the extrusion). (See the P1 keyword). If the order of the elements in
Array1 is reversed, then the polygon facing is reversed. When shading an extrusion
mesh, the shading array should have (n, steps+1) elements.
Revolution A (3, n) array of connected 3D points which dene the shape to revolve. The result-
ingpolygon mesh will havenx ((steps>3)+1) vertices(wherestepsisthenumber of
steps in the revolution). (See the P1 keyword). If the order of the elements in
Array1 is reversed, then the polygon facing is reversed. When shading a revolution
mesh, the shading array should have (n, (steps>3)+1) elements.
Array2
If the object type is 7 (Ruled Surface) then Array2 is a (3, m) array containing the 3D
points which dene the second ruled vector. If Array2 has fewer elements than Array1
then Array2 is processed with CONGRID to give it the same number of elements as
Array1. If Array1 has fewer elements than Array2 then Array1 is processed with
CONGRID to giveit thesamenumber of elementsasArray2. Array2must besupplied if
the object type is 7. Otherwise, Array2 is ignored.
Keywords
DEGREES
If set, then theinput parametersarein degrees(whereapplicable). Otherwise, theangles
are in radians.
P1 - P5
The meaning of the keywords P1 through P5 vary depending upon the object type. The
table below describes the differences.
Ruled A (3, n) array of connected 3D points which dene the shape of the rst ruled vec-
tor. Theoptional (3, m) Array2parameter denestheshapeof thesecond ruled vec-
tor. Theresultingpolygon mesh will have(n> m)*(steps+1) vertices(wherestepsis
the number of intermediate steps ). (See the P1 keyword). When shading a ruled
mesh, the shading array should have (n> m, steps+1) elements.
Surface
Type
Keywords
Triangulated P1 through P5 are ignored.
Rectangular If Array1isan (n, m) array, and if P1hasn elements, then thevaluescontained in P1
are the X coordinates for each column of vertices. Otherwise, FINDGEN(n) is used
for the X coordinates. If P2 hasmelements, then the values contained in P2 are the
Y coordinates for each row of vertices. Otherwise, FINDGEN(m) is used for the Y
coordinates. The polygon facing is reversed if the order of either P1 or P2 (but not
both) is reversed. P3, P4, and P5 are ignored.
Table 9-57: P1-P5 Keywords
Surface
Type
Array1 Type
Table 9-56: Array 1 Type
IDL Reference Guide MESH_OBJ
Examples
Create a 48x64 cylinder with a constant radius of 0.25.
MESH_OBJ, 3, Vertex_List, Polygon_List, $
Replicate(0.25, 48, 64), P4=0.5
Transform the vertices.
T3D, /RESET
Polar P1 species the polar angle of the rst column of Array1 (the default is 0). P2 speci-
es the polar angle of the last column of Array1 (the default is 2*PI). If P2 is less
than P1then thepolygon facingisreversed. P3speciestheradiusof therst rowof
Array1(thedefault is0). P4speciestheradiusof thelast rowof Array1(thedefault
ism-1). If P4 is less than P3 then the polygon facing is reversed. P5 is ignored.
Cylindrical P1 species the polar angle of the rst column of Array1 (the default is 0). P2 speci-
es the polar angle of the last column of Array1 (the default is 2*PI). If P2 is less
than P1then thepolygon facingisreversed. P3speciestheZ coordinateof therst
row of Array1 (the default is 0). P4 species the Z coordinate of the last row of
Array1 (the default ism-1). If P4 is less than P3 then the polygon facing is reversed.
P5 is ignored.
Spherical P1speciesthelongitudeof therst column of Array1(thedefault is0). P2species
thelongitudeof thelast column of Array1(thedefault is2*PI). IFP2islessthan P1
then thepolygon facingisreversed. P3speciesthelatitudeof therst rowof Array1
(thedefault is-PI/2). P4speciesthelatitudeof thelast rowof Array1(thedefault is
+PI/2). If P4 is less than P3 then the polygon facing is reversed. P5 is ignored.
Extrusion P1 species the number of steps in the extrusion (the default is 1). P2 is a three ele-
ment vector specifyingthedirection (and length) of theextrusion (thedefault is[ 0,
0, 1] ). P3, P4, and P5 are ignored.
Revolution P1 species the number of facets in the revolution (the default is 3). If P1 is less
than 3then 3isused. P2isathreeelement vector specifyingapoint that therotation
vector passesthrough (thedefault is[ 0, 0, 0] ). P3isathreeelement vector specifying
the direction of the rotation vector (the default is [ 0, 0, 1] ). P4 species the starting
angle for the revolution (the default is 0). P5 species the ending angle for the revo-
lution (the default is 2*PI). If P5 is less than P4 then the polygon facing is reversed.
Ruled P1speciesthenumber of steps in theruling(thedefault is1). P2, P3, P4, and P5
are ignored.
Surface
Type
Keywords
Table 9-57: P1-P5 Keywords
T3D, ROTATE=[0.0, 30.0, 0.0]
T3D, ROTATE=[0.0, 0.0, 40.0]
T3D, TRANSLATE=[0.25, 0.25, 0.25]
VERTEX_LIST = VERT_T3D(Vertex_List)
Create the window and view.
WINDOW, 0, XSIZE=512, YSIZE=512
CREATE_VIEW, WINX=512, WINY=512
Render the mesh.
SET_SHADING, LIGHT=[-0.5, 0.5, 2.0], REJECT=0
TVSCL, POLYSHADE(Vertex_List, Polygon_List, /NORMAL)
Create a cone (surface of revolution).
MESH_OBJ, 6, Vertex_List, Polygon_List, $
[[0.75, 0.0, 0.25], [0.5, 0.0, 0.75]], $
P1=16, P2=[0.5, 0.0, 0.0]
Create the window and view.
CREATE_VIEW, WINX=512, WINY=512, AX=30.0, AY=(140.0), ZOOM=0.5
Render the mesh.
SET_SHADING, LIGHT=[-0.5, 0.5, 2.0], REJECT=0
TVSCL, POLYSHADE(Vertex_List, Polygon_List, /DATA, /T3D)
See Also
CREATE_VIEW, POLYSHADE, SET_SHADING, VERT_T3D
IDL Reference Guide MESSAGE
MESSAGE
The MESSAGE procedure issues error and informational messages using the same
mechanism employed by built-in IDL routines. By default, the message is issued as an
error, the message is output, and IDL takes the action specied by the ON_ERROR
procedure. Asaside-effect of issuingtheerror, thesystemvariable!ERROR_STATEisset
and the text of the error message is placed in !ERROR_STATE.MSG or in
!ERROR_STATE.SYS_MSG for the operating systems component of the error message.
If thecall to theMESSAGEprocedurecausesexecution to halt, traceback information is
displayed automatically.
Calling Sequence
MESSAGE, [ Text ]
Arguments
Text
The text of the message to be issued. If Text is not supplied, MESSAGE returns quietly.
Keywords
CONTINUE
Set thiskeyword to return after issuingtheerror instead of takingtheaction specied by
ON_ERROR. Use this option when it is desirable to report an error and then continue
processing.
INFORMATIONAL
Set this keyword to issue informational text instead of an error. In this case, !ERR,
!ERROR, and !ERR_STRING are not set. The !QUIET system variable controls the
printing of informational messages.
IOERROR
Set this keyword to indicates that the error occurred while performing I/O. The action
specied by the ON_IOERROR procedure is executed instead of ON_ERROR.
NONAME
Set thiskeywordtosuppressprintingof theissuingroutinesnameat thebeginningof the
error message.
NOPREFIX
Usually, themessageincludesthemessageprexstring(asspeciedbytheMSG_PREFIX
eld of the !ERROR_STATE system variable) at the beginning. Set this keyword to omit
the prex.
MESSAGE IDL Reference Guide
NOPRINT
Set this keyword to prevent the message from printing to the screen and cause the other
actions to proceed quietly. The error system variables are updated as usual.
RESET
Set this keyword to set the !ERROR_STATE on page 39 system variable back to the
success state and clear any internal traceback information being saved for use by the
LAST_ERROR keyword to the HELP procedure.
TRACEBACK
Thiskeywordisobsoleteandisincludedfor compatibilitywithexistingcodeonly. Traceback
information is provided by default.
Example
As an example, assume the statement:
message, 'Unexpected value encountered.'
isexecuted in aprocedurenamed CALC. If an error occurs, thefollowingmessagewould
be printed:
% CALC: Unexpected value encountered.
and execution would halt.
See Also
CATCH, ON_ERROR, ON_IOERROR, STRMESSAGE
IDL Reference Guide MIN
MIN
The MIN function returns the value of the smallest element of Array. The type of the
result is the same as that of Array.
Calling Sequence
Result = MIN(Array [, Min_Subscript])
Arguments
Array
The array to be searched.
Min_Subscript
A named variable that, if supplied, is converted to a long integer containing the one-
dimensional subscript of theminimumelement. Otherwise, thesystemvariable!Cisset
to the one-dimensional subscript of the minimum element.
Keywords
MAX
Thenameof avariabletoreceivethevalueof themaximumarrayelement. If you needto
nd both theminimumand maximumarray values, usethiskeyword to avoid scanning
the array twice with separate calls to MAX and MIN.
NAN
Example
Create a simple two-dimensional array by entering:
D = DIST(100)
Find the minimum value in array D and print the result by entering:
PRINT, MIN(D)
See Also
MAX
MIN_CURVE_SURF IDL Reference Guide
MIN_CURVE_SURF
TheMIN_CURVE_SURFfunction interpolatesaregularly- or irregularly-gridded set of
pointswith either aminimumcurvaturesurfaceor athin-plate-splinesurface. It returns
a two-dimensional oating-point array containing the interpolated surface, sampled at
the grid points.
A minimum curvature spline surface is tted to the data points described by x, y, and z.
The basis function is:
C (x
0
, x
1
, y
0
, y
1
) = d
2
log(d
k
)
wheredisthedistancebetween (x
0
, y
0
), (x
1
, y
1
) andk= 1for minimumcurvaturesurface
or k= 2for Thin PlateSplines. For ndatapoints, asystemof n+3simultaneousequations
aresolvedfor thecoefcientsof thesurface. For anyinterpolation point, theinterpolated
value is:
Note The accuracy of this function is limited by the single-precision oating-point accu-
racy of the machine.
min_curve_surf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = MIN_CURVE_SURF(Z [, X, Y])
Arguments
Z, X, Y
Arrays containing theZ, X, and Y coordinates of the data points on the surface. Points
Keywords
TPS
Set thiskeyword to usethethin-plate-splinemethod. Thedefault isto usetheminimum
curvature surface method.
Input Grid Description:
f x y , ( ) b
0
b
1
x b
2
y a
i
C x
i
x y
i
y , , , ( )
+ + + =
IDL Reference Guide MIN_CURVE_SURF
REGULAR
If set, theZ parameter is a two-dimensional array of dimensions (n,m), containing
XGRID
XVALUES
XVALUES.
YGRID
YVALUES
An n-element array dening they locations of Z[ i,j] . Do not specify both YGRID and
YVALUES.
Output Grid Description:
GS
thedefault horizontal spacingis(xmax- xmin)/(NX-1). ysiscomputed in thesameway.
BOUNDS
NX
NY
XOUT
Use the XOUT keyword to specify a vector containing the output grid x values. If this
parameter is supplied, GS, BOUNDS, and NX are ignored for thex output grid. XOUT
allows you to specify irregularly-spaced output grids.
MIN_CURVE_SURF IDL Reference Guide
YOUT
Use the YOUT keyword to specify a vector containing the output grid yvalues. If this
parameter is supplied, GS, BOUNDS, and NY are ignored for theyoutput grid. YOUT
allows you to specify irregularly-spaced output grids.
XPOUT/ YPOUT
Use the XPOUT and YPOUT keywords to specify arrays that contain thex and y values
for theoutput points. If thesekeywordsareused, theoutput gridneednot beregular, and
all other output grid parameters are ignored. XPOUT and YPOUT must have the same
number of points, which is also the number of points returned in the result.
Example
N = 15 Number of random points.
Z = EXP(-2 * ((X-.5)^2 + (Y-.5)^2)) TheGaussian.
Use a 26 by 26 grid over the rectangle bounding x and y:
R = MIN_CURVE_SURF(Z, X, Y) Get thesurface.
R = MIN_CURVE_SURF(Z, X, Y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
Alternatively, get a 10 by 10 surface over the rectangle bounding x and y:
R = MIN_CURVE_SURF(Z, X, Y, NX=10, NY=10)
See Also
CONTOUR, TRI_SURF
IDL Reference Guide MK_HTML_HELP
MK_HTML_HELP
TheMK_HTML_HELPprocedure, given alist of IDL procedurelenames(.pro les),
VMStext librarylenames(.TLB les), or thenamesof directoriescontainingsuch les,
generates a le in HTML (HyperText Markup Language) format that contains
documentation for those routines that contain standard IDL documentation headers.
The resulting le can then be viewed with a World Wide Web browser such as Mosaic
or Netscape.
MK_HTML_HELP procedure makes single HTML le that starts with a list of the
routinesdocumented in thele. Thenamesof routinesin that list arehypertext linksto
thedocumentation for thoseroutines. Thedocumentation for each routineissimplythe
text of the documentation header copied from the corresponding.pro leno
reformatting is performed.
Thedocumentation headersof the.pro lesin question must havethefollowingformat:
The rst line of the documentation block contains only the characters;+, starting in
column 1.
The last line of the documentation block contains only the characters;-, starting in
column 1.
All other lines in the documentation block contain a; in column 1.
If a line containing the string NAME: exists in the documentation block, the contents
of the following line are used as the name of the routine being described. If the NAME:
eld is not present, the name of the source le is used as the routine name.
Theletemplate.pro in thegeneral subdirectory of theexamples subdirectory of
the IDL distribution contains a template for creating your own documentation headers.
This routine is supplied for users to make online documentation from their own IDL
programs. Although it could be used to create an HTML documentation le from the
lib subdirectory of the IDL distribution, we do not recommend doing so. The
documentation headers on the les in thelib directory are used for historical
purposesmost do not contain the most current or accurate documentation for those
routines. The most current documentation for IDLs built-in and library routines is
found in IDLs online help system (enter ? at the IDL prompt).
mk_html_help.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MK_HTML_HELP, Sources, Filename
MK_HTML_HELP IDL Reference Guide
Arguments
Sources
A string array containing the names of IDL procedure les (.pro les), VMS text
libraries(.TLB les), or directoriescontainingsuch les. TheSourcesarray may contain
both individual le and directory names. Each IDL procedure le must have the le
extension .pro, and each VMS text library must include the le extension .TLB.
Elements of theSourcesarray that do not have either of these extensions are assumed to
be directories.
All .pro les found in Sourcesare searched for documentation headers. The
documentation headersareextracted and saved in HTML format in thelespecied by
Filename.
Note More than one documentation block may exist in a single input le.
Filename
A string containing the name of the output le to be generated. HTML les are usually
saved in les named with a.html or .htm extension.
Keywords
STRICT
Set this keyword to force MK_HTML_HELP to adhere strictly to the HTML format by
scanningthedocumentation blocksfor HTMLreservedcharactersandreplacingthemin
theoutput lewith theappropriateHTML syntax. HTML reserved charactersinclude<
, > , & , and ". By default, this keyword is set to zero to allow for faster processing of the
input les.
TITLE
Astringthat supplesthenametobeusedasthetitleof theHTMLdocument. Thedefault
is Extended IDL Help.
VERBOSE
Set this keyword to display informational messages as MK_HTML_HELP generates the
HTML le. Normally, MK_HTML_HELP works silently.
Example
TogenerateanHTMLhelplenamedmyhelp.html fromthe.pro lesinthedirectory
/usr/home/dave/myroutines, use the command:
MK_HTML_HELP, '/usr/home/dave/myroutines', 'myhelp.html'
To generate an HTML help le for all routines in a given directory whose le names
contain the word plot, use the following commands:
plotfiles=FINDFILE('/usr/home/dave/myroutines/*plot*.pro')
IDL Reference Guide MK_HTML_HELP
MK_HTML_HELP, plotfiles, 'myplot.html'
See Also
DOC_LIBRARY
MODIFYCT IDL Reference Guide
MODIFYCT
The MODIFYCT procedure updates the distribution color table lecolors1.tbl,
located in thecolors subdirectory of theresource subdirectory of the main IDL
directory, or a user-designated le with a new, or modied, colortable.
modifyct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MODIFYCT, Itab, Name, R, G, B
Arguments
Itab
The index of the table to be updated, numbered from 0 to 255. If the specied entry is
greater than thenext availablelocation in thetable, theentrywill beadded tothetablein
theavailablelocation rather than theindex speciedbyItab. On return, Itabcontainsthe
index for thelocation that wasmodied or extended. Themodied tablecan bethen be
loaded with the IDL command: LOADCT, Itab.
Name
A string, up to 32 characters long, that contains the name for the new color table.
R
A 256-element vector that contains the values for the red colortable.
G
A 256-element vector that contains the values for the green colortable.
B
A 256-element vector that contains the values for the blue colortable.
Keywords
FILE
Set this keyword to the name of a colortable le to be modied instead of the le
colors1.tbl in the IDL directory.
See Also
LOADCT, XLOADCT
IDL Reference Guide MOMENT
MOMENT
The MOMENT function computes the mean, variance, skewness, and kurtosis of a
samplepopulation contained in an n-element vector X. If thevector containsnidentical
elements, MOMENT computesthemean and variance, and returnstheIEEEvalueNaN
for the skewness 5and kurtosis, which are not dened. (See Special Floating-Point
Values on page 152 of Building IDL Applications.)
When x = (x
0
, x
1
, x
2
, ..., x
n-1
), the various moments are dened as follows:
moment.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = MOMENT(X)
Arguments
X
Mean x
1
N
---- x
j
j 0 =
N 1
= =
Variance
1
N 1
------------- x
j
x ( )
2
j 0 =
N 1
=
Skewness
1
N
----
x
j
x
Variance
---------------------------
,

_
3
j 0 =
N 1
=
Kurtosis
1
N
----
x
j
x
Variance
---------------------------
,

_
4
3
j 0 =
N 1
=
Mean Absolute Deviation
1
N
---- x
j
x
j 0 =
N 1
=
Standard Deviation Variance =
MOMENT IDL Reference Guide
Keywords
DOUBLE
MDEV
Set this keyword to a named variable that will contain the mean absolute deviation of X.
NAN
SDEV
Set this keyword to a named variable that will contain the standard deviation of X.
Example
X = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
Compute the mean, variance, skewness and kurtosis.
result = MOMENT(X)
PRINT, 'Mean: ', result[0] & PRINT, 'Variance: ', result[1] & $
PRINT, 'Skewness: ', result[2] & PRINT, 'Kurtosis: ', result[3]
IDL prints:
Mean: 66.7333
Variance: 7.06667
Skewness: -0.0942851
Kurtosis: -1.18258
See Also
KURTOSIS, HISTOGRAM, MAX, MEAN, MEANABSDEV, MEDIAN, MIN,
MOMENT, STDDEV, SKEWNESS, VARIANCE
IDL Reference Guide MPEG_CLOSE
MPEG_CLOSE
TheMPEG_CLOSEprocedureclosesanMPEGsequenceopenedwiththeMPEG_OPEN
routine. Notethat MPEG_CLOSEdoesnot savetheMPEGleassociatedwiththeMPEG
sequence; useMPEG_SAVEto savethele. Thespecied MPEGsequenceidentier will
no longer be valid after calling MPEG_CLOSE.
mpeg_close.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MPEG_CLOSE, mpegID
Arguments
mpegID
Theuniqueidentier of theMPEGsequencetobefreed. (MPEGsequenceidentiersare
returned by the MPEG_OPEN routine.)
Example
See MPEG_OPEN for an example using this routine.
See Also
MPEG_OPEN, MPEG_PUT, MPEG_SAVE, XINTERANIMATE
MPEG_OPEN IDL Reference Guide
MPEG_OPEN
The MPEG_OPEN function initializes an IDLgrMPEG object for MPEG encoding and
returns the object reference. The MPEG routines provide a wrapper around the IDL
Object Graphics IDLgrMPEG object, eliminating the need to use the Object Graphics
interface to create MPEG les.
Note TheMPEGstandarddoesnot allowmovieswithoddnumbersof pixelstobecreated.
mpeg_open.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
mpegID = MPEG_OPEN(Dimensions)
Arguments
Dimensions
Atwo-element vector of theform[ xsize, ysize] indicatingthedimensionsof theimagesto
be used as frames in the MPEG movie le. All images in the MPEG le must have the
same dimensions.
Keywords
FILENAME
Set thiskeyword equal to astringrepresentingthenameof thelein which theencoded
MPEG sequence is to be saved. The default le name isidl.mpg.
Example
Thefollowingsequenceof IDLcommandsillustratesthestepsneededtocreatean MPEG
movielefromaseriesof imagearraysnamed image0, image1, .., imagen, wherenisthe
zero-based index of the last image in the movie:
mpegID = MPEG_OPEN() Open an MPEG sequence.
MPEG_PUT, mpegID, IMAGE=image0, FRAME=0
Add thefirst frame.
MPEG_PUT, mpegID, IMAGE=image1, FRAME=1
... Subsequent frames.
MPEG_PUT, mpegID, IMAGE=imagen, FRAME=n
Last frame.
IDL Reference Guide MPEG_OPEN
MPEG_SAVE, mpegID, FILENAME='myMovie.mpg'
SavetheMPEG sequencein the
filemyMovie.mpg.
MPEG_CLOSE, mpegID ClosetheMPEG sequence.
See Also
MPEG_CLOSE, MPEG_PUT, MPEG_SAVE, XINTERANIMATE
MPEG_PUT IDL Reference Guide
MPEG_PUT
TheMPEG_PUT procedurestoresthespecied imagearray at thespecied frameindex
in an MPEG sequence.
mpeg_put.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MPEG_PUT, mpegID
Arguments
mpegID
The unique identier of the MPEG sequence into which the image will be inserted.
(MPEG sequence identiers are returned by the MPEG_OPEN routine.)
Keywords
COLOR
Set thiskeywordtoreadoff an 8-bit displayandpasstheinformation throughthecurrent
color table to create a 24-bit image.
FRAME
Set this keyword equal to an integer specifying the frame at which the image is to be
loaded. If the frame number matches a previously loaded frame, the previous frame is
overwritten. The default is 0.
IMAGE
Set this keyword equal to an mx n image array or a 3 x mx n True Color image array
representingtheimagetobeloaded at thespecied frame. Thiskeyword isignored if the
WINDOW keyword is specied.
ORDER
Set this keyword to indicate that the rows of the image should be drawn from top to
bottom. By default, the rows are drawn from bottom to top.
WINDOW
Set this keyword to the index of a Direct Graphics Window (or to an object reference to
an IDLgrWindowor IDLgrBuffer object) to indicatethat theimageto beloaded isto be
read from the given window or buffer. If this keyword is specied, it overrides the value
of the IMAGE keyword.
IDL Reference Guide MPEG_PUT
Example
See Also
MPEG_CLOSE, MPEG_OPEN, MPEG_SAVE, XINTERANIMATE
MPEG_SAVE IDL Reference Guide
MPEG_SAVE
The MPEG_SAVE procedure encodes and saves an open MPEG sequence.
mpeg_save.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MPEG_SAVE, mpegID
Arguments
mpegID
The unique identier of the MPEG sequence to be saved to a le. (MPEG sequence
identiers are returned by the MPEG_OPEN routine.)
Keywords
FILENAME
Set thiskeywordtoastringrepresentingthenameof theletowhichtheencodedMPEG
sequence is to be saved. The default isidl.mpg.
Example
See Also
MPEG_CLOSE, MPEG_OPEN, MPEG_PUT, XINTERANIMATE
IDL Reference Guide MULTI
MULTI
The MULTI procedure expands the current color table to wrap around some number
of times.
multi.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
MULTI, N
Arguments
N
The number of times the color table will wrap. This parameter does not have to be an
integer.
Example
Display an image, load color table 1, and make that color table wrap around 3 times.
Enter:
TVSCL, DIST(256) Display a simpleimage.
LOADCT, 1 Load color table1.
MULTI, 3 Seehowthenewcolortableaffects
theimage.
See Also
STRETCH, XLOADCT
N_ELEMENTS IDL Reference Guide
N_ELEMENTS
TheN_ELEMENTSfunction returnsthenumber of elementscontainedin an expression
or variable.
Calling Sequence
Result = N_ELEMENTS(Expression)
Arguments
Expression
The expression for which the number of elements is to be returned. Scalar expressions
always have one element. The number of elements in an array is equal to the product of
its dimensions. If Expression is an undened variable, N_ELEMENTS returns zero.
Examples
Create an integer array, I by entering:
I = INTARR(4, 5, 3, 6)
Find the number of elements in I and print the result by entering:
PRINT, N_ELEMENTS(I)
To test if the variable Q is dened and, if not, set its value to 1, use the command:
IF N_ELEMENTS(Q) EQ 0 THEN Q=1
A typical useof N_ELEMENTSisto check if an optional input isdened, and if not, set
it to a default value:
IF (N_ELEMENTS(roo) EQ 0) THEN roo=rooDefault
Theoriginal valueof roo maybealteredbyacalledroutine, passingadifferent valueback
to the caller. Unless you intend for the routine to behave in this manner, you should
prevent it by differentiating N_ELEMENTS parameter from your routines variable:
IF (N_ELEMENTS(roo) EQ 0) THEN rooUse=roo $
ELSE rooUse=rooDefault
See Also
N_TAGS
IDL Reference Guide N_PARAMS
N_PARAMS
The N_PARAMS function returns the number of non-keyword parameters used in
callingan IDLprocedureor function. Thisfunction isonlyuseful within IDLprocedures
or functions. User-written proceduresandfunctionscan useN_PARAMStodetermineif
they were called with optional parameters.
Note In the case of object method procedures and functions, the SELF argument is not
counted by N_PARAMS.
Calling Sequence
Result = N_PARAMS()
Arguments
None. This function always returns the number of parameters that were used in calling
the procedure or function from which N_PARAMS is called.
See Also
KEYWORD_SET
N_TAGS IDL Reference Guide
N_TAGS
The N_TAGS function returns the number of structure tags contained in a structure
expression. It optionally returns the size, in bytes, of the structure.
Calling Sequence
Result = N_TAGS(Expression)
Arguments
Expression
Theexpression for which thenumber of structuretagsistobereturned. Expressionsthat
arenot of structuretypeareconsidered tohavenotags. N_TAGSdoesnot search for tags
recursively, so if Expression is a structure containing nested structures, only the number
of tags in the outermost structure are counted.
Keywords
LENGTH
Set this keyword to return the length of the structure, in bytes.
Note Thelength of astructureismachinedependent. Thelength of agiven structurewill
vary dependingupon thehost machine. IDL padsand alignsstructuresin amanner
consistent with the host machines C compiler.
Example
Find the number of tags in the system variable !P and print the result by entering:
PRINT, N_TAGS(!P)
Find the length of !P, in bytes:
PRINT, N_TAGS(!P, /LENGTH)
See Also
CREATE_STRUCT, N_ELEMENTS, TAG_NAMES, Structures on page41of Building
IDL Applications
IDL Reference Guide NEWTON
NEWTON
TheNEWTONfunction solvesasystemof nnon-linear equationsin ndimensionsusing
aglobally-convergent Newtonsmethod. Theresult isan n-element vector containingthe
solution.
NEWTON isbased on theroutinenewt described in section 9.7of Numerical Recipesin
Calling Sequence
Result = NEWTON(X, Vecfunc)
Arguments
X
An n-element vector containing an initial guess at the solution of the system.
Vecfunc
systemof non-linear equations. Thisfunctionmust accept ann-element vector argument
X and return an n-element vector result.
For example, suppose the non-linear system is dened by the following equations:
y
0
= x
0
+ x
1
- 3, y
1
= x
0
2
+ x
1
2
- 9
We write a function NEWTFUNC to express these relationships in the IDL language:
FUNCTION newtfunc, X
RETURN, [X[0] + X[1] -3.0, X[0]^2 + X[1]^2 - 9.0]
END
Keywords
CHECK
NEWTON calls an internal function named fmin() to determine whether the routine
has converged to a local minimum rather than to a global minimum (seeNumerical
Recipes, section 9.7). UsetheCHECK keyword to specify anamed variablewhich will be
set to1if theroutinehasconvergedtoalocal minimumor to0if it hasnot. If theroutine
does converge to a local minimum, try restarting from a different initial guess to obtain
the global minimum.
DOUBLE
NEWTON IDL Reference Guide
ITMAX
The maximum allowed number of iterations. The default value is 200.
STEPMAX
The scaled maximum step length allowed in line search. The default value is 100.0.
TOLF
Set the convergence criterion on the function values. The default value is 1.0 10
-4
.
TOLMIN
Set the criterion for deciding whether spurious convergence to a minimum of the
function fmin() has occurred. The default value is 1.0 10
-6
.
TOLX
Set the convergence criterion on X. The default value is 1.0 10
-7
.
Example
Use NEWTON to solve an n-dimensional system of n non-linear equations. Systems of
non-linear equationsmay havemultiplesolutions; startingthealgorithmswith different
initial guesses enables detection of different solutions.
X = [1.0, 5.0] Providean initial guess as theal-
gorithms startingpoint.
result = NEWTON(X, 'newtfunc') Computethesolution.
IDL prints:
-0.000346127 3.00000
X = [1.0, -1.0] Try a different startingpoint.
result = NEWTON(X,'newtfunc') Computethesolution.
IDL prints:
2.99999 8.37117e-05
See Also
BROYDEN, FX_ROOT, FZ_ROOTS
IDL Reference Guide NORM
NORM
The NORM function computes the Euclidean norm of a vector. Alternatively, NORM
computes the Innity norm of an array.
norm.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = NORM(A)
Arguments
A
A can be either of the following:
Ann-element real or complexvector, if NORMisbeingusedtocomputetheEuclidean
norm of a vector.
An mbynreal or complex array, if NORM isbeingusedtocomputetheInnitynorm
of an array.
Keywords
DOUBLE
Examples
Dene an n-element complex vector A:
A = [COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3,1)]
PRINT, NORM(A) ComputetheEuclideannormofA
and print.
IDL prints:
4.35890
Dene an mby n complex array A:
B = [[COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3,1)], $
[COMPLEX(1,-2), COMPLEX(2, 2), COMPLEX(1, 0)]]
PRINT, NORM(B, /DOUBLE) ComputetheInfinity norm of B
and print.
NORM IDL Reference Guide
IDL prints:
6.9907048
See Also
COND
IDL Reference Guide OBJ_CLASS
OBJ_CLASS
The OBJ_CLASS function returns the name of the class or superclasses of its argument,
as a string. If the supplied argument is not an object, a null string is returned.
Calling Sequence
Result = OBJ_CLASS(Arg)
Arguments
Arg
A scalar object reference or string variable for which the object class name is desired. If
Argisan object reference, itsobject classdenition isused. If Argisastring, it istaken to
be the name of the class for which information is desired. Passing a string argument is
primarily useful in conjunction with the SUPERCLASS keyword.
Keywords
COUNT
Set this keyword equal to a named variable that will contain the number of names
returned by OBJ_CLASS. It can beused to determinehowmany superclassesaclasshas
when the SUPERCLASS keyword is specied.
SUPERCLASS
Set this keyword to cause OBJ_CLASS to return the names of the objectsdirect
superclassesasastringarray, oneelement per superclass. Thesuperclassesareordered in
theorder theyappear in theclassstructuredeclaration. In thecasewheretheclasshasno
superclasses, a scalar null string is returned, and the COUNT keyword (if specied)
returns the value 0.
OBJ_DESTROY IDL Reference Guide
OBJ_DESTROY
The OBJ_DESTROY procedure is used to destroy an object. If the class (or one of its
superclasses) supplies a procedure method named CLEANUP, the method is called and
all arguments and keywords passed by the user are passed to it. This method should
perform any required cleanup on the object and return. Whether a CLEANUP method
actually exists or not, IDL will destroy the heap variable representing the object and
return.
Note that OBJ_DESTORY does not recurse. That is, if object1 contains a reference to
object2, destroyingobject1 will not destroy object2. Take care not to lose the only
reference to an object by destroying an object that contains that reference. Recursive
cleanup of object hierarchies is a good job for a CLEANUP method.
Calling Sequence
OBJ_DESTROY, ObjRef [ , Arg
1
, , Arg
n
]
Arguments
ObjRef
Theobject referencefor theobject to bedestroyed. ObjRef can bean array, in which case
all of the specied objects are destroyed in turn. If the NULL object reference is passed,
OBJ_DESTROY ignores it quietly.
Arg1Argn
Anyargumentsaccepted bytheCLEANUPmethod for theobject beingdestroyed can be
specied as additional arguments to OBJ_DESTROY.
Keywords
Any keywords accepted by the CLEANUP method for the object being destroyed can be
specied as keywords to OBJ_DESTROY.
IDL Reference Guide OBJ_ISA
OBJ_ISA
When one object class is subclassed (inherits) from another class, there is an Is A
relationship between them. The OBJ_ISA function is used to determine if an object
instance is subclassed from the specied class. OBJ_ISA returns True (1) if the specied
variable is an object and has the specied class in its inheritance graph, or False (0)
otherwise.
Calling Sequence
Result = OBJ_ISA(ObjectInstance, ClassName)
Arguments
ObjectInstance
A scalar or array variablefor which theOBJ_ISA test should beperformed. Theresult is
of type byte, and has the same size and organization asObjectInstance.
ClassName
A string giving the name of the class for which ObjectInstanceis being tested.
OBJ_NEW IDL Reference Guide
OBJ_NEW
Giventhenameof astructurethat denesanobject class, theOBJ_NEWfunctionreturns
an object reference to a new instance of the specied object type by carrying out the
following operations in order:
1. If the class structure has not been dened, IDL will attempt to nd and call a procedure
todeneit automatically. (SeeObject BasicsinObjectGraphicsfor details.) If thestructure
is still not dened, OBJ_NEW fails and issues an error.
2. If theclassstructurehasbeen dened, OBJ_NEWcreatesan object heapvariablecontain-
ing a zeroed instance of the class structure.
3. Once the new object heap variable has been created, OBJ_NEW looks for amethod
function named Class::INIT (whereClassis the actual name of the class). If an INIT
methodexists, it iscalledwiththenewobject asitsimplicit SELFargument, aswell asany
arguments and keywords specied in the call to OBJ_NEW. If the class has no INIT
method, theusual method-searchingrulesareapplied to nd onefromasuperclass. For
more information on methods and method-searching rules, see Method Routines in
Chapter 2 of Object Graphics.
TheINIT method isexpected toinitializetheobject instancedataasnecessaryto
meet the needs of the class implementation. INIT should return a scalar TRUE
value (such as 1) if the initialization is successful, and FALSE (such as 0) if the
initialization fails.
Note OBJ_NEW does not call all the INIT methods in an objects class hierarchy.
Instead, it simply calls the rst one it nds. Therefore, the INIT method for
a class should call the INIT methods of its direct superclasses as necessary.
4. If theINITmethodreturnstrue, or if noINITmethodexists, OBJ_NEWreturnsanobject
reference to the heap variable. If INIT returns false, OBJ_NEW destroys the new object
and returnstheNULL object reference, indicatingthat theoperation failed. Notethat in
this case the CLEANUP method is not called. See Destruction in Chapter 2 of Object
Graphicsfor more on CLEANUP methods.
If called without arguments, OBJ_NEW returns a NULL object reference. The NULL
object reference is special value that never refers to a value object. It is primarily used as
aplaceholder in structuredenitions, andastheinitial valuefor elementsof object arrays
created via OBJARR. The null object reference is useful as an indicator that an object
reference is currently not usable.
Calling Sequence
Result = OBJ_NEW([ObjectClassName[, Arg1...Argn]])
IDL Reference Guide OBJ_NEW
Arguments
ObjectClassName
Stringgivingthenameof thestructuretypethat denestheobject classfor which anew
object should be created.
If ObjectClassNameisnot provided, OBJ_NEWdoesnot createanewheap variable, and
returns theNull Object, which is a special object reference that is guaranteed to never
point at a valid object heap variable. The null object is a convenient value to use when
deningstructuredenitionsfor eldsthat areobject references, sinceit avoidstheneed
to have a pre-existing valid object reference.
Arg1Argn
Any argumentsaccepted by theINIT method for theclassof object beingcreated can be
specied when the object is created.
Keywords
Any keywords accepted by the INIT method for the class of object being created can be
specied when the object is created.
OBJ_VALID IDL Reference Guide
OBJ_VALID
The OBJ_VALID function veries the validity of its argument object references, or
alternatively returns a vector of references to all the existing valid objects.
If called with an argument, OBJ_VALID returns a byte array of the same size as the
argument. Each element of the result is set to True (1) if the corresponding object
reference in the argument refers to an existing object, and False (0) otherwise.
If called with an integer or arrayof integersasitsargument and theCAST keyword isset,
OBJ_VALIDreturnsanarrayof object references. Eachelement of theresult isareference
totheheapvariableindexedbytheinteger value. Integersusedtoindexheapvariablesare
shown in the output of the HELP and PRINT commands. This is useful primarily in
programming/debugging when the you have lost a reference but see it with HELP and
need toget areferencetoit interactively in order todeterminewhat it isand takestepsto
x the code. See the Examples section below for an example.
If noargument isspecied, OBJ_VALIDreturnsavector of referencestoall existingvalid
objects. If no valid objects exist, a scalar null object reference is returned.
Calling Sequence
Result = OBJ_VALID([ Arg] )
Arguments
Arg
Scalar or array argument of object reference type.
Keywords
CAST
Set this keyword equal to an integer that indexes a heap variable to create a new pointer
tothat heapvariable. Integersusedtoindex heapvariablesareshown in theoutput of the
HELPandPRINTcommands. Thisisuseful primarilyin programming/debuggingwhen
the you have lost a reference but see it with HELP and need to get a reference to it
interactively in order to determine what it is and take steps to x the code. See the
Examples section below for an example.
COUNT
Set thiskeywordequal toanamedvariablethat will containthenumber of currentlyvalid
objects. This value is returned as a longword integer.
IDL Reference Guide OBJ_VALID
Examples
To determine if a given object reference refers to a valid heap variable
IF (OBJ_VALID(obj)) THEN
To destroy all existing pointer heap variables:
OBJ_DESTROY, OBJ_VALID()
You can use the CAST keyword to reclaim lost object references. For example:
junk = {junk, data1:0, data2:0.0} Createa class structure.
A = OBJ_NEW('junk') Createan object.
PRINT, A Find the integer index.
IDL prints:
<ObjHeapVar3(JUNK)>
In this case, the integer index to the heap variable is 3. If we reassign the variable A, we
will lose the object reference, but the heap variable will still exist:
A = 0 Losetheobject reference.
PRINT, A, OBJ_VALID()
IDL prints:
0 <ObjHeapVar3(JUNK)>
We can reclaim the lost heap variable using the CAST keyword:
A = OBJ_VALID(3, /CAST) Reclaim thereference.
PRINT, A
IDL prints:
<ObjHeapVar3(JUNK)>
OBJARR IDL Reference Guide
OBJARR
The OBJARR function returns an object reference vector or array. The individual
elements of the array are set to the NULL object reference.
Calling Sequence
Result = OBJARR(D
1
, , D
n
)
Argument
Di
Keywords
NOZERO
OBJARR sets every element of the result to the null object reference. If NOZERO is
nonzero, this initialization is not performed and OBJARR executes faster.
Caution If youspecifyNOZERO, theresultingarraywill havewhatever valuehappenstoexist
at thesystemmemorylocation that thearrayisallocatedfrom. Youshouldbecareful
to initialize such an array to valid object reference values.
Example
Createa3element by 3element object referencearray with each element containingthe
null object reference:
A = OBJARR(3, 3)
IDL Reference Guide ON_ERROR
ON_ERROR
TheON_ERRORproceduredeterminestheaction taken when an error isdetectedinside
an IDL user procedure or function by setting state information applying to the current
routine and all nested routines. If an override exists within the nested routine, it takes
precedence over the ON_ERROR call.
Calling Sequence
ON_ERROR, N
Arguments
N
An integer that species the action to take. Valid values for N are:
0: Stop at the statement in the procedure that caused the error, the default action.
1: Return all the way back to the main program level.
2: Return to the caller of the program unit that established the ON_ERROR condition.
3: Return to the program unit that established the ON_ERROR condition.
See Also
CATCH, MESSAGE, ON_IOERROR, and Chapter 10, ControllingErrors, of Building
IDL Applications .
ON_IOERROR IDL Reference Guide
ON_IOERROR
TheON_IOERRORprocedurespecifiesastatement tobejumpedtoif an I/Oerror occurs
in thecurrent procedure. Normally, when an I/Oerror occurs, an error messageisprinted
andprogramexecutionisstopped. If ON_IOERRORiscalledandanI/Orelatederror later
occursin thesameprocedureactivation, control istransferred tothedesignated statement
with the error code stored in the system variable !ERROR_STATE. The text of the error
message is contained in !ERROR_STATE.MSG.
The effect of ON_IOERROR can be canceled by using the label NULL in the call.
Calling Sequence
ON_IOERROR, Label
Example
Thefollowingcodesegment readsan integer fromthekeyboard. If an invalid number is
entered, the program re-prompts.
i = 0 Number to read
valid = 0 Valid flag
WHILE valid EQ 0 DO BEGIN
ON_IOERROR, bad_num
READ, 'Enter Number: ', i
VALID = 1 If weget here, i is good.
bad_num: IF NOT valid THEN $
PRINT, 'You entered an invalid number.'
ENDWHILE
END
See Also
CATCH, MESSAGE, ON_ERROR, and Controlling Errors in Chapter 10 of Building
IDL Applications.
IDL Reference Guide ONLINE_HELP
ONLINE_HELP
The ONLINE_HELP procedure invokes the hypertext help viewer. If called with no
arguments, it simply starts the help viewer with the default IDL help le displayed.
Optionally, a different book, a keyword search string, or a context number can be
specied. Notethat thisprocedureisintendedfor usein user-written routines. Toinvoke
IDLs online help from the command line, it is much simpler to use the? command.
Calling Sequence
ONLINE_HELP[, Topic]
Arguments
Topic
An optional string that contains text to be searched for using the viewers keyword
search (not full-text search) facility. If thisargument isomitted, thespecied or default
book is displayed at its beginning.
If theCONTEXT keyword isset, thisargument should bean integer value(not astring)
that represents the context number of the help topic to be displayed.
Keywords
BOOK
Set this keyword to a string containing the name of the online help book to be
displayed. If this keyword is omitted, the default IDL help le is displayed. Any le
speciedbythiskeywordmust bein theappropriateformat for theviewer beinginvoked
(e.g., on Windows, the le must be a Windows.hlp help le; on Unix, it must be a
HyperHelp .hlp le).
By default, thisstringshould bethenameof alefound in thedefault location for IDLs
online help les (i.e., wherever the leidl.hlp is installed), without a path or le
extension. However, if the FULL_PATH keyword is set, this string should be a complete
path and lename to the online help le you wish to display.
CONTEXT
Set thiskeywordtoindicatethat theTopicargument isan integer valuethat representsthe
context number of the help topic to be displayed. This keyword is intended for use with
user-compiled help les that contain topics that have been mapped to specic context
numbers when they were compiled (using the [ MAP] section of the help project le).
Specifyinganon-existent context number causestherst topicof therequested help le
to be displayed.
ONLINE_HELP IDL Reference Guide
The help les shipped with IDL do not contain explicit context number mappings.
Therefore, the context numbers of specic topics are undocumented, unknown, and
subject to change between releases of the help system.
FULL_PATH
Set thiskeywordtoindicatethat thestringspeciedbytheBOOKkeywordisthefull path
to the le, rather than the default shorthand le specication, as described above.
QUIT
Set this keyword to close the online help viewer.
Example
Use the following command to launch the online help viewer and perform a keyword
search on the subject handle :
ONLINE_HELP, 'handle'
To open a help le named adg.hlp, located in the default help le directory, use the
command:
ONLINE_HELP, BOOK='adg.hlp'
To open a help le named myhelp.hlp, located in a directory named
/usr/home/keith, use the command:
ONLINE_HELP, BOOK='/usr/home/keith/myfile.hlp', /FULL_PATH
To open themyhelp.hlp le from the previous example and display the topic
corresponding to context number 100, use the command:
ONLINE_HELP, 100, /CONTEXT, $
BOOK='/usr/home/keith/myfile.hlp', /FULL_PATH
See Also
MK_HTML_HELP, Getting Help with IDL on page 241 of Using IDL
IDL Reference Guide OPEN
OPEN
The three OPEN procedures open a specied le for input and/or output.
OPENR (OPEN Read) opens an existing le for input only.
OPENW(OPEN Write) opensanewlefor input and output. When creatinganewle
under VMS, anewlewiththesamenameandahigher versionnumber iscreated. Under
other operatingsystems, if theleexists, it istruncatedanditsoldcontentsaredestroyed.
OPENU (OPEN Update) opens an existing le for input and output.
Notethat under Microsoft Windows, theseproceduresopen lesin text modebydefault.
Openinglesin text modepreservescarriage-return, line-feed (CR/LF) paris, which are
expectedbyDOSandWindowstext editors. Alsobydefault, certainother routinesinIDL
for Windows (PRINTF, for example) will change the mode of a le from binary to text.
The Windows-only keywords BINARY and NOAUTOMODE help control these
behaviors.
Calling Sequence
There are three forms of the OPEN procedure:
OPENR, Unit, File[, Record_Length]
OPENW, Unit, File[, Record_Length]
OPENU, Unit, File[, Record_Length]
Arguments
Unit
The unit number to be associated with the opened le.
File
A string containing the name of the le to be opened. Note the following platform-
specic behaviors:
Under Unix, the lename can contain any wildcard characters recognized by the shell
specied by the SHELL environment variable. However, it is faster not to use wildcards
because IDL doesnt use the shell to expand le names unless it has to. No wildcard
characters are allowed under VMS.
Under VMS, lenames that do not have a le extension are assumed to have the .DAT
extension. No such processing of le names occurs under Unix.
OPEN IDL Reference Guide
Record_Length
TheRecord_Length argument has meaning only under VMS. It species the le record
size in bytes. This argument is required when creating new, xed-length les, and is
optional when opening existing les. If this argument is present when creating variable-
length record les, it species the maximum allowed record size. If this argument is
present and no le organization keyword is specied, xed-length records are implied.
Duetolimitationsin RMS(theVMSRecord Management System), thelength of records
must alwaysbean even number of bytes. Odd record lengthsarethereforeautomatically
rounded up to the nearest even boundary.
Keywords
Note Platform-specic keywords are listed at the end of this section.
APPEND
Set thiskeyword to open thelewith thelepointer at theend of thele, ready for data
to beappended. Normally, theleisopened with thelepointer at thebeginningof the
le. Under Unix, use of APPEND prevents OPENW from truncating existing le
contents.
BUFSIZE
Set thiskeyword toavaluegreater than 512tospecify thesizeof theI/Obuffer (in bytes)
used when reading and writing les. Setting BUFSIZE=1 (or any other value less than
512) sets the buffer to the default size, which is platform-specic. Set BUFSIZE=0 to
disable I/O buffering.
Notethat thebuffer sizeisonlychangeablewhen readingand writingstreamles. Under
Unix, theNOSTDIOkeywordmust not beset. Alsonot that thesystemstdiomaychoose
to ignore the buffer size setting.
DELETE
Set this keyword to delete the le when it is closed.
Caution SettingtheDELETEkeywordcausestheletobedeletedevenif it wasopenedfor read-
only access. In addition, once a le is opened with this keyword, there is no way to
cancel its operation.
ERROR
A named variable to place the error status in. If an error occurs in the attempt to open
File, IDL normally takes the error handling action dened by the ON_ERROR and/or
ON_IOERROR procedures. OPEN always returns to the caller without generating an
error message when ERROR is present. A nonzero error status indicates that an error
occurred. The error message can then be found in the system variable !ERR_STRING.
For example, statements similar to the following can be used to detect errors:
OPENR, 1, 'demo.dat', ERROR = err Try to open thefiledemo.dat.
IF (err NE 0) then PRINTF, -2, !ERR_STRING
If err is nonzero, somethinghap-
pened. Print theerror messageto
thestandarderrorfile(logicalunit
-2).
F77_UNFORMATTED
Unformattedvariable-lengthrecordlesproducedbyUnixFORTRANprogramscontain
extrainformation alongwith thedatain order toallowthedatatobeproperlyrecovered.
This method is necessary because FORTRAN input/output is based on record-oriented
les, whileUnix lesaresimplebytestreamsthat donot imposeanyrecordstructure. Set
theF77_UNFORMATTEDkeyword toread and writethisextrainformation in thesame
manner asf77(1), sothat datatobeprocessedbybothIDLandFORTRAN. See UNIX-
Specic Information on page 213 of Building IDL Applications for further details.
Caution Do not confused this keyword with the VMS-only keyword FORTRAN.
GET_LUN
Set thiskeyword to usetheGET_LUN procedureto set thevalueof Unitbeforetheleis
opened. Instead of using the two statements:
GET_LUN, Unit
OPENR, Unit, 'data.dat'
you can use the single statement:
OPENR, Unit, 'data.dat', /GET LUN
MORE
If MOREisset, andthespeciedFileisaterminal, thenall output tothisunit isformatted
in a manner similar to the Unix more(1) command and sent to the standard output
stream. Output pausesat thebottomof eachscreen, at whichpoint theuser can pressone
of the following keys:
Space: Display the next page of text.
Return: Display the next line of text.
q or Q: Suppress all remaining output.
h or H: Display this list of options.
Example Thefollowingstatementsshowhowtooutput alenamedtext.dattotheterminal:
OPENR, inunit, 'text.dat', /GET_LUN Open thetext file.
OPENW, outunit, '/dev/tty', /GET_LUN, /MORE
Open theterminal as a file.
line = '' & READF, inunit, line Read thefirst line.
WHILE NOT EOF(inunit) DO BEGIN Whilethereis text left, output it.
PRINTF, outunit, line
READF, inunit, line
ENDWHILE
FREE_LUN, inunit & FREE_LUN, outunit Closethefiles and deallocatethe
units.
Under VMS, the MORE keyword is only allowed for stream mode les.
SWAP_ENDIAN
Set thiskeyword to swap byteorderingfor multi-bytedatawhen performingbinary I/O
on thespecied le. Thisisuseful when accessinglesalso used by another systemwith
byte ordering different than that of the current host.
SWAP_IF_BIG_ENDIAN
Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the
current system has big endian byte ordering. This keyword does not refer to the byte
ordering of the input data, but to the computer hardware.
SWAP_IF_LITTLE_ENDIAN
Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the
current system has little endian byte ordering. This keyword does not refer to the byte
ordering of the input data, but to the computer hardware.
VAX_FLOAT
The opened le contains VAX format oating point values. This keyword implies little
endian byte ordering for all data contained in the le, and superceeds any setting of the
SWAP_ENDIAN, SWAP_IF_BIG_ENDIAN, or SWAP_IF_LITTLE_ENDIAN keywords.
The default setting for this keyword is FALSE. Under VMS, starting the VAX_FLOAT
option totheIDL commandat startuphastheeffect of changingthisdefault andmaking
it TRUE. See Command Line Options on page 68 for details on this qualier. You can
change this setting at runtime using the VAX_FLOAT function.
Caution Please read Note On IEEE to VAX Format Conversion on page 790 before using
this feature.
WIDTH
The desired output width. When using the defaults for formatted output, IDL uses the
following rules to determine where to break lines:
If the output le is a terminal, the terminal width is used. Under VMS, if the le has
xed-length records or a maximum record length, the record length is used.
Otherwise, a default of 80 columns is used.
The WIDTH keyword allows the user to override this default.
XDR
Set this keyword to open the le for unformatted XDR (eXternal Data Representation)
I/O via the READU and WRITEU procedures. Use XDR to make binary data portable
between different machine architectures by reading and writing all data in a standard
format. Whenaleisopenfor XDRaccess, theonlyI/Odatatransfer proceduresthat can
be used with it are READU and WRITEU. XDR is described in Portable Unformatted
Input/Output on page 197 of Building IDL Applications.
Under VMS, the XDR keyword can only be used with stream les.
Macintosh-Only Keywords
MACCREATOR
Use this keyword to specify a four-character scalar string identifying the Macintosh le
creator code of the le being created. For example, set
MACCREATOR = 'MSWD'
to create a le with the creator codeMSWD. The default creator code isMIDL.
MACTYPE
Use this keyword to specify a four-character scalar string identifying the Macintosh le
type of the le being created. For example, set
MACTYPE = 'PICT'
to create a le of typePICT. The default le type isTEXT.
Windows-Only Keywords
BINARY
Set this keyword to treat opened les as binary les. When writing text to a binary le,
CR/LFpairsarewritten asLFonly. Notethat settingtheBINARYkeywordalonedoesnot
ensure that a routine that writes to the le will not change the mode to text.
NOAUTOMODE
Set this keyword to prevent IDL routines such as PRINTF from automatically changing
the mode from binary to text, or vice versa.
Unix-Only Keywords
NOSTDIO
Set this keyword to disable all use of the standard Unix I/O for the le, in favor of direct
callstotheoperatingsystem. Thisallowsdirect accesstodevices, such astapedrives, that
aredifcult or impossibletouseeffectivelythrough thestandardI/O. Usingthiskeyword
has the following implications:
No formatted or associated (ASSOC) I/O is allowed on the le. Only READU and
WRITEU are allowed.
Normally, attemptingtoreadmoredatathan isavailablefromalecausestheunlled
spacetobeset tozeroandanerror tobeissued. Thisdoesnot happenwithlesopened
with NOSTDIO. When using NOSTDIO, the programmer must check the transfer
count, either viatheTRANSFER_COUNT keywordstoREADUand WRITEU, or the
FSTAT function.
The EOF and POINT_LUN functions cannot be used with a le opened with NOST-
DIO.
Each call to READU or WRITEU maps directly to Unix read(2) and write(2) system
calls. The programmer must read the Unix system documentation for these calls and
documentation on thetarget deviceto determineif thereareany special rulesfor I/O
to that device. For example, the size of data that can be transferred to many cartridge
tape drives is often forced to be a multiple of 512 bytes.
VMS-Only Keywords
BLOCK
Set this keyword to process the le using RMS block mode. In this mode, most RMS
processingisbypassed and IDL readsand writesto thelein disk block units. Such les
can only be accessed via unformatted I/O commands. Block mode les are treated as an
uninterpreted stream of bytes in a manner similar to Unix stream les.
For best performance, by default IDL usesRMSblock modefor xed length record les.
However, when theSHARED keyword ispresent, IDL usesstandard RMSmode. Do not
specify both BLOCK and SHARED.
This keyword is ignored when used with stream les.
Note With some controller/disk combinations, RMS does not allow transfer of an odd
number of bytes.
DEFAULT
A scalar string that provides a default le specication from which missing parts of the
File argument are taken. For example, to make .LOG be the default le extension when
opening a new le, use the command:
OPENW, 'DATA', DEFAULT='.LOG'
This statement will open the le DATA.LOG.
EXTENDSIZE
Fileextension isarelativelyslowoperation, andit isdesirabletominimizethenumber of
times it is done. In order to avoid the unacceptable performance that would result from
extendingaleasingleblock at atime, VMSextendsitssizebyadefault number of blocks
in an attempt to trade a small amount of wasted disk space for better performance. The
EXTENDSIZEkeyword overridesthedefault, and speciesthenumber of disk blocksby
which the le should be extended. This keyword is often used in conjunction with the
INITIALSIZE and TRUNCATE_ON_CLOSE keywords.
FIXED
Set this keyword to indicate that the le has xed-length records. TheRecord_Length
argument is required when opening new, xed-length les.
FORTRAN
Set this keyword to use FORTRAN-style carriage control when creating a new le. The
rst byte of each record controls the formatting.
INITIALSIZE
Theinitial sizeof theleallocation in blocks. Thiskeyword isoften used in conjunction
with the EXTENDSIZE and TRUNCATE_ON_CLOSE keywords.
KEYED
Set this keyword to indicate that the le has indexed organization. Indexed les are
discussed in VMS-Specic Information on page 217 of Building IDL Applications.
LIST
Set thiskeywordtospecifycarriage-return carriagecontrol when creatinganewle. If no
carriage-control keyword is specied, LIST is the default.
NONE
Set thiskeyword tospecifyexplicit carriagecontrol when creatinganewle. When using
explicit carriagecontrol, VMSdoesnot add any carriagecontrol information to thele,
and theuser must explicitly add any desired carriagecontrol to thedatabeingwritten to
the le.
PRINT
Set this keyword to send the le to SYS$PRINT, the default system printer, when it is
closed.
SEGMENTED
Set this keyword to indicate that the le has VMS FORTRAN-style segmented records.
Segmentedrecordsareamethodbywhich FORTRANallowslogical recordstoexist with
record sizesthat exceed themaximumpossiblephysical record sizessupported by VMS.
Segmentedrecordlesareuseful primarilyfor passingdatabetween FORTRANandIDL
programs.
SHARED
Set thiskeyword to allowother processesread and writeaccessto thelein parallel with
IDL. If SHAREDisnot set, read-onlylesareopenedfor readsharingandread/writeles
are not shared. The SHARED keyword cannot be used with STREAM les.
Caution It isnot agood ideatoallowshared writeaccesstolesopen in RMSblock mode. In
block mode, VMScannot performtheusual recordlockingthat preventslecorrup-
tion. It is therefore possible for multiple writers to corrupt a block mode le. This
warningalsoappliestoxed-lengthrecorddiskles, whicharealsoprocessedinblock
mode. When using SHARED, do not specify either BLOCK or UDF_BLOCK.
STREAM
Set this keyword to open the le in stream mode using the Standard C Library (stdio).
SUBMIT
Set thiskeyword tosubmit theletoSYS$BATCH, thedefault systembatch queue, when
it is closed.
SUPERSEDE
Set thiskeyword toallowan existingletobesuperseded byanewleof thesamename,
type, and version.
TRUNCATE_ON_CLOSE
Set thiskeyword to freeany unused disk spaceallocated to thelewhen theleisclosed.
Thiskeywordcan beusedtoget ridof excessallocationscausedbytheEXTENDSIZEand
INITIALSIZE keywords. If the SHARED keyword is set, or the le is open for read-only
access, TRUNCATE_ON_CLOSE has no effect.
UDF_BLOCK
Set thiskeyword to createalesimilar to thosecreated with theBLOCK keyword except
that new les are created with the RMS undened record type. Files created in this way
can only be accessed by IDL in block mode, and cannot be processed by many VMS
utilities. Do not specify both UDF_BLOCK and SHARED.
VARIABLE
Set thiskeyword toindicatethat thelehasvariable-length records. If theRecord_Length
argument is present, it species the maximum record size. Otherwise, the only limit is
that imposed by RMS (32767 bytes). If no le organization is specied, variable-length
records are the default.
Caution VMSvariablelength recordshavea2-byterecord-length descriptor at thebeginning
of eachrecord. BecausetheFSTATfunctionreturnsthelengthof thedataleincluding
the record descriptors, reading a le with VMS variable length records into a byte
array of the size returned by FSTAT will result in an RMS EOF error.
format and back (IEEE to VAX to IEEE) is not a completely reversable operation, and
be recovered.
directions.
See VMS Floating-Point Arithmetic in IDL 5.1 on page 1401 for more information.
Example
ThefollowingexampleopenstheIDL distribution lepeople.dat and readsan image
from that le:
Open people.dat on fileunit
number 1. TheFILEPATH func-
tionisusedtoreturnthefull path
nameto this distribution file.
image=BYTARR(192, 192, /NOZERO) Definea variableinto which the
imagewill beread.
READU, 1, image Read thedata.
TV, image Display theimage.
See Also
CLOSE, GET_LUN, POINT_LUN, PRINT/PRINTF, READ/READF, READU,
VAX_FLOAT, WRITEU
OPLOT IDL Reference Guide
OPLOT
The OPLOT procedure plots vector data over a previously-drawn plot. It differs from
PLOT only in that it doesnot generateanewaxis. Instead, it usesthescalingestablished
bythemost recent call toPLOT andsimplyoverlaysaplot of thedataon theexistingaxis.
Calling Sequence
OPLOT, [X,] Y
Arguments
X
A vector argument. If X is not specied, Y is plotted as a function of point number
(starting at zero). If both arguments are provided, Y is plotted as a function of X.
created with OPLOT are limited to the range and precision of single-precision oating-
point values.
Y
The ordinate data to be plotted. This argument is converted to single-precision oating-
point before plotting.
Keywords
MAX_VALUE
Themaximumvaluetobeplotted. If thiskeywordispresent, datavaluesgreater than the
value of MAX_VALUE are treated as missing and are not plotted. Note that the IEEE
oating-point value NaN is also treated as missing data. (See Special Floating-Point
oating-point values.)
MIN_VALUE
The minimum value to be plotted. If this keyword is present, data values less than the
value of MIN_VALUE are treated as missing and are not plotted. Note that the IEEE
NSUM
The presence of this keyword indicates the number of data points to average when
plotting. If NSUM is larger than 1, every group of NSUM points is averaged to produce
one plotted point. If there aremdata points, then m/NSUM points are displayed. On
logarithmic axes a geometric average is performed.
IDL Reference Guide OPLOT
It isconvenient to useNSUM when thereisan extremely largenumber of datapointsto
plot because it plots fewer points, the graph is less cluttered, and it is quicker.
POLAR
Set this keyword to produce polar plots. TheX and Y vector parameters, both of which
must be present, are rst converted from polar to Cartesian coordinates. The rst
parameter is the radius, and the second is expressed in radians.
Example To make a polar plot, use the command:
OPLOT, /POLAR, R, THETA
THICK
Controlsthethicknessof thelinesconnectingthepoints. Athicknessof 1.0isnormal, 2.0
is double wide, etc.
not listed above. CLIPCOLORLINESTYLENOCLIPPSYM SUBTITLESYMSIZET3D
ZVALUE.
Example
Create a simple dataset by entering:
D = SIN(FINDGEN(100)/EXP(FINDGEN(100)/50))
Create an X-Y plot of vector D by entering:
PLOT, D
Overplot the sine of D as a thick, dashed line by entering:
OPLOT, SIN(D), LINESTYLE = 5, THICK = 2
See Also
OPLOTERR, PLOT
OPLOTERR IDL Reference Guide
OPLOTERR
The OPLOTERR procedure plots error bars over a previously drawn plot. A plot of X
versusYwith error barsdrawn fromY- Err toY+ Err iswritten totheoutput deviceover
any plot already there.
oploterr.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
OPLOTERR, [ X ,] Y , Err [, Psym ]
Arguments
X
An optional array of Xvalues. Theprocedurecheckswhether or not thethird parameter
passed is a vector to decide if X was passed. If X is not passed, then INDGEN(Y) is
assumed for the X values.
Y
The array of Y values. Y cannot be of type string.
Err
The array of error bar values.
PSYM
The plotting symbol to use (default = +7).
See Also
ERRPLOT, OPLOT, PLOTERR
IDL Reference Guide P_CORRELATE
P_CORRELATE
TheP_CORRELATEfunctioncomputesthepartial correlationcoefcient of adependent
variable and one particular independent variable when the effects of all other variables
involved are removed.
p_correlate.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = P_CORRELATE(X, Y, C)
Arguments
X
independent variable data.
Y
dependent variable data.
C
An integer, single-, or double-precision oating-point array that species the
independent variable data whose effects are to be removed. The columns of this two-
dimensional array correspond to then-element vectors of independent variable data.
Examples
Dene three sample populations:
X0 = [64, 71, 53, 67, 55, 58, 77, 57, 56, 51, 76, 68]
X1 = [57, 59, 49, 62, 51, 50, 55, 48, 52, 42, 61, 57]
X2 = [ 8, 10, 6, 11, 8, 7, 10, 9, 10, 6, 12, 9]
result = P_CORRELATE(X0, X1, REFORM(X2, 1, N_ELEMENTS(X2)))
Computethepartialcorrelationof
X0 and X1 with theeffects of X2
removed.
The result should be 0.533469.
See Also
A_CORRELATE, CORRELATE, C_CORRELATE, M_CORRELATE, R_CORRELATE
PCOMP IDL Reference Guide
PCOMP
ThePCOMPfunctioncomputestheprincipal componentsof anm-column, n-rowarray,
wheremisthenumber of variablesand nisthenumber of observationsor samples. The
principal componentsof amultivariatedataset may beused to restatethedatain terms
of derived variablesor may beused to reducethedimensionality of thedataby reducing
thenumber of variables(columns). Theresult isan nvariables-column (nvariables m),
n-row array of derived variables.
Calling Sequence
Result = PCOMP(A)
Arguments
A
An m-column, n-row, single- or double-precision oating-point array.
Keywords
COEFFICIENTS
Usethiskeyword to specify anamed variablethat will contain theprincipal components
used to compute the derived variables. The principal components are the coefcients of
the derived variables and are returned in an m-column, m-row array. The rows of this
arraycorrespondtothecoefcientsof thederivedvariables. Thecoefcientsarescaledso
that thesumsof their squaresareequal totheeigenvaluefromwhich theyarecomputed.
This keyword must be initialized to a nonzero value before calling PCOMP if the
principal components are desired.
COVARIANCE
Set this keyword to compute the principal components using the covariances of the
original data. The default is to use the correlations of the original data to compute the
principal components.
DOUBLE
EIGENVALUES
Usethiskeywordtospecifyanamedvariablethat will containaone-column, m-rowarray
of eigenvaluesthat correspondtotheprincipal components. Theeigenvaluesarelistedin
descending order. This keyword must be initialized to a nonzero value before calling
PCOMP if the eigenvalues are desired.
IDL Reference Guide PCOMP
NVARIABLES
Use this keyword to specify the number of derived variables. A value of zero, negative
values, andvaluesinexcessof theinput arrayscolumndimensionresult inacompleteset
(m-columns and n-rows) of derived variables.
STANDARDIZE
Set thiskeywordtoconvert thevariables(thecolumns) of theinput arraytostandardized
variables (variables with a mean of zero and variance of one).
VARIANCES
Usethiskeywordtospecifyanamedvariablethat will containaone-column, m-rowarray
of variances. The variances correspond to the percentage of the total variance for each
derived variable.
Example
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 derived variables based upon the principal components. The
COEFFICENTS, EIGENVALUES, and VARIANCES keywords must be initialized as
nonzero values prior to calling PCOMP.
coefficients = 1 & eigenvalues = 1 & variances = 1
PCOMP IDL Reference Guide
result = PCOMP(array, COEFFICIENTS = coefficients, $
EIGENVALUES = eigenvalues, VARIANCES = variances)
PRINT, result, FORMAT = '(4(f5.1, 2x))'
IDL prints:
81.4 15.5 -5.5 0.5
102.7 11.1 -4.1 0.6
109.9 20.3 -6.2 0.5
110.5 13.8 -6.3 0.6
81.8 17.1 -4.9 0.6
104.8 6.2 -5.4 0.6
121.3 8.1 -5.2 0.6
111.3 12.6 -4.0 0.6
97.0 6.4 -4.4 0.6
102.5 7.8 -6.1 0.6
118.5 11.2 -5.3 0.6
118.9 9.1 -4.7 0.6
81.5 8.8 -6.3 0.6
88.0 13.4 -3.9 0.6
74.3 7.5 -4.8 0.6
113.4 12.0 -5.1 0.6
109.7 7.7 -5.6 0.6
117.5 5.5 -5.7 0.6
91.4 12.0 -6.1 0.6
102.5 10.6 -4.9 0.6
PRINT, coefficients
IDL prints:
0.983668 0.947119 0.358085 0.925647
0.118704 -0.265644 0.932897 -0.215227
-0.134015 -0.179266 0.0378060 0.311214
-0.0185792 0.0161747 0.00707525 0.000456858
PRINT, eigenvalues
IDL prints:
2.84969
1.00128
0.148380
0.000657078
IDL Reference Guide PCOMP
PRINT, variances
IDL prints:
0.712422
0.250319
0.0370950
0.000164269
Therst twoderivedvariablesaccount for 96.3%of thetotal varianceof theoriginal data.
See Also
CORRELATE, EIGENQL
PLOT IDL Reference Guide
PLOT
The PLOT procedure draws graphs of vector arguments. If one parameter is used, the
vector parameter is plotted on the ordinate versus the point number on the abscissa. To
plot one vector as a function of another, use two parameters. PLOT can also be used to
create polar plots by setting the POLAR keyword.
Calling Sequence
PLOT, [X,] Y
Arguments
X
A vector argument. If X is not specied, Y is plotted as a function of point number
(starting at zero). If both arguments are provided, Y is plotted as a function of X.
created with PLOT are limited to the range and precision of single-precision oating-
point values.
Y
The ordinate data to be plotted. This argument is converted to single-precision oating-
point before plotting.
Keywords
ISOTROPIC
Set this keyword to force the scaling of the X and Y axes to be equal.
MAX_VALUE
MIN_VALUE
IDL Reference Guide PLOT
NSUM
The presence of this keyword indicates the number of data points to average when
plotting. If NSUM is larger than 1, every group of NSUM points is averaged to produce
one plotted point. If there aremdata points, then m/NSUM points are displayed. On
logarithmic axes a geometric average is performed.
It isconvenient to useNSUM when thereisan extremely largenumber of datapointsto
plot because it plots fewer points, the graph is less cluttered, and it is quicker.
POLAR
Set this keyword to produce polar plots. TheX and Y vector parameters, both of which
must be present, are rst converted from polar to Cartesian coordinates. The rst
parameter istheradius, and thesecond istheangle(expressed in radians). For example,
to make a polar plot, you would use a command such as:
PLOT, /POLAR, R, THETA
THICK
Controlsthethicknessof thelinesconnectingthepoints. A thicknessof 1.0isnormal, 2
is double wide, etc.
XLOG
Set this keyword to specify a logarithmic X axis, producing a log-linear plot. Set both
XLOGand YLOGto producealog-logplot. Notethat logarithmicaxesthat haveranges
of less than a decade are not labeled.
YNOZERO
Set thiskeyword to inhibit settingtheminimumYaxisvalueto zero when theYdataare
all positiveand nonzero, and no explicit minimumYvalueisspecied (usingYRANGE,
or !Y.RANGE). By default, theYaxisspanstherangeof 0to themaximumvalueof Y, in
the case of positive Y data. Set bit 4 in !Y.STYLE to make this option the default.
YLOG
Set this keyword to specify a logarithmic Y axis, producing a linear-log plot. Set both
XLOGand YLOGto producealog-logplot. Notethat logarithmicaxesthat haveranges
of less than a decade are not labeled.
DATA DAYS_OF_WEEK DEVICE FONT LINESTYLE MONTHS NOCLIP NODATA
NOERASE NORMAL POSITION PSYM SUBTITLE SYMSIZE T3D THICK TICKLEN
TITLE [ XYZ] CHARSIZE [ XYZ] GRIDSTYLE [ XYZ] MARGIN [ XYZ] MINOR
[ XYZ] RANGE [ XYZ] STYLE [ XYZ] THICK [ XYZ] TICKFORMAT [ XYZ] TICKLEN
PLOT IDL Reference Guide
[ XYZ] TICKNAME [ XYZ] TICKS [ XYZ] TICKV [ XYZ] TICK_GET [ XYZ] TITLE
ZVALUE.
Example
ThePLOT procedurehasmany keywordsthat allowyou to createavast variety of plots.
Here are a few simple examples using the PLOT command.
D = FINDGEN(100) Createa simpledataset.
PLOT, D, TITLE = 'Simple Plot' Createasimpleplotwiththetitle
SimplePlot
PLOT, SIN(D/3), COS(D/6) Plotoneargumentversusanother
PLOT, D, D, /POLAR, TITLE = 'Polar Plot'Createa polar plot
PLOT, SIN(D/10), PSYM=4, XTITLE='X Axis', YTITLE='Y Axis'
Useplottingsymbols instead of
connectinglines by includingthe
PSYMkeyword.LabeltheXandY
axes with XTITLE and YTITLE.
See Also
OPLOT, PLOTS
IDL Reference Guide PLOT_3DBOX
PLOT_3DBOX
ThePLOT_3DBOXprocedureplotsafunction of two variables(e.g., Z=f(X, Y)) insidea
3Dbox. Optionally, thedatacan beprojected onto the walls surroundingtheplot area.
plot_3dbox.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PLOT_3DBOX, X, Y, Z
Arguments
X
A vector (i.e., a one-dimensional array) of X coordinates.
Y
A vector of Y coordinates.
Z
A vector of Z coordinates. Z[i] is a function of X[i] and Y[i].
Keywords
GRIDSTYLE
Set this keyword to the linestyle index for the type of line to be used when drawing the
gridlines. Linestyles are described in Table 9-58:
Index Linestyle
0 Solid
1 Dotted
2 Dashed
3 Dash Dot
4 Dash Dot Dot Dot
5 Long Dashes
PLOT_3DBOX IDL Reference Guide
PSYM
Set this keyword to an plotting symbol index to be used in plotting the data. For more
information, see PSYM on page 105.
SOLID_WALLS
Set thiskeywordtocausetheboundary walls of theplot tobelledwiththecolor index
specied by the COLOR keyword.
XY_PLANE
Set this keyword to plot theX and Y values on the Z=0 axis plane.
XYSTYLE
Set thiskeyword to thelinestyleused to drawtheXYplaneplot. Seethetableabovefor a
list of linestyles.
XZ_PLANE
Set this keyword to plot theY and Z values on the Y=MAX(Y) axis plane.
XZSTYLE
Set thiskeyword to thelinestyleused to drawtheXZ planeplot. Seethetableabovefor a
list of linestyles.
YZ_PLANE
Set this keyword to plot theY and Z values on the X=MAX(X) axis plane.
YZSTYLE
Set thiskeyword to thelinestyleused to drawtheYZ planeplot. Seethetableabovefor a
list of linestyles.
SURFACE Keywords
In addition to the keywords described above, the AX, AZ, and ZAXIS keywords to the
SURFACE procedure are accepted by PLOT_3DBOX. See SURFACE on page 1090.
not listed above. BACKGROUND CHARSIZE CHARTHICK CLIP COLOR DATA
DEVICE LINESTYLE NOCLIP NOERASE NORMAL POSITION SUBTITLE T3D
THICK TICKLEN TITLE [ XYZ] CHARSIZE [ XYZ] GRIDSTYLE [ XYZ] MARGIN
[ XYZ] MINOR [ XYZ] RANGE [ XYZ] STYLE [ XYZ] THICK [ XYZ] TICKFORMAT
[ XYZ] TICKLEN [ XYZ] TICKNAME [ XYZ] TICKS [ XYZ] TICKV [ XYZ] TITLE .
IDL Reference Guide PLOT_3DBOX
Example
X = REPLICATE(5., 10.) Createsomedata to beplotted.
X1 = COS(FINDGEN(36)*10.*!DTOR)*2.+5.
X = [X, X1, X]
Y = FINDGEN(56)
Z = REPLICATE(5., 10)
Z1 = SIN(FINDGEN(36)*10.*!DTOR)*2.+5.
Z = [Z, Z1, Z]
PLOT_3DBOX, X, Y, Z, /XY_PLANE, /YZ_PLANE, /XZ_PLANE, $
/SOLID_WALLS, GRIDSTYLE=1, XYSTYLE=3, XZSTYLE=4, $
YZSTYLE=5, AZ=40, TITLE='Example Plot Box', $
XTITLE='X Coordinate', YTITLE='Y Coodinate', $
ZTITLE='Z Coordinate', SUBTITLE='Sub Title', $
/YSTYLE, ZRANGE=[0,10], XRANGE=[0,10], $
PSYM=-4, CHARSIZE=1.6 Createtheboxplotwithdatapro-
jected on all of thewalls. The
PSYMvalueof-4plotsthedataas
diamonds connected by lines.
See Also
PLOTS, SURFACE
PLOT_FIELD IDL Reference Guide
PLOT_FIELD
ThePLOT_FIELDprocedureplotsa2Deld. Nrandompointsarepicked, andfromeach
point a path is traced along the eld. The length of the path is proportional to the eld
vector magnitude.
plot_field.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PLOT_FIELD, U, V
Arguments
U
A 2D array giving the eld vector at each point in the U(X) direction.
V
A 2D array giving the eld vector at each point in the V(Y) direction.
Keywords
ASPECT
Set thiskeyword to theaspect ratio of theplot (i.e., theratio of theX sizeto Ysize). The
default is 1.0.
LENGTH
Set this keyword to the length of the longest eld vector expressed as a fraction of the
plotting area. The default is 0.1.
N
Set this keyword to the number of arrows to draw. The default is 200.
TITLE
Set this keyword to the title of plot. The default is Velocity Field.
Example
X = FINDGEN(20, 20) Createarray X.
Y = FINDGEN(20, 20)*3 Createarray Y.
PLOT_FIELD, X, Y Createplot.
IDL Reference Guide PLOT_FIELD
See Also
FLOW3, VEL, VELOVECT
PLOTERR IDL Reference Guide
PLOTERR
The PLOTERR procedure plots individual data points with error bars.
ploterr.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PLOTERR, [ X ,] Y , Err
Arguments
X
An optional array of Xvalues. Theprocedurechecksthenumber of argumentspassed to
decide if X was passed. If X is not passed, then INDGEN(Y) is assumed for the X values.
Y
The array of Y values. Y cannot be of type string.
Err
The array of error-bar values.
Keywords
TYPE
The type of plot to be produced. The possible types are:
1. X Linear - Y Linear (default)
2. X Linear - Y Log
3. X Log - Y Linear
4. X Log - Y Log
PSYM
The plotting symbol to use. The default is +7.
See Also
ERRPLOT, OPLOTERR, PLOT
IDL Reference Guide PLOTS
PLOTS
ThePLOTSprocedureplotsvectorsor pointson thecurrent graphicsdeviceineither two
or three dimensions. The coordinates can be given in data, device, or normalized form
using the DATA (the default), DEVICE, or NORMAL keywords.
TheCOLORkeywordcan beset toascalar or vector value. If it isset toavector value, the
linesegment connecting(X
i
, Y
i
) to(X
i+1
, Y
i+1
) isdrawn with acolor index of COLOR
i+1
.
In this case, COLOR must have the same number of elements asX and Y.
Calling Sequence
PLOTS, X [, Y [, Z]]
Arguments
X
A vector or scalar argument providing the X components of the points to be connected.
If only one argument is specied, X must be an array of either two or three vectors (i.e.,
(2,*) or (3,*)). In this special case, X[0,*] are taken as the X values, X[1,*] are
taken as the Y values, and X[2,*] are taken as the Z values.
Y
An optional argument providing the Y coordinate(s) of the points to be connected.
Z
An optional argument providing the Z coordinates of the points to be connected. If Z is
not provided, X and Y are used to draw lines in two dimensions.
Z has no effect if the keyword T3D is not specied and the system variable !P.T3D= 0.
Keywords
CONTINUE
Set thiskeyword to continuedrawingalinefromthelast point of themost recent call to
PLOTS.
Example
PLOTS, 0, 0 Position at (0,0).
PLOTS, 1, 1, /CONTINUE Draws vector from (0,0) to (1,1).
PLOTS, [2,3], [2,3], /CONTINUE Draws two vectors from (1,1) to
(2,2) to (3,3).
PLOTS IDL Reference Guide
not listed above. CLIP COLOR DATA DEVICE LINESTYLE NOCLIP NORMAL PSYM
SYMSIZE T3D THICK Z.
Examples
Draw a line from (100, 200) to (600, 700), in device coordinates, using color index 12:
PLOTS, [100,600], [200,700], COLOR=12, /DEVICE
Draw a polyline where the line color is proportional to the ordinate that ends each line
segment. First create datasets X and Y by entering:
X = SIN(FINDGEN(100)) & Y = COS(FINDGEN(100))
Now plot X and Y in normalized coordinates with colors as described above:
PLOTS, X, Y, COLOR = BYTSCL(Y, TOP=!D.N COLORS-1), /NORMAL
Load a good colortable to better show the result. Enter:
LOADCT, 13
Draw 3D vectors over an established SURFACE plot:
SURFACE, DIST(5), /SAVE TheSAVE keyword tells IDL to
savethe3Dtransformationestab-
lished by SURFACE.
PLOTS, [0,3], [0,3], [0,3], /T3D Draw a linebetween (0,0,0) and
(3,3,3). TheT3Dkeywordmakes
PLOTS usethepreviously estab-
lished 3D transformation.
(3,3,3).
(3,3,3).
See Also
ANNOTATE, XYOUTS
IDL Reference Guide PNT_LINE
PNT_LINE
The PNT_LINE function returns the perpendicular distance between a point P0 and a
linebetween pointsL0and L1. Thisfunction islimited bythemachineaccuracyof single
precision oating point.
pnt_line.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = PNT_LINE(P0, L0, L1 [ , Pl] )
Arguments
P0
The location of the point. P0 may have 2 to n elements, for n dimensions.
L0
One end-point of the line. L0 must have same number of elements asP0.
L1
The other end-point of the line. L1 must have the same number of elements asL0.
Pl
A named variable that will contain the location of the point on the line between L0 and
L1 that is closest to P0. Pl is not necessarily in the interval (L0, L1).
Keywords
INTERVAL
If set, and if thepoint on thelinebetween L0and L1that isclosest toP0isnot within the
interval (L0, L1), PNT_LINE will return the distance fromP0 to the closer of the two
endpointsL0 and L1.
Example
To print thedistancebetween thepoint (2,3) and thelinefrom(-3,3) to (5,12), and also
the location of the point on the line closest to (2,3), enter the following command:
PRINT, PNT_LINE([2,3], [-3,3], [5,12], Pl), Pl
IDL prints:
3.73705 -0.793104 5.48276
PNT_LINE IDL Reference Guide
See Also
CIR_3PNT, SPH_4PNT
IDL Reference Guide POINT_LUN
POINT_LUN
ThePOINT_LUNproceduresetsor obtainsthecurrent positionof thelepointer for the
specied le.
Note POINT_LUN cannot be used with les opened with the NOSTDIO keyword to the
OPENroutines. Dependingupon thedevicein question, theIOCTL function might
be used instead for les of this type.
Calling Sequence
POINT_LUN, Unit, Position
Arguments
Unit
Theleunit for thelein question. If Unitispositive, POINT_LUN setstheleposition
to the position given by Position. If negative, POINT_LUN gets the current le position
and assigns it to the variable given by Position. Note that POINT_LUN cannot be used
with the 3 standard le units (0, -1, and -2).
Position
If Unitispositive, Positiongivesthebyteoffset intotheleat whichthelepointer should
be set. For example, to rewind the le to the beginning, specify 0.
If Unitisnegative, Positionmust beanamed variableinto which thecurrent leposition
will bestored. Thereturnedtypewill bealongwordsignedinteger if theposition issmall
enough to t, and an unsigned 64-bit integer otherwise.
Under VMS, becareful tomovethelepointer onlytorecordboundaries. It isalwayssafe
to move to a le position that was previously obtained via POINT_LUN or the FSTAT
function. Fileswith indexed organization can only bepositioned to thebeginningof the
le.
Example
To movethelepointer 2048bytesinto theleassociated with leunit number 1, enter:
POINT_LUN, 1, 2048
To return the le pointer for le unit number 2, enter:
POINT_LUN, -2, pos
POINT_LUN IDL Reference Guide
See Also
GET_LUN, OPEN
IDL Reference Guide POLAR_CONTOUR
POLAR_CONTOUR
ThePOLAR_CONTOURproceduredrawsacontour plot fromdatainpolar coordinates.
Data can be regularly- or irregularly-gridded. All of the keyword options supported by
CONTOUR are available to POLAR_CONTOUR.
polar_contour.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
POLAR_CONTOUR, Z, Theta, R
Arguments
Z
The data values to be contoured. If the data is regularly gridded, Z must have the
dimensions (N_ELEMENTS(Theta), N_ELEMENTS(R). Note that the ordering of the
elements in the array Z is opposite that used by the POLAR_SURFACE routine.
Theta
A vector of angles in radians. For regularly-gridded data, Theta must have the same
number of elementsastherst dimension of Z. For ascattered grid, Thetamust havethe
same number of elements asZ.
R
A vector of radius values. For regularly-gridded data, R must have the same number of
elements as the second dimension of Z. For a scattered grid, R must have the same
number of elements asZ.
Keywords
POLAR_CONTOUR accepts all of the keywords accepted by the CONTOUR routine
except C_LABELS, DOWNHILL, FOLLOW, PATH_FILENAME, PATH_INFO, and
PATH_XY. See CONTOUR on page 300. In addition, there is one unique keyword:
SHOW_TRIANGULATION
Set this keyword to a color index to be used in overplotting the triangulation between
datapoints.
Example
The rst example uses POLAR_CONTOUR with regularly-gridded data:
nr = 12 Thenumber of radii.
POLAR_CONTOUR IDL Reference Guide
nt = 18 Thenumber of Thetas.
r = FINDGEN(nr)/(nr-1) Createa vector of radii.
theta = 2*!PI * FINDGEN(nt)/(nt-1) Createa vector of Thetas.
z = COS(theta*3) # (r-0.5)^2 Createsomedatavaluestobecon-
toured.
POLAR_CONTOUR, z, theta, r, /FILL, c_color=[2, 3, 4, 5]
Createthepolar contour plot.
See Also
CONTOUR
IDL Reference Guide POLAR_SURFACE
POLAR_SURFACE
ThePOLAR_SURFACEfunctioninterpolatesasurfacefrompolar coordinates(R, Theta,
Z) to rectangular coordinates(X, Y, Z). Thefunction returnsatwo-dimensional array of
the same type as Z.
polar_surface.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = POLAR_SURFACE(Z, R, Theta)
Arguments
Z
An array containingthesurfacevalueat each point. If thedataareregularly gridded in R
and Theta, Z is a two dimensional array, whereZi,j has a radius of Ri and an azimuth of
Thetaj. If thedataareirregularly-gridded, Ri and Thetai contain theradiusand azimuth
of each Zi. Note that the ordering of the elements in the array Z is opposite that used by
the POLAR_CONTOUR routine.
R
Theradius. If thedataareregularly gridded in Rand Theta, Zi,j hasaradiusof Ri. If the
dataareirregularly-gridded, Rmust havethesamenumber of elementsasZ, andcontains
the radius of each point.
Theta
The azimuth, in radians. If the data are regularly gridded in R and Theta, Zi,j has an
azimuth of Thetaj. If thedataareirregularly-gridded, Thetamust havethesamenumber
of elements asZ, and contains the azimuth of each point.
Keywords
GRID
Set this keyword to indicate that Z is regularly gridded in R and Theta.
SPACING
A two element vector containing the desired grid spacing of the resulting array in x and
y. If omitted, the grid will be approximately 51 by 51.
BOUNDS
Afour element vector, [ x
0
, y
0
, x
1
, y
1
] , containingthelimitsof thexygrid of theresulting
array. If omitted, the extent of input data sets the limits of the grid.
POLAR_SURFACE IDL Reference Guide
QUINTIC
Set this keyword to use quintic interpolation, which is slower but smoother than the
default linear interpolation.
MISSING
Use this keyword to specify a value to use for areas within the grid but not within the
convex hull of the data points. The default is 0.0.
Example
R = FINDGEN(50) / 50.0 Theradius.
THETA = FINDGEN(50) * (2 * !PI / 50.0) Theta.
Z = R # SIN(THETA) Makea function (tilted circle).
SURFACE, POLAR_SURFACE(Z, R, THETA, /GRID)
Show it.
See Also
POLAR Keyword (to PLOT)
IDL Reference Guide POLY
POLY
The POLY function evaluates a polynomial function of a variable. The result is equal to:
C
0
+ C
1
x + C
2
x
2
+ ...
poly.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = POLY(X, C)
Arguments
X
The variable. This value can be a scalar, vector or array.
C
Thevector of polynomial coefcients. Thedegreeof thepolynomial isN_ELEMENTS(C)
- 1.
See Also
FZ_ROOTS
POLY_2D IDL Reference Guide
POLY_2D
ThePOLY_2Dfunctionperformspolynomial warpingof images. Thisfunctionperforms
a geometrical transformation in which the resulting array is dened by:
g [x, y] = f [x', y'] = f [a [x, y], b [x, y]]
whereg[ x, y] representsthepixel in theoutput imageat coordinate(x, y), and f [ x', y'] is
thepixel at (x', y') in theinput imagethat isused to deriveg[ x, y] . Thefunctionsa(x, y)
and b(x, y) arepolynomialsin xand yof degreeN, whosecoefcientsaregiven by Pand
Q, and specify the spatial transformation:
Either the nearest neighbor or bilinear interpolation methods can be selected.
Calling Sequence
Result = POLY_2D(Array, P, Q [, Interp [, Dim
x
, Dim
y
]])
Arguments
Array
A two-dimensional array of any basictypeexcept string. Theresult hasthesametypeas
Array.
P and Q
P and Q are arrays containing the polynomial coefcients. Each array must contain
(N+1)
2
elements (whereN is the degree of the polynomial). For example, for a linear
transformation, P and Q contain four elements and can be a 2 x 2 array or a 4-element
vector. P
i,j
containsthecoefcient used todeterminex, and istheweight of thetermx
j
y
i
.
ThePOLYWARPprocedurecanbeusedtot (x,y) asafunctionof (x,y) anddetermines
the coefcient arraysP and Q.
Interp
Set this argument to a 1to perform bilinear interpolation. Set this argument to 2 to
perform cubic convolution interpolation (as described under the CUBIC keyword,
below). Otherwise, the nearest neighbor method is used. For the linear case, (N=1),
bilinear interpolation requires approximately twice as much time as does the nearest
neighbor method.
x a x y , ( ) P
i j ,
x
j
y
i
j 0 =
N
i 0 =
N
= =
y b x y , ( ) Q
i j ,
x
j
y
i
j 0 =
N
i 0 =
N
= =
IDL Reference Guide POLY_2D
Dim
x
If present, Dim
x
speciesthenumber of columnsintheoutput. If omitted, theoutput has
the same number of columns asArray.
Dim
y
If present, Dim
y
speciesthenumber of rowsin theoutput. If omitted, theoutput hasthe
same number of rows asArray.
Keywords
CUBIC
improves the reconstruction properties of this algorithm. Note that cubic convolution
interpolation works only with one- and two-dimensional arrays.
0
, and f is sampled
with spacinglessthan or equal to 1/2
0
, then f can bereconstructed by convolvingwith
a sinc function: sinc(x) = sin (x) / (x).
CA, July 1974.
MISSING
Species the output value for points whosex, y is outside the bounds of Array. If
MISSING is not specied, the resulting output value is extrapolated from the nearest
pixel of Array.
Example
Some simple linear (degree one) transformations are:
POLY_2D IDL Reference Guide
POLY_2D isoften used in conjunction with thePOLYWARPprocedureto warp images.
Create and display a simple image by entering:
A = BYTSCL(SIN(DIST(250)), TOP=!D.TABLE_SIZE) & TV, A
Set up the arrays of original points to be warped by entering:
XO = [61, 62, 143, 133]
YO = [89, 34, 38, 105]
Set up the arrays of points to be t by entering:
XI = [24, 35, 102, 92]
YI = [81, 24, 25, 92]
Use POLYWARP to generate the P and Q inputs to POLY_2D by entering:
POLYWARP, XI, YI, XO, YO, 1, P, Q
To perform an image warping based on P and Q, enter:
B = POLY_2D(A, P, Q)
Display the new image by entering:
TV, B, 250, 250
Imagescan also bewarped over irregularly gridded control pointsusingtheWARP_TRI
procedure.
See Also
POLYWARP
P
0,0
P
1,0
P
0,1
P
1,1
Q
0,0
Q
1,0
Q
0,1
Q
1,1
Effect
0 0 1 0 0 1 0 0 Identity
0 0 0.5 0 0 1 0 0 Stretch X by a factor of 2
0 0 1 0 0 2.0 0 0 Shrink Y by a factor of 2
z 0 1 0 0 1 0 0 Shift left by z pixels
0 1 0 0 0 0 1 0 Transpose
Table 9-59: Simple Transformations for Use with POLY_2D
IDL Reference Guide POLY_AREA
POLY_AREA
The POLY_AREA function returns the area of a polygon given the coordinates of its
vertices. This value is always positive.
It is assumed that the polygon hasn vertices with n sides and the edges connect the
vertices in the order:
[ (x1,y1), (x2,y2), ... , (xn,yn), (x1,y1)]
such that the last vertex is connected to the rst vertex.
poly_area.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = POLY_AREA(X, Y)
Arguments
X
An n-element vector of X coordinate locations for the vertices.
Y
An n-element vector of Y coordinate locations for the vertices.
Keywords
SIGNED
If set, returnsasignedarea. Polygonswithedgestraversedincounterclockwiseorder have
a positive area; polygons traversed in the clockwise order have a negative area.
See Also
DEFROI, POLYFILLV
POLY_FIT IDL Reference Guide
POLY_FIT
The POLY_FIT function performs a least-square polynomial t with optional error
estimates and returns a vector of coefcients with a length of NDegree+1.
The POLY_FIT routine uses matrix inversion. A newer version of this routine, SVDFIT,
uses Singular Value Decomposition. The SVD technique is more exible, but slower.
Another version of this routine, POLYFITW, performs a weighted least square t.
poly_fit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = POLY_FIT(X, Y, NDegree[,Yt, Yband, Sigma, Corrm] )
Arguments
X
Y
NDegree
The degree of the polynomial to t.
Yt
Anamedvariablethat will contain thevector of calculated Yvalues. Thesevalueshavean
error of plus or minusYband.
Yband
A named variable that will contain the error estimate for each point.
Sigma
A named variable that will contain the standard deviation in Y units.
Corrm
A named variable that will contain the correlation matrix of the coefcients.
Keywords
DOUBLE
Set this keyword to force computations to be done in double-precision arithmetic.
IDL Reference Guide POLY_FIT
Example
Inthisexample, weuseXandYdatacorrespondingtotheknownpolynomial f (x) = 0.25
- x + x
2
. Using POLY_FIT to compute a second degree polynomial t returns the exact
coefcients (to within machine accuracy).
X = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]
Definean11-elementvectorofin-
dependent variabledata.
Y = [0.25, 0.16, 0.09, 0.04, 0.01, 0.00, 0.01, 0.04, 0.09, 0.16, 0.25]
Definean11-elementvectorofde-
pendent variabledata.
result = POLY_FIT(X, Y, 2) Computethesecond degreepoly-
nomial fit to thedata.
PRINT, result Print thecoefficients.
IDL prints:
0.24999996
-0.99999974
0.99999975
See Also
COMFIT, CURVEFIT, GAUSSFIT, POLYFITW, REGRESS, SFIT, SVDFIT
POLYFILL IDL Reference Guide
POLYFILL
The POLYFILL procedure lls the interior of a region of the display enclosed by an
arbitrary two or three-dimensional polygon. The available lling methods are: solid ll,
hardware-dependent ll pattern, parallel lines, or apattern contained in an array. Not all
methods are available on every hardware output device.
The polygon is dened by a list of connected vertices stored in X, Y, and Z. The
coordinates can be given in data, device, or normalized form using the DATA, DEVICE,
or NORMAL keywords.
Line-ll method: Filling using parallel lines is device-independent and works on all
devicesthat can drawlines. Crosshatchingcan besimulated by performingmultiplells
withdifferent orientations. Thespacing, linestyle, orientation, andthicknessof thelling
lines can be specied using the corresponding keyword parameters. The LINE_FILL
keyword selects this lling style, but is not required if either the ORIENTATION or
SPACING parameters are present.
Solid ll method: Most, but not all, devices can ll with a solid color. Solid ll is
performed usingtheline-ll method for devicesthat dont havethishardwarecapability.
Method specifying keyword parameters are not required for solid lling.
Patterned ll: The method of patterned lling and the usage of various ll patterns is
hardwaredependent. Thell pattern arraycan beexplicitlyspecied with thePATTERN
keyword parameter for someoutput devices. If thisparameter isomitted, thepolygon is
lled with the hardware-dependent pattern index specied by the FILL_PATTERN
keyword.
Calling Sequence
POLYFILL, X [, Y [, Z]]
Arguments
X
Avector argument providingtheXcoordinatesof thepointstobeconnected. Thevector
must containat least threeelements. If onlyoneargument isspecied, Xmust beanarray
of either two or three vectors (i.e., (2,*) or (3,*)). In this special case, the vector
X[0,*] species the X values, X[1,*] species Y, and X[2,*] contain the Z values.
Y
A vector argument providing the Y coordinates of the points to be connected. Y must
contain at least three elements.
IDL Reference Guide POLYFILL
Z
An optional vector argument providingtheZ coordinatesof thepointsto beconnected.
If Z isnot provided, Xand Yareused todrawlinesin twodimensions. Z must contain at
least three elements. Z has no effect if the keyword T3D is not specied and the system
variable !P.T3D= 0.
Keywords
FILL_PATTERN
Thehardwaredependent ll pattern index for thePOLYFILLprocedure. If omittedor set
to 0, a solid ll results.
IMAGE_COORD
(Z-Buffer output only) A2x narraycontainingthell pattern arraysubscriptsof each of
then polygon vertices. Use this keyword in conjunction with the PATTERN keyword to
warp images over 2D and 3D polygons.
IMAGE_INTERP
(Z-Buffer output only) Species the method of sampling the PATTERN array when the
IMAGE_COORD keyword is present. The default method is to use nearest-neighbor
sampling. Bilinear interpolation sampling is performed if IMAGE_INTERP is set.
LINE_FILL
Set this keyword to indicate that polygons are to be lled with parallel lines, rather than
usingsolid or patterned llingmethods.When usingtheline-drawingmethod of lling,
the thickness, linestyle, orientation, and spacing of the lines may be specied with
keywords.
PATTERN
Arectangular array of pixelsgivingthell pattern. If thiskeyword parameter isomitted,
POLYFILL lls the area with a solid color. The pattern array may be of any size; if it is
smaller than the lled area the pattern array is cyclically repeated.
Note WhenthedisplaydeviceselectedisPostScript (PS), POLYFILLcanonlyll withsolid
colors.
For example, to ll the current plot window with a grid of dots, enter the following
commands:
PAT = BYTARR(10,10) Definepattern array as 10 by 10.
PAT(5,5) = 255 Set center pixel to bright.
POLYFILL, !X.WINDOW([0,1,1,0]), $
!Y.WINDOW([0,0,1,1]), /NORM, PAT = PATFill therectangle
defined by thefour corners of the
window with thepattern.
SPACING
The spacing, in centimeters, between the parallel lines used to ll polygons.
POLYFILL IDL Reference Guide
TRANSPARENT
(Z-Buffer output only) species the minimum pixel value to draw in conjunction with
thePATTERN and IMAGE_COORD keywords. Pixelslessthan thisvaluearenot drawn
and the Z-buffer is not updated.
not listed above. CLIP COLOR DATA DEVICE LINESTYLE NOCLIP NORMAL
ORIENTATION T3D THICK Z.
Z-Buffer-Specic Keywords
Certain keyword parameters are only active when the Z-buffer is the currently selected
graphics device: IMAGE_COORD, IMAGE_INTERP, TRANSPARENT and COLOR.
Theseparametersallowimagesto bewarped over 2D or 3D polygons, and theoutput of
shaded polygons. For examples, see The Z-Buffer Device on page62.
For shaded polygons, the COLOR keyword can specify an array that contains the color
index at each vertex. Color indices are linearly interpolated between vertices. If COLOR
containsascalar, theentirepolygon isdrawn with thegiven color index, just aswith the
other graphics output devices.
Images can be warped over polygons by passing in the image with the PATTERN
parameter, and a(2, n) array containingtheimagespacecoordinatesthat correspond to
each of the N vertices with the IMAGE_COORD keyword.
TheIMAGE_INTERPkeyword indicatesthat bilinear interpolation isto beused, rather
thanthedefault nearest-neighbor sampling. Pixelslessthanthevalueof TRANSPARENT
are not drawn, simulating transparency.
Example
Fill arectangular polygonthat hasthevertices(30,30), (100, 30), (100, 100), and(30, 100)
in device coordinates. Create the vectors of X and Y values by entering:
X = [30, 100, 100, 30] & Y = [30, 30, 100, 100]
Fill the polygon with color index 175 by entering:
POLYFILL, X, Y, COLOR = 175, /DEVICE
See Also
POLYFILLV
IDL Reference Guide POLYFILLV
POLYFILLV
ThePOLYFILLV function returnsavector containingtheone-dimensional subscriptsof
the array elements contained inside a polygon dened by vectorsX and Y.
If no points are contained within the polygon, a -1 is returned and an informational
messageisprinted. TheXand Yparametersarevectorsthat contain thesubscriptsof the
verticesthat denethepolygon in thecoordinatesystemof thetwo-dimensional S
x
byS
y
array. TheS
x
and S
y
parameters dene the number of columns and rows in the array
enclosing the polygon. At least three points must be specied, and all points should lie
within the limits: 0 Xi < Sx and 0 Y
i
< Syi.
Aswith thePOLYFILL procedure, thepolygon isdened by connectingeach point with
its successor and the last point with the rst. This function is useful for dening,
analyzing, and displaying regions of interest within a two-dimensional array.
The scan line coordinate system dened by Rogers in Procedural Elements for Computer
Graphics, McGraw-Hill, 1985, page 71, is used. In this system, the scan lines are
considered to pass through the center of each row of pixels. Pixels are activated if the
center of thepixel isto theright of theintersection of thescan lineand thepolygon edge
within the interval.
Calling Sequence
Result = POLYFILLV(X, Y, S
x
, S
y
[, Run_Length])
Arguments
X
A vector containing the X subscripts of the vertices that dene the polygon.
Y
A vector containing the Y subscripts of the vertices that dene the polygon.
S
x
The number of columns in the array surrounding the polygon.
S
y
The number of rows in the array surrounding the polygon.
Run_Length
Set thisoptional parameter toanonzerovaluetomakePOLYFILLVreturnavector of run
lengths, rather thansubscripts. For largepolygons, aconsiderablesavingsinspaceresults.
Whenrun-lengthencoded, eachelement withanevensubscript result containsthelength
of the run, and the following element contains the starting index of the run.
POLYFILLV IDL Reference Guide
Example
Todeterminethemean andstandarddeviation of theelementswithin atriangular region
dened by theverticesat pixel coordinates(100, 100), (200, 300), and (300, 100), inside
a 512 x 512 array called DATA, enter the commands:
P = DATA(POLYFILLV([100,200,300], [100,300,100], 512, 512))
Get thesubscripts of theelements
insidethetriangle.
STD = STDEV(P,MEAN) UsetheSTDEVfunctiontoobtain
themeanandstandarddeviation
of theselected elements.
See Also
POLYFILL
IDL Reference Guide POLYFITW
POLYFITW
ThePOLYFITWfunction performsaweighted least-squarepolynomial t with optional
error estimates and returns a vector of coefcients with a length of NDegree+1.
ThePOLYFITWroutineusesmatrix inversion. Anewer version of thisroutine, SVDFIT,
uses Singular Value Decomposition. The SVD technique is more exible, but slower.
Another version of thisroutine, POLY_FIT, performsaleast squaret without weighting.
polyfitw.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = POLYFITW(X, Y, Weights, NDegree[,Yt, Yband, Sigma, Corrm] )
Arguments
X
Y
A vector of independent variables, the same length asX.
Weights
A vector of weights, the same length asX and Y.
NDegree
The degree of the polynomial to t.
Yt
Anamedvariablethat will contain thevector of calculated Yvalues. Thesevalueshavean
error of plus or minusYband.
Yband
A named variable that will contain the error estimate for each point.
Sigma
A named variable that will contain the standard deviation of the returned coefcients.
Corrm
A named variable that will contain the correlation matrix of the coefcients.
See Also
CURVEFIT, GAUSSFIT, POLY_FIT, REGRESS, SFIT, SVDFIT
POLYSHADE IDL Reference Guide
POLYSHADE
ThePOLYSHADEfunctionreturnsashaded-surfacerepresentationof oneor moresolids
described by a set of polygons. This function accepts, as arguments, an array of three-
dimensional vertices and a list of the indices of the vertices that describe each polygon.
Output is a two-dimensional byte array containing the shaded image unless the current
graphics output device is the Z-buffer. If the current output device is the Z-buffer, the
resultsaremergedwiththeZ-bufferscontentsandthefunction result containsadummy
value.
Shading values are determined from one of three sources: a light source model, a user-
specied array containing vertex shade values, or a user-specied array containing
polygon shade values.
The shaded surface is constructed using the scan line algorithm. The default shading
model isacombination of diffusereection and depth cueing. With thisshadingmodel,
polygons are shaded using either constant shading, in which each polygon is given a
constant intensity, or with Gouraud shading where the intensity is computed at each
vertex and then interpolated over the polygon. Use the SET_SHADING procedure to
control the direction of the light source and other shading parameters.
User-specied shading arrays allow 4-dimensional displays that consist of a surface
dened by a set of polygons, shaded with values from another variable.
Calling Sequence
Result = POLYSHADE(Vertices, Polygons)
or
Result = POLYSHADE(X, Y, Z, Polygons)
Arguments
Vertices
A (3, n) array containing the X, Y, and Z coordinates of each vertex. Coordinates can be
in either data or normalized coordinates, depending on which keywords are present.
X, Y, Z
The X, Y, and Z coordinates of each vertex can, alternatively, be specied as three array
expressions of the same dimensions.
Polygons
An integer or longword arraycontainingtheindicesof theverticesfor each polygon. The
verticesof each polygon should belisted in counterclockwiseorder when observed from
outsidethesurface. Thevertex description of each polygon isavector of theform: [ n, i
0
,
i
1
, ..., i
n-1
] and the array Polygonsis the concatenation of the lists of each polygon. For
IDL Reference Guide POLYSHADE
example, to render a pyramid consisting of four triangles, Polygonswould contain 16
elements, made by concatenating four, four-element vectors of the form [ 3, V
0
, V
1
, V
2
] .
V
0
, V
1
, and V
2
are the indices of the vertices describing each triangle.
Keywords
DATA
Set this keyword to indicate that the vertex coordinates are in data units, the default
coordinate system.
NORMAL
Set this keyword to indicate that coordinates are in normalized units, within the three
dimensional (0,1) cube.
POLY_SHADES
An array expression, with thesamenumber of elementsastherearepolygonsdened in
thePolygonsarray, containing the color index used to render each polygon. No
interpolation isperformed if all pixelswithin agiven polygon havethesameshadevalue.
For most displays, this parameter should be scaled into the range of bytes.
SHADES
An array expression, with thesamenumber of elementsasVertices, containingthecolor
index at each vertex. The shading of each pixel is interpolated from the surrounding
SHADEvalues. For most displays, thisparameter shouldbescaledintotherangeof bytes.
Caution When using the SHADES keyword on True Color devices, we recommend that
decomposed color support be turned off, by setting DECOMPOSED=0 for
DEVICE on page 419.
T3D
Set this keyword to use the three-dimensional to two-dimensional transformation
contained in the homogeneous 4 by 4 matrix !P.T. Note that if T3D is set, !P.T must
contain a valid transformation matrix. The SURFACE, SCALE3, and T3D procedures
(and others) can all be used to set up transformations.
TOP
The maximum shading value when light source shading is in effect. The default value is
one less than the number of colors available in the currently selected graphics device.
XSIZE
The number of columns in the output image array. If this parameter is omitted, the
number of columns is equal to the X size of the currently selected display device.
Warning: The size parameters should be explicitly specied when the current graphics
device is PostScript or any other high-resolution device. Making the output image the
default full device size is likely to cause an insufcient memory error.
POLYSHADE IDL Reference Guide
YSIZE
Thenumber of rowsin theoutput imagearray. If thisparameter isomitted, thenumber
of rows is equal to the Y resolution of the currently selected display device.
Example
POLYSHADE is often used in conjunction with SHADE_VOLUME for volume
visualization. The following example creates a spherical volume dataset and renders an
isosurface from that dataset:
SPHERE = FLTARR(20, 20, 20) Createan empty, 3D array.
FOR X=0,19 DO FOR Y=0,19 DO FOR Z=0,19 DO $
SPHERE(X, Y, Z) = SQRT((X-10)^2 + (Y-10)^2 + (Z-10)^2)
Createthespherical dataset.
SHADE_VOLUME, SPHERE, 8, V, P Findtheverticesandpolygonsfor
a density level of 8.
SCALE3, XRANGE=[0,20], YRANGE=[0,20], ZRANGE=[0,20]
Set up an appropriate3D trans-
formationsowecanseethesphere.
This step is very important.
image = POLYSHADE(V, P, /T3D) Render theimage. Notethat the
T3Dkeywordhasbeensetsothat
thepreviously-established 3D
transformation is used.
TV, image Display theimage.
See Also
PROJECT_VOL, RECON3, SET_SHADING, SHADE_SURF, SHADE_VOLUME,
VOXEL_PROJ
IDL Reference Guide POLYWARP
POLYWARP
The POLYWARP procedure performs polynomial spatial warping.
Using least squares estimation, POLYWARP determines the coefcientsKx(i,j) and
Ky(i,j) of the polynomial functions:
Kx and Ky can be used as inputs P and Q to the built-in function POLY_2D. This
coordinatetransformation may bethen used to map fromXo, Yocoordinatesinto Xi, Yi
coordinates.
polywarp.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
POLYWARP, Xi, Yi, Xo, Yo, Degree, Kx, Ky
Arguments
Xi, Yi
Vectors of X and Y coordinates to be t as a function of Xo and Yo.
Xo, Yo
Vectorsof X and Yindependent coordinates. Thesevectorsmust havethesamenumber
of elements asXi and Yi.
Degree
The degree of the t. The number of coordinate pairs must be greater than or equal to
(Degree+1)
2
.
Kx
Anamedvariablethat will containthearrayof coefcientsfor Xi asafunctionof (Xo,Yo).
This parameter is returned as a (Degree+1) by (Degree+1) element array.
Ky
A named variable that will contain the array of coefcients for Yi. This parameter is
returned as a (Degree+1) by (Degree+1) element array.
X
i
Kx
i j ,
Xo
j
Yo
i

i j ,
=
Y
i
Ky
i j ,
Xo
j
Yo
i

i j ,
=
POLYWARP IDL Reference Guide
Example
Thefollowingexampleshowshowtodisplayan imageandwarpit usingthePOLYWARP
and POLY_2D routines.
Create and display the original image by entering:
A = BYTSCL(SIN(DIST(250)))
TVSCL, A
Now set up the Xis and Yis. Enter:
XI = [24, 35, 102, 92]
YI = [81, 24, 25, 92]
Enter the Xos and Yos:
XO = [61, 62, 143, 133]
YO = [89, 34, 38, 105]
Run POLYWARP to obtain a Kx and Ky:
POLYWARP, XI, YI, XO, YO, 1, KX, KY
Create a warped image based on Kx and Ky with POLY_2D:
B = POLY_2D(A, KX, KY)
Display the new image:
TV, B
See Also
POLY_2D, WARP_TRI
IDL Reference Guide POPD
POPD
ThePOPDprocedurechangesthecurrent workingdirectorytothedirectorysavedonthe
top of the directory stack maintained by the PUSHD and POPD procedures. This top
entry is then removed from the stack.
Attempting to pop a directory when the stack is empty causes a warning message to be
printed. The current directory is not changed in this case. The common block
DIR_STACK is used to store the directory stack.
popd.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
POPD
See Also
CD, PRINTD, PUSHD
POWELL IDL Reference Guide
POWELL
The POWELL procedure minimizes a user-written function Func of two or more
independent variables using the Powell method. POWELL does not require a user-
supplied analytic gradient.
POWELL isbased on theroutinepowell described in section 10.5of Numerical Recipes
Calling Sequence
POWELL, P, Xi, Ftol, Fmin, Func
Arguments
P
On input, Pisan n-element vector specifyingthestartingpoint. On output, it isreplaced
with the location of the minimum.
Xi
On input, Xi is an initial n by n element array whose columns contain the initial set of
directions (usually then unit vectors). On output, it is replaced with the then-current
directions.
Ftol
An input value specifying the fractional tolerance in the function value. Failure to
decrease by more than Ftol in one iteration signals completeness. For single-precision
computations, avalueof 1.0 10
-4
isrecommended; for double-precisioncomputations,
a value of 1.0 10
-8
is recommended.
Fmin
On output, Fmin contains the value at the minimum-point P of the user-supplied
function specied by Func.
Func
A scalar string specifying the name of a user-supplied IDL function of two or more
independent variables to be minimized. This function must accept a vector argument X
and return a scalar result.
For example, suppose we wish to minimize the function
To evaluate this expression, we dene an IDL function named POWFUNC:
f x y , ( ) x 2y + ( )e
x
2
y
2
=
IDL Reference Guide POWELL
FUNCTION powfunc, X
RETURN, (X[0] + 2.0*X[1]) * EXP(-X[0]^2 -X[1]^2)
END
Keywords
DOUBLE
ITER
Usethiskeyword tospecifyan output variablethat will beset tothenumber of iterations
performed.
ITMAX
Use this keyword to specify the maximum allowed number of iterations. The default is
200.
Caution POWELL halts once the value specied with ITMAX has been reached.
Example
We can use POWELL to minimize the function POWFUNC given above.
ftol = 1.0e-4 Definethefractional tolerance.
P = [.5d, -.25d] Definethestartingpoint.
xi = TRANSPOSE([[1.0, 0.0],[0.0, 1.0]]) Definethestartingdirectional vec-
tors in column format.
POWELL, P, xi, ftol, fmin, 'powfunc' Minimizethefunction.
PRINT, P Print thesolution point.
IDL prints:
-0.31622777 -0.63245552
The exact solution point is [ -0.31622777, -0.63245553] .
PRINT, fmin Print thevalueat thesolution
point.
IDL prints:
-0.95900918
The exact minimum function value is -0.95900918.
See Also
AMOEBA, DFPMIN
PRIMES IDL Reference Guide
PRIMES
The PRIMES function computes the rst K prime numbers. The result is aK-element
long integer vector.
primes.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = PRIMES(K)
Arguments
K
An integer or long integer scalar that species the number of primes to be computed.
Example
Compute the rst 25 prime numbers.
PRINT, PRIMES(25)
IDL prints:
2 3 5 7 11 13
17 19 23 29 31 37
41 43 47 53 59 61
67 71 73 79 83 89
97
IDL Reference Guide PRINT/PRINTF
PRINT/ PRINTF
The two PRINT procedures perform formatted output. PRINT performs output to the
standard output stream (IDL le unit -1), while PRINTF requires a le unit to be
explicitly specied.
Calling Sequence
PRINT [, Expr
1
, ..., Expr
n
]
or
PRINTF[, Unit, Expr
1
, ..., Expr
n
]
Arguments
Unit
For PRINTF, Unit species the le unit to which the output is sent.
Expr
i
The expressions to be output.
Keywords
AM_PM
FORMAT keyword.
DAYS_OF_WEEK
FORMAT keyword.
FORMAT
If FORMAT is not specied, IDL uses its default rules for formatting the output.
FORMAT allows the format of the output to be specied in precise detail, using a
FORTRAN-style specication. See Using Explicitly Formatted Input/Output on page
169 of Building IDL Applications.
MONTHS
FORMAT keyword.
PRINT/PRINTF IDL Reference Guide
STDIO_NON_FINITE
Set thiskeyword to allowthewritingof datalesreadableby Cor FORTRAN programs
on a given platform; it is otherwise unnecessary.The various systems supported by IDL
differ widelyin therepresentation usedfor non-niteoatingpoint values(i.e., NaNand
Innity). Consider that thefollowingareall possiblerepresentationsfor NaN on at least
one IDL platform:
NaN, NanQ, ?.0000, nan0x2, nan0x7, 1.#QNAN, -1.#IND0.
And the following are considered to be Innity:
Inf, Infinity, ++.0000, ----.0000, 1.#INF
On input, IDL can recognize any of these, but on output, it uses the same standard
representation on all platforms. Thispromotescross-platformconsistency. TocauseIDL
to use the system C library sprintf() function to format such values, yielding the
native representation for that platform, set the STDIO_NON_FINITE keyword.
VMS Keywords
REWRITE
When writing data to a le with indexed organization, set the REWRITE keyword to
specifythat thedatashouldupdatethecontentsof themost recentlyinput recordinstead
of creating a new record.
Format Compatibility
If the FORMAT keyword is not present and PRINT is called with more than one
argument, and the rst argument is a scalar string starting with the characters $(, this
initial argument istaken to betheformat specication, just asif it had been specied via
the FORMAT keyword. This feature is maintained for compatibility with version 1 of
VMS IDL.
Example
To print the string IDL is fun. enter the command:
PRINT, 'IDL is fun.'
To print the same message to the open le associated with le unit number 2, use the
command:
PRINTF, 2, 'IDL is fun.'
See Also
ANNOTATE, MESSAGE, WRITEU, XYOUTS
IDL Reference Guide PRINTD
PRINTD
The PRINTD procedure prints the contents of the directory stack maintained by the
PUSHD and POPD procedures. The contents of the directory stack are listed on the
default output device. The common block DIR_STACK is used to store the directory
stack.
printd.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PRINTD
See Also
CD, POPD, PUSHD
PROFILE IDL Reference Guide
PROFILE
The PROFILE function extracts a prole from an image and returns a oating-point
vector containing the values of the image along the prole line marked by the user.
profile.pro in thelib subdirectory of the IDL distribution.
Using PROFILE
Tomark aprolelineafter callingPROFILE, click intheimagewiththeleft mousebutton
tomark thebeginningandendingpoints. Thepixel coordinatesof theselectedpointsare
displayed in the IDL command log.
Calling Sequence
Result = PROFILE(Image[, XX, YY])
Arguments
Image
The data array representing the image. This array can be of any type except complex.
XX
A named variable that will contain the X coordinates of the points along the selected
prole.
YY
A named variable that will contain the Y coordinates of the points along the selected
prole.
Keywords
NOMARK
Set this keyword to inhibit marking the image with the prole line.
XSTART
ThestartingXlocation of thelower-left corner of Image. If thiskeyword isnot specied,
0 is assumed.
YSTART
ThestartingYlocation of thelower-left corner of Image. If thiskeyword isnot specied,
0 is assumed.
IDL Reference Guide PROFILE
Example
Display an image, select a prole and plot that prole in a new window.
A = BYTSCL(DIST(256)) Createan image.
TV, A Display theimage.
R = PROFILE(A) Extract a profilefrom theimage.
Mark two points on the image with the mouse.
WINDOW, /FREE Createa new plottingwindow.
PLOT, R Plot theprofile.
Note The PROFILES procedure is an interactive version of this routine.
See Also
PROFILES
PROFILER IDL Reference Guide
PROFILER
The PROFILER procedure allows you to access the IDL Code Proler. The IDL Code
Proler helps you analyze the performance of your applications. You can easily monitor
the calling frequency and execution time for procedures and functions.
Calling Sequence
PROFILER[, Module]
Arguments
Module
The program to which changes in proling will be applied. If Moduleis not specied,
proling changes will be applied to all currently-compiled programs.
Note TheModuleisoften named with respect tothelein which it isstored. For example,
the lebuild_it.pro may contain the module, build_it. If you specify the le
name, you will incur a syntax error.
Keywords
CLEAR
Set this keyword to disable proling of Moduleor of all compiled modules if Moduleis
not specied.
OUTPUT
Set this keyword to a specied variable in which to store the results of the REPORT
keyword.
REPORT
Set thiskeywordtoreport theresultsof proling. If you enter aprogramat thecommand
line, the PROFILER procedure will report the status of all the specied modules used
either since the beginning of the IDL session, or since the PROFILER was reset.
RESET
Set this keyword to clear the results of proling.
SYSTEM
Set this keyword to prole IDL system procedures and functions. By default, only user-
written or library les, which have been compiled, are proled.
IDL Reference Guide PROFILER
Example
PROFILER, /SYSTEM IncludeIDL system procedures
and functions when profiling.
A= DIST(500) Createa dataset usingthelibrary
functionDIST. NotethatDISTis
immediately compiled.
PROFILER, /REPORT Retrievetheprofilingresults.
IDL prints:
Module Type Count Only(s) Avg.(s) Time(s) Avg.(s)
FINDGEN (S) 1 0.000239 0.000239 0.000239 0.000239
FLTARR (S) 1 0.010171 0.010171 0.010171 0.010171
N_ELEMENTS (S) 1 0.000104 0.000104 0.000104 0.000104
ON_ERROR (S) 1 0.000178 0.000178 0.000178 0.000178
SQRT (S) 251 0.099001 0.000394 0.099001 0.000394
TV (S) 1 2.030000 2.030000 2.030000 2.030000
See Also
Debugging in IDL, chapter 6 of Using IDL.
PROFILES IDL Reference Guide
PROFILES
The PROFILES procedure interactively draws row or column proles of an image in a
separate window. A new window is created and the mouse location in the original
window is used to plot proles in the new window.
profiles.pro in thelib subdirectory of the IDL distribution.
Using PROFILES
Movethemousewithin theoriginal imageinteractivelycreatesproleplotsin thenewly-
created prolewindow. Pressingtheleft mousebutton togglesbetween rowand column
proles. The right mouse button exits
Calling Sequence
PROFILES, Image
Arguments
Image
The variable that represents the image displayed in current window. This data need not
bescaledintobytes. Theprolegraphsaremadefromthisarray, even if it isnot currently
displayed.
Keywords
ORDER
Set this keyword to 1 for images written top down or 0 for bottom up. Default is the
current value of !ORDER.
SX
Starting X position of the image in the window. If this keyword is omitted, 0 is assumed.
SY
Starting Y position of the image in the window. If this keyword is omitted, 0 is assumed.
WSIZE
The size of the PROFILES window as a fraction or multiple of 640 by 512.
IDL Reference Guide PROFILES
Example
Create and display an image and use the PROFILES routine on it.
A = BYTSCL(DIST(256)) Createan image.
PROFILES, A, WSIZE = .5 Run thePROFILES routine.
A 320 x 256 pixel PROFILES window should appear. Move the cursor over the original
image to see the prole at the cursor position. Press the left mouse button to toggle
between rowandcolumn proles. Presstheright mousebutton (with thecursor over the
original image) to exit the routine.
See Also
PROFILE
PROJECT_VOL IDL Reference Guide
PROJECT_VOL
ThePROJECT_VOL function returnsatwo-dimensional imagethat istheprojection of
a 3D volume of data onto a plane (similar to an X-ray). The returned image is a
translucent renderingof thevolume(thehighest datavalueswithin thevolumeshowup
asthebrightest regionsin thereturned image). Depth queuingand opacity may beused
toaffect theimage. Thevolumeisprojected usinga4x4matrix, soanytypeof projection
may beused includingperspective. Typically thesystemviewingmatrix (!P.T) isused as
the 4x4 matrix.
Note that the VOXEL_PROJ procedure performs many of the same functions as this
routine, and is faster.
project_vol.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Return = PROJECT_VOL(Vol, X_Sample, Y_Sample, Z_Sample)
Arguments
Vol
A 3D array of any type except string or structure containing the three dimensional
volume of data to project.
X_Sample
A long integer specifying the number of rays to project along the X dimension of the
image. The returned image will have the dimensionsX_sampleby Y_sample.
Y_Sample
A long integer specifying the number of rays to project along the Y dimension of the
image. To preservethecorrect aspect ratio of thedata, Y_sampleshould equal X_sample.
Z_Sample
Alonginteger specifyingthenumber of samplestotakealongeach ray. Higher valuesfor
X_sample, Y_sample, and Z_sampleincrease the image resolution as well as execution
time.
Keywords
DEPTH_Q
Set this keyword to indicate that the image should be created using depth queuing. The
depth queuing should be a single oating-point value between 0.0 and 1.0. This value
speciesthebrightnessof thefarthest regionsof thevolumerelativetotheclosest regions
IDL Reference Guide PROJECT_VOL
of the volume. A value of 0.0 will cause the back side of the volume to be completely
blacked out, whileavalueof 1.0indicatesthat theback sidewill showup just asbright as
the front side. The default is 1.0 (indicating no depth queuing).
OPAQUE
A 3D array of any type except string or structure, with the same size and dimensions as
Vol. Thisarrayspeciestheopacityof each cell in thevolume. OPAQUEvaluesof 0allow
all light to passthrough. OPAQUEvaluesarecumulative. For example, if aray emanates
fromadatavalueof 50, and then passesthrough 10opaquecells(each with adatavalue
of 0 and an opacity value of 5) then that ray would be completely blocked out (the cell
with the data value of 50 would be invisible on the returned image). The default is no
opacity.
TRANS
A 4x4 oating-point array to use as the transformation matrix when projecting the
volume. The default is to use the system viewing matrix (!P.T).
Example
Use the T3D routine to set up a viewing projection and render a volume of data using
PROJECT_VOL. First, create some data:
vol = RANDOMU(S, 40, 40, 40)
FOR I=0, 10 DO vol = SMOOTH(vol, 3)
vol = BYTSCL(vol(3:37, 3:37, 3:37))
opaque = RANDOMU(S, 40, 40, 40)
FOR I=0, 10 DO opaque = SMOOTH(opaque, 3)
opaque = BYTSCL(opaque(3:37, 3:37, 3:37), TOP=25B)
Set up the view:
xmin = 0 & ymin = 0 & zmin = 0
xmax = 34 & ymax = 34 & zmax = 34
!X.S = [-xmin, 1.0] / (xmax - xmin)
!Y.S = [-ymin, 1.0] / (ymax - ymin)
!Z.S = [-zmin, 1.0] / (zmax - zmin)
T3D, /RESET
T3D, TRANSLATE=[-0.5, -0.5, -0.5]
T3D, SCALE=[0.7, 0.7, 0.7]
T3D, ROTATE=[30, -30, 60]
T3D, TRANSLATE=[0.5, 0.5, 0.5]
PROJECT_VOL IDL Reference Guide
Generate and display the image:
img = PROJECT_VOL(vol, 64, 64, 64, DEPTH_Q=0.7, $
OPAQUE=opaque, TRANS=(!P.T))
TVSCL, img
See Also
POLYSHADE, VOXEL_PROJ
IDL Reference Guide PS_SHOW_FONTS
PS_SHOW_FONTS
The PS_SHOW_FONTS procedure displays all the PostScript fonts that IDL knows
about, with both the StandardAdobe and ISOLatin1 encodings. Each display takes a
separate page, and each character in each font is shown with its character index.
A PostScript le is produced, one page per font/mapping combination. The output le
containsalmost 70pagesof output. APostScript previewer isrecommended rather than
sending it to a printer.
ps_show_fonts.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PS_SHOW_FONTS
Keywords
NOLATIN
Set this keyword to prevent output of ISOLatin1 encodings.
See Also
PSAFM
PSAFM IDL Reference Guide
PSAFM
The PSAFM procedure takes an Adobe Font Metrics le as input and generates a new
AFM le in the format that IDL likes. This new le differs from the original in the
following ways:
Information not used by IDL is removed.
AFM les with the AdobeStandardEncoding are supplemented with an
ISOLatin1Encoding.
psafm.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PSAFM, Input_Filename, Output_Filename
Arguments
Input_Filename
A string that contains the name of existing AFM le from Adobe.
Output_Filename
A string that species the name of new IDL-format AFM le to be created.
See Also
PS_SHOW_FONTS
IDL Reference Guide PSEUDO
PSEUDO
ThePSEUDOprocedurecreatesapseudo-color tablebasedon theLHB(Lightness, Hue,
and Brightness) system and loads it.
The pseudo-color mapping used is generated by rst translating from the LHB
coordinatesystemtotheLABcoordinatesystem, ndingNcolorsspreadout alongahelix
that spansthisLABspace(supposedlyanear maximal entropymappingfor theeye, given
aparticular N) andremappingback intotheRGB(Red, Green, andBlue) colorspace. The
result is loaded as the current colortable.
pseudo.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PSEUDO, Litlo, Lithi, Satlo, Sathi, Hue, Loops [, Colr]
Arguments
Litlo
Starting lightness, from 0 to 100%.
Lithi
Ending lightness, from 0 to 100%.
Satlo
Sathi
Hue
Starting hue, in degrees, from 0 to 360.
Loops
The number of loops of hue to make in the color helix. This value can range from 0 to
around 3 to 5 and need not be an integer.
Colr
An optional (256,3) integer array in which the new R, G, and B values are returned.
Red = Colr[ *,0] , green = Colr[ *,1] , blue = Colr[ *,2] .
See Also
COLOR_CONVERT, COLOR_QUAN
PTR_FREE IDL Reference Guide
PTR_FREE
The PTR_FREE procedure destroys the heap variables pointed at by its pointer
arguments. Any memory used by theheap variableisreleased, and thevariableceasesto
exist. No change is made to the arguments themselves and all pointers to the destroyed
variablescontinuetoexist. Such pointersareknown asdanglingreferences. PTR_FREEis
theonly way that pointer heap variablescan bedestroyed. If PTR_FREEisnot called on
aheapvariable, it continuestoexist until theIDLsessionends, evenif nopointersremain
that can be used to reference it.
Note that PTR_FREE does not recurse. That is, if the heap variable pointed at by
pointer1 containspointer2, destroyingpointer1 will not destroy theheap variable
pointed at by pointer2. Take care not to lose the only pointer to a heap variable by
destroying a pointer to a heap variable that contains that pointer.
Calling Sequence
PTR_FREE, P
1
, ... , P
n
Arguments
P
i
Scalar or array arguments of pointer type. If the NULL pointer is passed, PTR_FREE
ignores it quietly.
IDL Reference Guide PTR_NEW
PTR_NEW
ThePTR_NEWfunction providestheprimarymechanismfor creatingheap variables. It
returns a pointer to the created variable.
Calling Sequence
Result = PTR_NEW([ InitExpr] )
Argument
InitExpr
If InitExpr is provided, PTR_NEW uses it to initialize the newly created heap variable.
Notethat thenewheap variabledoesnot point at theInitExpr variablein anysensethe
new heap variable simply contains a copy of its value.
If InitExpr is not provided, PTR_NEW does not create a new heap variable, and returns
theNull Pointer, aspecial pointer with axed known valuethat can never point at aheap
variable. The null pointer is useful as a terminator in dynamic data structures, or as a
placeholder in structure denitions.
Keywords
ALLOCATE_HEAP
Set this keyword to cause PTR_NEW to allocate an undened heap variable rather than
return a null pointer when InitExpr is not specied.
NO_COPY
Usually, when theInitExpr argument is provided, PTR_NEW allocates additional
memory to make a copy. If the NO_COPY keyword is set, the value data is taken away
fromtheInitExpr variableand attached directly to theheap variable. Thisfeaturecan be
used to move data very efciently. However, it has the side effect of causing theInitExpr
variabletobecomeundened. UsingtheNO_COPYkeywordiscompletelyequivalent to
the statement:
Result = PTR_NEW(TEMPORARY(InitExpr))
and is provided as a syntactic convenience.
PTR_VALID IDL Reference Guide
PTR_VALID
The PTR_VALID function veries the validity of its pointer arguments, or alternatively
returns a vector of pointers to all the existing valid pointer heap variables.
If called with an pointer or array of pointersasitsargument, PTR_VALID returnsabyte
array of thesamesizeastheargument. Each element of theresult isset to True(1) if the
corresponding pointer in the argument refers to an existing valid heap variable, or to
False (0) otherwise.
If called with an integer or arrayof integersasitsargument and theCAST keyword isset,
PTR_VALID returns an array of pointers. Each element of the result is a pointer to the
heap variable indexed by the integer value. Integers used to index heap variables are
shown in the output of the HELP and PRINT commands. This is useful primarily in
programming/debugging when the you have lost a reference but see it with HELP and
need toget areferencetoit interactively in order todeterminewhat it isand takestepsto
x the code. See the Examples section below for an example.
If no argument isspecied, PTR_VALID returnsavector of pointersto all existingvalid
pointer heap variableseven if therearecurrently no pointers to theheap variable. This
usageallowsyou to reclaim pointer heap variablesto which all pointershavebeen lost.
If no valid pointer heap variables exist, a scalar null pointer is returned.
Calling Sequence
Result = PTR_VALID([ Arg] )
Argument
Arg
Argcan be one of the following:
1. A scalar or array argument of pointer type.
2. If the CAST keyword is set, an integer index or array of integer indices to heap
variables. Integersusedtoindex heapvariablesareshown in theoutput of theHELP
and PRINT commands.
Keyword
CAST
Set this keyword to create a new pointer to each heap variable index specied in Arg.
COUNT
Set thiskeywordequal toanamedvariablethat will containthenumber of currentlyvalid
heap variables. This value is returned as a longword integer.
IDL Reference Guide PTR_VALID
Examples
To determine if a given pointer refers to a valid heap variable
IF (PTR_VALID(p)) THEN
To destroy all existing pointer heap variables:
PTR_FREE, PTR_VALID()
You can use the CAST keyword to reclaim lost heap variables. For example:
A = PTR_NEW(10)
PRINT, A
IDL prints:
<PtrHeapVar2>
In this case, the integer index to the heap variable is 2. If we reassign the variable A, we
will lose the pointer, but the heap variable will still exist:
A=0
PRINT, A, PTR_VALID()
IDL prints:
0 <PtrHeapVar2>
We can reclaim the lost heap variable using the CAST keyword:
A = PTR_VALID(2, /CAST)
PRINT, A
IDL prints:
<PtrHeapVar2>
PTRARR IDL Reference Guide
PTRARR
The PTRARR function returns a pointer vector or array. The individual elements of the
array are set to the Null Pointer.
Calling Sequence
Result = PTRARR(D
1
, ... , D
n
)
Argument
Di
Keywords
ALLOCATE_HEAP
Normally, PTRARRsetseveryelement of theresult tothenull pointer. It you wishIDLto
allocateheap variablesfor every element of thearray instead, set theALLOCATE_HEAP
keyword. In this case, every element of the array will be initialized to point at an
undened heap variable.
NOZERO
If ALLOCATE_HEAPisnot specied, PTRARRsetseveryelement of theresult tothenull
pointer. If NOZERO is nonzero, this initialization is not performed and PTRARR
executes faster. NOZERO is ignored if ALLOCATE_HEAP is specied.
CautionIf you specify NOZERO, theresultingarray will havewhatever valuehappensto exist
at thesystemmemorylocation that thearrayisallocatedfrom. Youshouldbecareful
to initialize such an array to valid pointer values.
Example
Create P, a 3 element by 3 element pointer array with each element containing the Null
Pointer by entering:
P = PTRARR(3, 3)
IDL Reference Guide PUSHD
PUSHD
ThePUSHDprocedurepushesadirectoryontothetopof thedirectorystack maintained
bythePUSHDand POPDprocedures. Thenameof thecurrent directoryispushed onto
the directory stack. This directory becomes the next directory used by POPD. IDL
changes directories to the one specied by theDir argument. The common block
DIR_STACK is used to store the directory stack.
pushd.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
PUSHD, Dir
Arguments
Dir
A string containing the name of the directory to change to. The current directory is
pushed onto the top of the directory stack.
See Also
CD, POPD, PRINTD
QROMB IDL Reference Guide
QROMB
TheQROMBfunction evaluatestheintegral of afunction over theclosed interval [ A, B]
usingRombergintegration. Theresult will havethesamestructureasthesmaller of Aand
B, and the resulting type will be single- or double-precision oating, depending on the
input types.
QROMB is based on the routineqromb described in section 4.3 of Numerical Recipes in
Calling Sequence
Result = QROMB(Func, A, B)
Arguments
Func
Ascalar stringspecifyingthenameof auser-suppliedIDLfunction tobeintegrated. This
function must accept a single scalar argument X and return a scalar result. It must be
dened over the closed interval [A, B] .
For example, if we wish to integrate the cubic polynomial
y = x
3
+ (x - 1)
2
+ 3
we dene a function CUBIC to express this relationship in the IDL language:
FUNCTION cubic, X
RETURN, X^3 + (X - 1.0)^2 + 3.0
END
A
The lower limit of the integration. A can be either a scalar or an array.
B
The upper limit of the integration. B can be either a scalar or an array.
Note If arraysarespeciedfor AandB, thenQROMBintegratestheuser-suppliedfunction
over theinterval [ A
i
, B
i
] for each i. If either Aor Bisascalar and theother an array,
the scalar is paired with each array element in turn.
Keywords
DOUBLE
IDL Reference Guide QROMB
EPS
The desired fractional accuracy. For single-precision calculations, the default value is
1.0 10
-6
. For double-precision calculations, the default value is 1.0 10
-12
.
JMAX
2
(JMAX - 1)
is the maximum allowed number of steps. If this keyword is not specied, a
default of 20 is used.
K
Integration is performed by Rombergs method of order 2K. If not specied, the default
is K=5. (K=2 is Simpsons rule).
Example
To integrate the CUBIC function (listed above) over the interval [ 0, 3] and print the
result:
PRINT, QROMB('cubic', 0.0, 3.0)
IDL prints:
32.2500
This is the exact solution.
See Also
INT_2D, INT_3D, INT_TABULATED, QROMO, QSIMP
QROMO IDL Reference Guide
QROMO
The QROMO function evaluates the integral of a function over the open interval (A, B)
using a modied Rombergs method.
QROMOisbased on theroutineqromo described in section 4.4of Numerical Recipesin
Calling Sequence
Result = QROMO(Func, A[ , B] )
Arguments
Func
dened over the open interval (A, B).
For example, if we wish to integrate the fourth-order polynomial
y = 1 / x
4
we dene a function HYPER to express this relationship in the IDL language:
FUNCTION hyper, X
RETURN, 1.0 / X^4
END
A
B
The upper limit of the integration. B can be either a scalar or an array. If the MIDEXP
keyword is specied, B is assumed to be innite, and should not be supplied by the user.
Note: If arrays are specied for A and B, then QROMO integrates the user-supplied
function over the interval [ A
i
, B
i
] for each i. If either A or B is a scalar and the other an
array, the scalar is paired with each array element in turn.
Keywords
DOUBLE
IDL Reference Guide QROMO
EPS
The fractional accuracy desired, as determined by the extrapolation error estimate. For
single-precision calculations, the default value is 1.0 10
-6
. For double-precision
calculations, the default value is 1.0 10
-12
.
JMAX
Set to specify themaximumallowed number of mid quadraturepointsto be3
(JMAX - 1)
.
The default value is 14.
K
Integration is performed by Rombergs method of order 2K. If not specified, the default is K=5.
MIDEXP
Use themidexp() function (seeNumerical Recipes, section 4.4) as the integrating
function. If theMIDEXPkeyword isspecied, argument Bisassumed to beinnite, and
should not be supplied by the user.
MIDINF
Use themidinf() function (seeNumerical Recipes, section 4.4) as the integrating
function.
MIDPNT
Use themidpnt() function (seeNumerical Recipes, section 4.4) as the integrating
function. This is the default if no other integrating function keyword is specied.
MIDSQL
Use themidsql() function (seeNumerical Recipes, section 4.4) as the integrating
function.
MIDSQU
Use themidsqu() function (seeNumerical Recipes, section 4.4) as the integrating function.
Example
To integrate the HYPER function (listed above) over the open interval (2, ) and print
the result:
PRINT, QROMO('hyper', 2.0, /MIDEXP)
IDL prints:
0.0412050
Caution When using the /MIDEXP keyword, the upper integration limit is assumed to be
innity and is not supplied.
See Also
INT_2D, INT_3D, INT_TABULATED, QROMB, QSIMP
QSIMP IDL Reference Guide
QSIMP
The QSIMP function performs numerical integration of a function over the closed
interval [ A, B] usingSimpsonsrule. Theresult will havethesamestructureasthesmaller
of Aand B, and theresultingtypewill besingle- or double-precision oating, depending
on the input types.
QSIMPisbased on theroutineqsimp described in section 4.2of Numerical RecipesinC:
Calling Sequence
Result = QSIMP(Func, A, B)
Arguments
Func
dened over the closed interval [A, B] .
For example, if we wish to integrate the fourth-order polynomial
y = (x
4
- 2x
2
) sin(x)
we dene a function SIMPSON to express this relationship in the IDL language:
FUNCTION simpson, X
RETURN, (X^4 - 2.0 * X^2) * SIN(X)
END
A
B
The upper limit of the integration. B can be either a scalar or an array.
Note: If arrays are specied for A and B, then QSIMP integrates the user-supplied
function over the interval [ A
i
, B
i
] for each i. If either A or B is a scalar and the other an
array, the scalar is paired with each array element in turn.
Keywords
DOUBLE
IDL Reference Guide QSIMP
EPS
The desired fractional accuracy. For single-precision calculations, the default value is
1.0 10
-6
. For double-precision calculations, the default value is 1.0 10
-12
.
JMAX
2
(JMAX - 1)
is the maximum allowed number of steps. If not specied, a default of 20 is
used.
Example
TointegratetheSIMPSONfunction (listedabove) over theinterval [ 0, /2] andprint the
result:
A = 0.0 Definelower limit of integration.
B = !PI/2.0 Defineupper limit of integration.
PRINT, QSIMP('simpson', A, B)
IDL prints:
-0.479158
The exact solution can be found using the integration-by-parts formula:
FB = 4.*B*(B^2-7.)*SIN(B) - (B^4-14.*B^2+28.)*COS(B)
FA = 4.*A*(A^2-7.)*SIN(A) - (A^4-14.*A^2+28.)*COS(A)
exact = FB - FA
PRINT, exact
IDL prints:
-0.479156
See Also
INT_2D, INT_3D, INT_TABULATED, QROMB, QROMO
QUERY_* ROUTINES IDL Reference Guide
QUERY_* ROUTINES
Query routinesallowusersto obtain information about an imagelewithout havingto
read the le. The following QUERY_* routines are available in IDL.
All of the QUERY_* routines return a result, which is a long with the value of 1 if the
query was successful (and the le type was correct) or 0 on failure. If the query was
successful, the return argument will be an anonymous structure containing all of the
available information for that image format.
Thestatusisintendedtobeusedtodetermineif it isappropriatetousethecorresponding
READ_ routine for a given le. The return status of the QUERY_* will indicate success
if thecorrespondingREAD_routineislikely tobeabletoread thele. Thereturn status
will indicate failure for cases that contain formats that are not supported by the READ_
routines, even though the les may be valid outside of the IDL environment. For
example, IDLs READ_BMP does not support 1-bit-deep images and so the
QUERY_BMP function would return failure in the case of a monochrome BMP le.
The returned anonymous structure will have (minimally) the following elds for all le
formats. If theledoesnot support multipleimagesin asinglele, theNUM_IMAGES
eld will alwaysbe1and theIMAGE_INDEX eld will alwaysbe0. Individual routines
will document additional elds which are returned for a specic format.
QUERY_BMP QUERY_DICOM
QUERY_GIF QUERY_JPEG
QUERY_PICT QUERY_PNG
QUERY_PPM QUERY_SRF
QUERY_TIFF
Table 9-60: IDL QUERY_* Routines
Field IDL data type Description
CHANNELS Long Number of samples per pixel
DIMENSIONS 2-D long array Size of the image in pixels
HAS_PALETTE Integer True if a palette is present
NUM_IMAGES Long Number of images in the le
IMAGE_INDEX Long Image number for which this
structure is valid
Table 9-61: Query Routines Info Structure
IDL Reference Guide QUERY_* ROUTINES
All the routines accept the IMAGE_INDEX keyword although formats which do not
support multiple images in a single le will ignore this keyword.
PIXEL_TYPE Integer IDL basic type code for a pixel
sample
TYPE String String identifying the le format
Field IDL data type Description
Table 9-61: Query Routines Info Structure
QUERY_BMP IDL Reference Guide
QUERY_BMP
QUERY_BMP is a method of obtaining information about a BMP image le without
having to read the le. See QUERY_* ROUTINES for more information.
Thisroutinereturnsalongwiththevalueof 1if thequerywassuccessful (andtheletype
was correct) or 0 on failure.
Calling Sequence
Result = QUERY_BMP (Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the BMP le to query.
Info
Returnsan anonymousstructurecontaininginformation about theimagein thele. The
Info.TYPE eld will return the value BMP.
Note See QUERY_* ROUTINES for detailed structure info.
Keywords
There are no keywords for this routine.
See Also
QUERY_* ROUTINES, READ_BMP, WRITE_BMP
IDL Reference Guide QUERY_DICOM
QUERY_DICOM
The QUERY_DICOM function tests a le for compatibility with READ_DICOM and
returns an optional structure containing information about images in the DICOM le.
Theresult is0on failure, and 1on success. Aresult of 1meansit islikely that thelecan
be read by READ_DICOM.
query_dicom.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = QUERY_DICOM(Filename[, Info])
Arguments
Filename
A scalar string containing the full pathname of the le to query.
Info
Info.TYPE eld will return the value DICOM.
Keywords
IMAGE_INDEX
Set this keyword to the index (zero based) of the image being queried in the le. This
keyword has no effect on les containing a single image.
Example
DICOM palettevectorsare16bit quantitiesand may not cover theentiredynamicrange
of the image. To view a paletted DICOM image use the following:
IF (QUERY_DICOM(file.dcm,info)) THEN BEGIN
IF (info.has_palette) THEN BEGIN
TV, READ_IMAGE(file.dcm,r, g, b), /ORDER
TVLCT,r/256, g/256, b/256
ENDIF
ENDIF
QUERY_DICOM IDL Reference Guide
See Also
READ_DICOM
IDL Reference Guide QUERY_GIF
QUERY_GIF
QUERY_GIFisamethodof obtaininginformationabout aGIFimagelewithout having
to read the le. See QUERY_* ROUTINES for more information.
Calling Sequence
Result = QUERY_GIF(Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the GIF le to query.
Info
Info.TYPE eld will return the value GIF.
Keywords
See Also
QUERY_* ROUTINES, READ_GIF, WRITE_GIF
QUERY_JPEG IDL Reference Guide
QUERY_JPEG
QUERY_JPG is a method of obtaining information about a JPEG image le without
Calling Sequence
Result = QUERY_JPEG(Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the JPEG le to query.
Info
Info.TYPE eld will return the value JPEG.
Keywords
See Also
QUERY_* ROUTINES, READ_JPEG, WRITE_JPEG
IDL Reference Guide QUERY_PICT
QUERY_PICT
QUERY_PICT is a method of obtaining information about a PICT image le without
Calling Sequence
Result = QUERY_PICT (Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the PICT le to query.
Info
Info.TYPE eld will return the value PICT.
Keywords
See Also
QUERY_* ROUTINES, READ_PICT, WRITE_PICT
QUERY_PNG IDL Reference Guide
QUERY_PNG
QUERY_PNG is a method of obtaining information about a PNG image le without
Calling Sequence
Result = QUERY_PNG(Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the PNG le to query.
Info
Info.TYPE eld will return the value PNG.
Keywords
Example
Query included in creating RGBA (16-bit/channel) and Color Indexed (8-
bits/channel) image.
rgbdata = INTARR(4,320,240)
cidata = BYTSCL(DIST(256))
red = indgen(256)
green = indgen(256)
blue = indgen(256)
WRITE_PNG,rgb_image.png,rgbdata
WRITE_PNG,ci_image.png,cidata,red,green,blue
Query and Read thedata
names = [rgb_image.png,ci_image.png,unknown.png]
IDL Reference Guide QUERY_PNG
FOR i=0,N_ELEMENTS(names)-1 DO BEGIN
ok = QUERY_PNG(names[i],s)
IF (ok) THEN BEGIN
HELP,s,/STRUCTURE
IF (s.HAS_PALETTE) THEN BEGIN
img = READ_PNG(names[i],rpal,gpal,bpal)
HELP,img,rpal,gpal,bpal
ENDIF ELSE BEGIN
img = READ_PNG(names[i])
HELP,img
ENDELSE
ENDIF ELSE BEGIN
PRINT,names[i], is not a PNG file
ENDELSE
ENDFOR
END
See Also
QUERY_* ROUTINES, READ_PNG, WRITE_PNG
QUERY_PPM IDL Reference Guide
QUERY_PPM
QUERY_PPM is a method of obtaining information about a PPM image le without
Calling Sequence
Result = QUERY_PPM (Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the PPM le to query.
Info
Returns an anonymous structure containing information about the image. The
Info.TYPE eld will return the value PPM.
Additional eld in the Info structure: MAXVAL - maximum pixel value in the image.
Keywords
MAXVAL
Set this keyword to a named variable to retrieve the maximum pixel value in the image.
See Also
QUERY_* ROUTINES, READ_PPM, WRITE_PPM
IDL Reference Guide QUERY_SRF
QUERY_SRF
QUERY_SRF is a method of obtaining information about an SRF image le without
Calling Sequence
Result = QUERY_SRF(Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the SRF le to query.
Info
Info.TYPE eld will return the value SRF.
Keywords
See Also
QUERY_* ROUTINES, READ_SRF, WRITE_SRF
QUERY_TIFF IDL Reference Guide
QUERY_TIFF
QUERY_TIFF is a method of obtaining information about a TIFF image le without
Calling Sequence
Result = QUERY_TIFF(Filename, Info)
Arguments
Filename
A scalar string containing the pathname of the TIFF le to query.
Info
Info.TYPE eld will return the value TIFF.
Additional eld in the Info structure: PLANAR_CONFIG.
Keywords
IMAGE_INDEX
Image number index. If this value is larger than the number of images in the le, the
function returns 0 (failure).
Example
Thisisan exampleof usingQUERY_TIFFtowriteand read amulti-imageTIFFle. The
first image is a 16-bit, single channel image stored using compression. The second
image is an RGB image stored using 32-bits/channel uncompressed.
;Write the image data
data = FIX(DIST(256))
rgbdata = LONARR(3,320,240)
WRITE_TIFF,multi.tif,data,COMPRESSION=1,/SHORT
WRITE_TIFF,multi.tif,rgbdata,/LONG,/APPEND
;Read the image data back
IDL Reference Guide QUERY_TIFF
ok = QUERY_TIFF(multi.tif,s)
IF (ok) THEN BEGIN
FOR i=0,s.NUM_IMAGES-1 DO BEGIN
imp = QUERY_TIFF(multi.tif,t,IMAGE_INDEX=i)
img = READ_TIFF(multi.tif,IMAGE_INDEX=i)
HELP,t,/STRUCTURE
HELP,img
ENDFOR
ENDIF
See Also
QUERY_* ROUTINES, READ_TIFF, WRITE_TIFF
R_CORRELATE IDL Reference Guide
R_CORRELATE
The R_CORRELATE function computes Spearmans (rho) or Kendallss (tau) rank
correlation of two sample populationsXand Y. The result is a two-element vector
containingtherank correlation coefcient andthetwo-sidedsignicanceof itsdeviation
from zero. The signicance is a value in the interval [ 0.0, 1.0] ; a small value indicates a
signicant correlation.
whereRx
i
and Ry
i
arethemagnitude-based ranksamongXand Y, respectively. Elements
of identical magnitudearerankedusingarank equal tothemean of theranksthat would
otherwise be assigned.
r_correlate.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = R_CORRELATE(X, Y)
Arguments
X
Y
Keywords
D
Set this keyword to a named variable that will contain the sum-squared difference of
ranks. If the KENDALL keyword is set, this parameter is returned as zero.
KENDALL
Set this keyword to compute Kendallss (tau) rank correlation. By default, Spearmans
(rho) rank correlation is computed.
rho
Rx
i
Rx ( ) Ry
i
Ry ( )
i 0 =
N 1
Rx
i
Rx ( )
2
i 0 =
N 1
Ry
i
Ry ( )
2
i 0 =
N 1
---------------------------------------------------------------------------------------- =
IDL Reference Guide R_CORRELATE
PROBD
Set thiskeyword to anamed variablethat will contain thetwo-sided signicancelevel of
ZD. If the KENDALL keyword is set, this parameter is returned as zero.
ZD
Set thiskeywordtoanamedvariablethat will contain thenumber of standarddeviations
by which D deviates from its null-hypothesis expected value. If the KENDALL keyword
is set, this parameter is returned as zero.
Example
X = [257, 208, 296, 324, 240, 246, 267, 311, 324, 323, 263, $
305, 270, 260, 251, 275, 288, 242, 304, 267]
Y = [201, 56, 185, 221, 165, 161, 182, 239, 278, 243, 197, $
271, 214, 216, 175, 192, 208, 150, 281, 196]
Compute Spearmans (rho) rank correlation of X and Y.
result = R_CORRELATE(X, Y)
PRINT, result
IDL prints:
[0.835967, 4.42899e-06]
Compute Kendallss (tau) rank correlation of X and Y.
result = R_CORRELATE(X, Y, /KENDALL)
PRINT, result
IDL prints:
[0.624347 0.000118732]
See Also
A_CORRELATE, CORRELATE, C_CORRELATE, M_CORRELATE, P_CORRELATE
R_TEST IDL Reference Guide
R_TEST
TheR_TEST function teststhehypothesisthat abinarypopulation (asequenceof 1sand
0s) represents a random sampling. The result is a two-element vector containing the
nearly-normal test statistic Z and its associated probability. This two-tailed test is based
on the theory of runs and is often referred to as the Runs Test for Randomness.
r_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = R_TEST(X)
Arguments
X
An n-element integer, single-, or double-precision oating-point vector. Elements not
equal to 0 or 1 are removed and the length of X is correspondingly reduced.
Keywords
N0
Set this keyword to a named variable that will contain the number of 0s in X.
N1
Set this keyword to a named variable that will contain the number of 1s in X.
R
Set thiskeyword to anamed variablethat will contain thenumber of runs(clustersof 0s
and 1s) in X.
Example
Dene a binary population.
X = [0, 1, 1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 0, 1, 0, 1, 0, 0, $
1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1]
Test the hypothesis that X represents a random sampling against the hypothesis that it
does not represent a random sampling at the 0.05 signicance level.
result = R_TEST(X, R = r, N0 = n0, N1 = n1)
PRINT, result
IDL Reference Guide R_TEST
IDL prints:
[2.26487, 0.0117604]
Print the values of the keyword parameters:
PRINT, 'Runs: ', r & PRINT, 'Zeros: ', n0 & PRINT, 'Ones: ', n1
Runs: 22
Zeros: 16
Ones: 14
The computed probability (0.0117604) is less than the 0.05 signicance level and
thereforewereject thehypothesisthat Xrepresentsarandomsampling. Theresultsshow
that there are too many runs, indicating a non-random cyclical pattern.
See Also
CTI_TEST, FV_TEST, KW_TEST, LNP_TEST, MD_TEST, RS_TEST, S_TEST,
TM_TEST, XSQ_TEST
RANDOMN IDL Reference Guide
RANDOMN
The RANDOMN function returns one or more normally-distributed, oating-point,
pseudo-random numbers with a mean of zero and a standard deviation of one.
RANDOMN uses the Box-Muller method for generating normally-distributed
(Gaussian) random numbers.
Calling Sequence
Result = RANDOMN(Seed [, D
1
, ..., D
n
])
Arguments
Seed
Avariableor constant used to initializetherandomsequenceon input, and in which the
state of the random number generator is saved on output.
Thestateof therandomnumber generator iscontainedinalonginteger vector. Thisstate
is saved in the Seed argument when the argument is a named variable. To continue the
pseudo-random number sequence, input the variable containing the saved state as the
Seed argument in the next call to RANDOMN or RANDOMU. Each independent
random number sequence should maintain its own state variable. To maintain a state
over repeated callsto aprocedure, theseed variablemay bestored in aCOMMON block.
In addition to states maintained by the user in variables, the RANDOMU and
RANDOMN functions contain a single shared generic state which is used if a named
variable is not supplied as the Seed argument or the named variable supplied is
undened. The generic state is initialized once using the time-of-day, and may be re-
initialized by providing a Seed argument which is a constant or expression.
If the Seed argument is:
an undened variable- thegenericstateisused and theresultinggenericstatearray is
stored in the variable.
a named variable which contains a longword array of the proper length - it used to
continue pseudo-random sequence, and is updated.
a named variable containing a scalar - the scalar value is used to start a new sequence
and the resulting state array is stored back in the variable.
a constant or expression - the value is used to re-initialize the generic state.
Note RANDOMN and RANDOMU use the same sequence. Starting or restarting the
sequencefor onestartsor restartsthesequencefor theother. SomeIDL routinesuse
the random number generator, so using them will initialize the seed sequence. An
example of such a routine is CLUST_WTS.
D
i
toeight dimensionscan bespecied. If nodimensionsarespecied, RANDOMNreturns
a scalar result
IDL Reference Guide RANDOMN
Keywords
Theformulasfor thebinomial, gamma, andPoisson distributionsarefromsection 7.3of
Numerical Recipes in C: TheArt of Scientic Computing(Second Edition), published by
Cambridge University Press.
BINOMIAL
Set thiskeywordtoa2-element array, [ n, p] , togeneraterandomdeviatesfromabinomial
distribution. If an event occurswithprobabilityp, withntrials, then thenumber of times
it occurs has a binomial distribution.
GAMMA
Set this keyword to an integer order i > 0 to generate random deviates from a gamma
distribution. The gamma distribution is the waiting time to theith event in a Poisson
randomprocessof unit mean. Agammadistribution of order equal to1isthesameasthe
exponential distribution.
NORMAL
Set this keyword to generate random deviates from a normal distribution.
POISSON
Set this keyword to the mean number of events occurring during a unit of time. The
POISSON keyword returns a random deviate drawn from a Poisson distribution with
that mean.
UNIFORM
Set this keyword to generate random deviates from a uniform distribution.
Examples
If you start the sequence with an undened variableif RANDOMN has already been
called, Seed is no longer undenedIDL initializes the sequence with the system time:
randomValue = RANDOMN(seed) ;Generateonerandom variable
andinitializethesequencewithan
undefined variable.
The new state is saved in seed.
To generate repeatable experiments, begin the sequence with a particular seed.
seed_value = 5L
randomValue = RANDOMN(seed_value) ;Generateonerandom variable
andinitializethesequencewith5.
PRINT, randomValue
Seed contains the state:
0.521414
RANDOMN IDL Reference Guide
To restart the sequence with a particular seed, reinitialize the variable:
seed = 5L
randomValue = RANDOMN(seed) ;Get a normal random number,
and restart thesequencewith a
seed of 5.
PRINT, randomValue
IDL prints the FLOAT random number:
0.521414
To create a 10 by 10 array of normally-distributed, random numbers, type:
R = RANDOMN(seed, 10, 10)
Since seed is undened, the generic state is used to initialize the random number
generator. Print the resulting values by entering:
PRINT, R
A moreinterestingexampleplotstheprobability function of 2000numbersreturned by
RANDOMN. Type:
PLOT, HISTOGRAM(RANDOMN(SEED, 2000), BINSIZE=0.1)
To obtain a sequence of 1000 exponential (gamma distribution, order 1) deviates, type:
Result = RANDOMN(seed, 1000, GAMMA=1)
Intuitively, the result contains a random series of waiting times for events occurring an
average of one per time period.
To obtain a series of 1000 random elapsed times required for the arrival of two events,
type:
Result = RANDOMN(seed, 1000, GAMMA=2) Returns a series of 1000 random
elapsed times required for the
arrival of two events.
To obtain a 128 x 128 array lled with Poisson deviates, with a mean of 1.5, type:
Result = RANDOMN(seed, 128, 128, POISSON=1.5)
To simulate the count of heads obtained when ipping a coin 10 times, type:
Result = RANDOMN(seed, BINOMIAL=[10,.5])
See Also
RANDOMU
IDL Reference Guide RANDOMU
RANDOMU
The RANDOMU function returns one or more uniformly-distributed, oating-point,
pseudo-random numbers in the range 0 < Y <1.0.
Therandomnumber generator istakenfrom: RandomNumber Generators: GoodOnes
areHardtoFind, Park andMiller, CommunicationsoftheACM, Oct 1988, Vol 31, No. 10,
p. 1192. To remove low-order serial correlations, a Bays-Durham shufe is added,
resulting in a random number generator similar to ran1() in Section 7.1 of Numerical
University Press.
Calling Sequence
Result = RANDOMU(Seed [, D
1
, ..., D
n
])
Arguments
Seed
Avariableor constant used to initializetherandomsequenceon input, and in which the
state of the random number generator is saved on output.
Thestateof therandomnumber generator iscontainedinalonginteger vector. Thisstate
is saved in the Seed argument when the argument is a named variable. To continue the
pseudo-random number sequence, input the variable containing the saved state as the
Seed argument in the next call to RANDOMN or RANDOMU. Each independent
random number sequence should maintain its own state variable. To maintain a state
over repeated callsto aprocedure, theseed variablemay bestored in aCOMMON block.
In addition to states maintained by the user in variables, the RANDOMU and
RANDOMN functions contain a single shared generic state which is used if a named
variable is not supplied as the Seed argument or the named variable supplied is
undened. The generic state is initialized once using the time-of-day, and may be re-
initialized by providing a Seed argument which is a constant or expression.
If the Seed argument is:
an undened variable- thegenericstateisused and theresultinggenericstatearray is
stored in the variable.
a named variable which contains a longword array of the proper length - it used to
continue pseudo-random sequence, and is updated.
a named variable containing a scalar - the scalar value is used to start a new sequence
and the resulting state array is stored back in the variable.
a constant or expression - the value is used to re-initialize the generic state.
RANDOMU IDL Reference Guide
Note RANDOMN and RANDOMU use the same sequence, so starting or restarting the
sequencefor onestartsor restartsthesequencefor theother. SomeIDL routinesuse
the random number generator, so using them will initialize the seed sequence. An
example of such a routine is CLUST_WTS.
D
i
toeight dimensionscan bespecied. If nodimensionsarespecied, RANDOMUreturns
a scalar result.
Keywords
Theformulasfor thebinomial, gamma, andPoisson distributionsarefromSection 7.3of
Numerical Recipes in C: TheArt of Scientic Computing(Second Edition), published by
Cambridge University Press.
BINOMIAL
Set thiskeywordtoa2-element array, [ n, p] , togeneraterandomdeviatesfromabinomial
distribution. If an event occurswithprobabilityp, withntrials, then thenumber of times
it occurs has a binomial distribution.
GAMMA
Set this keyword to an integer order i > 0 to generate random deviates from a gamma
distribution. The gamma distribution is the waiting time to theith event in a Poisson
randomprocessof unit mean. Agammadistribution of order equal to1isthesameasthe
exponential distribution.
NORMAL
Set this keyword to generate random deviates from a normal distribution.
POISSON
Set this keyword to the mean number of events occurring during a unit of time. The
POISSON keyword returns a random deviate drawn from a Poisson distribution with
that mean.
UNIFORM
Set this keyword to generate random deviates from a uniform distribution.
Example
This example simulates rolling two dice 10,000 times and plots the distribution of the
total using RANDOMU. Enter:
PLOT, HISTOGRAM(FIX(6 * RANDOMU(S, 10000)) + $
FIX(6 * RANDOMU(S, 10000)) + 2)
IDL Reference Guide RANDOMU
In the above statement, the expression RANDOMU(S, 10000) is a 10,000-element,
oating-point array of random numbers greater than or equal to 0 and less than 1.
Multiplying this array by 6 converts the range to 0 Y < 6.
Applying the FIX function yields a 10,000-point integer vector with values from 0 to 5,
onelessthan thenumberson onedie. Thiscomputation isdonetwice, oncefor each die,
then 2 is added to obtain a vector from 2 to 12, the total of two dice.
TheHISTOGRAM function makesavector in which each element containsthenumber
of occurrences of dice rolls whose total is equal to the subscript of the element. Finally,
this vector is plotted by the PLOT procedure.
An example of reusing a state vector to generate a repeatable sequence:
seed = 1001L ;Init seed for a repeatablesequence
print,randomu(seed,5) ;Print 1st 5 numbers of sequence
0.705884 0.285924 0.231151 0.715447 0.532836
seed = 1001L ;Re-init seed to samesequence
for i=0,4 do print, randomu(seed) ;Get 5 number of sequencewith 5 calls:
0.705884
0.285924
0.231151
0.715447
0.532836
See Also
RANDOMN
RANKS IDL Reference Guide
RANKS
The RANKS function computes the magnitude-based ranks of a sample population X.
Elementsof identical magnitudeties arerankedaccordingtothemeanof theranksthat
would otherwise be assigned. The result is a vector of ranks equal in length to X.
ranks.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = RANKS(X)
Arguments
X
An n-element integer, single-, or double-precision oating-point vector. Theelementsof
this vector must be in ascending order based on their magnitude.
Example
X = [-0.8, 0.1, -2.3, -0.6, 0.2, 1.1, -0.3, 0.6, -0.2, 1.1, $
-0.7, -0.2, 0.6, 0.4, -0.1, 1.1, -0.3, 0.3, -1.3, 1.1]
Allocate a two-column, n-row array to store the results.
array = FLTARR(2, N_ELEMENTS(X))
Sort the sample population and store in the 0th column of ARRAY.
array[0, *] = X[SORT(X)]
Compute the ranks of the sorted sample population and store in the 1st column of
ARRAY.
array[1, *] = RANKS(X[SORT(X)])
Display the sorted sample population and corresponding ranks with a two-decimal
format.
PRINT, array, FORMAT = '(2(5x, f5.2))'
IDL Reference Guide RANKS
IDL prints:
-2.30 1.00
-1.30 2.00
-0.80 3.00
-0.70 4.00
-0.60 5.00
-0.30 6.50
-0.30 6.50
-0.20 8.50
-0.20 8.50
-0.10 10.00
0.10 11.00
0.20 12.00
0.30 13.00
0.40 14.00
0.60 15.50
0.60 15.50
1.10 18.50
1.10 18.50
1.10 18.50
1.10 18.50
See Also
R_CORRELATE
RDPIX IDL Reference Guide
RDPIX
TheRDPIXprocedureinteractivelydisplaystheXposition, Yposition, andpixel valueat
the cursor.
rdpix.pro in thelib subdirectory of the IDL distribution.
Using RDPIX
RDPIX displaysastreamof X, Y, and pixel valueswhen themousecursor ismoved over
a graphics window. Press the left or center mouse button to create a new line of output.
Press the right mouse button to exit the procedure.
Calling Sequence
RDPIX, Image[, X0, Y0]
Arguments
Image
Thearray that containstheimagebeingdisplayed. Thisarray may beof any type. Rather
readingpixel valuesfromthedisplay, theyaretaken fromthisparameter, avoidingscaling
difculties.
X0, Y0
Thelocation of thelower-left corner of theimageareaon screen. If theseparametersare
not supplied, they are assumed to be zero.
Example
See Also
CURSOR, TVRD
IDL Reference Guide READ/READF
READ/ READF
The READ procedures perform formatted input into variables.
READ performs input from the standard input stream (IDL le unit 0), while READF
requires a le unit to be explicitly specied.
Calling Sequence
READ, [Prompt,] Var
1
, ..., Var
n
or
READF, [Prompt,] Unit, Var
1
, ..., Var
n
Arguments
Prompt
Note that the PROMPT keyword should be used instead of thePrompt argument for
compatibility with window-based versions of IDL.
A string or explicit expression (i.e, not a named variable) to be used as a prompt. This
argument should not be included if the FORMAT keyword is specied. Also, if this
argument begins with the characters $(, it is taken to be a format specication as
described below under Format Compatibility.
Using thePrompt argument does not work well with IDL for Windowsand IDL for
Macintosh. The desired prompt string is written to the log window instead of the
command input window. To create custom prompts compatible with these versions of
IDL, use the PROMPT keyword, described below.
Unit
For READF, Unit species the le unit from which the input is taken.
Var
i
The named variables to receive the input.
Keywords
AM_PM
Supplies a string array of two names to be used for the names of the AM and PM string
when processingexplicitlyformatted dates(CAPA, CApA, and CapAformat codes) with
the FORMAT keyword.
READ/READF IDL Reference Guide
DAYS_OF_WEEK
FORMAT keyword.
FORMAT
If FORMATisnot specied, IDLusesitsdefault rulesfor formattingtheinput. FORMAT
allows the format of the input to be specied in precise detail, using a FORTRAN-style
specication. See Using Explicitly Formatted Input/Output on page 169 of Building
IDL Applications.
MONTHS
FORMAT keyword.
PROMPT
Set this keyword to a scalar string to be used as a customized prompt for the READ
command. If the PROMPT keyword or Prompt argument is not supplied, IDL uses a
colon followed by a space ( : ) as the input prompt.
VMS Keywords
Note also that the obsolete VMS-only routine READ_KEY has been replaced by the
keywords below.
KEY_ID
Theindex key to beused (primary = 0, rst alternatekey = 1, etc...) when accessingdata
fromalewith indexed organization. If thiskeyword isomitted, theprimary key isused.
KEY_MATCH
Therelation tobeusedwhen matchingthesuppliedkeywithkeyeldvalues(EQ= 0, GE
= 1, GT = 2) when accessing data from a le with indexed organization. If this keyword
is omitted, the equality relation (0) is used.
KEY_VALUE
Thevalueof akeytobefoundwhen accessingdatafromalewith indexedorganization.
Thisvaluemust match thekey denition that isdetermined when thelewascreated in
terms of type and sizeno conversions are performed. If this keyword is omitted, the
next sequential record is used.
Format Compatibility
If theFORMATkeywordisnot present andREADiscalledwithmorethanoneargument, and
the first argument is a scalar string starting with the characters $(, this initial argument is
IDL Reference Guide READ/READF
takentobetheformat specification, just asif it hadbeenspecifiedviatheFORMATkeyword.
This feature is maintained for compatibility with version 1 of VMSIDL.
Example
To read a string value into the variable B from the keyboard, enter:
B = '' DefineBasastringbeforereading.
READ, B, PROMPT='Enter Name: ' Read input from theterminal.
To read formatted data from the previously-opened le associated with logical unit
number 7 into variable C, use the command:
READF, 7, C
See Also
READS, READU, WRITEU
READ_ASCII IDL Reference Guide
READ_ASCII
TheREAD_ASCII function readsdatafroman ASCII leinto an IDL structurevariable.
READ_ASCII may be used with templates created by the ASCII_TEMPLATE function.
This routine handles ASCII les consisting of an optional header of a xed number of
lines, followedbycolumnar data. Oneor morerowsof dataconstitutearecord. Each data
element within arecordisconsideredtobein adifferent column, or eld. Thedatain one
eld must be of, or promotable to, a single type (e.g., FLOAT). Adjacent elds may be
collectedintomulti-columnelds, calledgroups. Filesmayalsocontaincomments, which
exist between a user-specied comment string and the corresponding end-of-line.
READ_ASCII is designed to be used with templates created by the ASCII template
function.
read_ascii.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = READ_ASCII(Filename)
Arguments
Filename
A string containing the name of an ASCII le to read into an IDL variable.
Keywords
You can dene the attributes of a eld in two ways. If you use a template, you can either
use a previously generated template, or create a template with ASCII_TEMPLATE on
page 202. You can use COMMENT_SYMBOL, DATA_START, DELIMITER, or
MISSING_VALUE to either override template attributes or to provide one-time
attributes for the le to be read, without a template.
COMMENT_SYMBOL
Set thiskeywordtoastringthat identiesthecharacter usedtodelineatecommentsinthe
ASCII letoberead. When READ_ASCII encountersthecomment character, it discards
datafromthat point until it reachestheend of thecurrent line, identifyingtherest of the
line as a comment. The default character is a space, , specifying that no comments will
be recognized.
COUNT
Set thiskeyword equal to anamed variablethat will contain thenumber of recordsread.
IDL Reference Guide READ_ASCII
DATA_START
Set thiskeyword equal to thenumber of header linesyou want to skip. Thedefault value
is 0 if no template is specied.
DELIMITER
Set this keyword to a string that identies the end of a eld. If no delimiter is specied,
READ_ASCII usesinformation providedbythetemplatein use. Thedefault isaspace, ,
specifying that an empty element constitutes the end of a eld.
HEADER
Set this keyword equal to a named variable that will contain the header in a string array
of length DATA_START. If no header exists, an empty string is returned.
MISSING_VALUE
Set thiskeyword equal to avalueused to replaceany missingor invalid data. Thedefault
value, if no template is supplied, is !VALUES.F_NAN. See !VALUES on page 38 for
details.
NUM_RECORDS
Set thiskeyword equal to thenumber of recordsto read. Thedefault isto read up to and
including the last record.
RECORD_START
Set thiskeywordequal totheindexof therst recordtoread. Thedefault istherst record
of the le (record 0).
TEMPLATE
Use this keyword to specify the ASCII le template (generated by the function
ASCII_TEMPLATE), that denesattributesof theletoberead. Specicattributesof the
template may be overridden by the following keywords: COMMENT_SYMBOL,
DATA_START, DELIMITER, MISSING_VALUE.
VERBOSE
Set this keyword to print runtime messages.
Examples
To read ASCII datausingdefault leattributes, except for settingthenumber of skipped
header lines to 10, type:
data = READ_ASCII(file, DATA_START=10)
To useatemplateto deneleattributes, overridingthenumber of skipped header lines
dened in the template, type:
data = READ_ASCII(file, TEMPLATE=template, DATA_START=10)
READ_ASCII IDL Reference Guide
To use the ASCII_TEMPLATE GUI to generate a template within the function, type:
data = READ_ASCII(myfile, TEMPLATE=ASCII_TEMPLATE(mytemplate))
See Also
ASCII_TEMPLATE
IDL Reference Guide READ_BMP
READ_BMP
The READ_BMP function reads a Microsoft Windows Version 3 device independent
bitmap le(.BMP) and returnsabytearray containingtheimage. Dimensionsaretaken
from the BITMAPINFOHEADER of the le. In the case of 4-bit or 8-bit images, the
dimensions of the resulting array are (biWidth, biHeight).
For 24-bit images, the dimensions are (3, biWidth, biHeight). Color interleaving is
blue, green, red; i.e., Result[0,i,j] = blue, Result[ 1,i,j] = green, etc.
READ_BMPdoesnot handle1-bit-deepimagesor compressedimages, andisnot fast for
4-bit images. The algorithm works best on images where the number of bytes in each
scan-line is evenly divisible by 4.
read_bmp.pro in thelib subdirectory of the IDL distribution.
Note Tond information about apotential BMPlebeforetryingtoread itsdata, usethe
QUERY_BMP function.
Calling Sequence
Result = READ_BMP(Filename, [, R, G, B [, Ihdr])
Arguments
Filename
A scalar string specifying the full path name of the bitmap le to read.
R, G, B
Named variables that will contain the color tables from the le. There 16 elements each
for 4bit images, 256elementseach for 8bit images. Color tablesarenot dened or used
for 24 bit images.
Ihdr
Anamedvariablethat will contain astructureholdingtheBITMAPINFOHEADERfrom
the le. Tag names are as dened in the MS Windows Programmers Reference Manual,
Chapter 7.
Keywords
RGB
If this keyword is set, color interleaving of 16- and 24-bit images will be R, G, B, i.e.,
Result[ 0,i,j] = red, Result[ 1,i,j] = green, Result[ 2,i,j] = blue.
READ_BMP IDL Reference Guide
Example
To open, read, and display the BMP le named foo.bmp in the current directory and
store the color vectors in the variables R, G, and B, enter:
TV, READ_BMP('foo.bmp', R, G, B) Read and display an image
TVLCT, R, G, B Load its colors
Many applicationsthat use24-bit BMPlesoutsideIDL expect BMPlesto bestored as
BGR. For example, enter the following commands.
a = BYTARR(3, 200, 200)
a(0, *, *) = 255 Makea red squareimage.
TV, a, /TRUE View theimage.
WRITE_BMP, foo.bmp, a
If you open the.bmp lein certain bitmap editors, you may nd that thesquareisblue.
READ_BMP, foo.bmp, image
TV, image, /TRUE IDL reads theimageback in and
interprets it as red.
READ_BMP, foo.bmp, image, /RGB Flip theorder of theindices by
addingtheRGB keyword.
TV, image, /TRUE Displays theimagein blue.
See Also
WRITE_BMP, QUERY_BMP
IDL Reference Guide READ_DICOM
READ_DICOM
The READ_DICOM function reads an image from a DICOM le along with any
associated color table. Thereturn valuecan bea2D array for grayscaleor a3D array for
true color images. True color images are always returned in pixel interleave format. The
return array type depends on the DICOM image pixel type.
read_dicom.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = READ_DICOM (Filename[,Red, Green, Blue])
Arguments
Filename
This argument is a scalar string that contains the full pathname of the le to read.
Red, Green, Blue
Namedvariablesthat will containthered, green, andbluecolor vectorsfromtheDICOM
le if they exist.
Note DICOM color vectorscontain 16- bit color valuesthat may need tobeconverted for
use with IDL graphics routines.
Keywords
IMAGE_INDEX
Set this keyword to the index of the image to read from the le.
Example
TVSCL,READ_DICOM(FILEPATH(mr_knee.dcm,$
SUBDIR=[examples,data]))
See Also
QUERY_DICOM
READ_GIF IDL Reference Guide
READ_GIF
TheREAD_GIFprocedurereadsthecontentsof aGIFformat imageleand returnsthe
image and color table vectors (if present) in the form of IDL variables.
Although the GIF format allows les to contain multiple images, READ_GIF only reads
in the rst image in a le. Only 8-bit images are supported, and local colormaps arenot
supported.
Note TheGraphicsInterchangeFormatistheCopyright property of CompuServ Incor-
porated. GIF(SM) is a Service Mark property of CompuServ Incorporated.
read_gif.pro in thelib subdirectory of the IDL distribution.
Note To nd information about a potential GIF le before trying to read its data, use the
QUERY_DICOM function.
Calling Sequence
READ_GIF, Filename, Image[, R, G, B]
Arguments
Filename
A scalar string specifying the full path name of the image le to read.
Image
A named variable that will contain the image data read from the le.
R, G, B
Named variablesthat will contain theRed, Green, and Bluecolor vectors, if therasterle
contains colormaps.
Keywords
CLOSE
Set this keyword to close any open les. The CLOSE keyword is only useful if a le
containingmultipleimages(asspecied by theMULTIPLEkeyword) isin use. Notethat
you do not need to specify the normal arguments to READ_GIF (Filename, Image, etc.)
when using this keyword.
MULTIPLE
Set this keyword to read les that contain multiple images. Each call to READ_GIF
returns the next image, with the le remaining open between calls. TheFilename
argument is ignored and may be omitted after the rst call. Reading past the last image
IDL Reference Guide READ_GIF
returnsascalar valueof -1in thevariablespecied in theImageargument, and closesthe
le. R, G, and B color vectors are returned only once, along with the rst image.
Example
To open and read the GIF image le named foo.gif in the current directory, store the
image in the variableimage1.
READ_GIF, 'foo.gif', image1, R, G, B Storethecolor vectors in thevari-
ables R, G, and B.
TVLCT, R, G, B load thenew color tableand dis-
play theimage.
TV, image1
See Also
WRITE_GIF, QUERY_DICOM
READ_INTERFILE IDL Reference Guide
READ_INTERFILE
TheREAD_INTERFILEprocedurereadsimagedatastoredin Interle(v3.3) format and
returns a 3D array.
Note: thisisasimplisticreader. READ_INTERFILEcan only read aseriesof imagesif all
images have the same height and width. It does not get additional keyword information
beyond what is needed to read the image data. If any problems occur when reading the
le, READ_INTERFILE prints a message and stops.
If the data is stored on a bigendian machine and read on a littleendian machine (or vice
versa) the order of bytes in each pixel element may be reversed, requiring a call to
BYTEORDER
read_interfile.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
READ_INTERFILE, File, Data
Arguments
File
A scalar string containing the name of the Interle to read. Note: if the Interle has a
header le and a data le, this should be the name of the header le (also called the
administrative le).
Data
Anamedvariablethat will contain a3Darrayof dataasreadfromthele. Assumedtobe
a series of 2D images.
Example
READ_INTERFILE, '0_11.hdr', X
IDL Reference Guide READ_JPEG
READ_JPEG
The READ_JPEG procedure reads JPEG (Joint Photographic Experts Group) format
compressed images from les or memory. JPEG is a standardized compression method
for full-color and gray-scale images. This procedure reads JFIF format les (often called
JPEG les), including those produced by WRITE_JPEG.
READ_JPEG can optionally quantize true-color images contained in les to a pseudo-
color palette with a specied number of colors, and with optional color dithering.
Thisprocedureisbasedin part on thework of the Independent JPEGGroup. For abrief
explanation of JPEG, see WRITE_JPEG on page 1324.
Note All JPEGlesconsist of bytedata. Input dataisconvertedtobytesbeforebeingwritten
to a JPEG le.
Note Tond information about apotential JPEGlebeforetryingtoread itsdata, usethe
QUERY_JPEG function.
Calling Sequence
READ_JPEG, [Filename,] Image[,Colortable]
Arguments
Filename
A scalar string specifying the full pathname of the JFIF format (JPEG) le to be read. If
thisparameter isnot present, theUNIT and/or theBUFFERkeywordsmust bespecied.
Image
A named variable to contain the image data read from the le.
Colortable
Anamed variableto contain thecolormap, when readingatrue-color imagethat isto be
quantized. On completion, this variable contains a byte array with dimensions
(NCOLORS, 3). This argument is lled only if the image is color quantized (refer to the
COLORS keyword).
Keywords
BUFFER
Set thiskeyword toanamed variablethat isused for abuffer. Abuffer variableneed only
besupplied when readingmultipleimagesper le. Initializethebuffer variableto empty
by setting it to 0.
Example
READ_JPEG IDL Reference Guide
buff = 0 Initializebuffer.
OPENR, 1, 'images.jpg', /STREAM
FOR i=1, nimages DO BEGIN Process each image.
READ_JPEG, UNIT=1, BUFFER=buff, a
Read next image.
TV, a Display theimage.
ENDFOR
CLOSE, 1 Done.
COLORS
If the image le contains a true-color image that is to be displayed on an indexed color
destination, set COLORSto thedesired number of colorsto bequantized. COLORScan
be set to a value from 8 to 256. The DITHER and TWO_PASS_QUANTIZE keywords
affect themethod, speed, and quality of thecolor quantization. Thesekeywordshaveno
effect if the le contains a grayscale image.
DITHER
Set thiskeywordtouseditheringwith color quantization (i.e., if theCOLORSkeywordis
in use). Dithering is a method that distributes the color quantization error to
surroundingpixels, to achievehigher-quality results. Set theDITHERkeyword to oneof
the following values:
0No dithering. Images are read quickly, but with quality is low.
1Floyd-Steinberg dithering. This method relatively slow, but produces the highest
quality results. This is the default behavior.
2Ordered dithering. This method is faster than Floyd-Steinberg dithering, but pro-
duces lower quality results.
GRAYSCALE
Set thiskeywordtoreturnamonochrome(grayscale) image, regardlessof whether thele
contains an RGB or grayscale image.
ORDER
JPEG/JFIF images are normally written in top-to-bottom order. If the image is to be
stored into theImagearray in thestandard IDL order (frombottom-to-top) set ORDER
to 0. Thisisthedefault. If theimagearray isto betop-to-bottomorder, set ORDERto 1.
TRUE
Use this keyword to specify the index of the dimension for color interleaving when
readingatrue-color image. Thedefault is1, for pixel interleaving, (3, m, n). Avalueof 2
indicates line interleaving (m, 3, n), and 3 indicates band interleaving, (m, n, 3).
TWO_PASS_QUANTIZE
Set this keyword to use a two-pass color quantization method when quantization is in
effect (i.e., the COLORS keyword is in use). This method requires more memory and
time, but produces superior results to the default one-pass quantization method.
IDL Reference Guide READ_JPEG
UNIT
This keyword can be used to designate the logical unit number of an already open JFIF
le, allowing the reading of multiple images per le or the embedding of JFIF images in
other data les. When using this keyword, Filenameshould not be specied.
READ_JPEG buffers its input data. To read multiple images per le, use the BUFFER
keyword. When using VMS, open the le with the /STREAM keyword.
Examples
READ_JPEG, 'test.jpg', a Read a JPEG grayscaleimage.
READ_JPEG, 'test.jpg', a, TRUE=1 ReadanddisplayaJPEGtrue-col-
or imageon a true-color display.
TV, a, TRUE=1 Display theimagereturned with
pixel interleaving(i.e., with di-
mensions 3, m, n).
Read the image, setting the number of colors to be quantized to the maximum number
of available colors.
READ_JPEG, 'test.jpg', a, ctable, COLORS=!D.N_COLORS-1
ReadaJPEGtrue-colorimageon
an 8-bit pseudo-color display.
TVLCT, ctable Load thequantized colortable.
Note We could have also included the TWO_PASS_QUANTIZE and DITHER keywords
to improve the images appearance.
See Also
WRITE_JPEG, QUERY_JPEG
READ_PICT IDL Reference Guide
READ_PICT
The READ_PICT procedure reads the contents of a PICT (version 2) format image le
and returns the image and color table vectors (if present) in the form of IDL variables.
The PICT format is used by Apple Macintosh computers.
read_pict.pro in thelib subdirectory of the IDL distribution.
Note Tondinformation about apotential PICT lebeforetryingtoreaditsdata, usethe
QUERY_PICT function.
Calling Sequence
READ_PICT, Filename, Image[, R, G, B]
Arguments
Filename
A scalar string specifying the full pathname of the PICT le to read.
Image
A named variable that will contain the 2D image read fromFilename.
R, G, B
Named variables that will contain the Red, Green, and Blue color vectors read from the
PICT le.
Example
To open and read the PICT image le named foo.pict in the current directory, store
theimagein thevariableimage1, andstorethecolor vectorsin thevariablesR, G, andB,
enter:
READ_PICT, 'foo.pict', image1, R, G, B
To load the new color table and display the image, enter:
TVLCT, R, G, B
TV, image1
See Also
WRITE_PICT, QUERY_PICT
IDL Reference Guide READ_PNG
READ_PNG
The READ_PNG function reads the image contents of a Portable Network Graphics
(PNG) le and returns the image in an IDL variable. If the image contains a palette (see
QUERY_PNG), it can be returned as well in three IDL variables. READ_PNG supports
1, 2, 3 and 4 channel images with channel depths of 8, 16, or 32 bits.
Note Only singlechannel 8-bit imagesmay havepalettes. If an 8bit, singlechannel image
has index values marked as transparent these can be retrieved as well.
Note Tond information about apotential PNGlebeforetryingtoread itsdata, usethe
QUERY_PNG function.
Calling Sequence
Result = READ_PNG(Filename[, R, G, B]
Arguments
Filename
A scalar string containing the full pathname of the PNG le to read.
R, G, B
Named variables that will contain the Red, Green, and Blue color vectors if a color table
exists.
Keywords
VERBOSE
Produces additional diagnostic output during the read.
TRANSPARENT
Returns an array of pixel index values which are to be treated as transparent for the
purposes of image display.
Example
CreateanRGBA(16-bits/channel) andaColor Indexed(8-bit/channel) imagewitha
palette.
red = indgen(256)
READ_PNG IDL Reference Guide
green = indgen(256)
blue = indgen(256)
Query and read thedata
IF (ok) THEN BEGIN
HELP,s,/STRUCTURE
ENDIF ELSE BEGIN
HELP,img
ENDELSE
ENDIF ELSE BEGIN
ENDELSE
ENDFOR
END
See Also
WRITE_PNG, QUERY_PNG
IDL Reference Guide READ_PPM
READ_PPM
The READ_PPM procedure reads the contents of a PGM (gray scale) or PPM (portable
pixmap for color) format imageleand returnstheimagein theformof a2Dbytearray
(for grayscale images) or a (3, n, m) byte array (for true-color images).
Files to be read should adhere to the PGM/PPM standard. The following le types are
supported: P2 (graymap ASCII), P5 (graymap RAWBITS), P3 (true-color ASCII
pixmaps), and P6(true-color RAWBITSpixmaps). Maximumpixel valuesarelimited to
255. Images are always stored with the top row rst.
PPM/PGM format is supported by the PBMPLUS toolkit for converting various image
formats to and from portable formats, and by the Netpbm package.
read_ppm.pro in thelib subdirectory of the IDL distribution.
Note Tond information about apotential PPM lebeforetryingtoread itsdata, usethe
QUERY_PPM function.
Calling Sequence
READ_PPM, Filename, Image
Arguments
Filename
A scalar string specifying the full path name of the PGM or PPM le to read.
Image
A named variable that will contain the image. For grayscale images, Imageis a 2D byte
array. For true-color images, Imageis a (3, n, m) byte array.
Keywords
MAXVAL
A named variable that will contain the maximum pixel value.
Example
ToopenandreadthePGMimagelenamedfoo.pgm inthecurrent directoryandstore
the image in the variable IMAGE1:
READ_PPM, "foo.pgm", IMAGE1
READ_PPM IDL Reference Guide
See Also
WRITE_PPM, QUERY_PPM
IDL Reference Guide READ_SPR
READ_SPR
The READ_SPR function reads a row-indexed sparse array from a specied le and
returns the array as the result. Row-indexed sparse arrays are created using the SPRSIN
function and written to a le using the WRITE_SPR function.
read_spr.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = READ_SPR(Filename)
Arguments
Filename
A scalar string specifying the name of the le containing a row-indexed sparse array.
Example
Suppose we have already saved a row-indexed sparse array to a le named sprs.as, as
described in the documentation for the WRITE_SPR routine. To read the sparse array
from the le and store it in a variablesprs, use the following command:
sprs = READ_SPR('sprs.as')
See Also
FULSTR, LINBCG, SPRSAB, SPRSAX, SPRSIN, WRITE_SPR
READ_SRF IDL Reference Guide
READ_SRF
The READ_SRF procedure reads the contents of a Sun rasterle and returns the image
and color table vectors (if present) in the form of IDL variables.
READ_SRF only handles 1-, 8-, 24-, and 32-bit rasterles of typeRT_OLD and
RT_STANDARD. See the le/usr/include/rasterfile.h for the structure of Sun
rasterles.
read_srf.pro in thelib subdirectory of the IDL distribution.
Note To nd information about apotential SRFlebeforetryingto read itsdata, usethe
QUERY_SRF function.
Calling Sequence
READ_SRF, Filename, Image[, R, G, B]
Arguments
Filename
A scalar string containing the name of the rasterle to read.
Image
A named variable that will contain the 2D byte array (image).
R, G, B
Named variablesthat will contain theRed, Green, and Bluecolor vectors, if therasterle
contains colormaps.
Example
To open and read the Sun rasterle named sun.srf in the current directory, store the
image in the variableimage1, and store the color vectors in the variablesR, G, and B,
enter:
READ_SRF, 'sun.srf', image1, R, G, B
TVLCT, R, G, B
TV, image1
IDL Reference Guide READ_SRF
See Also
WRITE_SRF, QUERY_SRF
READ_SYLK IDL Reference Guide
READ_SYLK
The READ_SYLK function reads the contents of a SYLK (Symbolic Link) format
spreadsheet dataleand returnsthecontentsof thele, or of acell datarange, in an IDL
variable. READ_SYLK returns either a vector of structures or a 2D array containing the
spreadsheet cell data.
By default, READ_SYLK returns a vector of structures, each of which contains the data
from onerow of the table being read. In this case, the individual elds in the structures
have the tag names Col0, Col1, ..., Coln. If the COLMAJOR keyword is specied,
each of the structures returned contains data from onecolumn of the table, and the tag
names are Row0, Row1, ..., Rown.
Note: This routine reads only numeric and string SYLK data. It ignores all spreadsheet
and cell formatting information (cell width, text justication, font type, date, time, and
monetarynotations, etc). Notealsothat thedatain agiven cell rangemust beof thesame
data type (all integers, for example) in order for the read operation to succeed. See the
example below for further information.
read_sylk.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = READ_SYLK(File)
Arguments
File
A scalar string specifying the full path name of the SYLK le to read.
Keywords
ARRAY
Set this keyword to return an IDL array rather than a vector of structures. Note that all
thedatain thecell rangespecied must beof thesamedatatypetosuccessfullyreturn an
array.
COLMAJOR
Set thiskeywordtocreateavector of structureseachcontainingdatafromasinglecolumn
of thetablebeingread. If you arecreatingan array rather than avector of structures(the
ARRAY keyword is set), setting COLMAJOR has the same effect as transposing the
resulting array.
IDL Reference Guide READ_SYLK
This keyword should be set when importing spreadsheet data which has column major
organization (data stored in columns rather than rows).
NCOLS
Set thiskeywordtothenumber of spreadsheet columnstoread. If not specied, all of the
cell columns found in the le are read.
NROWS
Set thiskeyword tothenumber of spreadsheet rowstoread. If not specied, all of thecell
rows found in the le are read.
STARTCOL
Set thiskeyword to therst column of spreadsheet cellsto read. If not specied, theread
operation begins with the rst column found in the le (column 0).
STARTROW
Set this keyword to the rst row of spreadsheet cells to read. If not specied, the read
operation begins with the rst row of cells found in the le (row 0).
USEDOUBLES
Set this keyword to read any oating-point cell data as double-precision rather than the
default single-precision.
USELONGS
Set thiskeyword to read any integer cell dataaslonginteger typerather than thedefault
integer type.
Examples
Suppose the following spreadsheet table, with the upper left cell (value = Index ) at
location (0, 0), has been saved as the SYLK le le.slk :
Index Name Gender Platform
1 Beth F Unix
2 Lubos M VMS
3 Louis M Windows
4 Thierry M Macintosh
Notethat thedataformat of thetitlerow(string, string, string, string) isinconsistent with
the following four rows (int, string, string, string) in the table. Because of this, it is
impossible to read all of the table into a single IDL variable. The following two
commands, however, will read all of the data:
title = READ_SYLK("file.slk", NROWS = 1)
table = READ_SYLK("file.slk", STARTROW = 1)
PRINT, title Display thetop row of thetable.
READ_SYLK IDL Reference Guide
IDL prints:
{ Index Name Gender Platform}
PRINT, table
IDL prints:
{1 Beth F Unix}{2 Lubos M VMS}{3 Louis M Windows}{4 Thierry M Macintosh}
To retrieve only the Name column:
names = READ_SYLK("file.slk", /ARRAY, STARTROW = 1, $
STARTCOL = 1, NCOLS = 1)
PRINT, names
IDL prints:
Beth Lubos Louis Thierry
To retrieve the Name column in column format:
namescol = READ_SYLK("file.slk", /ARRAY, /COLMAJOR, $
STARTROW = 1, STARTCOL = 1, NCOLS = 1)
PRINT, namescol
IDL prints:
Beth
Lubos
Louis
Thierry
See Also
WRITE_SYLK
IDL Reference Guide READ_TIFF
READ_TIFF
TheREAD_TIFFfunction reads1and 3channel imageTIFFformat lesand returnsthe
image and color table vectors in the form of IDL variables. READ_TIFF returns a byte,
integer, long, or oat array (based on the data format in the TIFF le) containing the
image data. The dimensions of the result are the same as dened in the TIFF le
(Columns, Rows).
For TIFF images that are RGB interleaved by pixel, the output dimensions are (3,
Columns, Rows).
For TIFF images that are stored in planar interleave format, READ_TIFF returns the
integer value zero, sets the variable dened by the PLANARCONFIG keyword to 2, and
returns three separate images in the variables dened by the R, G, and B arguments.
If the le to be read is stored in planar interleave format and the R, G, B arguments are
not specied, the image will be returned in IMG as a [ 3,x,y] array.
Note To nd information about apotential TIFFlebeforetryingto read itsdata, usethe
QUERY_TIFF function.
Calling Sequence
Result = READ_TIFF(Filename[, R, G, B] [,IMAGE_INDEX=num] [,ORDER=ord]
[,PLANARCONFIG=p] [,/UNSIGNED] [,/VERBOSE] [,SUB_RECT=[x,y,width,height]]
[,GEOTIFF=geo])
Arguments
Filename
A scalar string specifying the full pathname of the TIFF le to read.
R, G, B
Namedvariablesthat will containtheRed, Green, andBluecolor vectorsof thecolor table
from the le if one exists.
Keywords
GEOTIFF
Returns an anonymous structure containing one eld for each of the GeoTIFF tags and
keys found in the le. If no GeoTIFF information is present in the le, the returned
variable is undened.
The GeoTIFF structure is formed using elds named from the following table.
READ_TIFF IDL Reference Guide
Anonymous Structure Field Name IDLDatatype
TAGS:
"MODELPIXELSCALETAG" DOUBLE[ 3]
"MODELTRANSFORMATIONTAG" DOUBLE[ 4,4]
"MODELTIEPOINTTAG" DOUBLE[ 6,*]
KEYS:
"GTMODELTYPEGEOKEY" INT
"GTRASTERTYPEGEOKEY" INT
"GTCITATIONGEOKEY" STRING
"GEOGRAPHICTYPEGEOKEY" INT
"GEOGCITATIONGEOKEY" STRING
"GEOGGEODETICDATUMGEOKEY" INT
"GEOGPRIMEMERIDIANGEOKEY" INT
"GEOGLINEARUNITSGEOKEY" INT
"GEOGLINEARUNITSIZEGEOKEY" DOUBLE
"GEOGANGULARUNITSGEOKEY" INT
"GEOGANGULARUNITSIZEGEOKEY" DOUBLE
"GEOGELLIPSOIDGEOKEY" INT
"GEOGSEMIMAJORAXISGEOKEY" DOUBLE
"GEOGSEMIMINORAXISGEOKEY" DOUBLE
"GEOGINVFLATTENINGGEOKEY" DOUBLE
"GEOGAZIMUTHUNITSGEOKEY" INT
"GEOGPRIMEMERIDIANLONGGEOKEY" DOUBLE
"PROJECTEDCSTYPEGEOKEY" INT
"PCSCITATIONGEOKEY" STRING
"PROJECTIONGEOKEY" INT
"PROJCOORDTRANSGEOKEY" INT
"PROJLINEARUNITSGEOKEY" INT
"PROJLINEARUNITSIZEGEOKEY" DOUBLE
"PROJSTDPARALLEL1GEOKEY" DOUBLE
Table 9-62: GEOTIFF Structures
Note If aGeoTIFFkey appearsmultipletimesin ale, only thevaluefor therst instance
of the key is returned.
IMAGE_INDEX
Selects the image number within the le to be read (see QUERY_TIFF to determine the
number of images in the le).
ORDER
Set thiskeyword to anamed variablethat will contain theorder valuefromtheTIFFle.
Thisvalueisreturnedas0for imageswritten bottomtotop, and1for imageswritten top
to bottom. If an order value does not appear in the TIFF le, an order of 1 is returned.
"PROJNATORIGINLONGGEOKEY" DOUBLE
"PROJNATORIGINLATGEOKEY" DOUBLE
"PROJFALSEEASTINGGEOKEY" DOUBLE
"PROJFALSENORTHINGGEOKEY" DOUBLE
"PROJFALSEORIGINLONGGEOKEY" DOUBLE
"PROJFALSEORIGINLATGEOKEY" DOUBLE
"PROJFALSEORIGINEASTINGGEOKEY" DOUBLE
"PROJFALSEORIGINNORTHINGGEOKEY" DOUBLE
"PROJCENTERLONGGEOKEY" DOUBLE
"PROJCENTERLATGEOKEY" DOUBLE
"PROJCENTEREASTINGGEOKEY" DOUBLE
"PROJCENTERNORTHINGGEOKEY" DOUBLE
"PROJSCALEATNATORIGINGEOKEY" DOUBLE
"PROJSCALEATCENTERGEOKEY" DOUBLE
"PROJAZIMUTHANGLEGEOKEY" DOUBLE
"PROJSTRAIGHTVERTPOLELONGGEOKEY" DOUBLE
"VERTICALCSTYPEGEOKEY" INT
"VERTICALCITATIONGEOKEY" STRING
"VERTICALDATUMGEOKEY" INT
"VERTICALUNITSGEOKEY" INT
READ_TIFF IDL Reference Guide
The ORDER keyword can return any of the following additional values (depending on
the source of the TIFF le):
Reference: Aldus TIFF 6.0 spec (TIFF version 42).
PLANARCONFIG
Set this keyword to a named variable that will contain the interleave parameter for the
TIFFle. Thisparameter isreturnedas1for TIFFlesthat areGrayScale, Palette, or RGB
color interleaved by pixel. This parameter is returned as 2 for RGB color TIFF les
interleaved by image.
SUB_RECT [x, y, width, height]
Set this keyword to a four-element array which species a rectangular region within the
leto extract. Only therectangular portionof theimageselected by thiskeyword isread
and returned. Therectangleismeasured in pixelsfromthelower left corner (right hand
coordinate system).
UNSIGNED
Set thiskeyword toreturn TIFFlescontainingunsigned 16-bit integersassigned 32-bit
longword arrays. If not set, return asigned 16-bit integer for theseles. In thiscase, data
valuesbetween 32768and 65535arereturned asnegativevaluesbetween -32768and -1.
This keyword has no effect if the input le does not contain 16-bit integers.
VERBOSE
Produce additional diagnostic output during the read.
Examples
Read thelemy.tif in thecurrent directory intothevariableimage, and savethecolor
tables in the variables, R, G, and B by entering:
image = READ_TIFF('my.tif', R, G, B)
To view the image, load the new color table and display the image by entering:
Rows Columns
1 top to bottom, left to right
2 top to bottom, right to left
3 bottom to top, right to left
4 bottom to top, left to right
5 top to bottom, left to right
6 top to bottom, right to left
7 bottom to top, right to left
8 bottom to top, left to right
Table 9-63: Values for the ORDER keyword
TVLCT, R, G, B
TV, image
Writeand read amulti-imageTIFFle. Thefirst imageisa16-bit singlechannel image
stored using compression. The second image is an RGB image stored using 32-
bits/channel uncompressed.
;Writetheimagedata
Read theimagedata back
IF (ok) THEN BEGIN
HELP,t,/STRUCTURE
HELP,img
ENDFOR
ENDIF
See Also
WRITE_TIFF, QUERY_TIFF
READ_WAVE IDL Reference Guide
READ_WAVE
The READ_WAVE procedure reads a.wave or .bwave le created by the Wavefront
Advanced Data Visualizer into an series of IDL variables.
Note READ_WAVE only preserves the structure of the variables if they are regularly
gridded.
read_wave.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
READ_WAVE, File, Variables, Names, Dimensions
Arguments
File
A scalar string containing the name of the Wavefront le to read.
Variables
Anamedvariablethat will containablock of thevariablescontainedinthewavefront le.
Sinceeach variablein awavefront lecan havemorethan oneeld(for instance, avector
variablehas3elds), theeldsof eachvariablemakeupthemajor index intothevariable
block. For instance, if aWavefront lehadonescalar variableandonevector variable, the
scalar would be extracted as follows:
scalar_variable = variables[0,*,*,*]
and the vector variable would be extracted as follows:
vector_variable = variables[1:3,*,*,*]
To nd the dimensions of the returned variable, see the description of theDimensions
argument.
Names
Anamed variablethat will contain thestringnamesof each variablecontained in thele.
Dimensions
A named variable that will contain a long array describing how many elds in the large
returned variable block each variable occupies. In the above example of one scalar
variable followed by a vector variable, the dimension variable would be[1,3].
Thisindicatesthat therst eldof thereturnedvariableblock wouldbethescalar variable
and the following 3 elds would comprise the vector variable.
IDL Reference Guide READ_WAVE
Keywords
MESHNAMES
Set this keyword to a named variable that will contain the name of the mesh used in the
Wavefront le for each variable.
See Also
WRITE_WAVE
READ_X11_BITMAP IDL Reference Guide
READ_X11_BITMAP
The READ_X11_BITMAP procedure reads bitmaps stored in the X Windows X11
format. The X Windowsbitmap program produces a C header le containing the
denition of a bitmap produced by that program. This procedure reads such a le and
creates an IDL byte array containing the bitmap. It is used primarily to read bitmaps to
be used as IDL widget button labels.
read_x11_bitmap.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
READ_X11_BITMAP, File, Bitmap [, X, Y]
Arguments
File
A scalar string containing the name of the le containing the bitmap.
Bitmap
A named variable that will contain the bitmap. This variable is returned as a byte array.
X
A named variable that will contain the width of the bitmap.
Y
A named variable that will contain the height of the bitmap.
Keywords
EXPAND_TO_BYTES
Set thiskeywordtoinstruct READ_X11_BITMAPtoreturn a2Darraywhich hasonebit
per byte (0 for a 0 bit), (255 for a 1 bit) instead.
Example
To open and read the X11 bitmap le named my.x11 in the current directory, store the
bitmap in thevariablebitmap1, and thewidth and height in thevariablesX and Y, enter:
READ_X11_BITMAP, 'my.x11', bitmap1, X, Y
To display the new bitmap, enter:
READ_X11_BITMAP, 'my.x11', image, /EXPAND_TO_BYTES
IDL Reference Guide READ_X11_BITMAP
TV, image, /ORDER
See Also
READ_XWD
READ_XWD IDL Reference Guide
READ_XWD
The READ_XWD function reads the contents of a le created by thexwd (X Windows
Dump) command and returns the image and color table vectors in the form of IDL
variables. READ_XWDreturnsa2Dbytearraycontainingtheimage. If thelecannot be
open or read, the return value is zero.
Note: thisfunction isintended to beused only on lescontaining8-bit pixmapscreated
with xwd version 6 or later.
read_xwd.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = READ_XWD(Filename[, R, G, B])
Arguments
Filename
A scalar string specifying the full pathname of the XWD le to read.
R, G, B
Namedvariablesthat will contain theRed, Green, andBluecolor vectors, if theXWDle
contains color tables.
Example
To open and read the X Windows Dump le named my.xwd in the current directory,
storetheimagein thevariableimage1, and storethecolor vectorsin thevariables, R, G,
and B, enter:
image1 = READ_XWD('my.xwd', R, G, B)
TVLCT, R, G, B
TV, image1
See Also
READ_X11_BITMAP
IDL Reference Guide READS
READS
The READS procedure performs formatted input from a string variable and writes the
results into one or more output variables. This procedure differs from the READ
procedure only in that the input comes from memory instead of a le.
Thisroutineisuseful when you need to examinetheformat of adatalebeforereading
the information it contains. Each line of the le can be read into a string using READF.
Then the components of that line can be read into variables using READS.
Calling Sequence
READS, Input, Var
1
, ..., Var
n
Arguments
Input
Thestringvariablefromwhichtheinput istaken. If thesuppliedargument isnot astring,
it isautomaticallyconverted. Theargument can bescalar or array. If Inputisan array, the
individual string elements are treated as successive lines of input.
Var
i
The named variables to receive the input.
Keywords
AM_PM
FORMAT keyword.
DAYS_OF_WEEK
FORMAT keyword.
FORMAT
If FORMATisnot specied, IDLusesitsdefault rulesfor formattingtheinput. FORMAT
allows the format of the input to be specied in precise detail, using a FORTRAN-style
specication. See Using Explicitly Formatted Input/Output on page 169 of Building
IDL Applications.
READS IDL Reference Guide
MONTHS
FORMAT keyword.
See Also
READ/READF, READU
IDL Reference Guide READU
READU
The READU procedure reads unformatted binary data from a le into IDL variables.
READU transfers data directly with no processing of any kind performed on the data.
Calling Sequence
READU, Unit, Var
1
, ..., Var
n
Arguments
Unit
The IDL le unit from which input is taken.
Var
i
Named variables to receive the data. For non-string variables, the number of bytes
required for Var areread. When READU isused with avariableof typestring, IDL reads
exactly the number of bytes contained in the existing string. For example, to read a 5-
character string, enter:
temp = '12345'
READU, unit, temp
Unix Keywords
TRANSFER_COUNT
Set this keyword to a named variable in which to return the number of elements
transferred by the input operation. Note that the number of elements is not the same as
the number of bytes (except in the case where the data type being transferred is bytes).
For example, transferring256oating-point numbersyieldsatransfer count of 256, not
1024 (the number of bytes transferred).
This keyword is useful with les opened with the NOSTDIO keyword to the OPEN
routines. Normally, attempting to read more data than is available from a le causes the
unlled space to be zeroed and an error to be issued. This does not happen with les
opened with the NOSTDIO keyword. Instead, the programmer must keep track of the
transfer count.
VMS Keywords
Note that the obsolete VMS routines FORRD, and FORRD_KEY have been replaced by
the READU command used with the following keywords.
READU IDL Reference Guide
KEY_ID
Theindex key to beused (primary = 0, rst alternatekey = 1, etc...) when accessingdata
fromalewith indexed organization. If thiskeyword isomitted, theprimary key isused.
KEY_MATCH
Therelation tobeusedwhen matchingthesuppliedkeywithkeyeldvalues(EQ= 0, GE
= 1, GT = 2) when accessing data from a le with indexed organization. If this keyword
is omitted, the equality relation (0) is used.
KEY_VALUE
Thevalueof akeytobefoundwhen accessingdatafromalewith indexedorganization.
Thisvaluemust match thekey denition that isdetermined when thelewascreated in
terms of type and sizeno conversions are performed. If this keyword is omitted, the
previous key value is used.
Example
The following commands can be used to open the IDL distribution le people.dat and
read an image from that le:
Openthefileforreadingasfileunit
1.
B = BYTARR(192, 192) Theimagewewanttoreadisa192
by192bytearray, somakeBthat
size.
READU, 1, B Read thedata into B.
TV, B Display theimage.
See Also
READ/READF, READS, WRITEU
IDL Reference Guide REBIN
REBIN
TheREBIN function resizesavector or array to dimensionsgiven by theparametersD
i
.
Thesupplieddimensionsmust beintegral multiplesor factorsof theoriginal dimension.
The expansion or compression of each dimension is independent of the others, so that
each dimension can be expanded or compressed by a different value.
If the dimensions of the desired result are not integer multiples of the original
dimensions, use the CONGRID function.
Calling Sequence
Result = REBIN(Array, D
1
, ..., D
n
)
Arguments
Array
The array to be resampled. Array can be of any basic type except complex or string.
D
i
The dimensions of the resulting resampled array. These dimensions must be integer
multiples or factors of the corresponding original dimensions.
Keywords
SAMPLE
Normally, REBIN uses bilinear interpolation when magnifying and neighborhood
averaging when minifying. Set the SAMPLE keyword to use nearest neighbor sampling
for both magnication and minication. Bilinear interpolation gives higher quality
results but requires more time.
Rules Used by REBIN
Assume the original vector Xhasn elements and the result is to havemelements.
Let f = n/m, theratio of thesizeof theoriginal vector, Xto thesizeof theresult. 1/f must
be an integer if n < m(expansion). f must be an integer if compressing, (n > m). The
various resizing options can be described as:
Expansion, n < m, SAMPLE = 0: Y
i
= F(X, f i) i = 0, 1, ... , m-1
Thelinear interpolation function, F(X, p) that interpolatesXat location p, isdened as:
Expansion, n < m, SAMPLE = 1:
Compression, n > m, SAMPLE = 0:
REBIN IDL Reference Guide
Compression, n > m, SAMPLE = 1:
No change, n = m: Y
i
= X
i
Endpoint Effects When Expanding
When expanding an array, REBIN interpolates, it never extrapolates. Each of then-1
intervalsinthen-element input arrayproducesm/ninterpolatesinthem-element output
array. The last m/n points of the result are obtained by duplicating element n-1 of the
input array because their interpolates would lie outside the input array.
For example
A = [0, 10, 20, 30] A four point vector.
B = REBIN(A, 12) Expand by a factor of 3.
PRINT, B
0 3 6 10 13 16 20 23 26 30 30 30
Note that the last element is repeated three times. If this effect is undesirable, use the
INTERPOLATE function. For example, to produce 12 equally spaced interpolates from
the interval 0 to 30:
B = INTERPOLATE(A, 3./11. * FINDGEN(12))
PRINT, B
0 2 5 8 10 13 16 19 21 24 27 30
Here, the sampling ratio is (n - 1)/(m- 1).
Example
D = SIN(DIST(50)/4) & TVSCL, D
F X p , ( )
X
p
p p ( ) X
p 1 +
X
p
( ) + if p n 1 <
X
p
if p n 1
'
=
Y
i
X
fi
=
Y
i
1 f ( ) X
j
j fi =
f i 1 + ( ) 1
=
Y
i
X
fi
=
IDL Reference Guide REBIN
Resize the image to be 5 times its original size and display the result by entering:
D = REBIN(D, 250, 250) & TVSCL, D
See Also
CONGRID
RECALL_COMMANDS IDL Reference Guide
RECALL_COMMANDS
The RECALL_COMMANDS function returns a string array containing the entries in
IDLscommandrecall buffer. Thesizeof thereturnedarrayisthesizeof recall buffer, even
if fewer than commandshavebeen entered (any empty buffer entrieswill contain null
strings). Thedefault sizeof thecommand recall buffer is20lines. (See !EDIT_INPUT
on page 42 for more information about the command recall buffer.)
Element zero of the returned array contains the most recent command.
Calling Sequence
Result = RECALL_COMMANDS()
IDL Reference Guide RECON3
RECON3
TheRECON3function can reconstruct athree-dimensional dataarrayfromtwoor more
images(or projections) of an object. For example, if you placed adark object in front of
awhitebackground and then photographed it threetimes(each timerotatingtheobject
a known amount) then these three images could be used with RECON3 to approximate
a 3D volumetric representation of the object. RECON3 also works with translucent
projections of an object. RECON3 returns a 3D byte array.
recon3.pro in thelib subdirectory of the IDL distribution.
Using RECON3
Imagesusedin reconstruction shouldshowstronglight/dark contrast between theobject
and thebackground. If theimagescontain low(dark) valueswheretheobject isand high
(bright) values where the object isnt, the MODE keyword should be set to +1 and the
returnedvolumewill havelowvalueswheretheobject is, andhighvalueswheretheobject
isnt. If theimagescontain high (bright) valueswheretheobject isand low(dark) values
where the object isnt, the MODE keyword should be set to -1 and the returned volume
will have high values where the object is, and low values where the object isnt.
In general, the object must be CONVEX for a good reconstruction to be possible.
Concave regions are not easily reconstructed. An empty coffee cup, for example, would
be reconstructed as if it were full.
Themoreimagesthebetter. Imagesfrommany different angleswill improvethequality
of the reconstruction. It is also important to supply images that are parallel and
perpendicular to any axes of symmetry. Using the coffee cup as an example, at least one
image should be looking through the opening in the handle. Telephoto images are also
better for reconstruction purposes than wide angle images.
Calling Sequence
Result = RECON3(Images, Obj_Rot, Obj_Pos, Focal, Dist, $
Vol_Pos, Img_Ref, Img_Mag, Vol_Size)
Arguments
Images
A 3D array containing the images to use to reconstruct the volume. Execution time
increases linearly with more images. Imagesmust be an 8-bit (byte) array with
dimensions (x, y, n) wherex is the horizontal image dimension, y is the vertical image
dimension, and n is the number of images. Note that n must be at least 2.
RECON3 IDL Reference Guide
Obj_Rot
A3x noating-point arrayspecifyingtheamount theobject isrotated tomakeit appear
asit doesin each image. Theobject isrst rotatedabout theXaxis, then about theYaxis,
andnallyabout theZaxis(withtheobjectsreferencepoint at theorigin). Obj_Rot[ 0, *]
istheXrotation for each image, Obj_Rot[ 1, *] istheYrotation, and Obj_Rot[ 2, *] isthe
Z rotation.
Obj_Pos
A3x noating-point arrayspecifyingtheposition of theobjectsreferencepoint relative
to the camera lens. The camera lens is located at the coordinate origin and points in the
negative Z direction (the view up vector points in the positive Y direction). Obj_Pos
should be expressed in this coordinate system. Obj_Pos[ 0, *] is the X position for each
image, Obj_Pos[ 1, *] istheYposition, and Obj_Pos[ 2, *] istheZ position. All thevalues
inObj_Pos[ 2, *] shouldbelessthanzero. Notethat thevaluesfor Obj_Pos, Focal, Dist, and
Vol_Posshould all be expressed in the same units (mm, cm, m, in, ft, etc.).
Focal
An n-element oating-point array specifyingthefocal length of thelensfor each image.
Focal may be set to zero to indicate a parallel image projection (innite focal length).
Dist
An n-element oating-point array specifying the distance from the camera lens to the
image plane (lm) for each image. Dist should be greater than Focal.
Vol_Pos
A3x 2oating-point array specifyingthetwo oppositecornersof acubethat surrounds
the object. Vol_Posshould be expressed in the objects coordinate system relative to the
objectsreferencepoint. Vol_Pos[ *, 0] speciesonecorner and Vol_Pos[ *, 1] speciesthe
opposite corner.
Img_Ref
A2xninteger or oating-point arraythat speciesthepixel locationat whichtheobjects
referencepoint appearsin each of theimages. Img_Ref[ 0, *] istheX coordinatefor each
image and Img_Ref[ 1, *] is the Y coordinate.
Img_Mag
A 2 x n integer or oating-point array that species the magnication factor for each
image. Thisnumber isactuallythelength (in pixels) that atest object would appear in an
image if it weren units long and n units distant from the camera lens. Img_Mag[ 0, *] is
the X dimension (in pixels) of a test object for each image, and Img_Mag[ 1, *] is the Y
dimension. All elements in Img_Magshould be greater than or equal to 1.
Vol_Size
A 3-element integer or oating-point array that speciesthesizeof the3D bytearray to
return. Execution time (and resolution) increases exponentially with larger values for
Vol_Size. Vol_Size[ 0] speciestheXdimension of thevolume, Vol_Size[ 1] speciestheY
dimension, and Vol_Size[ 2] species the Z dimension.
Keywords
MISSING
Set this keyword equal to a byte value for cells in the 3D volume that do not map to any
of thesupplied images. Thevalueof MISSINGispassed totheINTERPOLATEfunction.
The default value is zero.
MODE
Set this keyword to a value less than zero to dene each cell in the 3D volume as the
minimumof the corresponding pixels in the images. Set MODE to a value greater than
zero to deneeach cell in the3D volumeasthemaximumof thecorrespondingpixelsin
theimages. If MODEisset equal tozerothen each cell in the3Dvolumeisdened asthe
averageof the corresponding pixels in the images.
MODE should usually be set to -1 when the images contain a bright object in front of a
dark background or to +1 when the images contain a dark object in front of a light
background. Setting MODE=0 (the default) requires more memory since the volume
array must temporarily be kept as an integer array instead of a byte array.
Example
Assumptions for this example:
The objects major axis is parallel to the Z axis.
The objects reference point is at its center.
The camera lens is pointed directly at this reference point.
The reference point is 5000 mm in front of the camera lens.
The focal length of the camera lens is 200 mm.
If the camera is focused on the reference point, then the distance from the lens to the
cameras image plane must be
dist = (d * f ) / (d - f ) = (5000 * 200) / (5000 - 200) = (1000000 / 4800) = 208.333 mm
Theobject isroughly600mmwideand600mmhigh. Thereferencepoint appearsin the
exact center of each image.
If theobject is600mmhigh and 5000mmdistant fromthecameralens, then theobject
image height must be
hi = (h * f ) / (d - f ) = (600 * 200) / (5000 - 200) = (120000 / 4800) = 25.0 mm
The object image appears 200 pixels high so the nal magnication factor is
img_mag = (200 / 25) = 8.0
From these assumptions, we can set up the following reconstruction. First, dene the
variables:
RECON3 IDL Reference Guide
imgx = 256
imgy = 256
frames = 3
images = BYTARR(imgx, imgy, frames)
obj_rot = Fltarr(3, frames)
obj_pos = Fltarr(3, frames)
focal = Fltarr(frames)
dist = Fltarr(frames)
vol_pos = Fltarr(3, 2)
img_ref = Fltarr(2, frames)
img_mag = Fltarr(2, frames)
vol_size = [40, 40, 40]
The object is 5000 mm directly in front of the camera:
obj_pos[0, *] = 0.0
obj_pos[1, *] = 0.0
obj_pos[2, *] = -5000.0
The focal length of the lens is constant for all the images.
focal[*] = 200.0
The distance from the lens to the image plane is also constant.
dist[*] = 208.333
The cube surrounding the object is 600 mm x 600 mm.
vol_pos[*, 0] = [-300.0, -300.0, -300.0]
vol_pos[*, 1] = [ 300.0, 300.0, 300.0]
The image reference point appears at the center of all the images.
img_ref[0, *] = imgx / 2
img_ref[1, *] = imgy / 2
The image magnication factor is constant for all images. (The images havent been
cropped or resized).
img_mag[*,*] = 8.0
Only the object rotation changes from one image to the next. Note that the object is
rotated about the X axis rst, then Y, and then Z. Create some fake images for this
example.
images[30:160, 20:230, 0] = 255
images[110:180, 160:180, 0] = 180
obj_rot[*, 0] = [-90.0, 0.0, 0.0]
images[70:140, 100:130, 1] = 255
obj_rot[*, 1] = [-70.0, 75.0, 0.0]
images[10:140, 70:170, 2] = 255
images[80:90, 170:240, 2] = 150
obj_rot[*, 2] = [-130.0, 215.0, 0.0]
Reconstruct the volume.
vol = RECON3(images, obj_rot, obj_pos, focal, dist, $
vol_pos, img_ref, img_mag, vol_size, Missing=255B, Mode=(-1))
Display the volume.
shade_volume, vol, 8, v, p
scale3, xrange=[0,40], yrange=[0,40], zrange=[0,40]
image = polyshade(v, p, /t3d, xs=400, ys=400)
tvscl, image
See Also
POLYSHADE, SHADE_VOLUME, VOXEL_PROJ
REDUCE_COLORS IDL Reference Guide
REDUCE_COLORS
The REDUCE_COLORS procedure reduces the number of colors used in an image by
eliminating pixel values without members.
The pixel distribution histogram is obtained and the WHERE function is used to nd
bins with non-zero values. Next, a lookup table is made where table(old_pixel_value)
contains new_pixel_value, and then applied to the image.
reduce_colors.pro in thelib subdirectory of the IDL distribution.
Calling Sequence:
REDUCE_COLORS, Image, Values
Arguments
Image
On input, a variable that contains the original image array. On output, this variable
contains the color-reduced image array, writing over the original.
Values
A named variable that, on output, contains a vector of non-zero pixel values. If Image
contains pixel values from 0 to M, Valueswill be an M+1 element vector containing the
mapping from the old values to the new. Values[i] contains the new color index of old
pixel index i.
Example
To reducethenumber of colorsand display an imagewith theoriginal color tablesR, G,
B enter the commands:
REDUCE_COLORS, image, v
TVLCT, R[V], G[V], B[V]
See Also
COLOR_QUAN
IDL Reference Guide REFORM
REFORM
The REFORM function changes the dimensions of an array without changing the total
number of elements. If no dimensions are specied, REFORM returns a copy of Array
with all leading dimensions of size 1 removed. If dimensions are specied, the result is
given those dimensions. Only the dimensions of Array are changedthe actual data
remains unmodied.
Calling Sequence
Result = REFORM(Array, D
1
, ..., D
n
)
Arguments
Array
The array to have its dimensions modied.
D
i
The dimensions of the result. TheD
i
arguments can be either a single array containing
the new dimensions or a sequence of scalar dimensions. Array must have the same
number of elements as specied by the product of the new dimensions.
Keywords
OVERWRITE
Set this keyword to cause the specied dimensions to overwrite the present dimensions
of theArrayparameter. Nodataarecopied, onlytheinternal arraydescriptor ischanged.
The result of the function, in this case, is theArray parameter with its newly-modied
dimensions. For example, to change the dimensions of the variable a, without moving
data, enter:
a = REFORM(a, n1, n2, /OVERWRITE)
Example
REFORM can be used to remove degenerate leading dimensions of size one. Such
dimensions can appear when a subarray is extracted from an array with more
dimensions. For example
a = INTARR(10,10,10) a is a 3-dimensional array.
b = a[5,*,*] Extract a slice from a.
HELP, b, REFORM(b) UseHELP to show what RE-
FORM does.
REFORM IDL Reference Guide
Executing the above statements produces the output:
B INT = Array[1, 10, 10]
<Expression> INT = Array[10, 10]
The statements:
b = REFORM(a,200,5)
b = REFORM(a,[200,5])
have identical effect. They create a new array, b, with dimensions of (200, 5), from a.
See Also
REVERSE, ROT, ROTATE, TRANSPOSE
IDL Reference Guide REGRESS
REGRESS
The REGRESS function performs a multiple linear regression t and returns an Nterm-
element column vector of coefcients.
REGRESS ts the function:
y
i
= const + a
0
x
0,
i + a
1
x
1,
i + ... + a
Nterms-1
x
Nterms-1, i
regress.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = REGRESS(X, Y, Weights [, Yt, Const, Sigma, Ftest, R, Rmul, Chisq, Status])
Arguments
X
An NtermsbyNpointsarrayof independent variabledata, whereNtermsisthenumber of
coefcients (independent variables) and Npointsis the number of samples.
Y
An Npoints-element vector of dependent variable points.
Weights
An Npoints-element vector of weights for each equation. For instrumental (Gaussian)
weighting, set Weights
i
= 1.0/standard_deviation(Y
i
)
2
. For statistical (Poisson)
weighting, Weights
i
= 1.0/Y
i
. For no weighting, set Weights
i
= 1.0, and set the
RELATIVE_WEIGHT keyword.
Yt
A named variable that will contain an Npoints-elements vector of calculated values of Y.
Const
A named variable that will contain the constant term.
Sigma
A named variable that will contain the vector of standard deviations for the returned
coefcients.
Ftest
A named variable that will contain the value of F for test of t.
R
A named variable that will contain the vector of linear correlation coefcients.
REGRESS IDL Reference Guide
Rmul
A named variable that will contain the multiple linear correlation coefcient.
Chisq
A named variable that will contain a reduced, weighted chi-squared.
Status
Anamedvariablethat will contain thestatusof theinternal arrayinversion computation.
Statuswill contain 0 (zero) if the array was successfully inverted. Statuswill contain the
integer 1(one) if thearray wasnot successfully inverted becauseit issingular. Statuswill
containtheinteger 2(two) if thereisapossibilitythat theresult of theinversionandthe
resultingcoefcientsreturnedbyREGRESSisinaccurateduetotheuseof asmall pivot
element.
Keywords
RELATIVE_WEIGHT
If thiskeyword isset, theinput weights(theWvector) areassumed to berelativevalues,
and not based on known uncertaintiesin theYvector. Set thiskeyword in thecaseof no
weighting.
Example
X = [[0.0, 0.0], $ Createa two by six array of inde-
pendent variabledata.
[2.0, 1.0], $
[2.5, 2.0], $
[1.0, 3.0], $
[4.0, 6.0], $
[7.0, 2.0]]
Y = [5.0, 10.0, 9.0, 0.0, 3.0, 27.0] CreateanNpoints-elementvector
of dependent variabledata.
weights = REPLICATE(1.0, N_ELEMENTS(Y)) CreateanNpoints-elementvector
of uniform weights.
result = REGRESS(X, Y, weights, yfit, const, /RELATIVE_WEIGHT)
Computethefitusingmultiplelin-
ear regression
PRINT, const, result[0], result[1] Print thecoefficients of theregres-
sion model.
IDL prints:
5.00000 4.00000 -3.00000
See Also
CURVEFIT, GAUSSFIT, LMFIT, POLY_FIT, POLYFITW, SFIT, SVDFIT
IDL Reference Guide REPLICATE
REPLICATE
The REPLICATE function returns an array with the given dimensions, lled with the
scalar value specied as the rst parameter.
Calling Sequence
Result = REPLICATE(Value, D
1
[, ..., D
n
])
Arguments
Value
Thescalar valuewith which toll theresultingarray. Thetypeof theresult isthesameas
that of Value. Valuecan be any single element expression such as a scalar or 1 element
array. This includes structures.
D
i
The dimensions of the result.
Example
Create D, a 5-element by 5-element array with every element set to the string IDL by
entering:
D = REPLICATE('IDL', 5, 5)
REPLICATE can also be used to create arrays of structures. For example, the following
command creates a structure named emp that contains a string name eld and a long
integer employee ID eld:
employee = {emp, NAME:' ', ID:0L}
To create a 10-element array of this structure, enter:
emps = REPLICATE(employee, 10)
See Also
MAKE_ARRAY
REPLICATE_INPLACE IDL Reference Guide
REPLICATE_INPLACE
The REPLICATE_INPLACE procedure updates an existing array by replacing all or
selected parts of it with a specied value. REPLICATE_INPLACE can be faster and use
lessmemorythantheIDLfunctionREPLICATEor theIDLarraynotationfor largearrays
that already exist.
Note REPLICATE_INPLACE is much faster when operating on entire arrays and rows,
than when used on columns or higher dimensions.
Calling Sequence
REPLICATE_INPLACE, X, Value[, D1, Loc1 [, D2, Range]]
Arguments
X
Thearraytobeupdated. Xcan beof anynumerictype. REPLICATE_INPLACEdoesnot
change the size and type of X.
Value
Thevaluewhichwill ll all or part of X. Valuemaybeanyscalar or one-element arraythat
IDL can convert to the type of X. REPLICATE_INPLACE does not changeValue.
D1
An optional parameter indicating which dimension of X is to be updated.
Loc1
An array with thesamenumber of elementsasthenumber of dimensionsof X. TheLoc1
and D1argumentstogether determinewhich one-dimensional subvector (or subvectors,
if D1 and Rangeare provided) of X is to be updated.
D2
An optional parameter, indicatingin which dimension of Xagroup of one-dimensional
subvectors are to be updated. D2 should be different fromD1.
Range
An array of indices of dimension D2 of X, indicating where to put one-dimensional
updates of X.
Example
A = FLTARR( 40, 90, 10) Createa multidimensional zero
array.
IDL Reference Guide REPLICATE_INPLACE
REPLICATE_INPLACE, A, 4.5 Populateitwiththevalue4.5.(i.e.,
A[*]=4.5 )
REPLICATE_INPLACE, A, 20, 1, [0,4,0] Updatea singlesubvector.
(i.e., A[*,4,0]=20. )
REPLICATE_INPLACE, A, -8, 3, [0,0,0], 2, [0,5,89]
Updatea group of subvectors.
(i.e., A[ 0, [0, 5,89], * ] =-8 )
REPLICATE_INPLACE, A, 0., 3, [9,0,0] , 2, LINDGEN(90)
Updatea2-dimensional sliceofA
(i.e., A[9,*, *] =0.)
See Also
REPLICATE, BLAS_AXPY
RESOLVE_ALL IDL Reference Guide
RESOLVE_ALL
The RESOLVE_ALL procedure iteratively resolves (by compiling) any uncompiled user-
written or library procedures or functions that are called in any already-compiled
procedure or function. The process ends when there are no unresolved routines left to
compile. If anunresolvedprocedureor functionisnot intheIDLsearchpath, thisroutine
exits with an error, and no additional routines are compiled.
RESOLVE_ALL is useful when preparing SAVE/RESTORE les containing all the IDL
routines required for an application.
Note RESOLVE_ALL does not resolve procedures or functions that are called via
CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE. Class methods are not
resolved either.
Similarly, RESOLVE_ALL does not resolve widget event handler procedures based on a
call to the widget routine that uses the event handler. In general, it is best to include the
event handlingroutinein thesameprogramleasthewidget creation routinebuilding
widget programs in this way ensures that RESOLVE_ALL will catch the event handler
for a widget application.
Note RESOLVE_ALL isof special interest when constructingan IDL SAVElecontaining
thecompiledcodefor apackageof routines. If you areconstructingsucha.sav le,
that contains calls to built-in IDL system functions that are not present under all
operating systems (e.g., IOCTL, TRNLOG), you must make sure to use
FORWARD_FUNCTIONtotell IDLthat thesenamesarefunctions. Otherwise, IDL
may interpret them as arrays and generate unintended results.
resolve_all.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
RESOLVE_ALL
Keywords
CONTINUE_ON_ERROR
Set this keyword to allow continuation upon error.
QUIET
Set this keyword to suppress informational messages.
IDL Reference Guide RESOLVE_ALL
See Also
RESOLVE_ROUTINE, ROUTINE_INFO, .COMPILE in Executive Commands on
page 31.
RESOLVE_ROUTINE IDL Reference Guide
RESOLVE_ROUTINE
The RESOLVE_ROUTINE procedure compiles user-written or library procedures or
functions, given their names. Routinesarecompiledeven if theyarealreadydened. This
procedure is similar to the .COMPILE executive command, but can be invoked within
procedures and functions.
Calling Sequence
RESOLVE_ROUTINE, Name
Arguments
Name
Ascalar stringor stringarraycontainingthenameor namesof theprocedurestocompile.
If Namecontains functions rather than procedures, set the IS_FUNCTION keyword.
Keywords
IS_FUNCTION
Set this keyword to compile functions rather than procedures.
See Also
RESOLVE_ALL, ROUTINE_INFO, .COMPILE in Executive Commands on page 31.
IDL Reference Guide RESTORE
RESTORE
The RESTORE procedure restores the IDL variables and routines saved in a le by the
SAVE procedure.
Caution While les containing IDL variables can be restored by any version of IDL that
supportsthedatatypesof thevariables(inparticular, byanyversionof IDLlater than
the version that created the SAVE le), les containing IDL routines can only be
restored by versions of IDL that share the same internal code representation. Since
theinternal coderepresentationchangesregularly, youshouldalwaysarchivetheIDL
language source les (.pro les) for routines you are placing in IDL SAVE les so
you can recompile the code when a new version of IDL is released.
Note to VMS Users
When reading older VMS format les, IDL knows that all oating-point values are in
VAX format. These oating values are automatically converted to IEEE format. Only
VMS/IDL is able to restore the native VMS format.
Note If you are restoring a le created with VAX IDL version 1, you must restore on a
machine running VMS.
Calling Sequence
RESTORE[, Filename]
Arguments
Filename
A scalar string that contains the name of the le from which the IDL objects should be
restored. If not present, the leidlsave.dat is used.
Keywords
FILENAME
The name of the le from which the IDL objects should be restored. If not present, the
leidlsave.dat isused. Thiskeyword servesexactlythesamepurposeastheFilename
argumentonly one of them needs to be provided.
RELAXED_STRUCTURE_ASSIGNMENT
Normally, RESTORE is unable to restore a structure variable if the denition of its type
has changed since the SAVE le was written. A common case where this occurs is when
objectsaresaved and theclassstructureof theobjectschangebeforethey arerestored in
another IDL session. In such cases, RESTORE issues an error, skips the structure, and
continues restoring the remainder of the SAVE le.
RESTORE IDL Reference Guide
Setting the RELAXED_STRUCTURE_ASSIGNMENT keyword causes RESTORE to
restore such incompatible values using relaxed structure assignment, in which all
possible data are restored using a eld-by-eld copy. (See the description of the
STRUCT_ASSIGN procedure for additional details.)
RESTORED_OBJECTS
Set thiskeyword equal to anamed variablethat will contain an array of object references
for anyobjectsrestored. Theresultinglist of objectsisuseful for programmaticallycalling
the objects restore methods. If no objects are restored, the variable will contain a null
object reference.
VERBOSE
Set this keyword to have IDL print an informative message for each restored object.
Example
Suppose that you have saved all the variables from a previous IDL session with the
command:
SAVE, /VARIABLES, FILENAME = 'session1.sav'
The variables in the lesession1.sav can be restored by entering:
RESTORE, 'session1.sav'
See Also
JOURNAL, SAVE, STRUCT_ASSIGN
IDL Reference Guide RETALL
RETALL
TheRETALL command returnscontrol tothemain programlevel. Theeffect isthesame
as entering the RETURN command at the interactive command prompt until the main
level is reached.
Calling Sequence
RETALL
Arguments
None
See Also
RETURN
RETURN IDL Reference Guide
RETURN
The RETURN command causes the program context to revert to the next-higher
program level. RETURN can be called at the interactive command prompt (see
.RETURN on page 33), inside a procedure denition, or inside a function denition.
Calling RETURN from the main program level has no effect other than to print an
informational message in the command log.
CallingRETURN insideaproceduredenition returnscontrol to thecallingroutine, or
tothemain level. SincetheENDstatement in aproceduredenition alsoreturnscontrol
tothecallingroutine, it isonlynecessarytouseRETURNin aproceduredenition if you
wish control to revert to the calling routine before the procedure reaches its END
statement.
In a function denition, RETURN serves to dene the value passed out of the function.
Only a single value can be returned from a function.
Note The value can be an array or structure containing multiple data items.
Calling Sequence
RETURN, [Return_value]
Arguments
Return_value
In afunction denition, theReturn_valueisthevaluepassed out of thefunction when it
completes its processing.
Return valuesarenot allowed in proceduredenitions, or when callingRETURN at the
interactive command prompt.
Examples
You can useRETURN within aproceduredenition to exit theprocedureat somepoint
other than the end. For example, note the following procedure:
PRO RET_EXAMPLE, value
IF value THEN BEGIN
PRINT, value, ' is nonzero'
RETURN
END
PRINT, 'Input argument was zero.'
IDL Reference Guide RETURN
END
If theinput argument isnon-zero, theroutineprintsthevalueandexitsback tothecalling
procedure or main level. If the input argument is zero, control proceeds until the END
statement is reached.
When deningfunctions, useRETURN to specify thevaluereturned fromthefunction.
For example, the following function:
FUNCTION RET_EXAMPLE2, value
RETURN, value * 2
END
multipliestheinput valueby two and returnstheresult. If thisfunction isdened at the
main level, calling it from the IDL command prompt produces the following:
PRINT, RET_EXAMPLE2(4)
IDL prints:
8
See Also
RETALL
REVERSE IDL Reference Guide
REVERSE
The REVERSE function reverses the order of rows or columns in a one-, two-, or three-
dimensional array.
reverse.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = REVERSE(Array [, Subscript_Index])
Arguments
Array
The array containing the original data.
Subscript_Index
If thisparameter isomittedor 1, therst subscript isreversed(i.e., columnsarereversed).
Set thisparameter to2toreverserows. Set thisparameter to3toreversearoundthethird
dimension of the array. This argument must be present if Array is three dimensional.
Example
Reverse the order of an array where each element is set to the value of its subscript:
A = [[0,1,2],[3,4,5],[6,7,8]] Createan array.
PRINT, A Print thearray.
IDL prints:
0 1 2
3 4 5
6 7 8
PRINT, REVERSE(A) Reversethecolumns of A.
IDL prints:
2 1 0
5 4 3
8 7 6
IDL Reference Guide REVERSE
PRINT, REVERSE(A, 2) Reversetherows of A.
IDL prints:
6 7 8
3 4 5
0 1 2
See Also
INVERT, REFORM, ROT, ROTATE, SHIFT, TRANSPOSE
REWIND IDL Reference Guide
REWIND
TheREWIND procedurerewindsthetapeon thedesignated IDL tapeunit. REWIND is
available only under VMS. See the description of the magnetic tape routines in VMS-
Specic Information on page 217 of Building IDL Applications.
Calling Sequence
REWIND, Unit
Arguments
Unit
The magnetic tape unit to rewind. Unit must be a number between 0 and 9, and should
not be confused with standard le Logical Unit Numbers (LUNs).
See Also
SKIPF, TAPRD
IDL Reference Guide RIEMANN
RIEMANN
The RIEMANN procedure computes the Riemann sum (or its inverse) which helps
implement the backprojection operator used to reconstruct the cross-section of an
object, given projections through the object from multiple directions. This technique is
widely used in medical imaging in the elds of computed x-ray tomography, MRI
imaging, Positron Emission Tomography (PET), and also hasapplicationsin other areas
such as seismology and astronomy. The inverse Riemann sum, which evaluates the
projectionsgiven aslicethrough an object, isalsoadiscreteapproximation totheRadon
transform.
Given amatrix A(m,n), which will contain thereconstructed slice; avector P, containing
theray sumsfor agiven view; and an angleThetameasured in radiansfromthevertical:
theRiemann sum backprojects thevector Pinto A. For each element of A, thevalueof
the closest element of P is summed, leaving the result in A. Bilinear interpolation is an
option. All operations are performed in single-precision oating point.
In thereverseoperation, theraysumscontainedin theviewvector, P, arecomputedgiven
the original slice, A, and Theta. This is sometimes called front projection.
The Riemann sum can be written:
which isthesumof thedataalonglinesthrough an imagewith an angleof thetafromthe
vertical.
Calling Sequence
RIEMANN, P, A, Theta
Arguments
P
Ak-element oating-point projectionvector (or matrixif theROWkeywordisspecied).
For backprojection (when the BACKPROJECT keyword is set), P contains the ray sums
for a single view. For the inverse operation, P should contain zeros on input and will
contain the ray sums for the view on output.
A
An mby noating-point imagematrix. For backprojection, Acontainstheaccumulated
results. For the inverse operation, A contains the original image. Typically, k should be
larger than
A r i ( ) cos i , ( )
i 0 =
M 1

RIEMANN IDL Reference Guide
which is the diagonal size of A.
Theta
The angle of the ray sums from the vertical.
Keywords
BACKPROJECT
Set thiskeywordtoperformbackprojection in whichPissummedintoA. If thiskeyword
is not set, the inverse operation occurs and the ray sums are accumulated into P.
BILINEAR
Set this keyword to use bilinear interpolation rather than the default nearest neighbor
sampling. Results are more accurate but slower when bilinear interpolation is used.
CENTER
Set thiskeywordequal toaoating-point number specifyingthecenter of theprojection.
The default value for CENTER is one-half the number of elements of P.
COR
Set this keyword equal to a two-element oating-point vector specifying the center of
rotation in the array A. The default value is [ m/2., n/2.] , whereA is an mby n array.
For symmetric results, given symmetric operands, COR should be set to the origin of
symmetry [ (m-1)/2, (n-1)/2] , and CENTER should be set to (n-1)/2., wheren is the
number of elements in the projection vector, P.
CUBIC
0
, and f is sampled
with spacinglessthan or equal to 1/2
0
, then f can bereconstructed by convolvingwith
a sinc function: sinc(x) = sin (x) / (x).
m
2
n
2
+
IDL Reference Guide RIEMANN
CA, July 1974.
D
Usethiskeywordtospecifythespacingbetweenelementsof P, expressedinthesameunits
as the spacing between elements of A. The default is 1.0.
ROW
Set this keyword to specify theP vector as a given row within a matrix, so that the
sinogramarray can beused directly without havingto extract or insert each row. In this
case, Pmust bean array with arst dimension equal tok, and thevalueof ROWmust be
in the range of 0 to the number of vectors of length k in P, minus one.
Example
This example forms a synthetic image in A, computesNviewsequally spaced views, and
stores the stacked projections (commonly called the sinogram ) in a matrix PP. It then
backprojects the projections into the matrix B, forming the reconstructed slice. In
practical use, the projections are convolved with a lter before being backprojected.
N = 100L Definenumber of columns in A.
M = 100L Definenumber of rows in A.
nviews = 100 Number of views.
K = CEIL(SQRT(N^2 + M^2)) Thelength of thelongest projec-
tion. If filtered backprojection is
used, 1/2 thelength of theconvo-
lution kernel must also beadded.
A = FLTARR(N, M) Form original slice.
A(N/2:N/2+5, M/2:M/2+5) = 1.0 Simulatea squareobject.
pp = FLTARR(K, nviews) Makearray for sinogram.
FOR I=0, NVIEWS-1 DO RIEMANN, pp, A, I * !PI/nviews, ROW=i
Computeeach view.
TVSCL, pp Show sinogram.
B = FLTARR(N,M) Initial reconstructed image.
FOR I=0, nviews-1 DO $ Do thebackprojection for each
view.
RIEMANN, pp, B, I * !PI/nviews, /BACKPROJECT, ROW=i
TVSCL, B Show reconstructed array.
RIEMANN IDL Reference Guide
See Also
VOXEL_PROJ
IDL Reference Guide RK4
RK4
TheRK4function usesthefourth-order Runge-Kuttamethod to advanceasolution to a
system of ordinary differential equations one time-step H, given values for the variables
Y and their derivativesDydx known at X.
RK4isbased on theroutinerk4 described in section 16.1of Numerical RecipesinC: The
Art of Scientic Computing(Second Edition), published by Cambridge University Press,
and is used by permission.
Calling Sequence
Result = RK4(Y, Dydx, X, H, Derivs)
Arguments
Y
A vector of values for Y at X
Dydx
A vector of derivatives for Y at X.
X
A scalar value for the initial condition.
H
A scalar value giving interval length or step size.
Derivs
values of the derivativesDydx at X. This function must accept two arguments: A scalar
oating valueX, and onen-element vector Y. It must return an n-element vector result.
For example, supposethevaluesof thederivativesaredened by thefollowingrelations:
dy
0
/ dx = 0.5y
0,
dy
1
/ dx = 4.0 0.3y
1
0.1y
0
We can write a function DIFFERENTIAL to express these relationships in the IDL
language:
FUNCTION differential, X, Y
RETURN, [-0.5 * Y[0], 4.0 - 0.3 * Y[1] - 0.1 * Y[0]]
END
RK4 IDL Reference Guide
Keywords
DOUBLE
Example
To integrate the example system of differential equations for one time step, H:
H = 0.5 Definethestep size.
X = 0.0 Definean initial X value.
Y = [4.0, 6.0] Defineinitial Y values.
dydx = DIFFERENTIAL(X,Y) Calculatetheinitial derivative
values.
result = RK4(Y, dydx, X, H, 'differential')
Integrateovertheinterval (0,0.5).
IDL prints:
3.11523 6.85767
This is the exact solution vector to ve-decimal precision.
See Also
BROYDEN, NEWTON
IDL Reference Guide ROBERTS
ROBERTS
The ROBERTS function returns an approximation to the Roberts edge enhancement
operator for images: Ga(j,k) = (F
j, k
F
j + 1, k+ 1
( + (F
j, k+ 1
F
j + 1, k
(
which is a simple, two-dimensional differencing method for edge-sharpening and
isolation. Theresult of thisfunction isatwo-dimensional array of integer type, with the
same dimensions asImage.
Calling Sequence
Result = ROBERTS(Image)
Arguments
Image
Thetwo-dimensional array containingtheimageto which edgeenhancement isapplied.
Example
If thevariableIM containsatwo-dimensional imagearray, aRobertssharpened version
of IM can be displayed with the command:
TVSCL, ROBERTS(IM)
See Also
SOBEL
ROT IDL Reference Guide
ROT
The ROT function rotates an image by an arbitrary amount. At the same time, it can
magnify, demagnify, and/or translate an image. Note that if you want to rotate an array
by a multiple of 90 degrees, you should use the ROTATE function for faster results.
rot.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = ROT(A, Angle, [Mag, X
0
, Y
0
])
Arguments
A
The image array to be rotated. This array can be of any type, but must have two
dimensions. Theoutput imagehasthesamedimensionsanddatatypeof theinput image.
ANGLE
Angle of rotation in degreesclockwise.
MAG
An optional magnication factor. Avalueof 1.0resultsin nochange. Avaluegreater than
one performs magnication and a value less than one performs demagnication.
X
0
Xsubscript for thecenter of rotation. If omitted, X
0
equalsthenumber of columnsin the
image divided by 2.
Y
0
Y subscript for the center of rotation. If omitted, Y
0
equals the number of rows in the
image divided by 2.
Keywords
INTERP
Set this keyword to use bilinear interpolation. The default is to use nearest neighbor
sampling.
CUBIC
IDL Reference Guide ROT
0
, and f is sampled
0
CA, July 1974.
MISSING
Set this keyword to a value to be substituted for pixels in the output image that map
outside the input image.
PIVOT
Set thiskeyword to causetheimageto pivot around thepoint (X
0
, Y
0
) so that thispoint
mapsintothesamepoint in theoutput image. Bydefault, thepoint (X
0
, Y
0
) in theinput
image is mapped into the center of the output image.
Example
A = BYTSCL(DIST(256)) Createa byteimage.
TV, A Display it.
B = ROT(A, 33, 1.5, /INTERP) Rotatetheimage33degrees,mag-
nify it 15 times, and usebilinear
interpolation to maketheoutput
look nice.
TV, B Display therotated image.
See Also
ROTATE
ROTATE IDL Reference Guide
ROTATE
The ROTATE function returns a rotated and/or transposed copy of Array. ROTATE can
only rotate arrays in multiples of 90 degrees. To rotate by amounts other than multiples
of 90 degrees, use the ROT function. Note, however, that ROTATE is more efcient.
ROTATE can also be used to reverse the order of elements in vectors. For example, to
reverse the order of elements in the vector X, use the expression ROTATE(X,2). If X =
[ 0,1,2,3] then ROTATE(X,2)yields the resulting array, [ 3,2,1,0] .
Transposition isperformedbeforerotation. Rotationsareviewedwiththerst rowat the
top.
Calling Sequence
Result = ROTATE(Array, Direction)
Arguments
Array
The array to be rotated. Arraycan have only one or two dimensions. The result has the
sametypeasArray. Thedimensionsof theresult arethesameasthoseof Arrayif Direction
is equal to 0 or 2. The dimensions are transposed if the direction is 4 or greater.
Direction
Direction species the operation to be performed as follows:
Direction Transpose? RotationCounterclockwise X
1
Y
1
0 No None X
0
Y
0
1 No 90 -Y
0
X
0
2 No 180 -X
0
-Y
0
3 No 270 Y
0
-X
0
4 Yes None Y
0
X
0
5 Yes 90 -X
0
Y
0
6 Yes 180 -Y
0
-X
0
7 Yes 270 X
0
-Y
0
Table 9-64: Rotation Directions
IDL Reference Guide ROTATE
In thetableabove, (X
0
, Y
0
) aretheoriginal subscripts, and (X
1
, Y
1
) arethesubscriptsof
the resulting array. The notation -Y
0
indicates a reversal of the Y axis, Y
1
= N
y
- Y
0
- 1.
Direction is taken modulo 8, so a rotation of -1 is the same as 7, 9 is the same as 1, etc.
Note The assertion that Array is rotating counterclockwise may cause some confusion.
Remember that when arrays are displayed on the screen (using TV or TVSCL, for
example), the image is drawn with the origin (0,0) at the bottom left corner of the
window. Whenarraysareprintedontheconsoleor commandlogwindow(usingthe
PRINT command, for example), the(0,0) element isdrawn in theupper left corner
of thearray. Thismeansthat whilean imagedisplayed in awindowappearstorotate
counterclockwise, an array printed in thecommand logappearsto rotateclockwise.
Example
Create and display a wedge image by entering:
F = REPLICATE(1, 256) # FINDGEN(256) & TVSCL, F
To display the image rotated 90 degrees counterclockwise, enter:
TVSCL, ROTATE(F, 1)
See Also
ROT, TRANSPOSE
ROUND IDL Reference Guide
ROUND
TheROUND function returnstheinteger closest to itsargument. Thisvalueisreturned
as a longword integer with the same structure as the input argument.
Calling Sequence
Result = ROUND(X)
Arguments
X
Thevaluefor which theROUNDfunction istobeevaluated. Thisvaluecan besingle- or
double-precision, real or complex oating-point. ROUND returns a longword integer
with the same structure asX. Note that only the real part of a complex argument is
rounded and returned.
Example
To print the rounded values of a 2-element vector, enter:
PRINT, ROUND([5.1, 5.9])
IDL prints:
5 6
See Also
CEIL, COMPLEXROUND, FLOOR
IDL Reference Guide ROUTINE_INFO
ROUTINE_INFO
The ROUTINE_INFO function provides information about currently-compiled
procedures and functions. It returns a string array consisting of the names of dened
procedures or functions, or of parameters or variables used by a single procedure or
function.
Calling Sequence
Result = ROUTINE_INFO([Routine])
Arguments
Routine
Ascalar stringcontainingthenameof routinefor whichinformationwill bereturned. Routine
can beeither aprocedureor afunction. If Routineisnot supplied, ROUTINE_INFOreturns
a list of all currently-compiled procedures.
Keywords
FUNCTIONS
Set this keyword to return a string array containing currently-compiled functions. By
default, ROUTINE_INFOreturnsalist of compiledprocedures. If theSYSTEM keyword
is also set, ROUTINE_INFO returns a list of all IDL built-in internal functions.
PARAMETERS
Set this keyword to return an anonymous structure with the following elds:
NUM_ARGS
An integer containing the number of positional parameters used in Routine.
NUM_KW_ARGS
An integer containing the number of keyword parameters used in Routine.
ARGS
A string array containing the names of the positional parameters used in Routine.
KW_ARGS
A string array containing the names of the keyword parameters used in Routine.
Youmust supplytheRoutineargument whenusingthiskeyword. Notethat specifyingthe
SYSTEMkeywordalongwiththiskeywordwill generatean error. If Routinedoesnot take
any arguments, the ARGS eld is not included in the anonymous structure. Similarly, if
Routinedoes not take any keywords, the KW_ARGS eld is not included.
ROUTINE_INFO IDL Reference Guide
SOURCE
Set this keyword to return an array of anonymous structures with the following elds:
NAME
A string containing the name of the procedure or function.
PATH
A stringcontainingthefull path specication of thelethat containsthedenition
of the procedure or function.
If Routineis specied, information for that one routine is returned. If Routineis not
specied, information for all compiled routinesisreturned. If aroutineisunresolved or
itspathinformationisunavailablefor anyreason(if theroutinehasbeenSAVEdandthen
RESTOREd, for example), the PATH eld will contain a null string.
Notethat specifyingtheSYSTEMkeywordalongwiththiskeywordwill generatean error.
SYSTEM
Set thiskeywordtoreturn astringarraylistingall IDL built-in internal procedures. Built-
in internal procedures are part of the IDL executable, and arenot written in the IDL
language. If the FUNCTIONS keyword is also set, ROUTINE_INFO returns a list of all
IDL built-in internal functions.
UNRESOLVED
Set this keyword to return a string array listing procedures that are referenced in any
currently-compiledprocedureor function, but whicharethemselvesnot yet compiled. If
theFUNCTIONSkeywordisalsoset, ROUTINE_INFOreturnsalist of functionsthat are
referenced but not yet compiled.
Notethat specifyingtheSYSTEMkeywordalongwiththiskeywordwill generatean error.
VARIABLES
Set this keyword to return a string array listing variables dened in the procedure or
function.
Youmust supplytheRoutineargument whenusingthiskeyword. Notethat specifyingthe
SYSTEM keyword along with this keyword will generate an error.
See Also
RESOLVE_ALL, RESOLVE_ROUTINE
IDL Reference Guide RS_TEST
RS_TEST
TheRS_TESTfunctionteststhehypothesisthat twosamplepopulationsXandYhavethe
same mean of distribution against the hypothesis that they differ. X and Y may be of
different lengths. The result is a two-element vector containing the nearly-normal test
statisticZ and theone-tailed probability of obtainingavalueof Z or greater. Thistypeof
test isoften referredtoasthe Wilcoxon Rank-SumTest or the Mann-WhitneyU-Test.
The Mann-Whitney statistics for X and Y are dened as follows:
whereNxandNyarethenumber of elementsin XandY, respectively, andWxandWyare
therank sumsfor XandY, respectively. Thetest statisticZ, whichcloselyfollowsanormal
distribution for sample sizes exceeding 10 elements, is dened as follows:
rs_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = RS_TEST(X, Y)
Arguments
X
Y
An m-element integer, single-, or double-precision oating-point vector.
Keywords
UX
Set thiskeyword to anamed variablethat will contain theMann-Whitney statisticfor X.
U
x
N
x
N
y
N
x
N
x
1 + ( )
2
----------------------------- W
x
+ =
U
y
N
x
N
y
N
y
N
y
1 + ( )
2
----------------------------- W
y
+ =
Z
U
x
N
x
N
y
( ) 2
N
x
N
y
N
x
N
y
1 + + ( ) ( ) 12
--------------------------------------------------------------------- =
RS_TEST IDL Reference Guide
UY
Set this keyword to a named variable that will contain the Mann-Whitney statistic for Y.
Example
Dene two sample populations.
X = [-14, 3, 1, -16, -21, 7, -7, -13, -22, -17, -14, -8, $
7, -18, -13, -9, -22, -25, -24, -18, -13, -13, -18, -5]
Y = [-18, -9, -16, -14, -3, -9, -16, 10, -11, -3, -13, $
-21, -2, -11, -16, -12, -13, -6, -9, -7, -11, -9]
Test the hypothesis that two sample populations, {x
i
, y
i
}, have the same mean of
distribution against the hypothesis in that they differ at the 0.05 signicance level.
PRINT, RS_TEST(X, Y, UX = ux, UY = uy)
IDL prints:
[1.45134, 0.0733429]
Print the Mann-Whitney statistics:
PRINT, 'Mann-Whitney Statistics: Ux = ', ux, ', Uy = ', uy
IDL prints:
Mann-Whitney Statistics: Ux = 330.000, Uy = 198.000
therefore we do not reject the hypothesis that X and Y have the same mean of
distribution.
See Also
FV_TEST, KW_TEST, S_TEST, TM_TEST
IDL Reference Guide RSTRPOS
RSTRPOS
The RSTRPOS function nds thelast occurrence of a substring within an object string
(theSTRPOSfunction ndstherst occurrenceof asubstring). If thesubstringisfound
in the expression, RSTRPOS returns the character position of the match, otherwise it
returns -1.
rstrpos.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = RSTRPOS(Expression, Search_String [, Pos])
Arguments
Expression
The expression string in which to search for the substring.
Search_String
The substring to be searched for within Expression.
Pos
The character position before which the search is begun. If Posis omitted, the search
begins at the last character of Expression.
Example
exp = 'Holy smokes, Batman!' Definetheexpression.
pos = RSTRPOS(exp, 'smokes') Find theposition of a substring.
PRINT, pos Print thesubstrings position.
IDL prints:
5 Substringbeginsatposition5(the
sixth character).
See Also
STRPOS
S_TEST IDL Reference Guide
S_TEST
TheS_TEST function teststhehypothesisthat two samplepopulationsXand Yhavethe
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 xi and yi and its one-tailed signicance. This type of test is often
referred to as the Sign Test.
s_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = S_TEST(X, Y)
Arguments
X
Y
Keywords
ZDIFF
Set thiskeywordtoanamedvariablethat will contain thenumber of differencesbetween
correspondingpairsof xi and yi resultingin zero. Paired dataresultingin adifferenceof
zero are excluded from the ranking and the sample size is correspondingly reduced.
Example
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 thehypothesisthat thetwo samplepopulationshavethesamemean of distribution
against the hypothesis that they differ at the 0.05 signicance level.
PRINT, S_TEST(X, Y, ZDIFF = zdiff)
IDL prints:
[9.00000, 0.0729981]
IDL Reference Guide S_TEST
thereforewedonot reject thehypothesisthat XandYhavethesamemeanof distribution.
See Also
FV_TEST, KW_TEST, MD_TEST, RS_TEST, TM_TEST
SAVE IDL Reference Guide
SAVE
TheSAVEproceduresavesvariables, systemvariables, andIDLroutinesin aleusingthe
XDR (eXternal Data Representation) format for later recovery by RESTORE. Note that
variablesandroutinescannot besavedinthesamele. Notealsothat savelescontaining
routines may not be compatible between different versions of IDL, but that les
containing data are always backwards-compatible.
Calling Sequence
SAVE[, Var
1
, ..., Var
n
]
Arguments
Var
n
Optional named variables that are to be saved.
Keywords
ALL
Set thiskeywordtosaveall commonblocks, systemvariables, andlocal variablesfromthe
current IDL session.
Note Routinesandvariablescannot besavedinthesamele. SettingtheALLkeyworddoes
not save routines.
COMM
Set this keyword to save all main level common block denitions. Note that setting this
keyword does not cause the contents of the common block to be saved unless the
VARIABLES keyword is also set.
FILENAME
Astringcontainingthenameof theleintowhichtheIDLobjectsshouldbesaved. If this
keyword is not specied, the leidlsave.dat is used.
ROUTINES
Set this keyword to save user dened procedures and functions in a machine
independent, binaryform. If parametersarepresent, theymust bestringscontainingthe
names of the procedures and/or functions to be saved. If no parameters are present, all
compiledroutinesaresaved. If youareusingVMS, seetheXDRkeywordbelow. Routines
and variables cannot be saved in the same le.
Caution Because SAVE stores routines in a binary format, save les containing routines are
not guaranteed tobecompatiblebetween successiveversionsof IDL. You will not be
able to RESTORE save les containing routines if they are made with incompatible
IDL Reference Guide SAVE
versionsof IDL. In thiscase, youshouldrecompileyour original codewiththenewer
version of IDL. Save les containing data will always be restorable.
SYSTEM_VARIABLES
Set this keyword to save the current state of all system variables.
Caution Saving system variables is not recommended, as the structure may change between
versions of IDL.
VARIABLES
Set this keyword to save all variables in the current program unit. This option is the
default.
VERBOSE
Set this keyword to print an informative message for each saved object.
XDR
This keyword is obsoleteand will bequietly ignored (thereis no need to removeuses of the
XDR keyword from existing code). IDL always generates XDR format les, although it will
continueto read VAX format SAVE les generated by old versions of VMS IDL.
Example
Save the status of all currently-dened variables in the le variables1.dat by entering:
SAVE, /VARIABLES, FILENAME = 'variables1.dat'
The variables can be restored with the RESTORE procedure. Save the user procedures
MYPROC and MYFUN:
SAVE, /ROUTINES, 'MYPROC', 'MYFUN'
See Also
JOURNAL, RESOLVE_ALL, RESTORE
SCALE3 IDL Reference Guide
SCALE3
The SCALE3 procedure sets up transformation and scaling parameters for basic 3D
viewing. This procedure is similar to SURFR and SCALE3D, except that the data ranges
must be specied and the scaling does not vary with rotation. Results are stored in the
system variables !P.T, !X.S, !Y.S, and !Z.S.
scale3.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SCALE3
Keywords
XRANGE
A two-element vector containing the minimum and maximum X values. If omitted, the
X-axis scaling remains unchanged.
YRANGE
A two-element vector containing the minimum and maximum Y values. If omitted, the
Y-axis scaling remains unchanged.
ZRANGE
A 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.
Example
Set up a3D transformation wherethedatarangeis0to 20for each of the3axesand the
viewing area is rotated 20 degrees about the X axis and 55 degrees about the Z axis:
SCALE3, XRANGE=[0, 20], YRANGE=[0, 20], ZRANGE=[0, 20], AX=20, AZ=55
See Also
SCALE3D, SURFR, T3D
IDL Reference Guide SCALE3D
SCALE3D
The SCALE3D procedure scales the 3D unit cube (a cube with the length of each side
equal to 1) into the viewing area. Eight data points are created at the vertices of the 3D
unit cube. Theverticesarethen transformed by thevalueof thesystemvariable!P.T. The
systemistranslated to bringtheminimum(x,y,z) point to theorigin, and then scaled to
makeeach coordinatesmaximumvalueequal to 1. The!P.T systemvariableismodied
as a result.
scale3D.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SCALE3D
See Also
SCALE3, SURFR, T3D
SEARCH2D IDL Reference Guide
SEARCH2D
The SEARCH2D function nds objects or regions of similar data values within a two-
dimensional array. Given a starting location and a range of values to search for,
SEARCH2Dndsall thecellswithinthearraythat arewithinthespeciedrangeandhave
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 specied tolerances.
SEARCH2D returns a longword array that contains a list of the array subscripts that
dene the located object or region. The original X and Y indices of the array subscripts
returned by SEARCH2D can be found with the following IDL code:
index_y = Result / (SIZE(Array))(1)
index_x = Result - (index_y * (SIZE(Array))(1))
whereResult is the array returned by SEARCH2D and Array is the original input array.
The object within Array can be subscripted asArray(Region) or Array(index_x,
index_y).
search2d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = SEARCH2D(Array, Xpos, Ypos, Min_Val, Max_Val)
Arguments
Array
A two-dimensional array, of any data type, to be searched.
Xpos
The X coordinate (dimension 0 of Array) of the starting location.
Ypos
The Y coordinate (dimension 1 of Array) of the starting location.
Min_Val
The minimum data value for which to search. All array subscripts of all cells that are
connectedtothestartingcell, andhaveavaluebetweenMin_Val andMax_Val (inclusive)
are returned.
Max_Val
The maximum data value for which to search.
IDL Reference Guide SEARCH2D
Keywords
DECREASE
This keyword and the INCREASE keyword allow you to compensate for changing
intensitiesof datavalueswithin an object. An edge-enhanced copy of Arrayismadeand
compared to theorginal array if thiskeyword isset. When DECREASEor INCREASEis
set, any adjacent cells are found if their corresponding data values in the edge enhanced
arrayaregreater thanDECREASEandlessthanINCREASE. Inanycase, theadjacent cells
will never be selected if their data values are not between Min_Val and Max_Val. The
default for this keyword is 0.0 if INCREASE is specied.
INCREASE
This keyword and the DECREASE keyword allow you to compensate for changing
default for this keyword is 0.0 if DECREASE is specied.
LPF_BAND
Set this keyword to an integer value of 3 or greater to perform low-pass ltering on the
edge-enhanced array. The value of LPF_BAND is used as the width of the smoothing
window. ThiskeywordisonlyeffectivewhentheDECREASEor INCREASEkeywordsare
also specied. The default is no smoothing.
DIAGONAL
Set this keyword to cause SEARCH2D to nd cells meeting the search criteria whose
surrounding squares share a common corner. Normally, cells are considered adjacent
only when squares surrounding the cells share a common edge. Setting this option
requires more memory and execution time.
Example
Find all the indices corresponding to an object in an image:
img = FLTARR(512, 512) Createan imagewith different
valued regions.
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
TVSCL, img Display theimage.
region = SEARCH2D(img, 175, 300, 0.6, 0.8, /DIAGONAL)
Search for an object startingat
(175, 300) whosedata values are
between (0.6) and (0.8).
img = BYTSCL(img, TOP=127B) Scalethebackgroundcellsintothe
range0 to 127.
img[region] = 255B Highlight theobject region by set-
tingit to 255.
TVSCL, img Display thearray with thehigh-
lighted object in it.
See Also
SEARCH3D
SEARCH3D
The SEARCH3D function nds objects or regions of similar data values within a 3D
array of data. Given a starting location and a range of values to search for, SEARCH3D
ndsall thecellswithin thevolumethat arewithin thespecied rangeof valuesand 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 specied tolerances.
SEARCH3D returns a longword array that contains a list of the array subscripts that
dene the selected object or region. The original X and Y indices of the array subscripts
returned by SEARCH3D can be found with the following IDL code:
S = SIZE(Array)
index_z = Result / (S[1] * S[2])
index_y = (Result - (index_z * S[1] * S[2])) / S[1]
index_x = (Result - (index_z * S[1] * S[2])) - (index_y * S[1])
whereResultisthearrayreturnedbySEARCH3Dand Arrayistheoriginal input volume.
The object within Array can be subscripted asArray[Region] or Array[index_x,
index_y, index_z].
search3d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = SEARCH3D(Array, Xpos, Ypos, Zpos, Min_Val, Max_Val)
Arguments
Array
The three-dimensional array, of any data type except string, to be searched.
Xpos
The X coordinate (dimension 0 or Array) of the starting location.
Ypos
The Y coordinate (dimension 1 of Array) of the starting location.
Zpos
The Z coordinate (dimension 2 of Array) of the starting location.
Min_Val
Theminimumdatavaluefor which to search. All array subscriptsof all thecellsthat are
connectedtothestartingcell, andhaveavaluebetweenMin_Val andMax_Val (inclusive)
are returned.
Max_Val
The maximum data value for which to search.
Keywords
DECREASE
This keyword and the INCREASE keyword allow you to compensate for changing
default for this keyword is 0.0 if INCREASE is specied.
INCREASE
This keyword and the DECREASE keyword allow you to compensate for changing
default for this keyword is 0.0 if DECREASE is specied.
LPF_BAND
Set this keyword to an integer value of 3 or greater to perform low-pass ltering on the
edge-enhanced array. The value of LPF_BAND is used as the width of the smoothing
window. ThiskeywordisonlyeffectivewhentheDECREASEor INCREASEkeywordsare
also specied. The default is no smoothing.
DIAGONAL
Set this keyword to cause SEARCH3D to nd cells meeting the search criteria whose
surrounding cubes share a common corner or edge. Normally, cells are considered
adjacent onlywhencubessurroundingthecellsshareacommonedge. Settingthisoption
requires more memory and execution time.
Example
Find all the indices corresponding to an object contained in a 3D array:
vol = RANDOMU(s, 40, 40, 40) Createsomedata.
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
region = SEARCH3D(vol, 6, 22, 16, 1.2, 1.4, /DIAGONAL)
Searchforanobjectstartingat(6,
22, 16) whosedata values arebe-
tween (1.2) and (1.4).
vol = BYTSCL(vol, TOP=127B) Scalethebackgroundcellsintothe
range0 to 127.
vol[Region] = 255B Highlight theobject region by set-
tingit to 255.
WINDOW, 0, XSIZE=640, YSIZE=512, RETAIN=2
CREATE_VIEW, XMAX=39, YMAX=39, ZMAX=39, AX=(-30), AZ=30, ZOOM=0.8
Set up a 3-D view.
TVSCL, PROJECT_VOL(vol, 64, 64, 40, DEPTH_Q=0.4)
Displaythevolumewiththehigh-
lighted object in it.
See Also
SEARCH2D
SET_PLOT IDL Reference Guide
SET_PLOT
The SET_PLOT procedure sets the output device used by the IDL graphics procedures.
Keyword parameters control how the color tables are transferred to the newly selected
graphics device. SET_PLOT performs the following actions:
It sets the read-only system variable !D to reect the conguration of the new device.
It setsthedefault color !P.COLORtothemaximumcolor index minusoneor, in thecase
of devices with white backgrounds, such as PostScript, to 0 (black).
If theCOPYkeywordisset, thedevicecolor tablesarecopieddirectlyfromIDLsinternal
color tables. If the new devices color tables contain more indices than those of the old
device, the new devices tables are not completely lled.
If the INTERPOLATE keyword is set, the internal color tables are interpolated to ll the
range of the new device.
It sets the clipping rectangle to the entire device surface.
Warnings: After calling SET_PLOT to change graphics devices, the scaling contained in
the axis structures !X, !Y, and !Z is invalid. Any routines that rely on data coordinates
should not be called until a new data coordinate system has been established. Be careful
whenswitchingdevicesasthenumber of color indicesfrequentlydiffersbetweendevices.
When in doubt, reload the color table of the new device explicitly.
Calling Sequence
SET_PLOT, Device
Arguments
Device
Ascalar stringcontainingthenameof thedeviceto use. Thecaseof Deviceisignored by
IDL. See Chapter 8, IDL Graphics Devices for a list of device names.
Keywords
COPY
Set thiskeyword to copy thedevicescolor tablefromtheinternal color table, preserving
the current color mapping. The default is not to load the color table upon selection.
Caution Unlessthiskeyword isset, IDLsinternal color tableswill incorrectly reect thestate
of the devices color tables until they are reloaded by TVLCT or the LOADCT
procedure. Assuming that the previously-selected devices color table containsM
IDL Reference Guide SET_PLOT
elements, and the new devices color table containsN elements, then the minimum
of M and N elements are loaded.
INTERPOLATE
Set thiskeywordtoindicatethat thecurrent contentsof theinternal color tableshouldbe
interpolatedtocover therangeof thenewly-selecteddevice. Otherwise, theinternal color
tables are not changed.
Example
Change the IDL graphics device to PostScript by entering:
SET_PLOT, 'PS'
After changing the plotting device, all graphics commands are sent to that device until
changed again by another use of the SET_PLOT routine.
SET_SHADING IDL Reference Guide
SET_SHADING
TheSET_SHADINGproceduremodiesthelight sourceshadingparametersthat affect
the output of SHADE_SURF and POLYSHADE. Parameters can be changed to control
the light-source direction, shading method, and the rejection of hidden surfaces.
SET_SHADINGrst resetstheshadingparameterstotheir default values. Theparameter
values specied in the call then overwrite the default values. To reset all parameters to
their default values, simply call this procedure with no parameters.
Calling Sequence
SET_SHADING
Arguments
None.
Keywords
GOURAUD
Thiskeyword controlsthemethod of shadingthesurfacepolygonsby thePOLYSHADE
procedure. The SHADE_SURF procedure always uses the Gouraud method. Set this
keyword to a nonzero value (the default), to use Gouraud shading. Set this keyword to
zero to shade each polygon with a constant intensity.
Gouraud shading interpolates intensities from each vertex along each edge. Then, when
scan converting the polygons, the shading is interpolated along each scan line from the
edgeintensities. Gouraudshadingisslower than constant shadingbut usuallyresultsin a
more realistic appearance.
LIGHT
A three-element vector that species the direction of the light source. The default light
source vector is [ 0,0,1] , with the light rays parallel to the Z axis.
REJECT
Set this keyword (the default) to reject polygons as being hidden if their vertices are
ordered in aclockwisedirection asseen by theviewer. Thiskeyword should alwaysbeset
when renderingenclosed solidswhoseoriginal vertex listsarein counterclockwiseorder.
When rendering surfaces that are not closed or are not in counterclockwise order this
keywordcanbeset tozeroalthoughshadinganomaliesat boundariesbetweenvisibleand
hidden surfaces may occur.
VALUES
Atwo-element arraythat speciestherangeof pixel values(color indices) touse. Therst
element isthecolor index for thedarkest pixel. Thesecond element isthecolor index for
IDL Reference Guide SET_SHADING
thebrightest pixel. For example, to render ashaded surfacewith thedarkest shadeset to
pixel value 100 and the brightest value set to 150, use the commands:
SET_SHADING, VALUES=[100, 150]
SHADE_SURF, dataset
Example
Change the light source so that the light rays are parallel to the X axis:
SET_SHADING, LIGHT = [1, 0, 0]
See Also
POLYSHADE, SHADE_SURF
SET_SYMBOL IDL Reference Guide
SET_SYMBOL
The SET_SYMBOL procedure denes a DCL (Digital Command Language) interpreter
symbol for the current process. SET_SYMBOL is available only under VMS.
Calling Sequence
SET_SYMBOL, Name, Value
Arguments
Name
A scalar string containing the name of the symbol to be dened.
Value
A scalar string containing the value with which Nameis dened.
Keywords
TYPE
Indicatesthetableinto which Namewill bedened. SettingTYPEto 1speciesthelocal
symbol table, whileavalueof 2speciestheglobal symbol table. Thedefault isthelocal
table.
See Also
DELLOG (VMS Only), DELETE_SYMBOL (VMS Only), SETLOG (VMS Only)
IDL Reference Guide SETENV (Unix and Windows Only)
SETENV (Unix and Windows Only)
The SETENV procedure adds or changes an environment string in the process
environment.
Calling Sequence
SETENV, Environment_Expression
Arguments
Environment_Expression
A scalar string containing an environment expression to be added to the environment.
Example
Change the current shell variable by entering:
SETENV,'SHELL=/bin/sh'
Make sure to elimate any whitespace around the equal sign:
SETENV, 'VAR = H:\rsi' Thisisanincorrectusage;thereare
spaces around theequal sign.
SETENV, 'VAR=H:\rsi' Thisiscorrect;VARissettoH:\rsi.
See Also
DELLOG (VMS Only), GETENV, SETLOG (VMS Only)
SETLOG (VMS Only) IDL Reference Guide
SETLOG (VMS Only)
The SETLOG procedure denes a logical name. SETLOG is available only under VMS.
Calling Sequence
SETLOG, Lognam, Value
Arguments
Lognam
A scalar string containing the name of the logical to be dened.
Value
A string containing the value to which the logical will be set. If Valueis a string array,
Lognamis dened as a multi-valued logical where each element of Valuedenes one of
the equivalence strings.
Keywords
CONCEALED
If this keyword is set, RMS (VMS Record Management Services) interprets the
equivalence name as a device name.
CONFINE
If thiskeyword isset, thelogical nameisnot copied fromtheIDL processto itsspawned
subprocesses.
NO_ALIAS
If this keyword is set, the logical name cannot be duplicated in the same logical table at
an outer access mode. If another logical name with the same name already exists at an
outer access mode, it is deleted. See theVMS System Services Manual for additional
information on logical names and access modes.
TABLE
Ascalar stringcontainingthenameof thelogical tableintowhichLognamwill beentered.
If TABLE is not specied, LNM$PROCESS_TABLE is used.
TERMINAL
If this keyword is set, when attempting to translate the logical, further iterative logical
name translation on the equivalence name is not to be performed.
IDL Reference Guide SETLOG (VMS Only)
See Also
DELETE_SYMBOL (VMSOnly), DELLOG(VMSOnly), SETENV (Unix and Windows
Only), SET_SYMBOL
SETUP_KEYS IDL Reference Guide
SETUP_KEYS
TheSETUP_KEYSproceduresetsfunction keysfor usewith Unix versionsof IDL when
used with the standard tty command interface.
Under Unix, the number of function keys, their names, and the escape sequences they
send to the host computer vary enough between various keyboards that IDL cannot be
written to understand all keyboards. Therefore, IDL provides a very general routine
named DEFINE_KEY that allows the user to specify the names and escape sequences of
function keys.
SETUP_KEYSprovidesaconvenient interfacetoDEFINE_KEY, usinguser input (viathe
keywordsdescribedbelow), theTERMenvironment variableandthetypeof machinethe
current IDL is running on to determine what kind of keyboard you are using, and then
uses DEFINE_KEY to enter the proper denitions for the function keys.
The new mappings for the keys can be viewed using the command
HELP, /KEYS.
The need for SETUP_KEYS has diminished in recent years because most Unix terminal
emulators have adopted the ANSI standard for function keys, as represented by VT100
terminals and their many derivatives, as well as xterm and the newer CDE based dtterm.
The current version of IDL already knows the function keys of such terminals, so
SETUP_KEYS is not required. However, SETUP_KEYS is still needed to dene keys on
non-ANSI terminalssuch astheSun shelltool, SGI Iris-ansi terminal emulator, or IBMs
aixterm.
IDL doesnot support thefunction keysfromthehptermterminal emulator supplied on
HPsystems. Hptermusesnon ANSI-standardescapesequenceswhichIDLcannot parse.
Research Systems recommends the use of the xterm or dtterm terminal emulators
instead.
setup_keys.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SETUP_KEYS
Keywords
NOTE: If no keyword is specied, SETUP_KEYS uses !VERSION to determine the type
of machinerunningIDL. It assumesthat thekeyboard involved isof thesametype(this
assumption is correct).
IDL Reference Guide SETUP_KEYS
ANSI
Set this keyword to establish function key denitions for ANSI keyboards.
EIGHTBIT
Set thiskeywordtousethe8-bit versionsof theescapecodes(insteadof thedefault 7-bit)
when establishing VT200 function key denitions.
SUN
Set this keyword to establish function key denitions for a Sun3 keyboard.
VT200
Set this keyword to establish function key denitions for a DEC VT200 keyboard.
HP9000
Set thiskeywordtoestablishfunction keydenitionsfor an HP9000series300keyboard.
Although the HP 9000 series 300 supports both xterm and hpterm windows, IDL
supports only user-denable key denitions in xterm windowshpterm windows use
non-standard escape sequences which IDL does not attempt to handle.
IBM
Set this keyword to establish function key denitions for IBM keyboards.
MIPS
Set this keyword to establish function key denitions for a Mips RS series keyboard.
SGI
Set this keyword to establish function key denitions for SGI keyboards.
APP_KEYPAD
Set thiskeyword todeneescapesequencesfor thegroup of keysin thenumerickeypad,
enabling these keys to be programmed within IDL.
NUM_KEYPAD
Set this keyword to disable programmability of the numeric keypad.
See Also
DEFINE_KEY
SFIT IDL Reference Guide
SFIT
TheSFITfunction determinesapolynomial t toasurfaceandreturnsattedarray. The
function tted is:
sfit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = SFIT(Data, Degree)
Arguments
Data
The two-dimensional array of data to t. The sizes of the dimensions may be unequal.
Degree
The maximum degree of t (in one dimension).
Keywords
KX
Set this keyword to a named variable that will contain the array of coefcients for a
polynomial function of x and y to t data. This parameter is returned as aDegree+1 by
Degree+1 array.
Example
Create a grid from zero to six radians in the X and Y directions:
X = (FINDGEN(61)/10) # REPLICATE(1,61)
Y = TRANSPOSE(X)
Evaluate a function at each point:
F = -SIN(2*X) + COS(Y/2)
Compute a sixth-degree polynomial t to the function data:
result = SFIT(F, 6)
Display the original function on the left and the tted function on the right, using
identical axis scaling:
f x y , ( ) kx
j i ,
x
i
y
j

=
IDL Reference Guide SFIT
WINDOW, XSIZE = 800, YSIZE = 400
!P.MULTI = [0, 2, 1] Set up side-by-sideplots.
!P.BACKGROUND = 255 Set background color to white.
!P.COLOR = 0 Set plot color to black.
SURFACE, F, X, Y, ZRANGE = [-3, 3], ZSTYLE = 1
SURFACE, result, X, Y
See Also
CURVEFIT, GAUSSFIT, POLY_FIT, POLYFITW, REGRESS, SVDFIT
Figure 9-5: The original function (left) and the fitted function (right).
SHADE_SURF IDL Reference Guide
SHADE_SURF
The SHADE_SURF procedure creates a shaded-surface representation of a regular or
nearly-regular gridded surface with shading from either a light source model or from a
user-specied array of intensities. This procedure and its parameters are similar to
SURFACE. Givenaregular or near-regular gridof elevationsit producesashaded-surface
representation of the data with hidden surfaces removed.
The SET_SHADING procedure can be used to control the direction of the light source
and other shading parameters.
If the graphics output device has scalable pixels (e.g., PostScript), the output image is
scaled so that its largest dimension is less than or equal to 512 (unless the PIXELS
keyword isset to someother value). Thisdefault resolution may not behigh enough for
somedatasets. If your output looksjaggedor stair-stepped, tryspecifyingalarger value
with the PIXELS keyword.
When outputtingto adevicethat printsblack on awhitebackground, (e.g., PostScript),
pixels that contain the background color index of 0 are set to white.
Restrictions
If the(X, Y) grid isnot regular or nearlyregular, errorsin hidden lineremoval will occur.
If the T3D keyword is set, the 3D to 2D transformation matrix contained in !P.T must
project the Z axis to a line parallel to the device Y axis, or errors will occur. The
SHADE_SURF_IRR procedure can be used to render many datasets that do not meet
these requirements. Irregularly-gridded data can also be made interpolated to a regular
grid using the TRIGRID and TRIANGULATE routines.
Calling Sequence
SHADE_SURF, Z [, X, Y]
Arguments
Z
A two-dimensional array that contains the values that make up the surface. For details,
see SURFACE on page 1090.
created with SHADE_SURF are limited to the range and precision of single-precision
X
An optional vector or two-dimensional array that speciestheXcoordinatesof thegrid.
For details, see SURFACE on page 1090.
IDL Reference Guide SHADE_SURF
Y
Anoptional vector or two-dimensional arraythat specifiestheYcoordinatesof eachelevation.
Keywords
AX
This keyword species the angle of rotation, about the X axis, in degrees towards the
viewer. Thiskeywordiseffectiveonlyif !P.T3DandtheT3Dkeywordarenot set. If !P.T3D
is set, the three-dimensional to two-dimensional transformation used by SURFACE is
contained in the 4 by 4 array !P.T.
The surface represented by the two-dimensional array is rst rotated, AZ (see below)
degreesabout theZ axis, then by AXdegreesabout theXaxis, tiltingthesurfacetowards
the viewer (AX > 0), or away from the viewer.
The AX and AZ keyword parameters default to +30 degrees if omitted.
The three-dimensional to two-dimensional transformation represented by AX and AZ,
can be saved in !P.T by including the SAVE keyword.
AZ
This keyword species the counterclockwise angle of rotation about the Z axis. This
keyword is effective only if !P.T3D is not set. The order of rotation is AZ rst, then AX.
IMAGE
A named variable into which an image containing the shaded surface is stored. If this
keyword is omitted, the image is displayed but not saved.
MAX_VALUE
MIN_VALUE
PIXELS
Set this keyword to a scalar value that species the maximum size of the image
dimensions, in pixels. PIXELS only applies when the output device uses scalable pixels
(e.g., the PostScript device). Use this keyword to increase the resolution of the output
image if the default looks jagged or stair-stepped.
SHADE_SURF IDL Reference Guide
SAVE
Set this keyword to save the 3D to 2D transformation matrix established by
SHADE_SURF in the system variable eld !P.T. Use this keyword when combining the
output of SHADE_SURF with the output of other routines in the same plot.
SHADES
An array expression, of the same dimensions asZ, that contains the color index at each
point. Theshadingof each pixel isinterpolated fromthesurroundingSHADEvalues. If
thisparameter isomitted, light-sourceshadingisused. For most displays, thisparameter
should be scaled into the range of bytes.
DEVICE on page 419.
XLOG
YLOG
not listed above. AM_PM CHARSIZE CHARTHICK CLIP COLOR DATA
DAYS_OF_WEEK DEVICE FONT NOCLIP NODATA NORMAL POSITION
SUBTITLE T3D THICK TICKLEN TITLE [ XYZ] CHARSIZE [ XYZ] GRIDSTYLE
[ XYZ] MARGIN [ XYZ] MINOR MONTHS [ XYZ] RANGE [ XYZ] STYLE [ XYZ] THICK
[ XYZ] TICKFORMAT [ XYZ] TICKLEN [ XYZ] TICKNAME [ XYZ] TICKS [ XYZ] TICKV
[ XYZ] TICK_GET [ XYZ] TITLE ZVALUE.
Example
Create a simple dataset by entering:
D = DIST(40)
Display the dataset as a light-source shaded surface by entering:
SHADE_SURF, D, TITLE = 'Shaded Surface'
Instead of light-source shading, an array of the same size as the elevation dataset can be
used to color the surface. This technique creates four-dimensional displays. Create an
array of shades to use by entering the command:
S = SIN(D)
Nowcreateanewshaded surfacethat usesthearrayof shadingvaluesinstead of thelight
source. Enter:
SHADE_SURF, D, SHADES = BYTSCL(S)
IDL Reference Guide SHADE_SURF
Note that the BYTSCL function is used to scale S into the range of bytes.
See Also
POLYSHADE, SET_SHADING, SHADE_VOLUME, SURFACE
SHADE_SURF_IRR IDL Reference Guide
SHADE_SURF_IRR
The SHADE_SURF_IRR procedure creates a shaded surface representation of an
irregularly gridded elevation dataset.
Thedatamust berepresentableasan arrayof quadrilaterals. Thisroutineshould beused
when the (X, Y, Z) arrays are too irregular to be drawn by SHADE_SURF, but are still
semi-regular.
shade_surf_irr.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SHADE_SURF_IRR, Z, X, Y
Arguments
Z
An n x marray of elevations.
X
An n x marray containing theX location of each Z value.
Y
An n x marray containing theY location of each Z value.
Note Thegrid described by Xand Ymust consist of quadrilaterals, must besemi-regular,
and must be in clockwise order. Clockwise ordering means that:
x[i,j] <= x[i+1, j] for all j
and
y[i,j] <= y[i, j+1] for all i
Keywords
AX
The angle of rotation about the X axis. The default is 30 degrees.
AZ
The angle of rotation about the Z axis. The default is 30 degrees.
IDL Reference Guide SHADE_SURF_IRR
IMAGE
Set thiskeywordtoanamedvariablethat will contain theresultingshadedsurfaceimage.
Thevariableisreturned asabytearray of thesamesizeasthecurrently selected graphics
device.
PLIST
Set this keyword to a named variable that will contain the polygon list on return. This
featureisuseful when you want tomakeanumber of imagesfromthesameset of vertices
and polygons.
T3D
Set this keyword 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)
Example
Thefollowingexamplecreatesasemi-regular dataset in theproper format at displaysthe
resulting irregular surface.
z = DIST(10,10)*100.0 Createsomeelevation data.
x = FLTARR(10,10) & y = FLTARR(10,10) CreatearraystoholdXandYda-
ta.
FOR i = 0,9 do x[0:9,i] = FINDGEN(10)
FOR j = 0,9 DO y[j,0:9] = FINDGEN(10) EnsurethatXandYarraysarein
clockwise order.
x = x + RANDOMU(seed,10,10)*0.49
y = y + RANDOMU(seed,10,10)*0.49 MakeX and Y arrays irregular.
SHADE_SURF_IRR, z, x, y Display theirregular surface.
See Also
SHADE_SURF, TRIGRID
SHADE_VOLUME IDL Reference Guide
SHADE_VOLUME
Given a 3D volume and a contour value, SHADE_VOLUME produces a list of vertices
and polygons describing the contour surface. This surface can then be displayed as a
shaded surface by the POLYSHADE procedure. Shading is obtained from either a single
light-source model or from user-specied values.
SHADE_VOLUME computes the polygons that describe a three dimensional contour
surface. Each volume element (voxel) is visited to nd the polygons formed by the
intersections of the contour surface and the voxel edges. The method used by SHADE
VOLUMEisthat of Klemp, McIrvin and Boyd, 1990: PolyPaintAThree-Dimensional
Rendering Package, American Meteorology Society Proceedings, Sixth International
Conferenceon InteractiveInformation and Processing Systems. This method is similar to
themarchingcubesalgorithmdescribedbyLorenson andCline, 1987: MarchingCubes:
AHigh Resolution 3DSurfaceConstruction Algorithm, Computer Graphics21, 163-169.
This routine is limited to processing datasets that will t in memory.
Calling Sequence
SHADE_VOLUME, Volume, Value, Vertex, Poly
Arguments
Volume
Athree-dimensional array that containsthedataset to becontoured. If theVolumearray
is dimensioned (D
0
, D
1
, D
2
), the resulting vertex coordinates are as follows:
0< X < D
0
- 1; 0< Y< D
1
- 1; 0< Z < D
2
- 1.
Value
Thescalar contour value. Thisvaluespeciestheconstant-densitysurface(alsocalled an
isosurface) to be rendered.
Vertex
The name of a variable to receive the vertex array. On output, this variable is set to a (3,
n) oating-point array, suitable for input to POLYSHADE.
Poly
A named variable to receive the polygon list, an m-element, longword array. This list
describes the vertices of each polygon and is suitable for input to POLYSHADE. The
verticesof eachpolygon arelistedin counterclockwiseorder when observedfromoutside
thesurface. Thevertex description of eachpolygon isavector of theform: [n, i
0
, i
1
, ..., i
n-1
]
and thePoly array is the concatenation of the lists of each polygon. For example, when
rendering a pyramid consisting of four triangles, Poly would contain 16 elements, made
by concatenating four, four-element vectors of the form [ 3, V
0
, V
1
, V
2
] . V
0
, V
1
, and V
2
are the indices of the vertices describing each triangle.
IDL Reference Guide SHADE_VOLUME
Keywords
LOW
Set thiskeyword to display thelowsideof thecontour surface(i.e., thecontour surfaces
enclose high data values). If this keyword is omitted or is 0, the high side of the contour
surface is displayed and the contour encloses low data values. If this parameter is
incorrectly specied, errors in shading will result.
SHADES
An optional array, converted to byte type before use, that contains the user-specied
shadingcolor index for each voxel. Thisarraymust havethesamedimensionsasVolume.
On exit, this array is replaced by another array, that contains the shading value for each
vertex, contained in Vertex.
DEVICE on page 419.
VERBOSE
Set this keyword to print a message indicating the number of polygons and vertices that
are produced.
XRANGE
An optional two-element vector that containsthelimits, over therst dimension, of the
sub-volume to be considered.
YRANGE
An optional two-element vector that contains the limits, over the second dimension, of
the sub-volume to be considered.
ZRANGE
An optional two-element vector containing the limits, over the third dimension, of the
sub-volume to be considered.
Example
The following procedure shades a volume passed as a parameter. It uses the SCALE3
procedure to establish the viewing transformation. It then calls SHADE_VOLUME to
produce the vertex and polygon lists, and POLYSHADE to draw the contour surface.
Pro SHOWVOLUME, vol, thresh, LOW = low Display thecontour surfaceof a
volume.
s = SIZE(vol) Getthedimensionsofthevolume.
IF s[0] NE 3 THEN ... ... Error, must bea 3D array.
SCALE3, XRANGE=[0, S[1]], YRANGE=[0, S[2]], ZRANGE=[0, S[3]]
UseSCALE3 to establish the3D
SHADE_VOLUME IDL Reference Guide
transformation and coordinate
ranges.
IF N_ELEMENTS(low) EQ 0 THEN low = 0 Default =view high sideof con-
tour surface.
SHADE_VOLUME, vol, thresh, v, p, LOW = lowProducevertices and polygons.
TV, POLYSHADE(v,p,/T3D) Produceimageofsurfaceanddis-
play.
END
See Also
POLYSHADE, SHADE_SURF
IDL Reference Guide SHIFT
SHIFT
The SHIFT function shifts elements of vectors or arrays along any dimension by any
number of elements. The result is a vector or array of the same structure and type as
Array. Positive shifts are to the right while left shifts are expressed as a negative number.
All shifts are circular.
Elementsshifted off oneend wrap around and areshifted onto theother end. In thecase
of vectors the action of SHIFT can be expressed:
Result
(i + s) modulation
= Array
i
for (0 1 < n)
wheresis the amount of the shift, and n is the number of elements in the array.
Calling Sequence
Result = SHIFT(Array, S
1
, ..., S
n
)
Arguments
Array
The array to be shifted.
S
i
Theshift parameters. For arraysof morethan onedimension, theparameter S
n
species
theshift applied tothenth dimension. S
1
speciestheshift alongtherst dimension and
so on. If only one shift parameter is present and the parameter is an array, the array is
treated as a vector (i.e., the array is treated as having one-dimensional subscripts).
A shift specication of 0 means that no shift is to be performed along that dimension.
Example
The following example demonstrates using SHIFT with a vector. by entering:
A = INDGEN(5)
Print the original vector, the vector shifted one position to the
right, and the vector
shifted one position to
the left:
PRINT, A, SHIFT(A, 1), SHIFT(A, -1)
Executing these statements gives the result:
SHIFT IDL Reference Guide
0 1 2 3 4
4 0 1 2 3
1 2 3 4 0
Notice how elements of the vector that shift off the end wrap around to the other end.
This wrap around occurs when shifting arrays of any dimension.
See Also
ISHFT
IDL Reference Guide SHOW3
SHOW3
The SHOW3 procedure combines an image, a surface plot of the image data, and a
contour plot of the images data in a single tri-level display.
show3.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SHOW3, Image[, X, Y]
Arguments
Image
The two-dimensional array to display.
X
A vector containingtheX valuesof each column of Image. If theXargument isomitted,
columns have values 0, 1, ..., ncolumns-1.
Y
Avector containingtheYvaluesof each rowof Image. If theYargument isomitted, rows
have values 0, 1, ..., nrows-1.
Keywords
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.
E_CONTOUR
Set this keyword equal to an anonymous structure containing additional keyword
parameters that are passed to the CONTOUR procedure. Tag names in the structure
should be valid keyword arguments to CONTOUR, and the values associated with each
tag should be valid keyword values.
E_SURFACE
Set this keyword equal to an anonymous structure containing additional keyword
parametersthat arepassedtotheSURFACEprocedure. Tagnamesinthestructureshould
bevalidkeywordargumentstoSURFACE, andthevaluesassociatedwitheachtagshould
be valid keyword values.
SHOW3 IDL Reference Guide
SSCALE
Reduction scalefor surface. Thedefault is1. If thiskeyword isset to avalueother than 1,
thearraysizeisreducedbythisfactor for thesurfacedisplay. That is, thenumber of points
usedtodrawthewire-meshsurfaceisreduced. If thearraydimensionsarenot an integral
multiple of SSCALE, the image is reduced to the next smaller multiple.
Example
A = BESELJ(SHIFT(DIST(30,20), 15, 10)/2.,0)
Createa dataset.
SHOW3, A Show it with default display.
SHOW3, A, SQRT(FINDGEN(30)) Specify X axis proportional to
squareroot of values.
SHOW3, A, E_CONTOUR={C_CHARSIZE:2, DOWN:1}
Label CONTOURlineswithdou-
blesizecharacters, and include
downhill tick marks.
SHOW3, A, E_SURFACE={SKIRT:-1, ZRANGE:[-2,2]}
Draw a surfacewith a skirt and
scaleZ axis from -2 to 2.
See Also
CONTOUR, SURFACE
IDL Reference Guide SHOWFONT
SHOWFONT
The SHOWFONT procedure displays a TrueType or vector-drawn font (from the le
hersh1.chr, located in the main IDL directory) on the current graphics device.
showfont.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SHOWFONT, Font, Name
Arguments
Font
The index number of the font (may range from 3 to 29) or, if the TT_FONT keyword is
set, a string that contains the name of the TrueType font to display.
Name
A string that contains the text of a title to appear at the top of the font display.
Keywords
ENCAPSULATED
Set this keyword, if the current graphics device is PS, to make encapsulated PostScript
output.
TT_FONT
If this keyword is set, the specied font will be interpreted as a TrueType font.
Example
To create a display of the Helvetica italic TrueType font on the screen:
SHOWFONT, 'Helvetica Italic', 'Helvetica Italic', /TT_FONT
To create a display of Font 3 for PostScript:
SET_PLOT, 'PS' Set output to PostScript.
SHOWFONT, 3, 'Simplex Roman' Display font 3.
DEVICE, /CLOSE ClosethenewPSfile(savedbyde-
fault as idl.ps).
SHOWFONT IDL Reference Guide
See Also
EFONT, PS_SHOW_FONTS
IDL Reference Guide SIN
SIN
The periodic function SIN returns the trigonometric sine of X.
Calling Sequence
Result = SIN(X)
Arguments
X
The angle for which the sine is desired, specied in radians. If X is double-precision
oatingor complex, theresult isof thesametype. All other typesareconverted tosingle-
precision oating-point and yield oating-point results. When applied to complex
numbers:
sin x = COMPLEX(sin R cosh I, cos R sinh I)
whereR and I are the real and imaginary parts of x.
If input argument X is an array, the result has the same structure, with each element
containing the sine of the corresponding element of X.
Examples
To nd the sine of 0.5 radians and print the result, enter:
PRINT, SIN(0.5)
The following example plots the SIN function between 0 and 2 with 100 intervals:
X = 2*!PI/100 * FINDGEN(100)
PLOT, X, SIN(X)
Note: !PI is a read-only system variable that contains the single-precision value for .
See Also
ASIN, SINH
SINDGEN IDL Reference Guide
SINDGEN
The SINDGEN function returns a string array with the specied dimensions. Each
element of thearrayisset tothestringrepresentation of thevalueof itsone-dimensional
subscript, using IDLs default formatting rules.
Calling Sequence
Result = SINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
To create S, a six-element string vector with each element set to the string value of its
subscript, enter:
S = SINDGEN(6)
See Also
LINDGEN, UINDGEN, UL64INDGEN, ULINDGEN
IDL Reference Guide SINH
SINH
The SINH function returns the hyperbolic sine of X.
Calling Sequence
Result = SINH(X)
Arguments
X
The angle for which the hyperbolic sine is desired, specied in radians. If X is double-
precision oating-point, the result is also double-precision. Complex values are not
allowed. All other types are converted to single-precision oating-point and yield
oating-point results. SINH is dened as:
sinh x = (e
u
- e
-u
) / 2
hyperbolic sine of the corresponding element of X.
Examples
To nd the hyperbolic sine of each element in the array [ .5, .2, .4] and print the result,
enter:
PRINT, SINH([.5, .2, .4])
To plot the SINH function between 0 and 2 with 100 intervals, enter:
X = 2*!PI/100 * FINDGEN(100)
PLOT, X, SINH(X)
Note: !PI is a read-only system variable that contains the single-precision value of .
See Also
ASIN, SIN
SIZE IDL Reference Guide
SIZE
The SIZE function returns a vector that contains size and type information for its
argument if no keywords are set. If a keyword is set, SIZE returns the specied quantity.
Thereturned vector isalwaysof longword type. Therst element isequal to thenumber
of dimensions of Expression. This value is zero if Expression is scalar or undened. The
next elements contain the size of each dimension, one element per dimension (none if
Expressionisscalar or undened). After thedimensionsizes, thelast twoelementscontain
thetypecode(zeroif undened) and thenumber of elementsin Expression, respectively.
The type code is described in the table below.
Calling Sequence
Result = SIZE(Expression)
Type Code Data Type
0 Undened
1 Byte
2 Integer
3 Longword integer
4 Floating point
5 Double-precision oating
6 Complex oating
7 String
8 Structure
9 Double-precision complex
10 Pointer
11 Object reference
12 Unsigned Integer
13 Unsigned Longword Integer
14 64-bit Integer
15 Unsigned 64-bit Integer
Table 9-65: IDL Type Codes
IDL Reference Guide SIZE
Arguments
Expression
The expression for which size information is requested.
Keywords
Thefollowingkeywordsdeterminethereturn valueof theSIZEfunction. Thekeywords
are mutually exclusive specify at most one of the following.
DIMENSIONS
Set thiskeyword to return thedimensionsof Expression. If Expressionisscalar, theresult
is a longword scalar containing a 1. For arrays, the result is a longword array containing
the array dimensions.
FILE_LUN
Set thiskeyword toreturn theleunit towhich Expressionisassociated, if it isan IDL le
variable, as created with the ASSOC function. If Expression is not a le variable, 0 is
returned (0 is not a valid le unit for ASSOC).
N_DIMENSIONS
Set this keyword to return the number of dimension in Expression, if it is an array. If
Expression is scalar, 0 is returned.
N_ELEMENTS
Set this keyword to returns the number of data elements in Expression. Setting this
keyword is equivalent to using the N_ELEMENTS function.
STRUCTURE
Set this keyword to return all available information about Expression as an IDL_SIZE
structure. Notethat sincethestructureisanamed structure, thesizeof itseldsisxed.
The following are descriptions of the elds in the returned structure:
TNAME
Set this keyword to return the IDL type of Expression as a string.
TYPE_NAME Name of IDL type of Expression.
TYPEIDL Type code of Expression.
FILE_LUN If Expression is an IDL le variable, as created with the ASSOC
function, theleunit towhich it isassociated. Otherwise, 0.
N_ELEMENTS Number of data elements in Expression.
N_DIMENSIONS If Expressionisan array, thenumber of dimensions. Otherwise, 0.
DIMENSIONS An 8-element array containing the dimensions of Expression.
SIZE IDL Reference Guide
TYPE
Set this keyword to returns the IDL type code for Expression. See Table9-65, IDL Type
Codes, on page1022 for details.
Example
Print the size information for a 10 by 20 oating-point array by entering:
PRINT, SIZE(FINDGEN(10, 20))
IDL prints:
2 10 20 4 200
IDL showsthat thearray has2dimensions, equal to 10and 20, atypecodeof 4, and 200
elements total.
Similarly, to print only the number of dimensions of the same array:
PRINT, SIZE(FINDGEN(10, 20), /N_DIMENSIONS)
IDL prints:
2
IDL Reference Guide SKEWNESS
SKEWNESS
TheSKEWNESSfunctioncomputesthestatistical skewnessof ann-element vector. If the
variance of the vector is zero, the skewness is not dened, and SKEWNESS returns
!VALUES.F_NAN as the result. SKEWNESS calls the IDL function MOMENT.
Calling Sequence
Result = SKEWNESS(X)
Arguments
X
A numeric vector.
Keywords
DOUBLE
If this keyword is set, computations are done in double precision arithmetic.
NAN
Example
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
;Definethen-element vector of
sampledata.
result = SKEWNESS(x) ;Computetheskewness.
IDL prints:
-0.0942851
See Also
KURTOSIS, MEAN, MEANABSDEV, MOMENT, STDDEV, VARIANCE
SKIPF IDL Reference Guide
SKIPF
TheSKIPFprocedureskipsrecordsor leson thedesignated magnetictapeunit. SKIPF
is available only under VMS. If two parameters are supplied, les are skipped. If three
parameters are present, individual records are skipped.
Thenumber of lesor recordsactuallyskippedisstoredinthesystemvariable!ERR. Note
that when skippingrecords, theoperation terminatesimmediately when theend of ale
is encountered. See the description of the magnetic tape routines in VMS-Specic
Information on page 217 of Building IDL Applications.
Calling Sequence
SKIPF, Unit, Files
or
SKIPF, Unit, Records, R
Arguments
Unit
The magnetic tape unit to rewind. Unit must be a number between 0 and 9, and should
not be confused with the standard le Logical Unit Numbers (LUNs).
Files
The number of les to be skipped. Skipping is in the forward direction if the second
parameter is positive, otherwise les are skipped backwards.
Records
The number of records to be skipped. Skipping is in the forward direction if the second
parameter is positive, otherwise records are skipped backwards.
R
If thisargument ispresent, recordsareskipped, otherwiselesareskipped. Thevalueof
R is never examined. Its presence serves only to indicate that records are to be skipped.
IDL Reference Guide SLICER3
SLICER3
TheIDL SLICER3isawidget-based application to visualizethree-dimensional datasets.
This program supersedes the SLICER program.
slicer3.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SLICER3[, hData3D]
Arguments
hData3D
A pointer to a three-dimensional data array, or an array of pointers to multiple three-
dimensional arrays. If multiplearraysarespecied, theyall must havethesameX, Y, and
Z dimensions. If hData3Disnot specied, SLICER3createsa2x 2x 2array of bytedata
usingtheIDLBYTARRfunction. You can alsoloaddatainteractivelyviatheFilemenu of
the SLICER3 application (see Examples on page 1038 for details).
Note If data are loaded in this fashion, any data passed to SLICER3 via a pointer (or
pointers) is deleted, and the pointers become invalid.
Keywords
DATA_NAMES
Set this keyword equal to 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.
DETACH
Set thiskeywordtoplacethedrawingareainawindowthat isdetachedfromtheSLICER3
control panel. The drawing area can only be detached if SLICER3 is not run as a modal
application.
GROUP
Set this keyword equal to the Widget ID of an existing widget that serves as the group
leader for the SLICER3 graphical user interface. When a group leader is destroyed, all
widgetsin thegroup arealso destroyed. If SLICER3isstarted fromawidget application,
then GROUP should alwaysbe specied.
SLICER3 IDL Reference Guide
MODAL
Set thiskeywordtoblock user interactionwithall other widgets(andblock thecommand
line) until the SLICER3 exits. If SLICER3 is started from some other widget-based
application, then it is usually advisable to run SLICER3 with the MODAL keyword set.
Note SLICER3modiesthecurrent color table, aswell asvariouselementsof theplotting
system (i.e., the !X, !Y, !Z, and !P system variables). If the MODAL keyword
is set (recommended), then SLICER3 will, upon exit, restore these system variables
(and the color tables) to the values they had when SLICER3 was started.
The SLICER3 Graphical User Interface
The following options are available via SLICER3s graphical user interface.
File Menu
Load
Select this menu option to choose a le containing a 3D array (or arrays) to load into
SLICER3. Thelemust havebeen written in theformat specied byTable9-66. For each
dataarray in thele, thefollowingvaluesmust beincluded. Notethat therst six values
are returned by the IDL SIZE function; see Examples on page 1038 for an example of
how to create a data le suitable for SLICER3 with just a few IDL commands.
If multiple arrays are present in the le, they must all have the same dimensions.
Note Files saved by the Save Subset operation (see below) are suitable for input via the
Load operation.
Datalesthat aremoved fromoneplatformto another may not load asexpected, dueto
byte ordering differences. See the BYTEORDER and SWAP_ENDIAN for details.
Save/ Save Subset
SLICER3 must be in BLOCK mode to for this option to be available.
Select this menu option to save a subset of the 3D data enclosed in the current block to
the specied le. Subsets saved in this fashion are suitable for loading via the Load
menu option. If multiple 3D arrays are available when this option is selected, multiple
subsets are saved to the le.
Save/ Save Tiff Image
Select this menu option to save the contents of the current SLICER3 image window as a
TIFF image in the specied le. When running in 8-bit mode, a Class P palette color
TIFFleiscreated. In 24-bit mode, aClassR (interleavedbyimage) TIFFleiscreated.
Quit
Select this menu option to exit SLICER3.
Data item
Data
Type
Number
of Bytes
Number of dimension in array. (Note: Thisisalways
3 for valid SLICER3 data.)
long 4
Size of rst dimension. long 4
Size of second dimension. long 4
Size of third dimension. long 4
Datatype(Must betype1through 5. SeeSIZE on
page 1022 for a list of data types types.)
long 4
Total number of elements (dimX, dimY, dimZ). long 4
Number of charactersin dataname. (SeeSTRLEN
on page 1080 for the easiest way to determine this
number.)
long 4
Data name byte strlen()
3D data array. varies varies
Table 9-66: SLICER3 Data File Structure
Tools Menu
Erase
Select this menu option to erase the display window and delete all the objects in the
display list.
Delete/ ...
Asgraphical objectsarecreated, theyareaddedtothedisplaylist. Select thismenuoption
to delete a specic object from the list. When an object is deleted, the screen is redrawn
with the remaining objects.
Colors/ Reset Colors
Select this menu option to restore the original color scheme.
Colors/ Differential Shading
Usethismenu option tochangethepercentageof differential shadingappliedtotheX, Y,
and Z slices.
Colors/ Slice/ Block
Usethismenu option tolaunch theXLOADCT application tomodifythecolorsused for
slices and blocks
Colors/ Surface
isosurfaces.
Colors/ Projection
projections.
Note On some platforms, the selected colors may not become visible until after you exit
the XLOADCT application.
Options
Select this menu option to display a panel that allows you to set:
The axis visibility.
The wire-frame cube visibility.
The display window size.
About Menu
About Slicer
Select this menu item to display a text le containing information about SLICER3.
Main Draw Window
Operations available in the Main Draw Window are dependent on the mode selected in
the Mode Pulldown menu. 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, thefront sideof thecubeisused. In afewcases, thecoordinate
input is on the back side of the cube.
Data Pulldown Menu
If multiple datasets are currently available in SLICER3, this menu allows you to select
which data will be displayed in the Main Draw Window. Slices, blocks, iso-surfaces, etc.
are created from the currently selected data. If only one dataset is loaded, this menu is
inactive.
Mode Pulldown Menu
This menu is used to select the current mode of operation.
Slice Mode
Todisplayaslice, click anddragtheleft mousebuttonon
thewire-framecube. When thebutton isreleased, aslice
through the data will be drawn at that location.
Draw Radio Button
When in Drawmode, newsliceswill bemerged into the
current Z-buffer contents.
Expose Radio Button
When in Exposemode, newsliceswill bedrawn in front
of everything else.
Orthogonal Radio Button
When in Orthogonal mode, usetheleft mousebutton in
the main draw window to position and draw an
orthogonal slicing plane. Clicking the right mouse
button in themain drawwindow(or any mousebutton
in the small window) will toggle the slicing plane
orientation.
X/ Y/ Z Radio Buttons
X: This sets the orthogonal slicing plane orientation to be perpendicular to the X
axis.
Y: Thissetstheorthogonal slicingplaneorientationtobeperpendicular totheYaxis.
Z: Thissetstheorthogonal slicingplaneorientationtobeperpendicular totheZaxis.
Oblique Radio Button
Clickingany mousebutton in thesmall windowwill reset theobliqueslicingplaneto its
default orientation.
Normal Radio Button
When in thismode, click anddragtheleft mousebutton in thebigwindowtoset the
surface normal for the oblique slicing plane.
Center Radio Button
When in thismode, click anddragtheleft mousebutton in thebigwindowtoset the
center point for the surface normal.
Display Button
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 main
drawwindowtoset thelocationfor thepurple 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
When in this mode, the block will be added to the current
Z-buffer contents.
Subtract
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 Button
Clicking this button will cause the block to be drawn.
Surface Mode
Iniso-surfaceislikeacontour lineonacontour 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 islower than thecontour 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 thethreshold value, and on theother sideof
the surface, the data values are lower than the threshold
value.
When in Surface mode, a logarithmic histogram plot of
thedataisdisplayedinthesmall drawwindow. 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 pulldown menu
Iso-surfaces are normally rendered with light-source shading. If multiple datasets are
currentlyloaded, thenthismenuallowstheselectionof adifferent 3Darrayfor thesource
of theiso-surfaceshadingvalues. If only onedataset iscurrently loaded, then thismenu
is inactive.
Display Button
Clickingthisbutton will causetheiso-surfacetobecreatedanddrawn. Iso-surfacesoften
consist of tens of thousands of polygons, and can sometimes take considerable time to
create and render.
Projection Mode
A voxel projectionof a3Darrayistheprojectionof the
datavalueswithin that array onto aviewingplane. This
is similar to taking an X-ray image of a 3D object.
Max
Select this mode for a Maximum intensity projection.
Avg
Select this mode for an Average intensity projection.
Low
Select this mode for a Low resolution projection.
Med
Select this mode for a Medium resolution projection.
High
Select this mode for a High resolution projection.
Depth Queue % Slider
Usetheslider toset thedepthqueuepercent. Avalueof 50, for example, indicatesthat the
farthest part of the projection will be 50% as bright as the closest part of the projection.
Display Button
Clickingthisbutton will causetheprojection tobecalculatedanddrawn. Projectionscan
sometimes take considerable time to display. Higher resolution projections take more
computation time.
Threshold Mode
WheninThresholdmode, alogarithmichistogramplot of
thedataisdisplayed in thesmall drawwindow. Click and
drag the left mouse button on this plot to set the
minimum and maximum threshold values. To expand a
narrowrangeof datavaluesintothefull rangeof available
colors, set the threshold range before displaying slices,
blocks, or projections. The threshold settings also affect
thehistogramplot in Surface mode. Theminimumand
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 valuearenot drawn (clear). Iso-surfacesare
not affected by the transparency threshold. The
transparencythresholdvalueisalsoshowninatext 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.
Prole Mode
InProlemode, aplot isdisplayedshowingthedatavalues
alongaline. Thislineisalso shown superimposed on the
data in the main draw window. The bottom of the plot
correspondstothepurple endof theline, andthetopof
the plot corresponds to the blue end of the line.
Orthogonal
Click and drag the left mouse button to position the
proleline, based upon apoint on thefront facesof the
wire-framecube. Clickanddragtheright mousebuttonto
position theproleline, basedupon apoint on the back
facesof thewire-framecube. Astheprolelineismoved,
The prole plot is dynamically updated.
Oblique
Click and drag the left mouse button to position the
purple end of theprolelineon oneof thefront faces
of the wire-frame cube. Click and drag the right mouse
buttontopositionthe blue endof theprolelineonone
of the back faces of the wire-frame cube. As the prole
line is moved, The prole plot is dynamically updated.
Probe Mode
In Probemode, click and dragamousebutton over an object
in the main draw window. The actual X-Y-Z location within
thedatavolumeisdisplayedinthethreetext widgets. Also, the
data value at that 3D location is displayed in the status
window, abovethemain drawwindow. If thecursor isinside
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
thedatacubein thecurrent view. Asviewparametersare
changed, thiswindowisdynamicallyupdated. Themain
draw window is then updated when the user clicks on
Display, or exits View mode.
Display
Clickingon thisbutton will causetheobjectsin themain
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
Usethisslider toset theangleof therst viewrotation(in
degrees). The droplist widget adjacent to the slider
indicates which axis this rotation is about.
2nd Rotation
Usethisslider toset theangleof thesecondviewrotation
(in degrees). Thedroplist widget adjacent to theslider indicateswhich axisthisrotation
is about.
Zoom % Slider
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 % Slider
Usethisslider toset ascalefactor for theZaxis(tocompensatefor thedatasaspect ratio).
Operational Details
The SLICER3 procedure has the following side effects:
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.
On 24-bit displays, SLICER3 sets the device to non-decomposed color mode (DEVICE,
DECOMPOSED=0).
SLICER3breaksthecolor tableinto6 bands, basedupon thenumber of availablecolors
(wheremax_color=!D.N_COLORS on 8-bit displays, and max_color=256 on 24-bit
displays and nColor = (max_color - 9) / 5):
Annotation colors are the last band, and they are set up as shown in the table:
On 24-bit displays, you can often improve performance 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
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
Table 9-67: SLICER3 Band Start/End
Colorindex 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
Table 9-68: SLICER3 Color Bands
Examples
ThefollowingIDL commandsopen adatalefromtheIDL distribution and load it into
SLICER3:
file=FILEPATH('head.dat', SUBDIR=['examples', 'data'])
Choosea data file.
OPENR, UNIT, file, /GET_LUN Open thedata file.
data = BYTARR(80, 100, 57, /NOZERO) Createan array to hold thedata.
READU, UNIT, data Read thedata into thearray.
CLOSE, UNIT Closethedata file.
hData = PTR_NEW(data, /NO_COPY) Createapointertothedataarray.
SLICER3, hdata, DATA_NAMES=Dave Load thedata into SLICER3.
Note If data are loaded via the File menu after SLICER3 is launched with a pointer
argument (as shown above), the pointer becomes invalid. You can use an IDL
statement like the following to clean up after calling SLICER3 in this fashion:
if PTR_VALID(hdata) then PTR_FREE, hdata
Because we did not launch SLICER3 with the MODAL keyword, the last contents of the
main draw window still reside in IDLs Z-buffer. To retrieve this image after exiting
SLICER3, use the following IDL statements:
current_device = !D.Name Savethecurrent graphics device.
SET_PLOT, Z Changeto theZ-buffer device.
image_buffer = TVRD() ReadtheimagefromtheZ-buffer.
SET_PLOT, current_device Returntotheoriginal graphicsde-
vice.
TV, image_buffer Display theimage.
The following IDL commands manually create a data save le suitable for dynamic
loadinginto SLICER3. Notethat if you load datainto SLICER3asshown above, you can
also create save les by switching to BLOCK mode and using the Save Subset menu
option.
data_1 = INDGEN(20,30,40) Storesome3D data in a variable
called data_1.
data_2 = FINDGEN(20,30,40) Storesome3D data in a variable
called data_2.
data_1_name =Test Data 1
data_2_name =Data 2 Definethenamesforthedatasets.
Their names will appear in the
Data pulldown menu in
SLICER3.
dataFile = PICKFILE() Select a data filename.
GET_LUN, lun Writethefile.
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
See Also
GRID3, EXTRACT_SLICE, SHADE_VOLUME
SLIDE_IMAGE IDL Reference Guide
SLIDE_IMAGE
The SLIDE_IMAGE procedure creates a scrolling graphics window for examining large
images. Bydefault, 2drawwidgetsareused. Thedrawwidget on theleft showsareduced
version of the complete image, while the draw widget on the right displays the actual
image with scrollbars that allow sliding the visible window.
slide_image.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SLIDE_IMAGE [, Image]
Arguments
Image
A2Dimagearraytobedisplayed. If thisargument isnot specied, noimageisdisplayed.
The FULL_WINDOW and SCROLL_WINDOW keywords can be used to obtain the
window numbers of the two draw widgets so they can be drawn into at a later time.
Keywords
BLOCK
CONGRID
Normally, theimageisprocessedwiththeCONGRIDprocedurebeforeit iswrittentothe
fullyvisiblewindowontheleft. SpecifyingCONGIRD=0will forcetheimagetobedrawn
as is.
FULL_WINDOW
Set this keyword to a named variable that will contain the IDL window number of the
fullyvisiblewindow. Thiswindownumber canbeusedwiththeWSETproceduretodraw
to the scrolling window at a later point.
GROUP
Set thiskeywordtothewidget IDof thewidget that callsSLIDE_IMAGE. If set, thedeath
of the caller results in the death of SLIDE_IMAGE.
IDL Reference Guide SLIDE_IMAGE
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 processeventsin an event loop. Thedefault isthereforeto simply createthe
widgetsand return. Hence, when REGISTERisnot set, SLIDE_IMAGEcan bedisplayed
and the user can still type commands at the IDL command prompt.
RETAIN
This keyword is passed directly to the WIDGET_DRAW function. Set RETAIN to zero,
one, or two to specify howbackingstoreshould behandled for thewindow. RETAIN=0
speciesnobackingstore. RETAIN=1requeststhat theserver or windowsystemprovide
backingstore. RETAIN=2speciesthat IDL providebackingstoredirectly. See Backing
Store on page 144for details.Backing Store on page 103
SLIDE_WINDOW
Set this keyword to a named variable that will contain the IDL window number of the
slidingwindow. Thiswindownumber can beused with theWSET procedureto drawto
the scrolling window at a later time.
SHOW_FULL
Set this keyword to zero to show the entire image at full resolution in one scrolling
graphics window. By default, SHOW_FULL is set, displaying two draw widgets.
Note On Windows platforms only, using TVRD to return the array size of the displayed
image will cause the returned array to be off by the size of the frame (one pixel per
side). To return the dimensions of the original image, you must modify the
slide_image.pro library routine so that the FRAME keyword is not used with
SHOW_FULL.
TITLE
Set this keyword to the title to be used for the SLIDE_IMAGE widget. If this keyword is
not specied, Slide Image is used.
TOP_ID
Set this keyword to a named variable that will contain 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
SLIDE_IMAGE IDL Reference Guide
XSIZE
Set this keyword to the maximum width of the image that can be displayed by the
scrollingwindow. Thiskeywordshouldnot beconfusedwiththevisiblesizeof theimage,
controlled by the XVISIBLE keyword. If XSIZE is not specied, the width of Imageis
used. If Imageis not specied, 256 is used.
XVISIBLE
Set thiskeyword to thewidth of theviewport on thescrollingwindow. If thiskeyword is
not specied, 256 is used.
YSIZE
Set this keyword to the maximum height of the image that can be displayed by the
scrollingwindow. Thiskeywordshouldnot beconfusedwiththevisiblesizeof theimage,
controlled by theYVISIBLEkeyword. If YSIZEisnot present theheight of Imageisused.
If Imageis not specied, 256 is used.
YVISIBLE
Set thiskeyword totheheight of theviewport on thescrollingwindow. If thiskeyword is
not present, 256 is used.
Example
Open an image from the IDL distribution and load it into SLIDE_IMAGE:
image = BYTARR(768,512) Createa variableto hold theim-
age.
OPENR, unit, FILEPATH('nyny.dat', SUBDIR=['examples','data']), /GET_LUN
READU, unit, image
CLOSE, unit
image = BYTSCL(image) Scaletheimageintobyterangeof
thedisplay.
SLIDE_IMAGE, image Display theimage.
See Also
TV, TVSCL, WIDGET_DRAW, WINDOW
IDL Reference Guide SMOOTH
SMOOTH
The SMOOTH function returns a copy of Array smoothed with a boxcar average of the
specied width. The result has the same type and dimensions asArray. The algorithm
used by SMOOTH is:
whereN is the number of elements in A.
Calling Sequence
Result = SMOOTH(Array, Width)
Arguments
Array
The array to be smoothed. Array can have any number of dimensions.
Width
The width of the smoothing window, in each dimension. Width should be an odd
number, smaller than the smallest dimension of Array. If Width is an even number, one
plus the given value of Width is used. For example, if you use aWidth of 3 to smooth a
two-dimensional array, thesmoothingwindowwill contain nineelements(includingthe
element being smoothed). The value of Width does not affect the running time of
SMOOTH to a great extent.
Keywords
EDGE_TRUNCATE
Set this keyword to apply the smoothing function to all points. If the neighborhood
around a point includes a point outside the array, the nearest edge point is used to
computethesmoothedresult. If EDGE_TRUNCATEisnot set, theendpointsarecopied
from the original array to the result with no smoothing.
For example, when smoothing an n-element vector with a three point wide smoothing
window, therst point of theresult R
0
isequal toA
0
if EDGE_TRUNCATEisnot set, but
is equal to (A
0
+A
0
+A
1
)/3 if the keyword is set. In the same manner, point R
n-1
is set to
A
n-1
if EDGE_TRUNCATE is not set, or to (A
n-2
+A
n-1
+A
n-1
)/3 if it is.
Points not within a distance of Width/2 from an edge are not affected by this keyword.
R
i
1
w
---- A
i j w 2 +
i ,
j 0 =
w 1
w 2 ... N w , , =
A
i
otherwise ,
'
=
SMOOTH IDL Reference Guide
NAN
Example
D = SIN(DIST(256)/3) & TVSCL, D
Now display the same dataset smoothed with a width of 9 by entering:
TVSCL, SMOOTH(D, 9), 256, 256
See Also
DIGITAL_FILTER, LEEFILT, MEDIAN, TS_DIFF, TS_FCAST, TS_SMOOTH
IDL Reference Guide SOBEL
SOBEL
The SOBEL function implements an approximation of the 3 by 3, nonlinear edge-
enhancement operator:
Where the pixels surrounding the neighborhood of the pixel F(j, k) are numbered as follows:
Theresult of thisfunction isatwo-dimensional arrayof shortinteger type, with thesame
dimensionsasImage. Largeoriginal datavaluescauseoverowif theabsolutevalueof the
result is larger than 32768.
It should be noted that the previous description is not the true denition of the Sobel
function, but a fast approximation, dened as:
Calling Sequence
Result = SOBEL(Image)
Arguments
Image
The two-dimensional array containing the image to which edge enhancement will be
applied.
Example
If the variable IM contains an image, a Sobel edge-enhanced version can be displayed
with the command:
TVSCL, SOBEL(IM)
See Also
ROBERTS
G j k , ( ) X Y + =
X A
2
2A
3
A
4
+ + ( ) A
0
2A
7
A
6
+ + ( ) =
Y A
0
2A
1
A
2
+ + ( ) A
6
2A
5
A
4
+ + ( ) =
A
0
A
1
A
2
A
7
F j k , ( ) A
3
A
6
A
5
A
4
G j k , ( ) X
2
Y
2
+ =
SORT IDL Reference Guide
SORT
The SORT function returns a vector of subscripts that allow access to the elements of
Array in ascending order. The result is always a vector of longword type with the same
number of elements asArray.
Calling Sequence
Result = SORT(Array)
Arguments
Array
The array to be sorted. Array can be any basic type of vector or array. String arrays are
sortedusingtheASCII collatingsequence. Complex arraysaresortedbytheir magnitude.
Example
To illustrate, assume the vector A contains the elements [ 4, 3, 7, 1, 2] . Then:
SORT(A) = [3, 4, 1, 0, 2]
because:
A[ 3] < A[ 4] < A[ 1] < A[ 0] < A[ 2]
To see the elements of A in sorted order use the expression enter:
PRINT, A(SORT(A))
which prints:
1 2 3 4 7
To obtain the elements in descending order enter:
PRINT, A(REVERSE(SORT(A)))
which prints:
7 4 3 2 1
See Also
UINT, WHERE
IDL Reference Guide SPAWN
SPAWN
The SPAWN procedure spawns a child process to execute a command or series of
commands. Under Unix, theshell used(if any) isobtainedfromtheSHELLenvironment
variable. Under VMS, theDCL command languageinterpreter isused. Under Windows
3.1 and Windows 95, a DOS window is opened. Under Windows NT, a Command Shell
is opened. On the Macintosh, SPAWN opens specied les or applications.
Calling Sequence
SPAWN [, Command(s) [, Result]]
Arguments
Command
A string containing the command(s) to be executed.
If Command is not present, SPAWN starts an interactive command interpreter process.
Under Unix, thedefault shell isused. IDL execution suspendsuntil thenewshell process
terminates. Under Unix, shells that handle process suspension (e.g., /bin/csh) offer a
more efcient way to get the same effect.
If Command is not present under Windows, SPAWN creates an interactive MS-DOS
window or NT command shell window as a child process. Quit the shell session by
entering EXIT at the prompt.
Command must be of type string. Under VMS, it is restricted to being a scalar. Under
Unix, it can be a string array (each element is passed to the child process as a separate
argument) if used in conjunction with the NOSHELL keyword. If a new Unix shell
processisstarted (that is, if theNOSHELL keyword isnot specied), Commandmust be
a scalar string.
On the Macintosh, Command must consist of the names of les to be opened. Multiple
lenames can be entered. If the rst lename is an application, it is used to open the
remaining les. Otherwise, each le is opened by the application that owns it. IDL
execution resumes when the les have been opened.
Result
Anamedvariablein whichtoplacetheoutput fromthechildprocess. Eachlineof output
becomes a single array element. If Result is not present, the output from the child shell
process goes to the standard output.
Under Windows and the Macintosh OS, Result has no effect.
SPAWN IDL Reference Guide
Keywords
COUNT
If Resultispresent and thiskeyword isalso specied, COUNT speciesanamed variable
into which the number of lines of output is placed. This value gives the number of
elements placed into Result.
PID
A named variable into which the Process IDentication number of the child process is
stored.
Macintosh Keywords
MACCREATOR
Use this keyword to specify a four-character scalar string containing the Macintosh le
creator code of the application to be used to open the specied les. In no les were
specied, the application is launched without any les.
Unix Keywords
NOSHELL
Set this keyword to specify that Command should execute directly as a child process
without an intervening shell process. In this case, Command should be specied as a
string array in which the rst element is the name of the command to execute and the
following arguments are the arguments to be passed to the command (C programmers
will recognizethisasthesearetheelementsof theargv argument that Unix passesto the
child process main function). Since no shell is present, wildcard characters are not
expanded, and other tasks normally performed by the shell do not occur. NOSHELL is
useful when performing many SPAWNed operations from a program and speed is a
primary concern.
NOTTYRESET
SomeUnix systemsdrop characterswhen thetty modeisswitched between normal and
rawmodes. IDL switchesbetween thesemodeswhen readingcommand input and when
using the GET_KBRD function. On such systems, IDL avoids losing characters by
delaying the switch back to normal mode until it is truly needed. This method has the
benet of avoidingthelargenumber of modechangesthat wouldotherwisebenecessary.
Routines that cause output to be sent to the standard output (e.g., I/O operations, user
interactionandSPAWN) ensurethat thettyisinitsnormal modebeforeperformingtheir
operations.
If theNOTTYRESETkeywordisset, SPAWNdoesnot switchthettyback tonormal mode
beforelaunchingthechildprocessassuminginsteadthat thechildwill not sendoutput to
the tty. Use this keyword to avoid characters being dropped in a loop of the form:
WHILE (GET_KBRD(0) NE 'q') SPAWN, command
IDL Reference Guide SPAWN
This keyword has no effect on systems that dont suffer from dropped characters.
SH
Set this keyword to force the use of the/bin/sh shell. Usually, the shell used is
determined by the SHELL environment variable.
UNIT
If UNIT is present, SPAWN creates a child process in the usual manner, but instead of
waitingfor thespecied command to nish, it attachesabidirectional pipebetween the
child process and IDL. From the IDL session, the pipe appears as a logical le unit. The
other end of the pipe is attached to the child process standard input and output. The
UNITkeywordspeciesanamedvariableintowhichthenumber of theleunit isstored.
Once the child process is started, the IDL session can communicate with it through the
usual input/output facilities. After the child process has done its task, the CLOSE
procedurecanbeusedtokill theprocessandclosethepipe. SinceSPAWNusesGET_LUN
to allocate the le unit, FREE_LUN should be used to free the unit.
If UNIT is present, Command must be present, and Result is not allowed.
VMS Keywords
NOCLISYM
If this keyword is set, the spawned subprocess does not inherit command language
interpreter symbols from its parent process. You can specify this keyword to prevent
commandsredened by symbol assignmentsfromaffectingthespawned commands, or
to speed process startup.
NOLOGNAM
If thiskeywordisset, thespawnedsubprocessdoesnot inherit processlogical namesfrom
itsparent process. Youcanspecifythiskeywordtoprevent commandsredenedbylogical
name assignments from affecting the spawned commands, or to speed process startup.
NOTIFY
If this keyword is set, a message is broadcast to SYS$OUTPUT when the child process
completes or aborts. NOTIFY should be set in conjunction with the NOWAIT keyword.
NOWAIT
If thiskeywordisset, theIDLprocesscontinuesexecutingin parallel withthesubprocess.
Normally, the IDL process hibernates until the subprocess completes.
Example
To simply spawn a process from within IDL enter the command:
SPAWN
To execute the UNIX ls command and return to the IDL prompt, enter:
SPAWN IDL Reference Guide
SPAWN, 'ls'
To execute the UNIX ls command and store the result in the IDL string variable
listing, enter:
SPAWN, 'ls', listing
See Also
Dollar Sign ($) on page 59.
IDL Reference Guide SPH_4PNT
SPH_4PNT
Given four 3-dimensional points, the SPH_4PNT procedure returns the center and
radius necessary to dene the unique sphere passing through those points.
sph_4pnt.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SPH_4PNT, X, Y, Z, Xc, Yc, Zc, R
Arguments
X, Y, Z
4-element oating-point or double-precision vectors containing the X, Y, and Z
coordinates of the points.
Xc, Yc, Zc
Named variables that will contain the spheres center X, Y, and Z coordinates.
R
A named variable that will contain the spheres radius.
Example
Find thecenter and radiusof theuniquespherepassingthrough thepoints: (1, 1, 0), (2,
1, 2), (1, 0, 3), (1, 0, 1)
Dene the oating-point vectors containing the x, y and z coordinates of the points.
X = [1, 2, 1, 1] + 0.0 Definethefloating-point vectors
Y = [1, 1, 0, 0] + 0.0 containingthex, y and z
Z = [0, 2, 3, 1] + 0.0 coordinates of thepoints.
SPH_4PNT, X, Y, Z, Xc, Yc, Zc, R Computespherescenterandradi-
us.
PRINT, Xc, Yc, Zc, R Print theresults.
IDL prints:
-0.500000 2.00000 2.00000 2.69258
See Also
CIR_3PNT, PNT_LINE
SPH_SCAT IDL Reference Guide
SPH_SCAT
The SPH_SCAT function performs spherical gridding. Scattered samples on the surface
of asphereareinterpolated to aregular grid. Thisroutineisaconvenient interfacetothe
spherical gridding and interpolation provided by TRIANGULATE and TRIGRID. The
returned value of the function is a regularly-interpolated grid.
sph_scat.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = SPH_SCAT(Lon, Lat, F)
Arguments
Lon
Avector of samplelongitudes, indegrees. Notethat Lon,Lat,andFmust all havethesame
number of points.
Lat
A vector of sample latitudes, in degrees.
F
Avector of datavalueswhich arefunctionsof Lon and Lat. F
i
representsavalueat (Lon
i
,
Lat
i
).
Keywords
BOUNDS
Set this keyword to a four-element vector containing the grid limits in longitude and
latitudeof theoutput grid. Thefour elementsare: [ Lon
min
,Lat
min
,Lon
max
,Lat
max
] . If this
keyword isnot set, thegrid limitsareset to theextent of Lonand Lat. Notethat, to cover
all longitudes, you must explicitly specify the values for the BOUNDS keyword.
BOUT
Set this keyword to a named variable that, on return, contains a four-element vector
(similar to BOUNDS) that describes the actual extent of the regular grid.
GOUT
Set this keyword to a named variable that, on return, contains a two-element vector
(similar to GS) that describes the actual grid spacing.
IDL Reference Guide SPH_SCAT
GS
Set thiskeywordtoatwo-element vector that speciesthespacingbetween gridpointsin
longitude (the rst element) and latitude (the second element).
If this keyword is not set, the default value is based on the extents of Lon and Lat. The
default longitude spacing is (Lon
max
- Lon
min
)/(NX-1). The default latitude spacing is
(Lat
max
- Lat
min
)/(NY-1). If NXandNYarenot set, thedefault gridsizeof 26by26isused
for NX and NY.
NLON
Theoutput grid sizein thelongitudedirection. Thedefault valueis26. Notethat NLON
need not be specied if the size can be inferred from GS and BOUNDS.
NLAT
The output grid size in the latitude direction. The default value is 26. Note that NLAT
need not be specied if the size can be inferred from GS and BOUNDS.
Example
lon = RANDOMU(seed, 50) * 360. -180. Createsomerandom longitude
points.
lat = RANDOMU(seed, 50) * 180. -90. Createsomerandom latitude
points.
z = SIN(lat*!DTOR) Makea function to fit.
c = COS(lat*!DTOR)
x = COS(lon*!DTOR) * c
y = SIN(lon*!DTOR) * c
f = SIN(x+y) * SIN(x*z) Thefinished dependent variable.
r = SPH_SCAT(lon, lat, f, BOUNDS=[0, -90, 350, 85], GS=[10,5])
Interpolatethedata and return
theresult in variabler.
See Also
TRIANGULATE, TRIGRID
SPL_INIT IDL Reference Guide
SPL_INIT
The SPL_INIT function is called to establish the type of interpolating spline for a
tabulated set of functional valuesX
i
, Y
i
= F(X
i
). SPL_INIT returns the values of the 2nd
derivative of the interpolating function at the pointsX
i
.
It is important to realize that SPL_INIT should be called only onceto process an entire
tabulated function in arraysXand Y. Oncethishasbeen done, valuesof theinterpolated
function for any value of X can be obtained by calls (as many as desired) to the separate
function SPL_INTERP.
SPL_INIT isbased on theroutinesplinedescribed in section 3.3of Numerical Recipesin
Calling Sequence
Result = SPL_INIT(X, Y)
Arguments
X
An n-element input vector that species the tabulate points in ascending order.
Y
An n-element input vector that species the values of the tabulated function F(X
i
)
corresponding to X
i
.
Keywords
DOUBLE
YP0
The rst derivative of the interpolating function at the point X
0
. If YP0 is omitted, the
second derivative at the boundary is set to zero, resulting in a natural spline.
YPN_1
The rst derivative of the interpolating function at the point X
n-1
. If YPN_1 is omitted,
the second derivative at the boundary is set to zero, resulting in a natural spline.
IDL Reference Guide SPL_INIT
Example
X = (FINDGEN(21)/20.) * 2.0*!PI
Y = SIN(X)
PRINT, SPL_INIT(X, Y, YP0 = -1.1, YPN_1 = 0.0)
IDL prints:
23.1552 -6.51599 1.06983 -1.26115 -0.839544 -1.04023
-0.950336 -0.817987 -0.592022 -0.311726 2.31192e-05 0.311634
0.592347 0.816783 0.954825 1.02348 0.902068 1.02781
-0.198994 3.26597 -11.0260
PRINT, SPL_INIT(X, Y, YP0 = -1.1)
IDL prints:
23.1552 -6.51599 1.06983 -1.26115 -0.839544 -1.04023
-0.950336 -0.817988 -0.592020 -0.311732 4.41521e-05 0.311555
0.592640 0.815690 0.958905 1.00825 0.958905 0.815692
0.592635 0.311567 0.00000
See Also
SPL_INTERP, SPLINE, SPLINE_P
SPL_INTERP IDL Reference Guide
SPL_INTERP
Given thearraysXand Y, which tabulateafunction (with theX
i
in ascendingorder), and
given the array Y
2
, which is the output from SPL_INIT, and given an input value of X
2
,
the SPL_INTERP function returns a cubic-spline interpolated value for the given value
of X
I
. The result has the same structure asX
2
, and is either single- or double-precision
oating, based on the input type.
SPL_INTERP is based on the routinesplint described in section 3.3 of Numerical
Calling Sequence
Result = SPL_INTERP(X, Y, Y2, X2)
Arguments
X
An input array that species the tabulated points in ascending order.
Y
An input array that species the values of the tabulate function corresponding to X
i
.
Y2
The output from SPL_INIT for the specied X and Y.
X2
Theinput valuefor which an interpolated valueisdesired. Xcan bescalar or an array of
values. The result of SPL_INIT will have the same structure.
Keywords
DOUBLE
Example
To create a spline interpolation over a tabulated set of data, [ X
i
, Y
i
] , rst create the
tabulated data. In this example, X
i
will be in the range [ 0.0, 2] and Y
i
in the range
[ sin(0.0), sin(2)] .
X = (FINDGEN(21)/20.0) * 2.0 * !PI
Y = SIN(X)
IDL Reference Guide SPL_INTERP
Y
2
= SPL_INIT(X, Y) Calculateinterpolatingcubic
spline.
X
2
= FINDGEN(11)/11.0 * !PI DefinetheXvaluesPatwhichwe
desireinterpolated Y values.
result = SPL_INTERP(X, Y, Y
2
, X
2
) Calculatetheinterpolated Y val-
ues correspondingto X
2
[i].
PRINT, result
IDL prints:
0.00000 0.281733 0.540638 0.755739 0.909613 0.989796
0.989796 0.909613 0.755739 0.540638 0.281733
The exact solution vector is sin(X
2
).
To interpolate a line in the XY plane, see SPLINE_P.
See Also
SPL_INIT, SPLINE, SPLINE_P
SPLINE IDL Reference Guide
SPLINE
The SPLINE function performs cubic spline interpolation.
spline.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = SPLINE(X, Y, T [, Sigma])
Arguments
X
The abscissa vector. Valuesmust be monotonically increasing.
Y
The vector of ordinate values corresponding to X.
T
The vector of abscissa values for which the ordinate is desired. The values of T must be
monotonically increasing.
Sigma
Theamount of tension that isapplied to thecurve. Thedefault valueis1.0. If sigmais
close to 0, (e.g., .01), then effectively there is a cubic spline t. If sigma is large, (e.g.,
greater than 10), then the t will be like a polynomial interpolation.
Example
The commands below show a typical use of SPLINE:
X = [2.,3.,4.] X values of original function
Y = (X-3)^2 Makea quadratic
T = FINDGEN(20)/10.+2 Values for interpolated points
Z = SPLINE(X,Y,T) Do theinterpolation
See Also
SPL_INIT, SPLINE_P
IDL Reference Guide SPLINE_P
SPLINE_P
TheSPLINE_Pprocedureperformsparametriccubicsplineinterpolationwithrelaxedor
clamped end conditions.
This routine is both more general and faster than the SPLINE function. One call to
SPLINE_Pisequivalent totwocallstoSPLINE, asboththeXandYareinterpolatedwith
splines. It is suited for interpolating between randomly placed points, and the abscissa
values need not be monotonic. In addition, the end conditions may be optionally
specied via tangents.
spline_p.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SPLINE_P, X, Y, Xr, Yr
Arguments
X
The abscissa vector. X should be oating-point or double-precision.
Y
The vector of ordinate values corresponding to X. Y should be oating-point or double-
precision.
Neither X or Y need be monotonic.
Xr
A named variable that will contain the abscissa values of the interpolated function.
Yr
A named variable that will contain the ordinate values of the interpolated function.
Keywords
INTERVAL
Set this keyword equal to the desired interval in XY space between interpolants. If
omitted, approximately 8 interpolants per XY segment will result.
TAN0
Thetangent tothesplinecurveat X[ 0] , Y[ 0] . If omitted, thetangent iscalculatedtomake
thecurvatureof theresult zeroat thebeginning. TAN0isatwoelement vector, containing
the X and Y components of the tangent.
SPLINE_P IDL Reference Guide
TAN1
Thetangent to thesplinecurveat X[ n-1] , Y[ n-1] . If omitted, thetangent iscalculated to
makethecurvatureof theresult zeroat theend. TAN1isatwoelement vector, containing
the X and Y components of the tangent.
Example
The commands below show a typical use of SPLINE_P:
X = [0.,1,0,-1,0] Abscissasforsquarewithavertical
diagonal
Y = [0.,1,2,1,0] Ordinates
SPLINE_P, X, Y, XR, YR Interpolatewith relaxed end con-
ditions
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.
Asabove, but with settingtheinterval to0.05, makingmoreinterpolants, 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.
See Also
SPL_INIT, SPLINE
IDL Reference Guide SPRSAB
SPRSAB
TheSPRSABfunction performsmatrix multiplication on tworow-indexed sparsearrays
created by SPRSIN. The routine computes all components of the matrix products, but
onlystoresthosevalueswhoseabsolutemagnitudeexceedsthethresholdvalue. Theresult
is a row-indexed sparse array.
SPRSABisbased on theroutinesprstm described in section 2.7of Numerical Recipesin
Press, andisusedbypermission. Thedifferencebetween thetworoutinesisthat SPRSAB
performs the matrix multiplication A
.
B rather than A
.
B
T
.
Calling Sequence
Result = SPRSAB(A, B)
Arguments
A, B
Row-indexed sparse arrays created by the SPRSIN function.
Keywords
DOUBLE
THRESH
Usethiskeyword toset thecriterion for decidingtheabsolutemagnitudeof theelements
toberetained in sparsestoragemode. For single-precision calculations, thedefault value
is 1.0 10
-7
. For double-precision calculations, the default is 1.0 10
-14
.
Example
Begin by creating two arrays:
A = [[ 5.0, 0.0, 0.0, 1.0], $
[ 3.0, -2.0, 0.0, 1.0], $
[ 4.0, -1.0, 0.0, 2.0], $
[ 0.0, 3.0, 3.0, 1.0]]
B = [[ 1.0, 2.0, 3.0, 1.0], $
[ 3.0, -3.0, 0.0, 1.0], $
[-1.0, 3.0, 1.0, 2.0], $
SPRSAB IDL Reference Guide
[ 0.0, 3.0, 3.0, 1.0]]
sparse = SPRSAB(SPRSIN(A), SPRSIN(B)) Convertthearraystosparsearray
format beforemultiplying. The
variableSPARSE holds theresult
in sparsearray form.
result = FULSTR(sparse) Restorethesparsearray structure
to full storagemode.
IDL prints:
5.00000 13.0000 18.0000 6.00000
-3.00000 15.0000 12.0000 2.00000
1.00000 17.0000 18.0000 5.00000
6.00000 3.00000 6.00000 10.0000
We can check this result by multiplying the original arrays:
exact = B # A
PRINT, exact
IDL prints:
5.00000 13.0000 18.0000 6.00000
-3.00000 15.0000 12.0000 2.00000
1.00000 17.0000 18.0000 5.00000
6.00000 3.00000 6.00000 10.0000
See Also
FULSTR, LINBCG, SPRSAX, SPRSIN, READ_SPR, WRITE_SPR
IDL Reference Guide SPRSAX
SPRSAX
TheSPRSAX function takesarow-indexed sparsearray created by theSPRSIN function
and multiplies it by an n-element vector to its right. The result is an-element vector.
SPRSAXisbased on theroutinesprsax described in section 2.7of Numerical Recipesin
Calling Sequence
Result = SPRSAX(A, X)
Arguments
A
X
An n-element right hand vector.
Keywords
DOUBLE
Example
Begin by creating an array A:
A = [[ 5.0, 0.0, 0.0], $
[ 3.0, -2.0, 0.0], $
[ 4.0, -1.0, 0.0]]
X = [1.0, 2.0, -1.0] Definetheright-hand vector.
result = SPRSAX(SPRSIN(A),X) Convert to sparseformat, then
multiply by X.
IDL prints:
5.00000 -1.00000 2.00000
See Also
FULSTR, LINBCG, SPRSAB, SPRSIN, READ_SPR, WRITE_SPR
SPRSIN IDL Reference Guide
SPRSIN
TheSPRSIN function convertsan array into arow-index sparsestoragemode, retaining
only elements with an absolute magnitude greater than or equal to the specied
threshold.
The result is a row-indexed sparse array contained in structure form. The structure
consistsof twolinear sparsestoragevectors: SA, avector of arrayvalues, andIJA, avector
of subscripts to the SA vector. The length of these vectors is equal to the number of
diagonal elementsof thearray, plusthenumber of off-diagonal elementswithanabsolute
magnitudegreater that or equal tothethresholdvalue. Diagonal elementsof thearrayare
always retained even if their absolute magnitude is less than the specied threshold.
SPRSIN isbased on theroutinesprsin described in section 2.7of Numerical Recipesin
Calling Sequence
Result = SPRSIN(A)
Arguments
A
An n by n array of any type except string or complex.
Keywords
COLUMN
DOUBLE
Set this keyword to convert the sparse array to double-precision.
THRESH
Usethiskeyword toset thecriterion for decidingtheabsolutemagnitudeof theelements
toberetained in sparsestoragemode. For single-precision calculations, thedefault value
is 1.0 10
-7
. For double-precision values, the default is 1.0 10
-14
.
Example
Suppose we wish to convert the following array to sparse storage format:
A = [[ 5.0, -0.2, 0.1], $
IDL Reference Guide SPRSIN
[ 3.0, -2.0, 0.3], $
[ 4.0, -1.0, 0.0]]
sparse = SPRSIN(A, THRESH = 0.5) Convert to sparsestoragemode.
All elements of thearray A that
haveabsolutevalues less than
THRESH areset to zero.
The variable SPARSE now contains a representation of A in structure form. See the
description of FULSTRfor an examplethat restoressuch astructuretofull storagemode.
See Also
FULSTR, LINBCG, SPRSAB, SPRSAX, READ_SPR, WRITE_SPR
SQRT IDL Reference Guide
SQRT
The SQRT function returns the square root of X.
Calling Sequence
Result = SQRT(X)
Arguments
X
Thevaluefor which thesquareroot isdesired. If Xisdouble-precision oating-point or
complex, the result is of the same type. All other types are converted to single-precision
oating-point and yield oating-point results. When applied to complex numbers, z =
x+iy:
The ambiguous sign is taken to be the same as the sign of y. The result has the same
structure asX.
Example
To nd the square root of 145 and store the result in variable S, enter:
S = SQRT(145)
See Also
Exponentiation on page 29 of Building IDL Applications.
z
1 2 /
1
2
-- r x + ( )
1 2 /
i
1
2
-- r x ( )
1 2 /
t =
r x
2
y
2
+ =
IDL Reference Guide STANDARDIZE
STANDARDIZE
The STANDARDIZE 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.
standardize.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = STANDARDIZE(A)
Argument
A
An m-column, n-row single- or double-precision oating-point array.
Keywords
DOUBLE
Example
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], $
STANDARDIZE IDL Reference Guide
[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]]
FOR K = 0, 3 DO PRINT, MOMENT(array[K,*])
Computethemean and variance
of each variableusingtheMO-
MENT function. Theskewness
and kurtosis arealso computed.
result = STANDARDIZE(array) Computethestandardized vari-
ables.
FOR K = 0, 3 DO PRINT, MOMENT(result[K,*])
Computethemean and variance
of each standardized variableus-
ingtheMOMENT function. The
skewness and kurtosis arealso
computed.
IDL prints:
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
-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
See Also
MOMENT
IDL Reference Guide STDDEV
STDDEV
The STDDEV function computes the standard deviation of an n-element vector.
Calling sequence
Result = STDDEV(X)
Arguments
X
A numeric vector.
Keywords
DOUBLE
If this keyword is set, computations are performed in double precision arithmetic.
NAN
Example
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
; Definethen-element vector of
sampledata.
result = STDDEV(x) ;Computethestandarddeviation.
PRINT, result
IDL prints:
2.65832
See Also
KURTOSIS, MEAN, MEANABSDEV, MOMENT, SKEWNESS, VARIANCE
STOP IDL Reference Guide
STOP
The STOP procedure stops the execution of a running program or batch le. Control
reverts to the interactive mode.
Calling Sequence
STOP[, Expr
1
, ..., Expr
n
]
Arguments
Expr
i
One or more expressions whose value is printed. If no parameters are present, a brief
message describing where the STOP was encountered is printed.
Example
Suppose that you want to stop the execution of a procedure and print the values of the
variables A, B, C and NUM. At the appropriate location in your procedure include the
command:
STOP, A, B, C, NUM
To continue execution of the procedure (if possible) enter the IDL executive command:
.CONT
See Also
BREAKPOINT, EXIT, WAIT
IDL Reference Guide STR_SEP
STR_SEP
The STR_SEP function divides a string into pieces as designated by a separator string.
STR_SEP returns a string array where each element is a separated piece of the original
string.
str_sep.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = STR_SEP(Str, Separator)
Arguments
Str
The string to be separated.
Separator
The separator string.
Keywords
TRIM
Set thiskeywordtoremoveleadingandtrailingblanksfromeachelement of thereturned
string array. TRIM performs STRTRIM(String, 2).
REMOVE_ALL
Set this keyword to remove all blanks from each element of the returned string array.
REMOVE_ALL performs STRCOMPRESS(String, /REMOVE_ALL)
ESC
Set this keyword to interpret the characters following the <ESC> character literally and
not as separators. For example, if the separator is a comma and the escape character is a
backslash, the character sequence a\,b is interpreted as a single eld containing the
characters a,b.
Example
str = 'Doug.is.a.cool.dude!' Createa string.
parts = STR_SEP(str, '.') Separatethepartsbetweenthepe-
riods.
STR_SEP IDL Reference Guide
HELP, parts Confirm that thestringhas been
broken up into 5 elements.
IDL prints:
PARTS STRING = Array[5]
PRINT, parts[3]
IDL prints:
cool
See Also
STRMID, STRPOS
IDL Reference Guide STRARR
STRARR
The STRARR function returns a string array containing zero-length strings.
Calling Sequence
Result = STRARR(D
1
, ..., D
n
)
Arguments
D
i
Example
To create S, a 20-element string vector, enter:
S = STRARR(20)
See Also
LON64ARR, LONARR, MAKE_ARRAY, UINTARR, ULON64ARR, ULONARR
STRCOMPRESS IDL Reference Guide
STRCOMPRESS
The STRCOMPRESS function returns a copy of Stringwith all whitespace (blanks and
tabs) compressed to a single space or completely removed.
Calling Sequence
Result = STRCOMPRESS(String)
Arguments
String
The string to be compressed. If not of type string, it is converted using IDLs default
formattingrules. If Stringisan array, theresult isan arraywith thesamestructureeach
element contains a compressed copy of the corresponding element of String.
Keywords
REMOVE_ALL
Set this keyword to removeall whitespace. Normally, all whitespace is compressed to a
singlespace.
Example
Create a string variable S by entering:
S = 'This is a string with spaces in it.'
Now print S with all of the whitespace removed by entering:
PRINT, STRCOMPRESS(S, /REMOVE_ALL)
IDL prints:
Thisisastringwithspacesinit.
See Also
STRTRIM
IDL Reference Guide STRETCH
STRETCH
The STRETCH procedure stretches the image display color tables so the full range runs
from one color index to another. The modied colortable is loaded, but the COLORS
common block is not changed. The original colortable can be restored by calling
STRETCH with no arguments. A colortable must be loaded before STRETCH can be
called.
stretch.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
STRETCH [, Low, High [, Gamma]]
Arguments
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. If no parameters are supplied,
the original color tables are restored.
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.
Gamma
An optional Gamma correction factor. If this value is omitted, 1.0 is assumed. Gamma
correction works by raising the color indices to theGamma power, assuming they are
scaled into the range 0 to 1.
Keywords
CHOP
Set thiskeywordtoset color indicesabovetheupper thresholdtocolor index0. Normally,
values above the upper threshold are set to the maximum color index.
Example
Load the STD GAMMA-II color table by entering:
LOADCT, 5
Create and display and image by entering:
STRETCH IDL Reference Guide
TVSCL, DIST(300)
Nowadjust thecolor tablewith STRETCH. Maketheentirecolor tablet in therange0
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
See Also
GAMMA_CT, H_EQ_CT, MULTI, XLOADCT
IDL Reference Guide STRING
STRING
TheSTRINGfunction returnsitsargumentsconverted to stringtype. It issimilar to the
PRINT procedure, except that itsoutput isplaced in astringrather than beingoutput to
the terminal. The case in which a single expression of type byte is specied without the
FORMAT keyword is specialsee the discussion below for details.
Note Applying the STRING function to a byte array containing a null (zero) value will
result in the resulting string being truncated at that position.
Calling Sequence
Result = STRING(Expression
1
, ..., Expression
n
)
Arguments
Expression
n
The expressions to be converted to string type.
Keywords
AM_PM
FORMAT keyword.
DAYS_OF_WEEK
FORMAT keyword.
FORMAT
Aformat stringtobeusedin formattingtheexpressions. See UsingExplicitlyFormatted
Input/Output on page 169 of Building IDL Applications. Note that formatted output
from STRING is limited to a maximum of 1024 lines.
MONTHS
FORMAT keyword.
PRINT
Set this keyword to specify that any special case processing should be ignored and that
STRING should behave exactly as the PRINT procedure would.
STRING IDL Reference Guide
Differences Between STRING and PRINT
The behavior of STRING differs from the behavior of the PRINT procedure in the
following ways (unless the PRINT keyword is set):
When called with a single non-byte argument and no format specication, STRING
returnsaresult that hasthesamedimensionsastheoriginal argument. For example, the
statement:
HELP, STRING(INDGEN(5))
gives the result:
<Expression> STRING = Array[5]
while:
HELP, STRING(INDGEN(5), /PRINT)
results in:
<Expression> STRING =' 0 1 2 3 4'
If called with a single argument of byte type and the FORMAT keyword is not used,
STRINGsimplystorestheunmodiedvaluesof eachbyteelement intheresult. Thisresult
isastringcontainingthebytevaluesfromtheoriginal argument. Thus, theresult hasone
less dimension than the original argument. For example, a 2-dimensional byte array
becomesavector of strings, abytevector becomesascalar string. However, abytescalar
also becomes a string scalar. For example, the statement:
PRINT, STRING([72B, 101B, 108B, 108B, 111B])
produces the output:
Hello
because the argument to STRING, is a byte vector. Its rst element is a 72B which is the
ASCII code for H, the second is 101B which is an ASCII e, and so forth.
If both the FORMAT and PRINT keywords are not present and STRING is called with
more than one argument, and the last argument is a scalar string starting with the
characters $( or (, thisnal argument istaken tobetheformat specication, just asif
it had been specied via the FORMAT keyword. This feature is maintained for compati-
bility with version 1 of VMS IDL.
Example
To convert thecontentsof variableAto stringtypeand storetheresult in thevariableB,
enter:
B = STRING(A)
IDL Reference Guide STRING
See Also
BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64,
PRINT/PRINTF, UINT, ULONG, ULONG64
STRLEN IDL Reference Guide
STRLEN
TheSTRLEN function returnsthelength of itsstring-typeargument. If theargument is
not a string, it is rst converted to string type.
Calling Sequence
Result = STRLEN(Expression)
Arguments
Expression
Theexpression for which thestringlength isdesired. If thisparameter isnot astring, it is
converted using IDLs default formatting rules in order to determine the length. The
result isalonginteger. If Expressionisan array, theresult isalonginteger array with the
samestructure, whereeach element containsthelength of thecorrespondingExpression
element.
Example
To nd the length of the string IDL is fun and print the result, enter:
PRINT, STRLEN('IDL is fun')
IDL prints:
10
IDL Reference Guide STRLOWCASE
STRLOWCASE
TheSTRLOWCASEfunction returnsacopy of Stringconverted to lowercasecharacters.
Only uppercase characters are modiedlowercase and non-alphabetic characters are
copied without change.
Calling Sequence
Result = STRLOWCASE(String)
Arguments
String
The string to be converted. If this argument is not a string, it is converted using IDLs
default formatting rules. If Stringis an array, the result is an array with the same
structureeach element contains a lower case copy of the corresponding element of
String.
Example
To convert the string IDL is fun to all lowercase characters and print the result, enter:
PRINT, STRLOWCASE('IDL is fun')
IDL prints:
idl is fun
See Also
STRUPCASE
STRMESSAGE IDL Reference Guide
STRMESSAGE
The STRMESSAGE function returns the text of the error message specied by Err. This
function isespecially useful in conjunction with theCODEeld of the!ERROR_STATE
systemvariablewhich alwayscontainstheerror number of thelast error. TheMSGeld
of the !ERROR_STATE system variable contains the text of the last error message.
Calling Sequence
Result = STRMESSAGE(Err)
Arguments
Err
The error number or text. Programs must not make the assumption that certain error
numbersarealwaysrelated to certain error messagestheactual correspondencechanges
over time as IDL is modied.
Keywords
BLOCK
Set thiskeyword toreturn thenameof themessageblock that denesErr. If thiskeyword
is specied, Err must be an error code.
CODE
Set this keyword to return the error code for the error message specied in Err. If this
keyword is specied, Err must be an error name.
NAME
Set thiskeyword toreturn astringcontainingtheerror messagethat goeswith Err. If this
keyword is specied, Err must be an error code.
Example
Print the error message associated with error number 4 by entering:
PRINT, STRMESSAGE(4)
See Also
MESSAGE
IDL Reference Guide STRMID
STRMID
The STRMID function extracts a substring from a string expression. The result of the
function is a string of Length characters taken fromExpression, starting at character
position First_Character.
Calling Sequence
Result = STRMID(Expression, First_Character [, Length])
Arguments
Expression
The expression from which the substring is to be extracted. If this argument is not a
string, it is converted using IDLs default formatting rules. If Expression is an array, the
result is an array with the same structure, where each element contains the substring of
the correspondingExpression element.
First_Character
The starting position within Expression at which the substring starts. The rst character
position is 0.
Length
The length of the substring. If there are not enough characters left in the main string to
obtain Length characters, the substring is truncated. If Length is not supplied, STRMID
extracts all characters from the specied start position to the end of the string.
Example
If the variable B contains the string IDL is fun, the substring is can be extracted and
stored in the variable C with the command:
C = STRMID(B, 4, 2)
See Also
RSTRPOS, STRPOS, STRPUT, STRTRIM
STRPOS IDL Reference Guide
STRPOS
TheSTRPOSfunction ndstherst occurrenceof asubstringwithin an object string. If
Search_Stringoccursin Expression, STRPOSreturnsthecharacter position of thematch,
otherwise it returns -1.
Calling Sequence
Result = STRPOS(Expression, Search String [, Pos])
Arguments
Expression
The expression in which to search for the substring. If this argument is not a string, it is
converted using IDLs default formatting rules. If Expression is an array, the result is an
array with thesamestructure, whereeach element containstheposition of thesubstring
within the corresponding element Expression. If Expression is the null string, STRPOS
returns the value -1.
Search_String
The substring to be searched for within Expression. If this argument is not a string, it is
converted using IDLs default formatting rules. If Search_Stringis the null string,
STRPOS returns the smaller of Posor one less than the length of Expression.
Pos
Thecharacter position at which thesearch isbegun. If Posisomitted, thesearchbeginsat
the rst character (character position 0). If Posis less than zero, zero is used for the
starting position.
Example
Find theposition of thestringfun within thestring IDL isfun and print theresult by
entering:
PRINT, STRPOS('IDL is fun', 'fun')
IDL prints:
7
See Also
RSTRPOS, STRMID, STRPUT, STRTRIM
IDL Reference Guide STRPUT
STRPUT
TheSTRPUTprocedureinsertsthecontentsof onestringintoanother. Thesourcestring,
Source, is inserted into the destination string, Destination, starting at the given position,
Position. Characters in Destination before the starting position and after the starting
position plusthelengthof Sourceremain unchanged. Thelengthof thedestination string
isnot changed. If theinsertion extendspast theend of thedestination, it isclipped at the
end.
Calling Sequence
STRPUT, Destination, Source[, Position]
Arguments
Destination
The named string variable into which Sourceis inserted. Destination must be a named
variable of type string. If it is an array, Sourceis inserted into every element of the array.
Source
A scalar string to be inserted into Destination. If this argument is not a string, it is
converted using IDLs default formatting rules.
Position
Thecharacter positionat whichtheinsertionisbegun. If Positionisomitted, theinsertion
beginsat therst character (character position 0). If Positionislessthan zero, zeroisused
for the initial position.
Examples
If thevariableAcontainsthestring IBM isfun, thesubstring IBM can beoverwritten
with the string IDL by entering:
STRPUT, A, 'IDL', 0
The following commands demonstrate the clipping of output that extends past the end
of the destination string:
STRPUT, A, 'FUNNY', 7
PRINT, A
IDL prints:
IDL is FUN
See Also
STRMID, STRPOS, STRTRIM
STRTRIM IDL Reference Guide
STRTRIM
The STRTRIM function returns a copy of Stringwith leading and/or trailing blanks
removed.
Calling Sequence
Result = STRTRIM(String, [Flag])
Arguments
String
Thestringtohaveleadingand/or trailingblanksremoved. If thisargument isnot astring,
it is converted using IDLs default formatting rules. If it is an array, the result is an array
with the same structure where each element contains a trimmed copy of the
corresponding element of String.
Flag
Avaluethat controlstheaction of STRTRIM. If Flagiszeroor not present, trailingblanks
areremoved. Leadingblanksareremovedif it isequal to1. Both areremovedif it isequal
to 2.
Example
Converting variables to string type often results in undesirable leading blanks. For
example, the following command converts the integer 56 to string type:
C = STRING(56)
Entering the command:
HELP, C
IDL prints:
C STRING = ' 56'
which shows that there are six leading spaces before the characters 5 and 6. To remove
these leading blanks, enter the command:
C = STRTRIM(C, 1)
To conrm that the blanks were removed, enter:
HELP, C
IDL prints:
C STRING = '56'
See Also
STR_SEP, STRMID, STRPOS, STRPUT
IDL Reference Guide STRUCT_ASSIGN
STRUCT_ASSIGN
The IDL = operator is unable to assign a structure value to a structure of a different
type. TheSTRUCT_ASSIGN procedureperforms relaxed structureassignment, which
isaeld-by-eld copy of astructureto another structure. Fieldsarecopied accordingto
the following rules:
1. Anyeldsfoundinthedestinationstructurethat arenot foundinthesourcestructure
are zeroed (set to zero, the empty string, or a null pointer or object reference
depending on the type of eld).
2. Any eldsin thesourcestructurethat arenot found in thedestination structureare
quietly ignored.
3. Anyeldsthat arefoundinboththesourceanddestinationstructuresarecopiedone
at atime. If necessary, typeconversion isdoneto maketheir typesagree. If aeld in
the source structure has fewer data elements than the corresponding eld in the
destination structure, then the extra elements in the eld in the destination struc-
ture are zeroed. If a eld in the source structure has more elements than the
corresponding eld in the destination structure, the extra elements are quietly
ignored.
Relaxedstructureassignment isespeciallyuseful whenrestoringstructuresfromdisk les
into an environment where the structure denition has changed. See the description o f
the RELAXED_STRUCTURE_ASSIGNMENT keyword to the RESTORE procedure for
additional details. Relaxed Structure Assignment on page 55 of Building IDL
Applications provides a more in-depth discussion of the structure-denition process.
Calling Sequence
STRUCT_ASSIGN, Source, Destination
Arguments
Source
Anamedvariableor element of anarraycontainingastructure, thecontentsof whichwill
be assigned to the structure specied by theDestination argument. Sourcecan be an
object reference if STRUCT_ASSIGN is called inside an object method.
Destination
Anamedvariablecontainingastructureintowhichthecontentsof thestructurespecied
by theSourceargument will be inserted. Destination can be an object reference if
STRUCT_ASSIGN is called inside an object method.
STRUCT_ASSIGN IDL Reference Guide
Keywords
VERBOSE
Set this keyword to cause STRUCT_ASSIGN to issue informational messages about any
incompatibilities that prevent data from being copied.
Examples
Thefollowingexamplecreatestwo anonymousstructures, then usesSTRUCT_ASSIGN
to insert the contents of the rst into the second.
source = { a:FINDGEN(4), b:12 }
dest = { a:INDGEN(2), c:20 }
STRUCT_ASSIGN, /VERBOSE, source, dest
IDL prints:
% STRUCT_ASSIGN: <Anonymous> tag A is longer than destination.
The end will be clipped.
% STRUCT_ASSIGN: Destination lacks <Anonymous> tag B. Not copied.
After assignment, dest containsatwo-element integer array [ 0, 1] in itseld A and the
integer 0 in its eld C. Sincedest does not have a eld B, eld B fromsource is not
copied.
IDL Reference Guide STRUPCASE
STRUPCASE
The STRUPCASE function returns a copy of Stringconverted to upper case. Only
lowercasecharactersaremodieduppercaseand non-alphabeticcharactersarecopied
without change.
Calling Sequence
Result = STRUPCASE(String)
Arguments
String
The string to be converted. If this argument is not a string, it is converted using IDLs
default formatting rules. If it is an array, the result is an array with the same structure
where each element contains an uppercase copy of the corresponding element of String.
Example
To print an uppercase version of the string IDL is fun, enter:
PRINT, STRUPCASE('IDL is fun')
IDL prints:
IDL IS FUN
See Also
STRLOWCASE
SURFACE IDL Reference Guide
SURFACE
TheSURFACEproceduredrawsawire-mesh representation of atwo-dimensional array
projected into two dimensions, with hidden lines removed.
Restrictions
If the(X, Y) gridisnot regular or nearlyregular, errorsin hidden lineremoval occur. The
TRIGRID and TRIANGULATE routines can be used to interpolate irregularly-gridded
data points to a regular grid before plotting.
If the T3D keyword is set, the 3D to 2D transformation matrix contained in !P.T must
project the Z axis to a line parallel to the device Y axis, or errors will occur.
The surface lines may blend together when drawing large arrays, especially on low or
medium resolution displays. Use the REBIN or CONGRID procedure to resample the
array to a lower resolution before plotting.
Calling Sequence
SURFACE, Z [, X, Y]
Arguments
Z
Thetwo-dimensional arraytobedisplayed. If XandYareprovided, thesurfaceisplotted
asafunction of the(X, Y) locationsspecied by their contents. Otherwise, thesurfaceis
generated as a function of the array index of each element of Z.
createdwithSURFACEarelimitedtotherangeandprecision of single-precision oating-
point values.
X
A vector or two-dimensional array specifying the X coordinates of the grid. If this
argument isavector, each element of XspeciestheXcoordinatefor acolumn of Z(e.g.,
X[0] species the X coordinate for Z[0,*]). If X is a two-dimensional array, each
element of XspeciestheXcoordinateof thecorrespondingpoint in Z(X
ij
speciesthe
X coordinate for Z
ij
).
This argument is converted to single-precision oating-point before plotting.
Y
A vector or two-dimensional array specifying the Y coordinates of the grid. If this
argument is a vector, each element of Y species the Y coordinate for a row of Z (e.g.,
Y[0] species the Y coordinate for Z[*,0]). If Y is a two-dimensional array, each
IDL Reference Guide SURFACE
element of Y species the Y coordinate of the corresponding point in Z (Y
ij
species the
Y coordinate for Z
ij
).
This argument is converted to single-precision oating-point before plotting.
Keywords
AX
This keyword species the angle of rotation, about the X axis, in degrees towards the
viewer. This keyword is effective only if !P.T3D is not set. If !P.T3D is set, the three-
dimensional to two-dimensional transformation used by SURFACE is taken from the 4
by 4 array !P.T.
The surface represented by the two-dimensional array is rst rotated, AZ (see below)
degreesabout theZ axis, then by AXdegreesabout theXaxis, tiltingthesurfacetowards
the viewer (AX > 0), or away from the viewer.
The AX and AZ keyword parameters default to +30 degrees if omitted and !P.T3D is 0.
The three-dimensional to two-dimensional transformation represented by AX and AZ,
can be saved in !P.T by including the SAVE keyword.
AZ
This keyword species the counterclockwise angle of rotation about the Z axis. This
keyword is effective only if !P.T3D is not set. The order of rotation is AZ rst, then AX.
BOTTOM
The color index used to draw the bottom surface. If not specied, the bottom is drawn
with the same color as the top.
HORIZONTAL
A keyword ag which if set causes SURFACE to only draw lines across the plot
perpendicular to the line of sight. The default is for SURFACE to draw both across the
plot and from front to back.
LEGO
Set thiskeyword toproducestacked histogram-styleplots. Each datavalueisrendered as
a box covering the XY extent of the cell and with a height proportional to the Z value.
If theX and Y arguments are specied, only N
x
-1 columns and N
y
-1 rows are drawn.
(This means that the last row and column of array data are not displayed.) The
rectangular area covered by Z[ i, j] is given by X[ i] , X[ i+1] , Y[ j] , and Y[ j+1] .
LOWER_ONLY
Set thiskeywordtodrawonlythelower surfaceof theobject. Bydefault, bothsurfacesare
drawn.
MAX_VALUE
MIN_VALUE
SAVE
Set thiskeyword tosavethe3Dto2Dtransformation matrix established bySURFACEin
thesystemvariableeld !P.T. Usethiskeyword when combiningtheoutput of SURFACE
with additional output from other routines in the same plot.
When used with AXIS, the SAVE keyword parameter saves the scaling parameters
established by the call in the appropriate axis system variable, !X, !Y, or !Z. This causes
subsequent overplots to be scaled to the new axis.
Example To display a two-dimensional array using SURFACE, and to then superimpose
contoursover thesurface(thisexampleassumesthat !P.T3Diszero, itsdefault value.),
enter the following commands:
SURFACE, Z, /SAVE Makea surfaceplot and savethe
transformation.
CONTOUR, Z, /NOERASE, /T3D Makecontours,donterase,usethe
3Dto2Dtransformplacedin!P.T
by SURFACE.
To display a surface and to then display a at contour plot, registered above the
surface:
SURFACE, Z, /SAVE Makethesurface, savetransform.
CONTOUR, Z, /NOERASE, /T3D, ZVALUE=1.0Nowdisplayaflatcontourplot,
at themaximum Z value(nor-
malized coordinates).
You can display the contour plot below the surface with by using a ZVALUE of 0.0.
SHADES
Thiskeyword allowsuser-specied coloringof themesh surfaces. Set thiskeyword to an
arraythat speciesthecolor indexof thelinesemanatingfromeachdatapoint towardthe
top and right.
DEVICE on page 419.
IDL Reference Guide SURFACE
SKIRT
Thiskeyword representsaZ-valueat which todrawaskirt around thearray. TheZ value
is expressed in data units. The default is no skirt.
If the skirt is drawn, each point on the four edges of the surface is connected to a point
on theskirt which hasthegiven Z value, and thesameX and Yvaluesastheedgepoint.
In addition, each point on the skirt is connected to its neighbor.
UPPER_ONLY
Set this keyword to draw only the upper surface of the object. By default, both surfaces
are drawn.
XLOG
YLOG
Set this keyword to specify a logarithmic Yaxis.
ZAXIS
This keyword species the placement of the Z axis for the SURFACE plot.
Bydefault, SURFACEdrawstheZaxisat theupper left corner of theaxisbox. Tosuppress
the Z axis, useZAXIS=-1 in the call. The position of the Z axis is determined from the
value of ZAXIS as follows: 1 = lower right, 2 = lower left, 3 = upper left, and 4 = upper
right.
ZLOG
Set this keyword to specify a logarithmic Zaxis.
DATA DAYS_OF_WEEK DEVICE FONT LINESTYLE NOCLIP NODATA NOERASE
NORMAL POSITION SUBTITLE T3D THICK TICKLEN TITLE [ XYZ] CHARSIZE
[ XYZ] GRIDSTYLE [ XYZ] MARGIN [ XYZ] MINOR MONTHS [ XYZ] RANGE
[ XYZ] STYLE[ XYZ] THICK [ XYZ] TICKFORMAT [ XYZ] TICKLEN [ XYZ] TICKNAME
[ XYZ] TICKS [ XYZ] TICKV [ XYZ] TICK_GET [ XYZ] TITLE ZVALUE.
Example
D = DIST(30) Createasimpledatasettodisplay.
SURFACE, D Plot a simplewire-mesh surface
representation of D.
SURFACE, D, SKIRT=0.0, TITLE = 'Surface Plot', CHARSIZE = 2
Createawire-meshplotofDwith
a titleand a skirt around the
edges of thedataset at Z=0.
See Also
CONTOUR, SHADE_SURF
IDL Reference Guide SURFR
SURFR
The SURFR procedure sets up 3D transformations. This procedure duplicates the
rotation, translation, and scalingfeaturesof theSURFACEroutine, but doesnot display
any data. The resulting transformations are stored in the !P.T system variable.
surfr.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
SURFR
Keywords
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.
See Also
SCALE3, SCALE3D, T3D
SVDC IDL Reference Guide
SVDC
The SVDC procedure computes the Singular Value Decomposition (SVD) of a square
(nx n) or non-square (nx m) array as the product of orthogonal and diagonal arrays.
SVD is a very powerful tool for the solution of linear systems, and is often used when a
solution cannot be determined by other numerical algorithms.
The SVD of an (mx n) non-square array A is computed as the product of an (mx n)
column orthogonal array U, an (n x n) diagonal array SV, composed of the singular
values, and the transpose of an (n x n) orthogonal array V: A = U SV V
T
SVDCisbasedon theroutinesvdcmp describedin section 2.6of Numerical RecipesinC:
Calling Sequence
SVDC, A, W, U, V
Arguments
A
Thesquare(nxn) or non-square(nxm) single- or double-precision oating-point array
to decompose.
W
On output, W is an n-element output vector containing the singular values.
U
On output, U is an n-column, m-row orthogonal array used in the decomposition of A.
V
On output, V is an n-column, n-row orthogonal array used in the decomposition of A.
Keywords
COLUMN
DOUBLE
IDL Reference Guide SVDC
Example
To nd the singular values of an array A:
A = [[1.0, 2.0, -1.0, 2.5], $ Definethearray A.
[1.5, 3.3, -0.5, 2.0], $
[3.1, 0.7, 2.2, 0.0], $
[0.0, 0.3, -2.0, 5.3], $
[2.1, 1.0, 4.3, 2.2], $
[0.0, 5.5, 3.8, 0.2]]
SVDC, A, W, U, V ComputetheSingular ValueDe-
composition.
PRINT, W Print thesingular values.
IDL prints:
8.81973 2.65502 4.30598 6.84484
Toverifythedecomposition, usetherelationshipA= U##SV##TRANSPOSE(V), where
SV is a diagonal array created from the output vector W.
sv = FLTARR(4, 4)
FOR K = 0, 3 DO sv(K,K) = W[K]
result = U ## sv ## TRANSPOSE(V)
PRINT, result
IDL prints:
1.00000 2.00000 -1.00000 2.50000
1.50000 3.30000 -0.500001 2.00000
3.10000 0.700000 2.20000 0.00000
2.23517e-08 0.300000 -2.00000 5.30000
2.10000 0.999999 4.30000 2.20000
-3.91155e-07 5.50000 3.80000 0.200000
This is the input array, to within machine precision.
See Also
CHOLDC, LUDC, SVSOL
Linear Systems on page 453 of Using IDL.
SVDFIT IDL Reference Guide
SVDFIT
The SVDFIT function performs a general least squares t with optional error estimates
and returns a vector of coefcients. Either a user-supplied function written in the IDL
language or a built-in polynomial can be used to t the data.
SVDFIT is based on the routinesvdfit described in section 15.4 of Numerical Recipes
Calling Sequence
Result = SVDFIT(X, Y [, M])
Arguments
X
Y
M
The number of coefcients in the tting function. For polynomials, M is equal to the
degreeof thepolynomial + 1. If theMargument isnot specied, you must supply initial
coefcient estimates using the A keyword. In this case, M is set equal to the number of
elements of the array specied by the A keyword.
Keywords
A
Set this keyword equal to a vector of initial estimates for the tted function parameters.
SVDFIT returnsavector of coefcientsthat areimprovementsof theinitial estimates. If
A is supplied, the M argument will be set equal to the number of elements in the vector
specied by A.
CHISQ
Set this keyword equal to a named variable that will contain the sum of squared errors
multiplied by weights if weights are specied.
COVAR
Set thiskeyword equal to anamed variablethat will contain thecovariancematrix of the
tted coefcients.
IDL Reference Guide SVDFIT
DOUBLE
FUNCTION_NAME
Set thiskeywordequal toastringcontainingthenameof auser-suppliedIDLbasisfunction
withMcoefficients. If thiskeywordisomitted, andtheLEGENDREkeywordisnot set, IDL
assumesthat theIDL procedureSVDFUNCT, foundin thefilesvdfunct.pro, locatedin
thelib subdirectory of the IDL distribution, is to be used. SVDFUNCT uses the basis
functions for the fitting polynomial
The function to be t must be written as an IDL function and compiled prior to calling
SVDFIT. Thefunction must accept valuesof X(ascalar), andM(ascalar). It must return
an M-element vector containing the basis functions.
LEGENDRE
Set this keyword to use Legendre polynomials instead of the function specied by the
FUNCTION_NAME keyword. If the LEGENDRE keyword is set, the IDL uses the
function SVDLEGfound in thelesvdleg.pro, located in thelib subdirectory of the
IDL distribution.
SIGMA
Set this keyword equal to a named variable that will contain the vector of standard
deviations for the returned coefcients.
SINGULAR
Set thiskeywordequal toanamedvariablethat will containthenumber of singular values
returned. Thisvalueshouldbe0. If not, thebasisfunctionsdonot accuratelycharacterize
the data.
VARIANCE
Set thiskeywordequal toanamedvariablethat will contain thevariance(sigmasquared)
of each coefcient M.
WEIGHTS
Set thiskeywordequal toavector of weightsfor Y
i
. Thisvector shouldbethesamelength
asX and Y. The error for each term is weighted by WEIGHTS
i
when computing the t.
Frequently, WEIGHTS
i
= 1.0/
2
i
, where is the measurement error or standard
deviation of Y
i
(Gaussian or instrumental weighting), or WEIGHTS= 1/Y (Poisson or
statistical weighting). If WEIGHTS is not specied, WEIGHTS
i
is assumed to be 1.0.
Caution You can not set any of the elements of the WEIGHTS array equal to zero.
y A i ( )x
i
i 0 =
M
=
SVDFIT IDL Reference Guide
YFIT
Set this keyword equal to a named variable that will contain the vector of calculatedY values.
Example
To t a function of the following form:
rst, create the function in IDL, then create a procedure to perform the t. Enter the
following IDL commands into a le called example_svdfit.pro:
FUNCTION myfunct, X ,M
return,[ [1.0], [SIN(2*X)/X], [COS(4.*X)^2.] ]
END
PRO example_svdfit
C = [7.77, 8.88, -9.99] Providean array of coefficients.
X = FINDGEN(100)/15.0 + 0.1
Y = C[0] + C[1] * SIN(2*X)/X + C[2] * COS(4.*X)^2.
sig = 0.05 * Y Set uncertainties to 5%
A=[1,1,1] Providean initial guess
result_a = SVDFIT(X, Y, A=A, WEIGHTS=(1/SIG^2.), $
FUNCTION_NAME='myfunct', SIGMA=SIGMA, YFIT=YFIT)
; Plot the results
PLOT, X, YFIT
FOR I = 0, N_ELEMENTS(A)-1 DO $
PRINT, I, result_a[I], SIGMA[I], C[I],$
FORMAT = '(" result_a ( ",I1," ) = ",F7.4," +- ",F7.4," VS. ",F7.4)'
END
Place the leexample_svdfit.pro in a directory in the IDL search path, and enter
example_svdfit at thecommandprompt tocreatetheplot. In addition tocreatingthe
plot, IDL prints:
result_a [ 0 ] = 7.7700 +- 0.1757 VS. 7.7700
result_a [ 1 ] = 8.8800 +- 0.1631 VS. 8.8800
result_a [ 2 ] = -9.9900 +- 0.2833 VS. -9.9900
F x ( ) A 0 ( ) A 1 ( )
2x ( )
x
----------- A 2 ( ) 4x ( ) cos
2
+ sin + =
IDL Reference Guide SVDFIT
See Also
CURVEFIT, GAUSSFIT, LMFIT, POLY_FIT, POLYFITW, REGRESS, SFIT
SVSOL IDL Reference Guide
SVSOL
The SVSOL function uses back-substitution to solve a set of simultaneous linear
equationsAx = b, given theU, W, and V arrays returned by the SVDC procedure. None
of the input arguments are modied, making it possible to call SVSOL multiple times
with different right hand vectors, B.
SVSOL is based on the routinesvbksb described in section 2.6 of Numerical Recipes in
Calling Sequence
Result = SVSOL(U, W, V, B)
Arguments
U
An n-column, m-row orthogonal array used in the decomposition of A. Normally, U is
returned from the SVDC procedure.
W
An n-element vector containing singular values. Normally, W is returned from the
SVDCprocedure. Small values(closeto machineoating-point precision) should beset
to zero prior to calling SVSOL.
V
An n-column, n-row orthogonal array used in the decomposition of A. Normally, V is
returned from the SVDC procedure.
B
An m-element vector containing the right hand side of the linear systemAx = b.
Keywords
COLUMN
Set this keyword if the input arraysU and V are in column-major format (composed of
column vectors) rather than in row-major format (composed of row vectors).
DOUBLE
IDL Reference Guide SVSOL
Example
To solve the linear systemAx = b using Singular-value decomposition and back
substitution, begin with an array A which serves as the coefcient array:
A = [[1.0, 2.0, -1.0, 2.5], $ Definethearray A.
[1.5, 3.3, -0.5, 2.0], $
[3.1, 0.7, 2.2, 0.0], $
[0.0, 0.3, -2.0, 5.3], $
[2.1, 1.0, 4.3, 2.2], $
[0.0, 5.5, 3.8, 0.2]]
B = [0.0, 1.0, 5.3, -2.0, 6.3, 3.8] Definetheright-hand sidevector
B.
SVDC, A, W, U, V DecomposeA.
PRINT, SVSOL(U, W, V, B) Computethesolution and print
theresult.
IDL prints:
1.00095 0.00881170 0.984176 -0.0100954
This is the correct solution.
See Also
CRAMER, GS_ITER, LU_COMPLEX, CHOLSOL, LUSOL, SVDC, TRISOL
SWAP_ENDIAN IDL Reference Guide
SWAP_ENDIAN
The SWAP_ENDIAN function reverses the byte ordering of arbitrary scalars, arrays or
structures. It can make bigendian number littleendian and vice-versa. Notethat the
BYTEORDER procedure can be used to reverse the byte ordering of scalars and arrays
(SWAP_ENDIAN also allows structures).
SWAP_ENDIAN returns values of the same type and structure as the input value, with
the pertinent bytes reversed.
swap_endian.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = SWAP_ENDIAN(Variable)
Arguments
Variable
The named variablescalar, array, or structureto be swapped.
Example
A = SWAP_ENDIAN(A) Reversethebyteorder of A
See Also
BYTEORDER
IDL Reference Guide SYSTIME
SYSTIME
The SYSTIME function returns the current system time as either a string that contains
thecurrent day, dateandtime, or asthenumber of secondselapsedsinceJanuary1, 1970.
Calling Sequence
Result = SYSTIME(Arg)
Arguments
Arg
If Argis present and nonzero, the number of seconds elapsed since January 1, 1970 is
returned asadouble-precision, oating-point value. Theelapsed timeiscomputed from
January 1, 1970, GMT.
Otherwise, if Argiszero, ascalar stringcontainingthecurrent local date/timein standard
24-character system format is returned. This format is:
DOW MON DD HH:MM:SS YEAR
whereDOWistheday of theweek, MON isthemonth, DDistheday of themonth, HH
is the hour, MM is the minute, SS is the second, and YEAR is the year.
Keywords
JULIAN
If theJULIAN keyword isset, SYSTIMEreturnsthetimeasaadoubleprecision oating
value containing the current Julian date.
SECONDS
If the SECONDS keyword is set, SYSTIME returns the number of seconds elapsed since
January 1 1970. This option is equivalent to setting Arg to a non-zero value.
Examples
PRINT, STRMID(SYSTIME(0), 0, 3) Print theday of theweek.
The following program fragment could be used to determine the time required by a
16,384 point FFT:
T = SYSTIME(1)
A = FFT(FINDGEN(16384), -1)
PRINT, SYSTIME(1) - T, ' Seconds'
SYSTIME IDL Reference Guide
See Also
CALDAT, CALENDAR, JULDAY
IDL Reference Guide T_CVF
T_CVF
The T_CVF function computes the cutoff valueV in a Students t distribution with Df
degreesof freedomsuch that theprobabilitythat arandomvariableXisgreater than Vis
equal to a user-supplied probability P.
T_cvf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = T_CVF(P, Df)
Arguments
P
Df
number of degrees of freedom of the Students t distribution.
Example
Usethefollowingcommandtocomputethecutoff valueinaStudentst distribution with
vedegreesof freedomsuch that theprobabilitythat arandomvariableXisgreater than
the cutoff value is 0.025. The result should be 2.57058.
result = T_CVF(0.025, 5)
PRINT, result
IDL prints:
2.57058
See Also
CHISQR_CVF, F_CVF, GAUSS_CVF, T_PDF
T_PDF IDL Reference Guide
T_PDF
The T_PDF function computes the probability P that, in a Students t distribution with
Df degreesof freedom, arandomvariableXislessthan or equal toauser-specied cutoff
valueV.
t_pdf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = T_PDF(V, Df)
Arguments
V
value.
Df
number of degrees of freedom of the Students t distribution.
Example
theStudentst distribution with 15degreesof freedom, islessthan or equal to0.691. The
result = T_PDF(0.691, 15)
PRINT, result
IDL prints:
0.749940
See Also
BINOMIAL, CHISQR_PDF, F_PDF, GAUSS_PDF, T_CVF
IDL Reference Guide T3D
T3D
The T3D procedure implements three-dimensional transforms.
This routine accumulates one or more sequences of translation, scaling, rotation,
perspective, and oblique transformations and stores the result in !P.T, the 3D
transformation system variable. All the IDL graphic routines use this (4,4) matrix for
output. Notethat !P.T3Disnotset, sofor thetransformationstohaveeffect you must set
!P.T3D = 1 (or set the T3D keyword in subsequent calls to graphics routines).
This procedure is based on that of Foley & Van Dam, Fundamentals of Interactive
Computer Graphics, Chapter 8, Viewing in Three Dimensions. The matrix notation is
reversed from the normal IDL sense, i.e., here, the rst subscript is the column, the
second is the row, in order to conform with this reference.
A right-handed system is used. Positive rotations are counterclockwise when looking
from a positive axis position towards the origin.
t3d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
T3D
Keywords
Any, all, or noneof thefollowingkeywordscan bepresent in acall to T3D. Theorder of
the input parameters does not matter.
The transformation specied by each keyword is performed in the order of their
descriptionsbelow(e.g., if both TRANSLATEand SCALEarespecied, thetranslation is
done rst).
OBLIQUE
Atwo-element vector of obliqueprojection parameters. PointsareprojectedontotheXY
plane at Z=0 as follows:
x' = x + z(d * COS(a))
y' = y + z(d * SIN(a))
where OBLIQUE[ 0] = d and OBLIQUE[ 1] = a.
PERSPECTIVE
Perspectivetransformation. Thisparameter isascalar (p) that indicatestheZ distanceof
thecenter of theprojection. ObjectsareprojectedintotheXYplaneat Z=0, andtheeye
is at point (0,0,p).
T3D IDL Reference Guide
RESET
Set this keyword to reset the transformation to the default identity matrix.
ROTATE
A three-element vector of the rotations, in DEGREES, about the X, Y, and Z axes.
Rotations are performed in the order of X, Y, and then Z.
SCALE
A three-element vector of scale factors for the X, Y, and Z axes.
TRANSLATE
A three-element vector of the translations in the X, Y, and Z directions.
XYEXCH
Set this keyword to exchange the X and Y axes.
XZEXCH
Set this keyword to exchange the X and Z axes.
YZEXCH
Set this keyword to exchange the Y and Z axes.
Examples
To reset the transformation, rotate 30 degs about the X axis and do perspective
transformation with the center of the projection at Z = -1, X=0, and Y=0, enter:
T3D, /RESET, ROT = [ 30,0,0], PERS = 1.
Transformations may be cascaded, for example:
T3D, /RESET, TRANS = [-.5,-.5,0], ROT = [0,0,45]
T3D, TRANS = [.5,.5,0]
Therst commandresets, translatesthepoint (.5,.5,0) tothecenter of theviewport, then
rotates 45 degrees counterclockwise about the Z axis. The second call to T3D moves the
origin back to the center of the viewport.
See Also
SCALE3, SCALE3D, SURFR
IDL Reference Guide TAG_NAMES
TAG_NAMES
The TAG_NAMES function returns a string array containing the names of the tags in a
structureexpression. It can also beused to determinetheexpressionsstructurename(if
the structure has a name).
Calling Sequence
Result = TAG_NAMES(Expression)
Arguments
Expression
The structure expression for which the tag names are returned. This argument must be
of structure type. TAG_NAMES does not search for tags recursively, so if Expression is a
structurecontainingnested structures, onlythenamesof tagsin theoutermost structure
are returned.
Keywords
STRUCTURE_NAME
Set thiskeyword to return ascalar stringthat containsthenameof thestructureinstead
of the names of the tags in the structure. If the structure is anonymous, a null string is
returned.
Example
Print the names of the tags in the system variable !P by entering:
PRINT, TAG_NAMES(!P)
IDL prints:
BACKGROUND CHARSIZE CHARTHICK CLIP COLOR FONT LINESTYLE MULTI
NOCLIP NOERASE NSUM POSITION PSYM REGION SUBTITLE SYMSIZE T
T3D THICK TITLE TICKLEN CHANNEL
PRINT, TAG_NAMES(!P, /STRUCTURE_NAME) Printthenameofthestructurein
thesystem variable!P.
IDL prints:
!PLT
See Also
CREATE_STRUCT, N_TAGS
TAN IDL Reference Guide
TAN
The TAN function returns the tangent of X.
Calling Sequence
Result = TAN(X)
Arguments
X
The angle for which the tangent is desired, specied in radians. If X is double-precision
oating-point, the result is of the same type. Complex values are not allowed. All other
types are converted to single-precision oating-point and yield oating-point results. If
Xisan array, theresult hasthesamestructure, with each element containingthetangent
of the corresponding element of X.
Examples
T = TAN(0.5) Find thetangent of 0.5 radians
andstoretheresultinthevariable
T.
See Also
ATAN, TANH
IDL Reference Guide TANH
TANH
The TANH function returns the hyperbolic tangent of X.
Calling Sequence
Result = TANH(X)
Arguments
X
Thevaluefor which thehyperbolictangent isdesired, specied in radians. If Xisdouble-
precision oating-point, the result is also double-precision. Complex values are not
allowed. All other types are converted to single-precision oating-point and yield
oating-point results. TANH is dened as:
hyperbolic tangent of the corresponding element of X.
Example
PRINT, TANH(1) Find thehyperbolic tangent of 1
radian and print theresult.
PLOT, TANH(FINDGEN(101)/10. - 5) Plotthehyperbolictangentfrom-
5 to +5 with an increment of 0.1.
See Also
ATAN, TAN
tanh x ( )
e
x
e
x
e
x
e
x
+
------------------- =
TAPRD IDL Reference Guide
TAPRD
The TAPRD procedure reads the next record on the selected tape unit into the specied
array. TAPRD is available only under VMS. No data or format conversion, with the
exception of optional byte reversal, is performed. The array must be dened with the
desired type and dimensions. If the read is successful, the system variable !ERR is set to
the number of bytes read. See the description of the magnetic tape routines in VMS-
Specic Information on page 217 of Building IDL Applications.
Calling Sequence
TAPRD, Array, Unit [, Byte_Reverse]
Arguments
Unit
Themagnetictapeunit to read. Thisargument must beanumber between 0and 9, and
should not be confused with standard le Logical Unit Numbers (LUNs).
Array
A named variable into which the data is read. If Array is larger than the tape record, the
extraelementsof thearray arenot changed. If thearray isshorter than thetaperecord, a
dataoverrunerror occurs. Thelengthof Arrayandtherecordsonthetapecanrangefrom
14 bytes to 65,235 bytes.
Byte_Reverse
If thisparameter ispresent, theeven and odd numbered bytesareswapped after reading,
regardless of the type of data or variables. This enables reading tapes containing short
integersthat werewritten on machineswith different byteordering. You can alsousethe
BYTORDER routine to re-order different data types.
See Also
TAPWRT
IDL Reference Guide TAPWRT
TAPWRT
TheTAPWRT procedurewritesdatafromtheArrayparameter to theselected tapeunit.
TAPWRT isavailableonlyunder VMS. Onephysical recordcontainingthesamenumber
of bytesasthearrayiswritten eachtimeTAPWRTiscalled. Theparametersandusageare
identical to those in the TAPRD procedure with the exception that here theArray
parameter can be an expression. Consult the TAPRD procedure for details. See the
description of themagnetictaperoutinesin VMS-SpecicInformation on page217of
Building IDL Applications.
Calling Sequence
TAPWRT, Array, Unit [, Byte_Reverse]
Arguments
Unit
Themagnetictapeunit to write. Thisargument must beanumber between 0and 9, and
should not be confused with standard le Logical Unit Numbers (LUNs).
Array
The expression representing the data to be output. The length of Array and the records
on the tape can range from 14 bytes to 65,235 bytes.
Byte_Reverse
If this parameter is present, the even and odd numbered bytes are swapped on output,
regardlessof thetypeof dataor variables. Thisenableswritingtapesthat arecompatible
with other machines.
See Also
TAPRD
TEK_COLOR IDL Reference Guide
TEK_COLOR
TheTEK_COLORprocedureloadsa32-color colortablesimilar to thedefault Tektronix
4115 colortable. This colortable is useful because of its distinct colors.
Bydefault, thispaletteconsistsof 32colors. Therst 9colorsare: Index0=black, 1=white,
2=red, 3=green, 4=blue, 5=cyan, 6=magenta, 8=orange.
Calling Sequence
TEK_COLOR[, Start_Index, Colors]
Arguments
Start_Index
An optional starting index for the palette. The default is 0. If this argument is included,
the colors are loaded into the current colortable starting at the specied index.
Colors
The number of colors to load. The default is 32, which is also the maximum.
See Also
LOADCT, XLOADCT
IDL Reference Guide TEMPORARY
TEMPORARY
TheTEMPORARYfunction returnsatemporary copy of avariable, and setstheoriginal
variabletoundened. Thisfunctioncanbeusedtoconservememorywhenperforming
operations on large arrays, as it avoids making a new copy of results that are only
temporary. In general, the TEMPORARY routine can be used to advantage whenever a
variable containing an array on the left hand side of an assignment statement is also
referenced on the right hand side.
Calling Sequence
Result = TEMPORARY(Variable)
Arguments
Variable
The variable to be referenced and deleted.
Example
Assume the variableA is a large array. The statement:
A = A + 1
createsanewarrayfor theresult of theaddition, placesthesumintothenewarray, assigns
it to a, and then frees the old allocation of a. Total storage required is twice the size of a.
The statement:
A = TEMPORARY(A) + 1
requires no additional space.
See Also
DELVAR
THIN IDL Reference Guide
THIN
The THIN function returns the skeleton of a bi-level image. The skeleton of an object
in an image is a set of lines that reect the shape of the object. The set of skeletal pixels
can be considered to be the medial axis of the object. For a much more extensive
discussion of skeletons and thinning algorithms, seeAlgorithms for Graphics and Image
Processing, Theo Pavlidis, Computer Science Press, 1982. The THIN function is adapted
from Algorithm 9.1 (the classical thinning algorithm).
Oninput, thebi-level imageisarectangular arrayinwhichpixelsthat composetheobject
have a nonzero value. All other pixels are zero. The result is a byte type image in which
skeletal pixels are set to 2 and all other pixels are zero.
Calling Sequence
Result = THIN(Image)
Arguments
Image
The two-dimensional image (array) to be thinned.
Example
The following commands display the thinned edges of a Sobel ltered image:
Open a filefor reading.
A = BYTARR(192, 192) Createa bytearray in which to
storetheimage.
READU, 1, A Read first 192 by 192 image.
TV, A, 0 Display theimage.
TVSCL, THIN(SOBEL(A) GT 75), 1 ApplytheSobelfilter,thresholdthe
imageatvalue75,anddisplaythe
thinned edges.
See Also
ROBERTS, SOBEL
IDL Reference Guide THREED
THREED
TheTHREEDprocedureplotsa2Darrayasapseudo3Dplot. Theorientationof thedata
is xed.
threed.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
THREED, A [, Sp]
Arguments
A
The two-dimensional array to plot.
Sp
The spacing between plot lines. If Sp is omitted, the spacing is set to: (MAX(A)-
MIN(A))/ROWS. If Sp is negative, hidden lines are not removed.
Keywords
TITLE
Set this keyword to the main plot title.
XTITLE
Set this keyword to the X axis title.
YTITLE
Set this keyword to the Y axis title.
Example
A = -SHIFT(DIST(30), 15, 15) Createa 2D dataset.
THREED, A Makea THREED plot.
SURFACE, A Compareto SURFACE.
See Also
SURFACE
TIME_TEST2 IDL Reference Guide
TIME_TEST2
The TIME_TEST2 procedure is a general-purpose IDL benchmark program that
performs approximately 20 common operations and prints the time required.
time_test.pro in thelib subdirectory of theIDL distribution. Thislealso contains
the procedure GRAPHICS_TIMES, used to time graphical operations.
Calling Sequence
TIME_TEST2[, Filename]
Arguments
Filename
An optional string that contains the name of output le for the results of the time test.
Example
TIME_TEST2 Run thecomputational tests.
GRAPHICS_TIMES Run thegraphics tests. Notethat
TIME_TEST2 must becompiled
beforeGRAPHICS_TIMES will
run.
See Also
SYSTIME
IDL Reference Guide TM_TEST
TM_TEST
The TM_TEST function computes the Students T-statistic and the probability that two
sample populationsX and Y have signicantly different means. X and Y may be of
different lengths. The result is a two-element vector containing the T-statistic and its
signicance. The signicance is a value in the interval [ 0.0, 1.0] ; a small value (0.05 or
0.01) indicatesthat XandYhavesignicantlydifferent means. Thedefault assumption is
that the data is drawn from populations with the same true variance. This type of test is
often referred to as the t-means test.
The T-statistic for sample populationsx and y with meansx andyis dened as:
wherex = (x
0
, x
1
, x
2
, ..., x
N-1
) and y = (y
0
, y
1
, y
2
..., y
M-1
)
tm_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TM_TEST(X, Y)
Arguments
X
Y
An m-element integer, single-, or double-precision oating-point vector. If thePAIRED
keyword is set, X and Y must have the same number of elements.
Keywords
PAIRED
If thiskeyword isset, Xand Yareassumed to bepaired samplesand must havethesame
number of elements.
T
x y
x
i
x ( )
2
y
i
y ( )
2
j 0 =
M 1
+
j 0 =
N 1
N M 2 + ( )
----------------------------------------------------------------------
1
N
----
1
M
----- +
,
_
-------------------------------------------------------------------------------------------------- =
TM_TEST IDL Reference Guide
UNEQUAL
If this keyword is set, X and Y are assumed to be from populations with unequal
variances.
Example
X = [257, 208, 296, 324, 240, 246, 267, 311, 324, 323, 263, $
305, 270, 260, 251, 275, 288, 242, 304, 267]
Y = [201, 56, 185, 221, 165, 161, 182, 239, 278, 243, 197, $
271, 214, 216, 175, 192, 208, 150, 281, 196]
Compute the Students t-statistic and its signicance assuming that X and Y belong to
populations with the same true variance.
PRINT, TM_TEST(X, Y)
IDL prints:
5.52839 2.52455e-06
The result indicates that X and Y have signicantly different means.
See Also
FV_TEST, KW_TEST, RS_TEST, S_TEST
IDL Reference Guide TOTAL
TOTAL
The TOTAL function returns the sum of the elements of Array. The sum of the array
elements over a given dimension is returned if theDimension argument is present.
Calling Sequence
Result = TOTAL(Array [, Dimension])
Arguments
Array
The array to be summed. This array can be of any basic type except string. If Array is
double-precision oating-point, complex, or double-precision complex, the result is of
the same type. Otherwise, the result is single-precision oating-point.
Dimension
Thedimension over whichtosum, startingat one. If thisargument isnot present or zero,
thescalar sumof all thearray elementsisreturned. If thisargument ispresent, theresult
is an array with one less dimension than Array. For example, if the dimensions of Array
areN
1
, N
2
, N
3
, andDimensionis2, thedimensionsof theresult are(N
1
, N
3
), andelement
(i,j) of the result contains the sum:
Keywords
DOUBLE
Set this keyword to perform the summation in double-precision oating-point.
NAN
Example
Sum the elements of the array [ 20, 10, 5, 5, 3] and print the result by entering:
PRINT, TOTAL([20, 10, 5, 5, 3])
A
i k j , ,
k 0 =
N
2
1

TOTAL IDL Reference Guide
IDL prints:
43.0000
When a multi-dimensional array is used, the results are different, as shown in the
followingexample. Createave-element by ve-element array lled with oating-point
values by entering:
A = FINDGEN(5,5)
Display the sums of each of the rows in A by entering:
PRINT, TOTAL(A, 1)
IDL prints:
10.0000 35.0000 60.0000 85.0000 110.000
Display the sums of each of the columns in A by entering:
PRINT, TOTAL(A, 2)
IDL prints:
50.0000 55.0000 60.0000 65.0000 70.0000
See Also
FACTORIAL
IDL Reference Guide TRACE
TRACE
The TRACE function computes the trace of an n by n array.
trace.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TRACE(A)
Arguments
A
An n by n real or complex array.
Keywords
DOUBLE
Example
Dene an array.
A = [[ 2.0,1.0, 1.0, 1.5], $
[ 4.0, -6.0, 0.0, 0.0], $
[-2.0, 7.0, 2.0, 2.5], $
[ 1.0, 0.5, 0.0, 5.0]]
result = TRACE(A) Computethetraceof A.
PRINT, result Print Result.
IDL prints:
3.00000
See Also
TOTAL
TRANSPOSE IDL Reference Guide
TRANSPOSE
The TRANSPOSE function returns the transpose of Array. If an optional permutation
vector is provided, the dimensions of Array are rearranged as well.
Calling Sequence
Result = TRANSPOSE(Array [, P])
Arguments
Array
The array to be transposed.
P
A vector specifying how the dimensions of Array will be permuted. The elements of P
correspond to the dimensions of Array; theith dimension of the output array is
dimension P[ i] of the input array. Each element of the vector P must be unique.
Dimensions start at zero and can not be repeated.
If P is not present, the order of the indices of Array is reversed.
Example
Print a simple array and its transpose by entering:
PRINT, INDGEN(3,3)
PRINT, TRANSPOSE(INDGEN(3,3))
IDL prints the original array:
0 1 2
3 4 5
6 7 8
and its transpose:
0 3 6
1 4 7
2 5 8
To see how a multi-dimensional transposition works, rst create a three-dimensional
array A:
A = INDGEN(2, 3, 4)
Take the transpose, reversing the order of the indices:
IDL Reference Guide TRANSPOSE
B = TRANSPOSE(A)
Now re-order the dimensions of A, so that the second dimension becomes the rst, the
third becomes the second, and the rst becomes the third:
C = TRANSPOSE(A, [1, 2, 0])
Now view the sizes of the three arrays:
HELP, A, B, C
IDL prints:
A INT = Array[2, 3, 4] Theoriginal array.
B INT = Array[4, 3, 2] Original array with indices re-
versed.
C INT = Array[3, 4, 2] Original array with indices re-or-
dered.
See Also
REFORM, ROT, ROTATE, REVERSE
TRI_SURF IDL Reference Guide
TRI_SURF
The TRI_SURF function interpolates a regularly- or irregularly-gridded set of points
with a smooth quintic surface. The result is s a two-dimensional oating-point array
containing the interpolated surface, sampled at the grid points.
TRI_SURF is similar to MIN_CURVE_SURF but the surface tted is a smooth surface,
not a minimum curvature surface. TRI_SURF has the advantage of being much more
efcient for larger numbers of points.
Note TheTRI_SURFfunction isdesigned to interpolatelowresolution data. Largearrays
may cause TRI_SURF to issue the following error message:
Partial Derivative Approximation Failed to Converge
In such cases, interpolation is most likely unnecessary.
tri_surf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TRI_SURF(Z [, X, Y])
Arguments
X, Y, Z
arrays containing the X, Y, and Z coordinates of the data points on the surface. Points
Keywords
EXTRAPOLATE
Set this keyword to cause TRI_SURF to extrapolate the surface to points outside the
convex hull of input points. This keyword has no effect if the input points are regularly
gridded.
LINEAR
Set thiskeywordtouselinear interpolation, without gradient estimates, insteadof quintic
interpolation. Linear interpolation does not extrapolate, although it is faster and more
numerically stable.
IDL Reference Guide TRI_SURF
MISSING
Set thiskeywordequal tothevaluetowhichpointsoutsidetheconvexhull of input points
shouldbeset. Thedefault is0. Thiskeywordhasnoeffect if theinput pointsareregularly
gridded.
Input grid description:
REGULAR
If set, theZ parameter is a two-dimensional array of dimensions (n,m), containing
XGRID
XVALUES
XVALUES.
YGRID
YVALUES
An n-element array dening theylocations of Z[ i,j] . Do not specify both YGRID and
YVALUES.
Output grid description:
Note The output grid must enclose the convex hull of the input points.
GS
thedefault horizontal spacingis(xmax- xmin)/(NX-1). YSiscomputedin thesameway.
BOUNDS
TRI_SURF IDL Reference Guide
NX
NY
Examples
Example 1: Irregularly gridded cases
N = 15 Number of random points
Z = EXP(-2 * ((X-.5)^2 + (Y-.5)^2)) TheGaussian
Use a 26 by 26 grid over the rectangle bounding x and y:
R = TRI_SURF(Z, X, Y) Get thesurface
R = TRI_SURF(z, x, y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
Alternatively, get a 10 by 10 surface over the rectangle bounding x and y:
R = TRI_SURF(z, x, y, NX=10, NY=10)
Example 2: Regularly gridded cases
z = randomu(seed, 5, 6) Makesomerandom data
CONTOUR, TRI_SURF(z, /REGULAR) Interpolateto a 26 x 26 grid
See Also
CONTOUR, MIN_CURVE_SURF
IDL Reference Guide TRIANGULATE
TRIANGULATE
The TRIANGULATE procedure constructs a Delaunay triangulation of a planar set of
points. Delaunay triangulationsarevery useful for theinterpolation, analysis, and visual
display of irregularly-gridded data. In most applications, after the irregularly gridded
data points have been triangulated, the function TRIGRID is invoked to interpolate
surface values to a regular grid.
Since Delaunay triangulations have the property that the circumcircle of any triangle in
the triangulation contains no other vertices in its interior, interpolated values are only
computed from nearby points.
TRIANGULATE can, optionally, return the adjacency list that describes, for each node,
theadjacent nodesintheDelaunaytriangulation. Withthislist, theVoronoi polygon(the
polygon described by the set of points which are closer to that node than to any other
node) can be computed for each node. This polygon contains the area inuenced by its
associated node. Tiling of the region in this manner is also called Dirichlet, Wigner-
Seithz, or Thiessen tessellation.
The grid returned by the TRIGRID function can be input to various routines such as
SURFACE, TV, and CONTOUR. See the description of TRIGRID for an example.
TRIANGULATEandTRIDGRIDcan alsobeusedtoperformgriddingandinterpolation
over thesurfaceof asphere. Theinterpolation isC
1
continuous, meaningthat theresult
iscontinuousover both thefunction valueand itsrst derivative. Thisfeatureisideal for
interpolatingan irregularly-sampleddataset over part or all of thesurfaceof theearth(or
other (spherical) celestial bodies). Extrapolationoutsidetheconvexhull of samplepoints
is also supported. To perform spherical gridding, you must include the FVALUE and
SPHERE keywords described below. The spherical gridding technique used in IDL is
based on the paper Interpolation of Data on the Surface of a Sphere, R. Renka, Oak
RidgeNational Laboratory Report ORNL/CSD-108, 1982.
Calling Sequence
TRIANGULATE, X, Y, Triangles [, B]
Arguments
X
An array that contains the X coordinates of the points to be triangulated.
Y
An array that contains the Y coordinates of the points to be triangulated. ParametersX
and Y must have the same number of elements.
TRIANGULATE IDL Reference Guide
Triangles
Anamedvariablethat, on exit, containsthelist of trianglesin theDelaunaytriangulation
of thepointsspeciedbyXandY. Trianglesisalongwordarraydimensioned(3, Number-
of-Triangles), whereTriangles[0, i], Triangles[1, i], andTriangles[2, i]
contain the indices of the vertices of thei-th triangle (i.e., X[Tr[*, i]] and
Y[Triangles[*, i]] are the X and Y coordinates of the vertices of thei-th triangle).
B
An optional, named variable that, upon return, contains a list of the indices of the
boundary points in counterclockwise order.
Keywords
CONNECTIVITY
Set thiskeyword to anamed variablein which theadjacency list for each of theNnodes
(xy point) is returned. The list has the following form:
Each element i, i 0 < N, contains the starting index of the connectivity list for nodei
within thelist array. Toobtain theadjacency list for nodei, extract thelist elementsfrom
LIST[ i] to LIST[ i+1] -1.
Theadjacency list isordered in thecounter-clockwisedirection. Therst itemon thelist
of boundary nodesisthesubscript of thenodeitself. For interior nodes, thelist contains
the subscripts of the adjacent nodes in counter-clockwise order.
For example, the call:
TRIANGULATE, X, Y, CONNECTIVITY = LIST
returnstheadjacencylist inthevariableLIST. Thesubscriptsof thenodesadjacent toX[ i]
and Y[ i] are contained in the array:
LIST[LIST[i] : LIST[i+1]-1]
DEGREES
Set this keyword to indicate that theX and Y arguments contain longitude and latitude
coordinatesspecied in degrees. Thiskeyword isonlyeffectiveif theSPHEREkeyword is
also set. If DEGREES is not set, X and Y are assumed to be specied in radians when a
spherical triangulation is performed.
FVALUE
Set this keyword to a named variable that contains sample values for each
longitude/latitudepoint inaspherical triangulation. Onoutput, theelementsof FVALUE
arerearrangedtocorrespondtotheneworderingof XandY(asdescribedintheSPHERE
keyword, below). This reordered array can be passed to TRIGRID to complete the
interpolation.
IDL Reference Guide TRIANGULATE
REPEATS
Set this keyword to a named variable to return a (2, n) list of the indices of duplicated
points. That is, for each i,
X[REPEATS(0,i)] = X[REPEATS(1,i)]
and
Y[REPEATS(0,i)) = Y(REPEATS(1,i)]
SPHERE
Set this keyword to a named variable in which the results from a spherical triangulation
are returned. This result is a structure that can be passed to TRIGRID to perform
spherical gridding. Thestructurecontainsthe3D Cartesian locationssamplepointsand
the adjacency list that describes the triangulation.
When spherical triangulation is performed, X and Y are interpreted as longitude and
latitude, in either degrees or radians (see the DEGREE keyword, above). Also, the order
of the elements within theX and Y parameters is rearranged (see the FVALUE keyword,
above).
Example
For a examples using the TRIANGULATE routine, see the TRIGRID function.
See Also
SPH_SCAT, TRIGRID
TRIGRID IDL Reference Guide
TRIGRID
Given datapointsdened bytheparametersX, Y, andZand atriangulation of theplanar
set of points determined by X and Y, the TRIGRID function returns a regular grid of
interpolatedZvalues. Linear or smoothquinticpolynomial interpolationcanbeselected.
Extrapolation for gridpoints outside of the triangulation area is also an option. The
resulting grid is a two-dimensional array of the same data type asZ, with user-specied
bounds and spacing. An input triangulation can be constructed using the procedure
TRIANGULATE. Together, the TRIANGULATE procedure and the TRIGRID function
constituteIDLssolution to theproblemof irregularly-gridded data, includingspherical
gridding.
Calling Sequence
Result = TRIGRID(X, Y, Z, Triangles [, GS, Limits])
or, for spherical gridding:
Result = TRIGRID(F , GS, Limits, SPHERE=S)
Arguments
X, Y, Z
Input arraysof X, Y, andZcoordinatesof datapoints. Integer, long, double-precision and
oating-point valuesareallowed. In addition, Zcan beacomplex array. All threearrays
must have the same number of elements.
F
When performingaspherical gridding, thisargument should bethenamed variablethat
containstherearranged samplevaluesthat werereturned by TRIANGULATEsFVALUE
keyword.
Triangles
A longword array of the form output by TRIANGULATE. That is, Triangleshas the
dimensions (3, Number-of-Triangles) and, for each i, Triangles[0,i],
Triangles[1,i], and Triangles[2,i] are the indices of the vertices of thei-th
triangle.
GS
If present, GSshouldbeatwo-element vector [ XS,YS] , whereXSisthehorizontal spacing
between grid pointsand YSisthevertical spacing. Thedefault isbased on theextentsof
X and Y. If the grid starts at X valuex
0
and ends at x
1
,then the horizontal spacing is
(x
1
- x
0
)/50
IDL Reference Guide TRIGRID
The default for YS is computed in the same way. Since the default grid spacing divides
each axis into 50 intervals and produces 51 samples, TRIGRID returns a grid with
dimensions (51, 51).
If theNXor NYkeywordsareset tospecifytheoutput grid dimensions, either or both of
thevaluesof GSmaybeset to0. Inthiscase, thegridspacingiscomputedastherespective
range divided by the dimension minus one:
(x
1
- x
0
)/(NX-1) and (y
1
- y
0
)/(NY-1)
For spherical gridding, GS is assumed to be specied in radians, unless the DEGREES
keyword is set.
Limits
If present, Limitsshould be a four-element vector [ x
0
, y
0
, x
1
, y
1
] that species the data
range to be gridded (x
0
and y
0
are the lower X and Y data limits, and x
1
and y
1
are the
upper limits). The default for Limitsis:
[MIN(X), MIN(Y), MAX(X), MAX(Y)]
If the NX or NY keywords are not specied, the size of the grid produced is specied by
the value of Limits. If the NX or NY keywords are set to specify the output grid
dimensions, a grid of the specied size will be used regardless of the value of Limits.
Keywords
DEGREES
For a spherical gridding, set this keyword to indicate that the grid spacing (theGS
argument) is specied in degrees rather than radians.
EXTRAPOLATE
Set thiskeyword equal toan arrayof boundarynodeindices(asreturned bytheoptional
parameter Bof theTRIANGULATEprocedure) to extrapolateto grid pointsoutsidethe
triangulation. Theextrapolationisnot smooth, but shouldgiveacceptableresultsinmost
cases.
Settingthiskeywordsetsthequinticinterpolation mode, asif theQUINTICkeywordhas
been specied.
INPUT
Set this keyword to a named variable (which must be an array of the appropriate size to
hold the output from TRIGRID) in which the results of the gridding are returned. This
keyword is provided to make it easy and memory-efcient to perform multiple calls to
TRIGRID. The interpolates within each triangle overwrite the array and the array is not
initialized.
MAX_VALUE
Set this keyword to a value that represents the maximumZ value to be gridded. Data
larger than this value are treated as missing data and are not gridded.
MIN_VALUE
Set this keyword to a value that represents the minimumZ value to be gridded. Data
smaller than this value are treated as missing data and are not gridded.
MISSING
TheZ value to be used for grid points that lie outside the triangles in Triangles. The
default is 0. This keyword also applies to data points outside the range specied by
MIN_VALUE and MAX_VALUE.
Note Letting MISSING default to 0 does not always produce the same result as explicitly
setting it to 0. For example, if you specify INPUT and not EXTRAPOLATE, letting
MISSINGdefault to0will result in theINPUTvaluesbeingusedfor dataoutsidethe
Traingles; explicitly setting MISSSING to 0 will result in 0 being used for the data
outside the Triangles.
NX
The output grid size in thex direction. The default value is 51.
NY
The output grid size in theydirection. The default value is 51.
QUINTIC
If QUINTICisset, smoothinterpolationisperformedusingAkimasquinticpolynomials
from A Method of Bivariate Interpolation and Smooth Surface Fitting for Irregularly
DistributedDataPoints inACMTransactionsonMathematical Software, 4, 148-159. The
default method is linear interpolation.
Derivatives are estimated by Renkas global method in A Triangle-Based C1
Interpolation Method in Rocky Mountain Journal of Mathematics, vol. 14, no. 1, 1984.
QUINTICisnot availablefor complex datavalues. SettingtheEXTRAPOLATEkeyword
implies the use of quintic interpolation; it is not necessary to specify both.
SPHERE
For aspherical gridding, set thiskeyword to thenamed variablethat containstheresults
of the spherical triangulation returned by TRIANGULATEs SPHERE keyword.
XGRID
Set this keyword equal to a named variable that will contain a vector of X values for the
output grid.
YGRID
Set this keyword equal to a named variable that will contain a vector of Y values for the
output grid.
Note The following table shows the interrelationships between the keywords EXATRAP-
OLATE, INPUT, MAX_VALUE, MIN_VALUE, MISSING, and QUINTIC.
Example
The rst example creates and displays a 50 point random normal distribution. The
random points are then triangulated, with the triangulation displayed. Next, the
interpolated surface is computed and displayed using linear and quintic interpolation.
Finally, the smooth extrapolated surface is generated and shown.
x = RANDOMN(seed, 50) Make50 normal x, y points.
y = RANDOMN(seed, 50)
z = EXP(-(x^2 + y^2)) MaketheGaussian.
PLOT, x, y, psym=1 Show points.
TRIANGULATE, x, y, tr, b Obtain triangulation.
FOR i=0, N_ELEMENTS(tr)/3-1 DO BEGIN & $Show thetriangles.
t = [tr[*,i], tr[0,i]] & $ Subscripts of vertices [0,1,2,0].
PLOTS, x[t], y[t] & $ Connect triangles.
ENDFOR
SURFACE, TRIGRID(x, y, z, tr) Show linear surface.
SURFACE, TRIGRID(x, y, z, tr, /QUINTIC) Show smooth quintic surface.
SURFACE, TRIGRID(x, y, z, tr, EXTRA = b)Show smooth extrapolated sur-
face.
SURFACE, TRIGRID(X, Y, Z, Tr, NX=12, NY=24)
Output grid sizeis 12 x 24.
SURFACE, TRIGRID(X, Y, Z, Tr, $
INPUT EXTRAPOLATE MISSING
Not in
Triangles
Beyond
(MIN,MAX)
_VALUE
no no no uses 0 uses 0
no no yes uses MISSING uses MISSING
no yes no EXTRAPOLATEs uses 0
no yes yes EXTRAPOLATEs uses MISSING
yes no no uses INPUT uses INPUT
yes no yes uses MISSING uses MISSING
yes yes no EXTRAPOLATEs uses INPUT
yes yes yes EXTRAPOLATEs uses MISSING
Table 1: Keyword Interrelationships for the TRIGRID function
[.1, .1], NX=20) Outputgridsizeis20x11.TheX
gridis[0, .1,.2,...,19*.1=1.9].
TheY grid goes from 0 to 1.
SURFACE, TRIGRID(X, Y, Z, Tr, $
[0,0], [0,0,5,4],NX=20, NY=40) Outputsizeis20x40. Therange
of thegrid in X and Y is specified
by theLimits parameter. Grid
spacingin X is [5-0]/(20-1) =
0.263. Grid spacingin Y is (4-
0)/(40-1) =0.128.
The next example shows how to perform spherical gridding:
lon = RANDOMU(seed, 50) * 360. - 180. Createsomerandom longitude
points.
lat = RANDOMU(seed, 50) * 180. - 90. Createsomerandom latitude
points.
f = SIN(lon * !DTOR)^2 * $
COS(lat * !DTOR) Makea fakefunction valueto be
passed to FVALUE. Thesystem
variable!DTORcontainsthecon-
version valuefor degrees to radi-
ans.
TRIANGULATE, lon, lat, tr, $
SPHERE=s, FVALUE=f, /DEGREES Performaspherical triangulation.
r=TRIGRID(f, SPHERE=s, [2.,2.],$
[-180.,-90.,178.,90.], /DEGREES) Performaspherical triangulation
usingthevalues returned from
TRIANGULATE. Theresult, r, is
a 180 by 91 element array.
The next example shows the use of the INPUT keyword:
x = RANDOMN(seed, 50) Make50 normal x, y points.
y = RANDOMN(seed, 50)
z = EXP(-(x^2 + y^2)) MaketheGaussian.
PLOT, x, y, psym=1 Show points.
TRIANGULATE, x, y, tr, b Obtain triangulation.
FOR i=0, N_ELEMENTS(tr)/3-1 DO BEGIN $ Show thetriangles.
t = [tr[*,i], tr[0,i]] & $ Subscripts of vertices [0,1,2,0].
PLOTS, x[t], y[t] Connect triangles.
ENDFOR
xtemp=fltarr(51,51) Thedefaultsizeforthereturnval-
ueoftrigrid. xtempshouldbethe
sametypeas Z. xtemp provides
temporary spacefor trigrid.
xtemp = TRIGRID(x, y, z, INPUT = xtemp, tr)
surface, xtemp Show linear surface.
in=
read,"Press enter",in
xtemp = TRIGRID(x, y, z, tr, INPUT = xtemp, /QUINTIC)
surface,xtempShow smooth quintic surface.
in=
xtemp = TRIGRID(x, y, z, tr, INPUT = xtemp, EXTRA = b)
surface,xtemp Show smooth extrapolated sur-
face.
in=
end
See Also
SPH_SCAT, TRIANGULATE
TRIQL IDL Reference Guide
TRIQL
The TRIQL procedure uses the QL algorithm with implicit shifts to determine the
eigenvaluesandeigenvectorsof areal, symmetric, tridiagonal array. TheroutineTRIRED
can beusedtoreduceareal, symmetricarraytothetridiagonal formsuitablefor input to
this procedure.
TRIQL isbased on theroutinetqli described in section 11.3of Numerical RecipesinC:
Calling Sequence
TRIQL, D, E, A
Arguments
D
On input, thisargument shouldbeann-element vector containingthediagonal elements
of the array being analyzed. On output, D contains the eigenvalues.
E
An n-element vector containingtheoff-diagonal elementsof thearray. E
0
isarbitrary. On
output, this parameter is destroyed.
A
A named variable that returns then eigenvectors.
If the eigenvectors of a tridiagonal array are desired, Ashould be input as an identity
array. If the eigenvectors of an array that has been reduced by TRIRED are desired, Ais
input as the array Q output by TRIRED.
Keywords
DOUBLE
Example
To compute eigenvalues and eigenvectors of a real, symmetric, tridiagonal array, begin
with an array A representing a symmetric array.
A = [[ 3.0, 1.0, -4.0], $
[ 1.0, 3.0, -4.0], $
IDL Reference Guide TRIQL
[-4.0, -4.0, 8.0]]
TRIRED, A, D, E Computethetridiagonal form of
A.
Compute the eigenvalues (returned in vector D) and the eigenvectors (returned in the
rows of the array A):
TRIQL, D, E, A
PRINT, D Print eigenvalues.
IDL prints:
2.00000 4.76837e-7 12.0000
The exact values are:
[2.0, 0.0, 12.0]
PRINT, A Print eigenvectors.
IDL prints:
0.707107 -0.707107 0.00000
-0.577350 -0.577350 -0.577350
-0.408248 -0.408248 0.816497
The exact eigenvectors are:
[ 1.0/sqrt(2.0), -1.0/sqrt(2.0), 0.0/sqrt(2.0)],
[-1.0/sqrt(3.0), -1.0/sqrt(3.0), -1.0/sqrt(3.0)],
[-1.0/sqrt(6.0), -1.0/sqrt(6.0), 2.0/sqrt(6.0)
See Also
EIGENVEC, ELMHES, HQR, TRIRED
TRIRED IDL Reference Guide
TRIRED
TheTRIREDprocedureusesHouseholdersmethod to reduceareal, symmetricarray to
tridiagonal form.
TRIREDisbased on theroutinetred2 described in section 11.2of Numerical Recipesin
Calling Sequence
TRIRED, A, D, E
Arguments
A
An n by n real, symmetric array that is replaced, on exit, by the orthogonal array Q
effecting the transformation. The routine TRIQL can use this result to nd the
eigenvectors of the array A.
D
An n-element output vector containing the diagonal elements of the tridiagonal array.
E
An n-element output vector containing the off-diagonal elements.
Keywords
DOUBLE
Example
See the description of TRIQL for an example using this function.
See Also
EIGENVEC, ELMHES, HQR, TRIQL, TRIRED
IDL Reference Guide TRISOL
TRISOL
The TRISOL function solves tridiagonal systems of linear equations that have the form:
A
T
U = R
Note: becauseIDLsubscriptsareincolumn-roworder, theequationaboveiswrittenA
T
U
= R rather than AU = R. The result U is a vector of length n whose type is identical to A.
TRISOL isbased on theroutinetridag described in section 2.4of Numerical Recipesin
Calling Sequence
Result = TRISOL(A, B, C, R)
Arguments
A
Avector of length ncontainingthen-1sub-diagonal elementsof A
T
. Therst element of
A, A
0
, is ignored.
B
An n-element vector containing the main diagonal elements of A
T
.
C
An n-element vector containingthen-1super-diagonal elementsof A
T
. Thelast element
of C, C
n-1
, is ignored.
R
An n-element vector containing the right hand side of the linear system
A
T
U = R.
Keywords
DOUBLE
Example
Tosolveatridiagonal linear system, begin with an arrayrepresentingareal tridiagonal linear system. (Note
that only three vectors need be specied; there is no need to enter the entire array shown.)
TRISOL IDL Reference Guide
Dene a vector A containing the sub-diagonal elements with a leading 0.0 element:
A = [0.0, 2.0, 2.0, 2.0]
Dene B containing the main diagonal elements:
B = [-4.0, -4.0, -4.0, -4.0]
Dene C containing the super-diagonal elements with a trailing 0.0 element:
C = [1.0, 1.0, 1.0, 0.0]
Dene the right-hand side vector:
R = [6.0, -8.0, -5.0, 8.0]
Compute the solution and print:
result = TRISOL(A, B, C, R)
PRINT, result
IDL prints:
-1.00000 2.00000 2.00000 -1.00000
The exact solution vector is [ -1.0, 2.0, 2.0, -1.0] .
See Also
CRAMER, GS_ITER, LU_COMPLEX, CHOLSOL, LUSOL, SVSOL, TRISOL
4.0 1.0 0.0 0.0
2.0 4.0 1.0 0.0
0.0 2.0 4.0 1.0
0.0 0.0 2.0 4.0
IDL Reference Guide TRNLOG
TRNLOG
TheTRNLOGfunction searchestheVMSlogical nametablesfor aspeciedlogical name
andreturnstheequivalencestring(s) inanIDLvariable. TRNLOGisavailableonlyunder
VMS. TRNLOG also returns the VMS status code associated with the translation as a
longword value. Aswith all VMSstatuscodes, successisindicated by an odd value(least
signicant bit is set) and failure by an even value.
Calling Sequence
Result = TRNLOG(Lognam, Value)
Arguments
Lognam
A scalar string containing the name of the logical to be translated.
Value
A named variable into which the equivalence string is placed. If Lognam has more than
oneequivalencestring, therst oneisused. TheFULL_TRANSLATION keyword can be
used to obtain all equivalence strings.
Keywords
ACMODE
The access mode to be used in the translation. The possible access modes are:
When you specify theACMODEkeyword, all namesat accessmodeslessprivileged than
thespeciedmodeareignored. If you donot specifyACMODE, thetranslation proceeds
without regard toaccessmode. However, thesearch proceedsfromtheoutermost (User)
to the innermost (Kernal) mode. Thus, if two logical names with the same name but
different accessmodesexist in thesametable, thenamewith theoutermost accessmode
is used.
Mode Value
Kernal 0
Executive 1
Supervisor 2
User 3
Table 9-69: TRNLOG Access Modes
TRNLOG IDL Reference Guide
FULL_TRANSLATION
Set thiskeywordtoobtain thefull set of equivalencestringsfor Lognam. Bydefault, when
translatingamultivalued logical name, Valueonly receivestherst equivalencestringas
ascalar value. Whenthiskeywordisset, Valueinsteadreturnsastringarray. Eachelement
of thisarray containsoneof theequivalencestrings. For example, under recent versions
of VMS, the SYS$SYSROOT logical can have multiple values. To see these values from
within IDL, enter:
ret = TRNLOG('SYS$SYSROOT', trans, /FULL, /ISSUE_ERROR)
Translatethelogical.
PRINT, trans View theequivalencestrings.
ISSUE_ERROR
Set this keyword to issue an error message if the translation fails. Normally, no error is
issued and the user must examine the return value to determine if the operation failed.
RESULT_ACMODE
If present, this keyword species a named variable in which to place the access mode of
the translated logical. The access modes are summarized above.
RESULT_TABLE
If present, this keyword species a named variable. The name of the logical table
containing the translated logical is placed in this variable as a scalar string.
TABLE
A scalar string giving the name of the logical table in which to search for Lognam. If
TABLE is not specied, the standard VMS logical tables are searched until a match is
found, starting with LNM$PROCESS_TABLE and ending with LNM$SYSTEM_TABLE.
See Also
GETENV
IDL Reference Guide TS_COEF
TS_COEF
The TS_COEF function computes the coefcients
1
,
2
, ... ,
P
used in aP
th
order
autoregressivetime-seriesforecastingmodel. Theresult isaP-element vector whosetype
is identical to X.
ts_coef.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TS_COEF(X, P)
Arguments
X
An n-element single- or double-precision oating-point vector containing time-series
samples.
P
An integer or longinteger scalar that speciesthenumber of coefcientstobecomputed.
Keywords
MSE
Use this keyword to specify a named variable that will contain the mean square error of
theP
th
order autoregressive model.
Example
Dene an n-element vector of time-series samples.
X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99, $
5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31, $
5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76]
result = TS_COEF(X, 5) Computethecoefficients of a 5th
order autoregressivemodel.
PRINT, result
IDL prints:
1.30168 -0.111783 -0.224527 0.267629 -0.233363
See Also
TS_FCAST
TS_DIFF IDL Reference Guide
TS_DIFF
The TS_DIFF function recursively computes the forward differences of an n-element
time-seriesk times. The result is an n-element differenced time-series with its last k
elements as zeros.
ts_diff.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TS_DIFF(X, K)
Arguments
X
An n-element integer, single- or double-precision oating-point vector containingtime-
series samples.
K
A positive integer or long integer scalar that species the number of timesX is to be
differenced. K must be in the interval [ 1, N_ELEMENTS(X) - 1] .
Keywords
DOUBLE
Example
Dene an n-element vector of time-series samples:
X = [389, 345, 303, 362, 412, 356, 325, 375, $
410, 350, 310, 388, 399, 362, 325, 382, $
399, 382, 318, 385, 437, 357, 310, 391]
PRINT, TS_DIFF(X, 2) Computethesecond forward dif-
ferences of X.
IDL prints:
2 101 -9 -106 25 81 -15 -95 20
118 -67 -48 0 94 -40 -34 -47 131
-15 -132 33 128 0 0
See Also
SMOOTH, TS_FCAST
IDL Reference Guide TS_FCAST
TS_FCAST
TheTS_FCAST function computesfutureor past valuesof astationarytime-seriesusing
aP
th
order autoregressive model. The result is an Nvalues-element vector whose type is
identical to X.
A P
th
order autoregressive model relates a forecasted valuex
t
of the time seriesX= [ x
0
,
x
1
, x
2
, ... , x
t-1
] , as a linear combination of P past values.
The coefcients
1
,
2
, ... ,
P
are calculated such that they minimize the uncorrelated
random error terms, wt.
ts_fcast.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TS_FCAST(X, P, Nvalues)
Arguments
X
samples.
P
An integer or longinteger scalar that speciesthenumber of actual time-seriesvaluesto
be used in the forecast. In general, a larger number of values results in a more accurate
forecast.
Nvalues
An integer or long integer scalar that species the number of future or past values to be
computed.
Keywords
BACKCAST
Set this keyword to produce past values (backward forecasts or backcasts )
DOUBLE
x
t

1
x
t 1

2
x
t 2

P
x
t P
w
t
+ + + + =
TS_FCAST IDL Reference Guide
Example
Dene an n-element vector of time-series samples:
X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99, $
5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31, $
5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76]
PRINT, TS_FCAST(X, 10, 5) Computeandprintfivefutureval-
ues of thetime-series usingten
time-series values.
IDL prints:
4.65870 4.58380 4.50030 4.48828 4.46971
PRINT, TS_FCAST(X, 10, 5, /BACKCAST) Computefivepast values of the
time-series usingten time-series
values.
IDL prints:
6.94862 6.91103 6.86297 6.77826 6.70282
See Also
A_CORRELATE, COMFIT, CURVEFIT, SMOOTH, TS_COEF , TS_DIFF, TS_FCAST
IDL Reference Guide TS_SMOOTH
TS_SMOOTH
TheTS_SMOOTH function computescentral, backward, or forwardmovingaveragesof
an n-element time-series. Autoregressive forecasting and backcasting are used to
extrapolatethetime-seriesandcomputeamovingaveragefor eachpoint. Theresult isan
n-element vector of the same data type as the input vector.
Note that central moving averages requireNvalues/2 forecasts and Nvalues/2 backcasts.
Backward moving averages requireNvalues-1 backcasts. Forward moving averages
requireNvalues-1 forecasts.
ts_smooth.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = TS_SMOOTH(X, Nvalues)
Arguments
X
samples. Note that n must be greater than or equal to 11.
Nvalues
A scalar of type integer or long integer that species the number of time-series values
used to compute each moving-average. If central-moving averages are computed (the
default), this parameter must be an odd integer greater than or equal to three.
Keywords
BACKWARD
Set this keyword to compute backward-moving averages. If BACKWARD is set, the
Nvaluesargument must be an integer greater than one.
DOUBLE
FORWARD
Set thiskeyword to computeforward-movingaverages. If FORWARD isset, theNvalues
argument must be an integer greater than one.
ORDER
An integer or long-integer scalar that speciestheorder of theautoregressivemodel used
tocomputetheforecastsand backcastsof thetime-series. Bydefault, atime-serieswith a
TS_SMOOTH IDL Reference Guide
lengthbetween 11and219elementswill usean autoregressivemodel withan order of 10.
A time-series with a length greater than 219 will use an autoregressive model with an
order equal to 5% of its length. The ORDER keyword is used to override this default.
Example
Dene an n-element vector of time-series samples.
X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99,$
5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31,$
5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76]
PRINT, TS_SMOOTH(X, 11) Computethe11-point central-
moving-averages of thetime-se-
ries.
IDL prints:
6.65761 6.60592 6.54673 6.47646 6.40480 6.33364
6.27000 6.20091 6.14273 6.09364 6.04455 5.99000
5.92273 5.85455 5.78364 5.72636 5.65818 5.58000
5.50182 5.42727 5.34182 5.24545 5.15273 5.07000
5.00182 4.94261 4.87205 4.81116 4.75828 4.71280
See Also
SMOOTH, TS_DIFF, TS_FCAST
IDL Reference Guide TV
TV
TheTV proceduredisplaysimageson theimagedisplay without scalingtheintensity. To
display an image with scaling, use the TVSCL procedure.
Note To display a true-color image (an image with 16, 24, or 32 bits per pixel) you must
specify the TRUE keyword.
WhiletheTVproceduredoesnot scaletheintensityof an image, it doesconvert theinput
image data to byte type. Values outside the range [ 0,255] are wrapped during the
conversion. In addition, for displays with less than 256 colors, elements of the input
image with values between !D.TABLE_SIZE and 255 will be displayed using the color
index !D.TABLE_SIZE-1.
Calling Sequence
TV, Image[, Position]
or
TV, Image[, X, Y [, Channel]]
Arguments
Image
A vector or two-dimensional array to be displayed as an image. If this argument is not
already of byte type, it is converted prior to use.
X, Y
If X and Y are present, they specify the lower-left coordinate of the displayed image,
relative to the lower-left corner of the screen.
Position
An integer specifyingtheposition for Imagewithin thegraphicswindow. Imagepositionsrun fromthetop
left of the screen to the bottom right. If a position number is used instead of X and Y, the position of the
image is calculated from the dimensions of the image as follows (integer arithmetic is used):
For example, when displaying 128 by 128 images on a 512 by 512 display, the position
numbers run from 0 to 15 as follows:
0 1 2 3
4 5 6 7
8 9 10 11
12 13 14 15
TV IDL Reference Guide
Note, when using a device with scalable pixels (e.g., PostScript), the XSIZE and YSIZE
keywords should also be used.
Channel
The memory channel to be written. It is assumed to be zero if not specied. This
parameter isignoredondisplaysystemsthat haveonlyonememorychannel. Whenusing
adecomposed display system, thered channel is1, thegreen channel is2, and theblue
channel is 3. Channel 0 indicates all channels.
Keywords
CENTIMETERS
Set this keyword to indicate that theX, Y, Xsize, Ysize, and Z arguments are given in
centimeters from the origin. This system is useful when dealing with devices, such as
PostScript printers, that donot provideadirect relationshipbetweenimagepixelsandthe
size of the resulting image.
CHANNEL
The memory channel to be written to . The CHANNEL keyword is identical to the
optional Channel argument.
INCHES
Set thiskeyword to indicatethat all position and sizevaluesaregiven in inchesfromthe
origin. This system is useful when dealing with devices, such as PostScript printers, that
do not provide a direct relationship between image pixels and the size of the resulting
image.
ORDER
If specied, ORDERoverridesthecurrent settingof the!ORDERsystemvariablefor the
current image only. If set, the image is drawn from the top down instead of the normal
bottom up.
TRUE
Set this keyword to a nonzero value to indicate that a true-color (16-, 24-, or 32-bit)
imageistobedisplayed. ThevalueassignedtoTRUEspeciestheindexof thedimension
Xsize Ysize , Sizeof display or window =
Xdim Ydim , Dimensionsof imageto bedisplayed =
N
x
Xsize
Ydim
------------- Imagesacrossscreen = =
X XdimPosition
moduloN
x
StartingX = =
Y Ysize Ydim 1
Position
N
x
------------------- - + StartingY = =
IDL Reference Guide TV
over whichcolor isinterleaved. Theimageparameter must havethreedimensions, oneof
whichmust beequal tothree. For example, set TRUEto1todisplayan imagethat ispixel
interleaved and hasdimensionsof (3, m, n). Specify 2for row-interleaved images, of size
(m, 3, n), and 3 for band-interleaved images of the form (m, n, 3).
See True-Color Images on page158for an exampleusingthiskeyword to write24-bit
images to the PostScript device.
WORDS
Set this keyword to indicate that words (short integers) instead of 8-bit bytes are to be
transferred tothedevice. Thiskeyword isvalid only when usingdevicesthat can transfer
16-bit pixels. The normal transfer uses 8-bit pixels. If this keyword is set, theImage
parameter isconverted to short integer type, if necessary, and then written to thedisplay.
XSIZE
Thewidth of theresultingimage. On deviceswith scalablepixel size(such asPostScript),
if XSIZE is specied the image will be scaled to t the specied width. If neither XSIZE
nor YSIZE is specied, the image will be scaled to ll the plotting area, while preserving
theimagesaspect ratio. Thiskeywordisignoredbypixel-baseddevicesthat areunableto
change the size of their pixels.
YSIZE
Theheight of theresultingimage. On deviceswithscalablepixel size(suchasPostScript),
if YSIZE is specied the image will be scaled to t the specied height. If neither XSIZE
nor YSIZE is specied, the image will be scaled to ll the plotting area, while preserving
theimagesaspect ratio. Thiskeywordisignoredbypixel-baseddevicesthat areunableto
change the size of their pixels.
not listed above. CHANNEL, DATA, DEVICE, NORMAL, T3D, Z.
Example
D = BYTSCL(DIST(256)) & TV, D Createand display a simpleim-
age.
ERASE Erasethescreen.
Use the position parameter to display a number of images in the same window.
TV, D, 0 Displaytheimageintheupperleft
corner.
TV, D, 1 Displayanothercopyoftheimage
in thenext position.
TV IDL Reference Guide
See Also
ERASE, SLIDE_IMAGE, TVRD, TVSCL, WIDGET_DRAW, WINDOW
IDL Reference Guide TVCRS
TVCRS
The TVCRS procedure manipulates the display device cursor. The initial state of the
cursor is device dependent. Call TVCRS with one argument to enable or disable the
cursor. Call TVCRS with two parameters to enable the cursor and place it on pixel
location (X, Y).
Note Under Macintosh, the cursor cannot be positioned from an IDL program using the
TVCRS procedure. The Macintosh interface does not allow the cursor to be posi-
tioned by any device except the mouse.
Calling Sequence
TVCRS[, ON_OFF]
or
TVCRS[, X, Y]
Arguments
ON_OFF
This argument species whether the cursor should be on or off. If this argument is
present and nonzero, the cursor is enabled. If ON_OFF is zero or no parameters are
specied, the cursor is turned off.
X
The column to which the cursor is set.
Y
The row to which the cursor is set.
Keywords
CENTIMETERS
Set thiskeyword to causeX and Yto beinterpreted ascentimeters, based on thecurrent
device resolution.
INCHES
Set thiskeywordtocauseXandYtobeinterpretedasinches, basedon thecurrent device
resolution.
HIDE_CURSOR
By default, disabling the cursor works differently for window systems than for other
devices. For window systems, the cursor is restored to the standard cursor used for non-
TVCRS IDL Reference Guide
IDL windows(and remainsvisible), whilefor other devicesit iscompletely blanked out.
If the HIDE keyword is set, disabling the cursor causes it to always be blanked out.
not listed above. DATA, DEVICE, NORMAL, T3D, Z.
Example
To enable the graphics cursor and position it at device coordinate (100, 100), enter:
TVCRS, 100, 100
To position the cursor at data coordinate (0.5, 3.2), enter:
TVCRS, 0.5, 3.2, /DATA
See Also
CURSOR, RDPIX
IDL Reference Guide TVLCT
TVLCT
The TVLCT procedure loads the display color translation tables from the specied
variables. Although IDL uses the RGB color system internally, color tables can be
specied to TVLCT using any of the following color systems: RGB (Red, Green, Blue),
HLS(Hue, Lightness, Saturation), and HSV (Hue, Saturation, Value). Alphavaluesmay
alsobeusedwhen usingthesecondformof thecommand. Thetypeandmeaningof each
argument is dependent upon the color system selected, as described below. Color
arguments can be either scalar or vector expressions. If no color-system keywords are
present, theRGBcolor systemisused. See ImageDisplayRoutines onpage379of Using
IDL for a more complete explanation of color systems.
Calling Sequence
TVLCT, V
1
, V
2
, V
3
[, Start]
or
TVLCT, V [, Start]
Arguments
TVLCTwill accept either threen-element vectors(V
1
, V
2
, andV
3
) or asinglenby3array
(V) as an argument. The vectors (or columns of the array) have different meanings
dependingon thecolor systemchosen. If an array Visspecied, V[ *,0] isthesameasV
1
,
V[ *,1] is the same asV
2
, V[ *,2] is the same asV
3
. In the description below, we assume
that three vectors, V
1
, V
2
, and V
3
are specied.
TheV
1
, V
2
, and V
3
arguments have different meanings depending upon which color
system they represent.
R, G, B Color System
The parametersV
1
, V
2
, and V
3
contain the Red, Green, and Blue values, respectively.
Values are interpreted as integers in the range 0 (lowest intensity) to 255 (highest
intensity). Theparameterscan bescalarsor vectorsof up to256elements. Bydefault, the
three arguments are assumed to be R, G, and B values.
H, L, S Color System
ParametersV
1
, V
2
, andV
3
contain theHue, Lightness, andSaturation valuesrespectively.
All parametersareoating-point. Hueisexpressedindegreesandisreducedmodulo360.
V
2
(lightness) and V
3
(saturation) and can range from 0 to 1.0. Set the HLS keyword to
have the arguments interpreted this way.
TVLCT IDL Reference Guide
H, S, V Color System
ParametersV
1
, V
2
, and V
3
contain values for Hue, Saturation, and Value (similar to
intensity). All parametersareoating-point. Hueisin degrees. TheSaturation andValue
can rangefrom0to1.0. Set theHSVkeyword tohavetheargumentsinterpreted thisway.
Start
An integer valuethat speciesthestartingpoint in thecolor translation tableinto which
the color intensities are loaded. If this argument is not specied, a value of zero is used,
causing the tables to be loaded starting at the rst element of the translation tables.
Keywords
GET
Set thiskeyword to return theRGBvaluesfromtheinternal color tablesinto theV
1
, V
2
,
and V
3
parameters. For example, the statements:
TVLCT, H, S, V, /HSV
TVLCT, R, G, B, /GET
load acolor tablebased in theHSVsystem, and then read theequivalent RGBvaluesinto
the variables R, G, and B.
HLS
Set thiskeyword toindicatethat theparametersspecifycolor usingtheHLScolor system.
HSV
Set thiskeywordtoindicatethat theparametersspecifycolor usingtheHSVcolor system.
Example
R = BYTSCL(SIN(FINDGEN(256))) Createa set of R, G, and B color-
map vectors.
G = BYTSCL(COS(FINDGEN(256)))
B = BINDGEN(256)
TVLCT, R, G, B Load thesevectors into thecolor
table.
TVSCL, DIST(400) Displayanimagetoseetheeffectof
thenew color table.
See Also
LOADCT, XLOADCT, XPALETTE
IDL Reference Guide TVRD
TVRD
The TVRD function returns the contents of the specied rectangular portion of the
current graphics window or device. (X
0
, Y
0
) is the coordinate of the lower left corner of
theareatoberead and N
x
, N
y
isthesizeof therectanglein columnsand rows. Theresult
is a byte array of dimensionsN
x
by N
y
. All parameters are optional. If no arguments are
supplied, the entire display device area is read.
Important Note about TVRD and Backing Store
On some systems, when backing store is provided by the window system (the RETAIN
keyword to DEVICEor WINDOWisset to 1), readingdatafromawindowusingTVRD
may cause unexpected results. For example, data may be improperly read from the
window even when the image displayed on screen is correct. Having IDL provide the
backing store (set the RETAIN keyword to 2) ensures that the window contents will be
read properly. Moredetailed notesabout TVRDand theXWindowsystemcan befound
below in Unexpected Results Using TVRD with X Windows on page 1162.
Calling Sequence
Result = TVRD([X
0
[, Y
0
[, N
x
[, N
y
[, Channel]]]]])
Arguments
X
0
The starting column of data to read. The default is 0.
Y
0
The starting row of data to read. The default is 0.
N
x
Thenumber of columnstoread. Thedefault isthewidth of thedisplaydeviceor window
lessX
0
.
N
y
Thenumber of rowstoread. Thedefault istheheight of thedisplaydeviceor windowless
Y
0
.
Channel
The memory channel to be read. If not specied, this argument is assumed to be zero.
This parameter is ignored on display systems that have only one memory channel.
TVRD IDL Reference Guide
Keywords
CHANNEL
The memory channel to be read. The CHANNEL keyword is identical to the optional
Channel argument.
Note: if thedisplayisa24-bit display, andboththeCHANNELandTRUEparametersare
absent, the maximum RGB value in each pixel is returned.
ORDER
Set this keyword to override the current setting of the !ORDER system variable for the
current imageonly. If set, it causestheimagetoberead fromthetop down instead of the
normal bottom up.
TRUE
If this keyword is present, it indicates that a true-color image is to be read, if the display
is capable. The value assigned to TRUE species the index of the dimension over which
color isinterleaved. Theresult isan (3, n
x
, n
y
) pixel-interleaved array if TRUEis1; or an
(n
x
, 3, n
y
) line-interleaved array if TRUE is 2; or an (n
x
, n
y
, 3) image-interleaved array if
TRUE is 3.
WORDS
Set this keyword to indicate that words are to be transferred from the device. This
keyword is valid only when using devices that can transfer 16-bit pixels. The normal
transfer uses 8-bit pixels. If this keyword is set, the function result is an integer array.
Unexpected Results Using TVRD with X Windows
When using TVRD with the X Windows graphics device, there are two unexpected
behaviors that can be confusing to users:
Whenreadingfromawindowthat isobscuredbyanother window(i.e., thetarget window
has another window on top or in front of it), TVRD may return the contents of the
window in front as part of the image contained in the target window.
Whenreadingfromaniconiedwindow, theXserver mayreturnastreamof BadMatch
protocol events.
IDLusestheXlibfunction XGetSubImage() toimplement TVRD. Thefollowingquote
is from the documentation for XGetSubImage() found in TheX Window Systemby
Robert W. Scheier and James Gettys, Second Edition, page 174. It explains the reasons
for the behaviors described above:
If thedrawableisawindow, thewindowmust beviewable, and it must bethecasethat
if there were no... overlapping windows, the specied rectangle of the window would be
fullyvisibleonthescreen, ... or aBadMatcherror results. If thewindowhasbacking-store,
then the backing-store contents are returned for regions of the window that are
IDL Reference Guide TVRD
obscured... If the window does not have backing-store, the returned contents of such
obscured regions are undened.
Hence, the rst behavior is caused by attempting to use TVRD on an obscured window
that does not have backing store provided by the X server. The result in this case is
undened, meaningthat thedifferent serverscanproduceentirelydifferent results. Many
servers simply return the image of the obscuring window.
The second behavior is caused by attempting to read from a non-viewable (i.e.,
unmapped) window. AlthoughIDLcouldrefusetoallowTVRDtowork withunmapped
windows, some X servers return valid and useful results. Therefore, TVRD is allowed to
attempt to read from unmapped windows.
Both of these behavior problems can be solved by using one of the following methods:
Always make sure that your target window is mapped and is not obscured before using
TVRD on it. The following IDL command can be used:
WSHOW, Window_Index, ICONIC=0
MakeIDL providebackingstore(rather than thewindowsystem) bysettingtheRETAIN
keyword to DEVICE or WINDOW equal to 2.
For afull description of backingstore, See BackingStore on page144. Notethat under
X Windows, backing store is a request that may or may not be honored by the X server.
Manyserverswill honor backingstorefor 8-bit visualsbut ignorethemfor 24-bit visuals
because they require three times as much memory.
Example
T = TVRD() Readtheentirecontentsofthecur-
rent display deviceinto thevari-
ableT.
See Also
RDPIX, TV, WINDOW
TVSCL IDL Reference Guide
TVSCL
The TVSCL procedure scales the intensity values of Imageinto the range of the image
display and outputs the data to the image display at the specied location. The array is
scaled so the minimum data value becomes 0 and the maximum value becomes the
maximum number of available colors (held in the system variable !D.TABLE_SIZE) as
follows:
wherethemaximumandminimumarefoundbyscanningthearray. Theparametersand
keywords of the TVSCL procedure are identical to those accepted by the TV procedure.
For additional information about each parameter, consult the description of TV.
Calling Sequence
TVSCL, Image[, Position]
or
TVSCL, Image[, X, Y [, Channel]]
Arguments
Image
A two-dimensional array to be displayed as an image. If this argument is not already of
byte type, it is converted prior to use.
X, Y
If X and Y are present, they specify the lower left coordinate of the displayed image.
Position
Image position. See the discussion of the TV procedure for a full description.
Channel
Thememorychannel tobewritten. Thisargument isassumed tobezeroif not specied.
This parameter is ignored on display systems that have only one memory channel.
Keywords
TVSCL accepts all of the keywords accepted by the TV routine. See TV on page 1153.
In addition, there are two unique keywords:
Output !D.TABLE_SIZE
Data Data
min
Data
max
Data
min
-------------------------------------------- =
IDL Reference Guide TVSCL
NAN
Set thiskeywordtocauseTVSCLtotreat elementsof Imagethat arenot numbers(that is,
elementsthat havethespecial oating-point valuesInnityor NaN) asmissingdata, and
display them using color index 0 (zero). Note that color index 0 is also used to display
elements that have the minimum value in theImagearray.
TOP
The maximum value of the scaled result. If TOP is not specied, 255 is used. Note that
the minimum value of the scaled result is always 0.
Example
Display a oating-point array as an image using the TV command. Enter:
TV, DIST(200)
Note that the image is not easily visible because the values in the array have not been
scaled into the full range of display values. Now display the image with the TVSCL
command by entering:
TVSCL, DIST(200)
Notice how much brighter the image appears.
See Also
ERASE, SLIDE_IMAGE, TV, WIDGET_DRAW, WINDOW
UINDGEN IDL Reference Guide
UINDGEN
The UINDGEN function returns an unsigned integer array with the specied
dimensions. Each element of thearrayisset tothevalueof itsone-dimensional subscript.
Calling Sequence
Result = UINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
L = UINDGEN(10, 10)
See Also
LINDGEN, SINDGEN, UL64INDGEN, ULINDGEN
IDL Reference Guide UINT
UINT
The UINT function returns a result equal to Expression converted to unsigned integer
type.
Calling Sequence
Result = UINT(Expression[, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to unsigned integer.
Offset
of data extracted fromExpression to be treated as unsigned integer data. See the
details.
D
i
i
Example
If Acontainstheoating-point value32000.0, it canconvertedtoanunsignedinteger and
B = UINT(A)
See Also
BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING,
ULONG, ULONG64
UINTARR IDL Reference Guide
UINTARR
The UINTARR function returns an unsigned integer vector or array.
Calling Sequence
Result = UINTARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, UINTARR sets every element of the result to zero. If NOZERO is set, this
zeroing is not performed and UINTARR executes faster.
Example
To create L, a 100-element, unsigned integer vector with each element set to 0, enter:
L = UINTARR(100)
See Also
LON64ARR, LONARR, MAKE_ARRAY, STRARR, ULON64ARR, ULONARR
IDL Reference Guide UL64INDGEN
UL64INDGEN
TheUL64INDGEN function returnsan unsigned 64-bit integer array with thespecied
Calling Sequence
Result = UL64INDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
L = UL64INDGEN(10, 10)
See Also
LINDGEN, SINDGEN, UINDGEN, ULINDGEN
ULINDGEN IDL Reference Guide
ULINDGEN
The ULINDGEN function returns an unsigned longword array with the specied
Calling Sequence
Result = ULINDGEN(D
1
, ..., D
n
)
Arguments
D
i
Example
L = ULINDGEN(10, 10)
See Also
LINDGEN, SINDGEN, UINDGEN, UL64INDGEN
IDL Reference Guide ULON64ARR
ULON64ARR
The ULON64ARR function returns an unsigned 64-bit integer vector or array.
Calling Sequence
Result = ULON64ARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, ULON64ARR sets every element of the result to zero. If NOZERO is set, this
zeroing is not performed and ULON64ARR executes faster.
Example
To create L, a 100-element, unsigned 64-bit vector with each element set to 0, enter:
L = ULON64ARR(100)
See Also
LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULONARR
ULONARR IDL Reference Guide
ULONARR
The ULONARR function returns an unsigned longword integer vector or array.
Calling Sequence
Result = ULONARR(D
1
, ..., D
n
)
Arguments
D
i
Keywords
NOZERO
Normally, ULONARR sets every element of the result to zero. If NOZERO is set, this
zeroing is not performed and ULONARR executes faster.
Example
To create L, a 100-element, unsigned longword vector with each element set to 0, enter:
L = ULONARR(100)
See Also
LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR
IDL Reference Guide ULONG
ULONG
The ULONG function returns a result equal to Expression converted to the unsigned
longword integer type.
Calling Sequence
Result = ULONG(Expression[, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to unsigned longword integer.
Offset
of dataextractedfromExpressiontobetreatedasunsignedlongwordinteger data. Seethe
details.
D
i
i
Example
If Acontainstheoating-point value32000.0, it can converted to an unsigned longword
integer and stored in the variable B by entering:
B = ULONG(A)
See Also
UINT, ULONG64
ULONG64 IDL Reference Guide
ULONG64
The ULONG64 function returns a result equal to Expression converted to the unsigned
64-bit integer type.
Calling Sequence
Result = ULONG64(Expression[, Offset [, Dim
1
, ..., Dim
n
]])
Arguments
Expression
The expression to be converted to unsigned 64-bit integer.
Offset
of data extracted fromExpression to be treated as unsigned 64-bit integer data. See the
details.
D
i
i
Example
If A contains the oating-point value 32000.0, it can converted to an unsigned 64-bit
integer and stored in the variable B by entering:
B = ULONG64(A)
See Also
UINT, ULONG
IDL Reference Guide UNIQ
UNIQ
TheUNIQfunction returnsthesubscriptsof theuniqueelementsin an array. Notethat
repeated elements must be adjacent in order to be found. This routine is intended to be
used with theSORT function: seetheexamplesbelow. Thisfunction wasinspired by the
Unix uniq(1) command.
UNIQ returns an array of indices into the original array. Note that the index of the last
element in each set of non-unique elements is returned. The following expression is a
copy of the sorted array with duplicate adjacent elements removed:
Array(UNIQ(Array))
UNIQ returns 0 (zero) if the argument supplied is a scalar rather than an array.
uniq.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = UNIQ(Array [, Index])
Arguments
Array
The array to be scanned. For UNIQ to work properly, the array must be sorted into
monotonic order unless the optional parameter Idx is supplied.
Index
This optional parameter is an array of indices into Array that order the elements into
monotonic order. That is, the expression:
Array(Index)
yieldsan arrayin whichtheelementsof Arrayarerearrangedintomonotonicorder. If the
array is not already in monotonic order, use the command:
UNIQ(Array, SORT(Array))
Examples
Find the unique elements of an unsorted array:
array = [1, 2, 1, 2, 3, 4, 5, 6, 6, 5] Createan array .
b = array(UNIQ(array, SORT(array))) VariableBholdsanarraycontain-
ingthesorted,uniquevaluesinar-
ray.
UNIQ IDL Reference Guide
PRINT, b
IDL prints
1 2 3 4 5 6
See Also
SORT, WHERE
IDL Reference Guide USERSYM
USERSYM
The USERSYM procedure is used to dene the plotting symbol that marks points when
the plotting symbol is set to plus or minus 8. Symbols can be drawn with vectors or can
be lled. Symbols can be of any size and can have up to 50 vertices. See Dening Your
Own Plotting Symbols on page 296 of Using IDL.
Calling Sequence
USERSYM, X [, Y]
Arguments
X, Y
TheXand/or Yparametersdenetheverticesof thesymbol asoffsetsfromthedatapoint
in unitsof approximatelythesizeof acharacter. In thecaseof avector drawn symbol, the
symbol isformedbyconnectingtheverticesin order. If onlyoneargument isspecied, it
must bea(2, N) array of vertices, with element [ 0, i] containingtheX coordinateof the
vertex, and element [ 1, i] containing the Y. If both arguments are provided, X contains
only the X coordinates.
Keywords
COLOR
The color used to draw the symbols, or used to ll the polygon. The default color is the
same as the line color.
FILL
Set this keyword to ll the polygon dened by the vertices. If FILL is not set, lines are
drawn connecting the vertices.
THICK
The thickness of the lines used in drawing the symbol. The default thickness is 1.0.
Example
Make a large, diamond-shaped plotting symbol. Dene the vectors of X values by
entering:
X = [-6, 0, 6, 0, -6]
Dene the vectors of Y values by entering:
Y = [0, 6, 0, -6, 0]
USERSYM IDL Reference Guide
Now call USERSYM to create the new plotting symbol 8. Enter:
USERSYM, X, Y
Generate a simple plot to test the plotting symbol by entering:
PLOT, FINDGEN(20), PSYM = 8
See Also
PLOT
IDL Reference Guide VARIANCE
VARIANCE
The VARIANCE function computes the statistical variance of an n-element vector.
Calling sequence
Result = VARIANCE(X)
Arguments
X
Keywords
DOUBLE
If this keyword is set, VARIANCE performs its computations in double precision
arithmetic and returns a double precision result. If this keyword is not set, the
computations and result depend upon the type of the input data (integer and oat data
return oat results, while double data returns double results).
NAN
Example
x = [1, 1, 1, 2, 5] Definethen-element vector of
sampledata.
result = VARIANCE(x) Computethevariance.
PRINT, result
IDL prints:
3.00000
See Also
KURTOSIS, MEAN, MEANABSDEV, MOMENT, STDDEV, SKEWNESS
VAX_FLOAT IDL Reference Guide
VAX_FLOAT
The VAX_FLOAT function performs one of two possible actions:
1. Determine, and optionally change, thedefault valuefor theVAX_FLOAT keyword to the
OPEN procedures and the CALL_EXTERNAL function.
2. Determine if an open le unit has the VAX_FLOAT attribute set.
See the discussion of VAX oating-point conversion in VMS Floating-Point Arithmetic
in IDL 5.1 on page1401 and the VAX_FLOAT keyword to OPEN on page783 for more
on the VAX oating-point conversion issue.
Calling Sequence
Result = VAX_FLOAT([Default])
Arguments
Default
Default is used to change the default value of the VAX_FLOAT keyword to the OPEN
proceduresandtheCALL_EXTERNALfunction. Avalueof 0(zero) makesthedefault for
those keywords False. A non-zero value makes the default True. SpecifyingDefault in
conjunction with the FILE_UNIT keyword will cause an error.
Note If theFILE_UNIT keyword isnot specied, thevaluereturned fromVAX_FLOAT is
thedefault valuebeforeanychangeismade. Thisisthecaseevenif Defaultisspecied.
This allows you to get the old setting and change it in a single operation.
Keywords
FILE_UNIT
Set thiskeywordequal tothelogical leunit number (LUN) of an open le. VAX_FLOAT
returns True (1) if the le was opened with the VAX_FLOAT attribute, or False (0)
otherwise. Setting the FILE_UNIT keyword when theDefault argument is specied will
cause an error.
Example
To determine if the default VAX_FLOAT keyword value for OPEN and
CALL_EXTERNAL is True or False:
default_vax_float = VAX_FLOAT()
IDL Reference Guide VAX_FLOAT
To determine the current default value of the VAX_FLOAT keyword for OPEN and
CALL_EXTERNAL and change it to True (1) in a single operation:
old_vax_float = VAX_FLOAT(1)
To determine if the le currently open on logical le unit 1 was opened with the
VAX_FLOAT keyword set:
file_is_vax_float = VAX_FLOAT(FILE_UNIT=1)
See Also
CALL_EXTERNAL, OPEN, Command Line Options on page 68 of Using IDL, and
VMS Floating-Point Arithmetic in IDL 5.1 on page1401.
VEL IDL Reference Guide
VEL
The VEL procedure draws a velocity (ow) eld with arrows following the eld
proportional in length to the eld strength. Arrows are composed of a number of small
segments that follow the streamlines.
vel.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
VEL, U, V
Arguments
U
The X component at each point of the vector eld. U must be a 2D array.
V
TheYcomponent at eachpoint of thevector eld. Vmust havethesamedimensionsasU.
Keywords
NVECS
The number of vectors (arrows) to draw. If this keyword is omitted, 200 vectors are
drawn.
XMAX
X axis size as a fraction of Y axis size. The default is 1.0. This argument is ignored when
!P.MULTI is set.
LENGTH
Thelengthof eacharrowlinesegment expressedasafractionof thelongest vector divided
by the number of steps. The default is 0.1.
NSTEPS
The number of shoots or line segments for each arrow. The default is 10.
TITLE
A string containing the title for the plot.
Example
X = DIST(20) Createa vector of X values.
IDL Reference Guide VEL
Y = SIN(X)*100 Createa vector of Y values.
VEL, X, Y Plot thevector field.
See Also
FLOW3, PLOT_FIELD, VELOVECT
VELOVECT IDL Reference Guide
VELOVECT
The VELOVECT procedure produces a two-dimensional velocity eld plot. A directed
arrow is drawn at each point showing the direction and magnitude of the eld.
velovect.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
VELOVECT, U, V [, X, Y]
Arguments
U
The X component of the two-dimensional eld. U must be a two-dimensional array.
V
The Y component of the two dimensional eld. Vmust have the same dimensions asU.
X
Optional abcissaevalues. Xmust beavector with alength equal totherst dimension of
U and V.
Y
Optional ordinatevalues. Ymust beavector withalengthequal totheseconddimension
of U and V.
Keywords
Note Keywordsnot described herearepassed directly to thePLOT procedureand may be
used to set options such as TITLE, POSITION, NOERASE, etc.
COLOR
Set this keyword equal to the color index used for the plot.
DOTS
Set thiskeyword to1toplaceadot at each missingpoint. Set thiskeyword to0or omit it
to draw nothing for missing points. Has effect only if MISSING is specied.
LENGTH
Set this keyword equal to the length factor. The default of 1.0 makes the longest (U,V)
vector the length of a cell.
IDL Reference Guide VELOVECT
MISSING
Set this keyword equal to the missing data value. Vectors with a length greater than
MISSING are ignored.
PLOT Keywords
In addition to the keywords described above, all other keywords accepted by the PLOT
procedure are accepted by VELOVECT. See PLOT on page800.
Example
U = RANDOMN(S, 20, 20) Createsomerandom data.
V = RANDOMN(S, 20, 20)
VELOVECT, U, V Plot thevector field.
VELOVECT, U, V, MISSING=18, /DOTS Plot thefield, usingdots to repre-
sent vectors with values greater
than 18.
VELOVECT, U, V, MISSING=18, /DOTS, XTITLE='Random Vectors'
Plot with a title. Notethat the
XTITLEkeywordispasseddirectly
to thePLOT procedure.
See Also
FLOW3, PLOT, PLOT_FIELD, VEL
VERT_T3D IDL Reference Guide
VERT_T3D
The VERT_T3D function transforms a 3D array by a 4x4 transformation matrix and
returns the transformed array. The 3D points are typically an array of polygon vertices
that were generated by SHADE_VOLUME or MESH_OBJ.
vert_t3d.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = VERT_T3D(Vertex_List)
Arguments
Vertex_List
A 3 x n array of 3D coordinates to transform.
Keywords
MATRIX
The 4x4 transformation matrix to use. The default is to use the system viewing matrix
(!P.T).
NO_COPY
Normally, acopy of Vertex_list istransformed and theoriginal Vertex_list ispreserved. If
NO_COPYisset, however, then theoriginal Vertex_Listwill beundenedafter thecall to
VERT_T3D. Using the NO_COPY requires less memory.
NO_DIVIDE
Normally, whena[ x, y, z, 1] vector istransformedbya4x4matrix, thenal homogeneous
coordinatesareobtainedbydividingthex, y, andzcomponentsof theresult vector bythe
fourth element in the result vector. Setting the NO_DIVIDE keyword will prevent
VERT_T3D from performing this division. In some cases (usually when a perspective
transformationisinvolved) thefourthelement intheresult vector canbeverycloseto(or
equal to) zero.
SAVE_DIVIDE
Set this keyword to a named variable that will hold receive the fourth element of the
transformed vector(s). If Vertex_list is a vector then SAVE_DIVIDE is a scalar. If
Vertex_list is an array then SAVE_DIVIDE is an array of n elements. This keyword only
has effect when the NO_DIVIDE keyword is set.
IDL Reference Guide VERT_T3D
Example
Transform four points representing a square in the x-y plane by rst translating +2.0 in
the positive X direction, and then rotating 60.0 degrees about the Y axis.
points = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], $
[1.0, 1.0, 0.0], [0.0, 1.0, 0.0]]
T3D, /RESET
T3D, TRANSLATE=[2.0, 0.0, 0.0]
T3D, ROTATE=[0.0, 60.0, 0.0]
points = VERT_T3D(points)
See Also
T3D
VOIGT IDL Reference Guide
VOIGT
The VOIGT function returns the intensity of an atomic absorption line prole (also
known as a VOIGT prole) based on the Voigt damping parameter a and the frequency
offset u, in units of the Doppler width. The result is always oating-point and has the
same structure as the arguments. Note that a and u should not both be vectors.
The returned line prole(a, u) is dened as:
whereH is the classical Voigt function:
The Doppler width v
D
(assuming no turbulence), is dened as:
where
0
is the line center frequency. The dimensionless frequency offset u and the
damping parameter a are determined by:
Here, is the transition rate:
where isthespontaneousdecay rate, and
col
istheatomiccollision rate. SeeRadiative
Processes in Astrophysicsby G. B. Rybicki and A. P. Lightman (1979) p 291 for more
information. The algorithm is from Armstrong, JQSRT 7, 85. (1967).
Calling Sequence
Result = VOIGT(A, U)
a u , ( )
H a u , ( )
v
D

-------------------
H a u , ( )
a
---
e
y
2
y d
a
2
u y ( )
2
+
-------------------------------

=
v
D

0
c
-----b

0
c
----- 2kT m = =
u

0
D
-------------- =
a

4
D
----------------- =
2
col
+ =
IDL Reference Guide VOIGT
Arguments
A
The Voigt dampingparameter.
U
The dimensionless frequency offset in Doppler widths.
See Also
LEEFILT, ROBERTS, SOBEL
VORONOI IDL Reference Guide
VORONOI
TheVORONOI procedurecomputestheVoronoi polygon of apoint within an irregular
gridof points, giventheDelaunaytriangulation. TheVoronoi polygonof apoint contains
the region closer to that point than to any other point.
For interior points, the polygon is constructed by connecting the midpoints of the lines
connecting the point with its Delaunay neighbors. Polygons are traversed in a
counterclockwise direction.
For exterior points, theset isdescribed bythemidpointsof theconnectinglines, plusthe
circumcenters of the two triangles that connect the point to the two adjacent exterior
points.
voronoi.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
VORONOI, X, Y, I0, C, Xp, Yp, Rect
Arguments
X
An array containing the X locations of the points.
Y
An array containing the Y locations of the points.
I0
An array containing the indices of the points.
C
A connectivity list from the Delaunay triangulation. This list is produced with the
CONNECTIVITY keyword of the TRIANGULATE procedure.
Xp, Yp
Named variables that will contain the X and Y vertices of Voronoi polygon.
Rect
The bounding rectangle: [ Xmin, Ymin, Xmax, Ymax] . Because the Voronoi polygon
(VP) for points on the convex hull extends to innity, a clipping rectangle must be
supplied to closethepolygon. Thisrectanglehasno effect on theVPof interior points.
If thisrectangledoesnot encloseall theVoronoi vertices, theresultswill beincorrect. If
this parameter, which must be a named variable, is undened or set to a scalar value, it
will be calculated.
IDL Reference Guide VORONOI
Example
To draw the Voronoi polygons of each point of an irregular grid:
N = 20
X = RANDOMU(seed, N) Createa random grid of N points
TRIANGULATE, X, Y, tr, CONN=C Triangulateit
FOR I=0, N-1 DO BEGIN & $
VORONOI, X, Y, I, C, Xp, Yp & $ Get theith polygon
POLYFILL, Xp, Yp, COLOR = (I MOD 10) + 2 & $
Draw it
ENDFOR
See Also
TRIANGULATE
VOXEL_PROJ IDL Reference Guide
VOXEL_PROJ
TheVOXEL_PROJfunctiongeneratesvisualizationsof volumetricdatabycomputing2D
projectionsof acolored, semi-transparent volume. Parallel raysfromanygiven direction
are cast through the volume, onto the viewing plane. User-selected colors and opacities
can be assigned to arbitrary data ranges, simulating the appearance of the materials
contained within the volume.
The VOXEL_PROJ function can be combined with the Z-buffer to render volume data
over objects. Cuttingplanescan alsobespeciedtoviewselectedportionsof thevolume.
Other options include: selectable resolution to allow quick preview renderings, and
average and maximum projections.
VOXEL_PROJ renders volumes using an algorithm similar to the one described by
Drebin, Carpenter, and Hanrahan, in Volume Rendering, Computer Graphics, Volume
22, Number 4, August 1988, pp. 125-134, but without the surface extraction and
enhancement step.
Voxel rendering can be quite time consuming. The time required to render a volume is
proportional to the viewing areas size, in pixels, times the thickness of the volume cube
in the viewing direction, divided by the product of the user-specied X, Y, and Z steps.
Calling Sequence
Result = VOXEL_PROJ(V [, RGBO])
Arguments
V
Athree-dimensional arraycontainingthevolumetoberendered. Thisarrayisconverted
to byte type if necessary.
RGBO
This optional parameter is used to specify the look-up tables that indicate the color and
opacity of each voxel value. This argument can be one of the following types:
A (256, 4) byte array for true-color rendering. This array represents 256 sets of red,
green, blue, andopacity(RGBO) componentsfor eachvoxel value, scaledintotherange
of bytes(0to255). TheR, G, andBcomponentsshouldalreadybescaledbytheopacity.
For example, if a voxel value of 100 contains a material that is red, and 35% opaque,
theRGBOvaluesshouldbe, respectively: [ 89, 0, 0, 89] because255* 0.35= 89. If more
thanonematerial ispresent, theRGBOarrayscontainthesumof theindividual RGBO
arrays. Thecontent andshapeof theRGBOcurvesishighlydependent uponthevolume
data and experimentation is often required to obtain the best display.
IDL Reference Guide VOXEL_PROJ
A (256, 2) byte array for volumes with only one material or monochrome rendering.
Thisarrayrepresents256setsof pixel valuesandtheir correspondingopacitiesfor each
voxel value.
If this argument is omitted, the average projection method, or maximum intensity
method (if the MAXIMUM_INTENSITY keyword is set) is used.
Keywords
BACKGROUND
A one- or three-element array containing the background color indices. The default is
(0,0,0), yielding a black background with most color tables.
CUTTING_PLANE
A oating-point array specifying the coefcients of additional cutting planes. The array
has dimensions of (4, N), where N is the number of additional cutting planes from 1 to
6. Cutting planes are constraints in the form of:
C[ 0] * X + C[ 1] * Y + C[ 2] * Z + D > 0
The X, Y, and Z coordinates are specied in voxel coordinates. For example, to specify a
cutting plane that excludes all voxels with an X value greater than 10:
CUTTING_PLANE = [ -1.0, 0, 0, 10.] , for the constraint: -X + 10 > 0.
INTERPOLATE
Set thiskeyword to usetri-linear interpolation to determinethedatavaluefor each step
on aray. Otherwise, thenearest-neighbor methodisused. Settingthiskeyword improves
thequalityof imagesproduced, especiallywhenthevolumehaslowresolution inrelation
to the size of the viewing plane, at the cost of more computing time.
MAXIMUM_INTENSITY
Set thiskeyword to makethevalueof each pixel in theviewingplanethemaximumdata
value along the corresponding ray. TheRGBO argument is ignored if present.
STEP
Set thiskeyword toathree-element vector, [ Sx, Sy, Sz] , that controlstheresolution of the
resulting projection. The rst two elements contain the step size in the X and Y view
plane, in pixels. The third element is the sampling step size in the Z direction, given in
voxels. Sx and Sy must be integers equal to or greater than one, whileSz can contain a
fractional part. If Sx or Sy are greater than one, the values of intermediate pixels in the
output image are linearly interpolated. Higher step sizes require less time because fewer
rays are cast, at the expense of lower resolution in the output image.
XSIZE
Thewidth, in pixels, of theoutput image. If thiskeyword isomitted, theoutput imageis
as wide as the currently-selected output device.
VOXEL_PROJ IDL Reference Guide
YSIZE
Theheight, in pixels, of theoutput image. If thiskeyword isomitted, theoutput imageis
as tall as the currently selected output device.
ZBUFFER
An integer array, with the same width and height as the output image, that contains the
depth portion of the Z-buffer. Include this parameter to combine the previously-read
contents of a Z-buffer with a voxel rendering. See the third example, below, for details.
ZPIXELS
Abytearray, withthesamewidthandheight astheoutput image, that containstheimage
portionof theZ-buffer. Includethisparameter tocombinethecontentsof aZ-buffer with
a voxel rendering. See the third example, below, for details.
Examples
In the following example, assume that variableV contains a volume of data, with
dimensionsVx by Vy by Vz. The volume contains two materials, muscle tissue
represented by a voxel range of 50 to 70, that we want to render with red color, and an
opacity of 20; and bone tissue represented by a voxel range of 220-255, that we want to
render with white color, and an opacity of 50:
rgbo = BYTARR(256,4) Createtheopacity vector.
rgbo[50:70, [0,3]] = 20 Red and opacity for muscle.
rgbo[220:255, *] = 50 Whiteand opacity for bone.
Although it is common to use trapezoidal or Gaussian functions when forming the
RGBO arrays, this example uses rectangular functions for simplicity.
SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-1]
Setuptheaxisscalinganddefault
rotation.
C = VOXEL_PROJ(V, rgbo) Computeprojected image.
TV, COLOR_QUAN(C, 3, R, G, B) Convertfrom24-bitto8-bitimage
and display.
TVLCT, R, G, B Load quantized color tables.
Thisexamplerequiredapproximately27secondsonatypical workstationtocomputethe
viewin a640- by 512-pixel viewingwindow. Addingthekeyword STEP=[2,2,1] in the
call toVOXEL_PROJdecreasedthecomputingtimetoabout 8seconds, at theexpenseof
slightly poorer resolution.
When viewingavolumewith only oneconstituent, theRGBOarray should contain only
an intensity/opacity valuepair. To illustrate, if in theaboveexample, only musclewasof
interest we create the RGBO argument as follows:
IDL Reference Guide VOXEL_PROJ
rgbo = BYTARR(256,2) Createan empty 256 x 2 array.
rgbo[50:70, *] = 20 Intensity and opacity for muscle
TV, VOXEL_PROJ(V, rgbo) Computeand display theproject-
ed image.
C = (FINDGEN(256)/255.) # [255., 0., 0] Createcolor tablearray for red.
TVLCT, C[*,0], C[*,1], C[*,2] Load colors.
The following example demonstrates combining a volume with the contents of the Z-
buffer:
SET_PLOT, 'Z' Set plottingto Z-buffer.
DEVICE, /Z_BUFFER Turn on Z buffering.
Set scaling.
POLYFILL, [0, Vx-1, Vx-1, 0], [0, 0, Vy-1, Vy-1], Vz/2., /T3D
Drawapolygonatzequal tohalf
thedepth
zpix = TVRD() Readpixel valuesfromtheZ-buff-
er.
zbuff = TVRD(/WORDS,/CHAN) Read depth values from theZ-
buffer.
SET_PLOT, 'X' Back to display window
C = VOXEL_PROJ(V, rgbo, ZPIX=zpix, ZBUFF=zbuff)
Computethevoxel projectionand
usetheZPIXELS and ZBUFFER
keywords to combinethevolume
withthepreviously-readcontents
of theZ-buffer.
TV, COLOR_QUAN(C, 3, R, G, B) Convertfrom24-bitto8-bitimage
and display.
TVLCT, R, G, B Load thequantized color tables.
See Also
POLYSHADE, PROJECT_VOL, RECON3, SHADE_VOLUME
WAIT IDL Reference Guide
WAIT
TheWAIT proceduresuspendsexecution of an IDL programfor aspecied period. Note
that becauseof other activity on thesystem, theduration of programsuspension may be
longer than requested.
Calling Sequence
WAIT, Seconds
Arguments
Seconds
The duration of the wait, specied in seconds. This parameter can be a oating-point
value to specify a fractional number of seconds.
Example
To makean IDL programsuspend execution for about veand onehalf seconds, usethe
command:
WAIT, 5.5
See Also
EXIT, STOP
IDL Reference Guide WARP_TRI
WARP_TRI
The WARP_TRI function returns an image array with a specied geometric correction
applied. Images are warped using control (tie) points such that locations (Xi, Yi) are
shifted to (Xo, Yo).
The irregular grid dened by (Xo, Yo) is triangulated using TRIANGULATE. Then the
surfacesdenedby(Xo, Yo, Xi) and(Xo, Yo, Yi) areinterpolatedusingTRIGRIDtoget the
locationsin theinput imageof each pixel in theoutput image. Finally, INTERPOLATEis
called to obtain the result. Linear interpolation is used by default. Smooth quintic
interpolation is used if the QUINTIC keyword is set.
warp_tri.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = WARP_TRI(Xo, Yo, Xi, Yi, Image)
Arguments
Xo, Yo
Vectors containing the locations of the control (tie) points in the output image.
Xi, Yi
Vectors containing the location of the control (tie) points in the input image. Xi and Yi
must be the same length asXo and Yo.
Image
The image to be warped. May be any type of data.
Keywords
OUTPUT_SIZE
Set this keyword equal to a 2-element vector containing the size of the output image. If
omitted, the output image is the same size asImage.
QUINTIC
Set thiskeyword tousesmooth quinticinterpolation. Quinticinterpolation isslower but
the derivatives are continuous across triangles, giving a more pleasing result than the
default linear interpolation.
EXTRAPOLATE
Set this keyword to extrapolate outside the convex hull of the tie points. Setting this
keyword implies the use of QUINTIC interpolation.
WARP_TRI IDL Reference Guide
See Also
INTERPOLATE, TRIANGULATE, TRIGRID
IDL Reference Guide WDELETE
WDELETE
The WDELETE procedure deletes IDL windows.
Calling Sequence
WDELETE[, Window_Index [, ...]]
Arguments
Window_Index
A list of one or more window indices to delete. If this argument is not specied, the
current window (as specied by the system variable !D.WINDOW) is deleted. If the
window being deleted is not the active window, the value of !D.WINDOW remains
unchanged. If thewindowbeingdeleted istheactivewindow, !D.WINDOWisset to the
highest numbered window index or to -1 if no windows remain open.
If this window index is the widget ID of a draw widget, that widget is deleted.
Example
Create IDL graphics window number 5 by entering:
WINDOW, 5
Delete window 5 by entering:
WDELETE, 5
See Also
WINDOW, WSET, WSHOW
WEOF IDL Reference Guide
WEOF
The WEOF procedure writes an end of le mark, sometimes called a tape mark, on the
designatedtapeunit at thecurrent position. WEOFisavailableonlyunder VMS. Thetape
must be mounted as a foreign volume. See VMS-Specic Information on page 217 of
Building IDL Applications.
Calling Sequence
WEOF, Unit
Arguments
Unit
Themagnetictapeunit on which theend of lemark iswritten. Thisargument must be
a number between 0 and 9, and should not be confused with standard le Logical Unit
Numbers (LUNs).
See Also
TAPWRT
IDL Reference Guide WF_DRAW
WF_DRAW
TheWF_DRAWproceduredrawsweather frontsof varioustypesusingparametricspline
interpolation to smooth the lines. WF_DRAW uses the POLYFILL routine to make the
annotations on the front lines.
wf_draw.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WF_DRAW, X, Y
Arguments
X, Y
Vectors of abcissae and ordinates dening the front to be drawn.
Keywords
COLD
Set this keyword to draw a cold front. The default is a plain line with no annotations. A
cold front can also be specied by setting the keyword FRONT_TYPE = 1.
COLOR
Use this keyword to specify the color to use. The default = !P.COLOR.
CONVERGENCE
Set this keyword to draw a convergence line. A convergence line can also be specied by
setting the keyword FRONT_TYPE = 5.
DATA
Set this keyword if X and Y are specied in data coordinates.
DEVICE
Set this keyword if X and Y are specied in device coordinates.
FRONT_TYPE
Set this keyword equal to the numeric index of type of front to draw. Front type indices
are as follows: COLD=1, WARM=2, OCCLUDED=3, STATIONARY=4,
CONVERGENCE = 5. Not required if plain line is desired or if an explicit front type
keyword is specied.
WF_DRAW IDL Reference Guide
INTERVAL
Use this keyword to specify the spline interpolation interval, in normalized units. The
default = 0.01. Larger valuesgivecoarser approximationsto curves, smaller valuesmake
more interpolated points.
NORM
Set this keyword if X and Y are specied in normalized coordinates. This is the default.
OCCLUDED
Set this keyword to draw an occluded front. An occluded front can also be specied by
PSYM
Set this keyword a standard PSYM value to draw a marker on each actual (X, Y) data
point. See PSYM on page105 for a list of the symbol types.
STATIONARY
Set this keyword to draw a stationary front. A stationary front can also be specied by
SYM_HT
Usethiskeyword to specify theheight of front symbols, in normalized units. Thedefault
= 0.02.
SYM_LEN
Usethiskeywordtospecifythelengthandspacingfactor for front symbols, innormalized
units. The default = 0.15.
THICK
Use this keyword to specify the line thickness. The default = 1.0.
WARM
Set thiskeyword to drawawarmfront. Awarmfront can also bespecied by settingthe
keyword FRONT_TYPE = 2.
Example
Draw a front given 3 points:
WF_DRAW, [40, 20, 40], [30, 40, 25], /COLD
See Also
ANNOTATE, XYOUTS
IDL Reference Guide WHERE
WHERE
The WHERE function returns a longword vector that contains the one-dimensional
subscriptsof thenonzeroelementsof Array_Expression. Thelengthof theresultingvector
is equal to the number of nonzero elements in the parameter. Frequently the result of
WHEREisused asavector subscript toselect elementsof an array usinggiven criteria. If
all elementsof Array_Expressionarezerotheresult of WHEREisascalar integer with the
value -1.
The system variable !ERR is set to the number of nonzero elements. This effect is for
compatibility with previousversionsof IDL and shouldnotbeused in newcode. Usethe
COUNT argument to return this value instead.
Calling Sequence
Result = WHERE(Array_Expression [, Count])
Arguments
Array_Expression
Thearray to besearched. Thisargument can beof any basictypeexcept string. Both the
real and imaginary parts of a complex number must be zero for the number to be
considered zero.
Count
A named variable that, on exit, is set to the number of nonzero elements found in
Array_Expression. This value is returned as a longword integer.
When WHERE Returns -1
If all the elements of Array_Expression are zero, WHERE returns a scalar integer with a
value of -1. Attempting to use this result as an index into another array results in a
subscriptsout of bounds error. In situationswherethisispossible, codesimilar to the
following can be used to avoid errors:
index = WHERE(array, count) UseCount to get thenumber of
nonzero elements.
IF count NE 0 THEN result = array[index]
Onlysubscriptthearrayifitssafe.
WHERE IDL Reference Guide
Example
array = FINDGEN(100) Createa 100-element, floating-
pointarraywhereeachelementis
set to thevalueof its subscript.
B = WHERE(array GT 20, count) Find thesubscripts of all theele-
mentsinthearraythathavevalues
greater than 20.
PRINT, count Printhowmanyelementsmetthe
search criteria.
PRINT, B Print thesubscripts of found ele-
ments.
values = array[B] Makeanarraycontainingtheval-
ues of array referred to by B.
Note TheWHEREfunction behavesdifferently with different kindsof array expressions.
For instance, if arelational operator isused to comparean array, A, with ascalar, B,
then everyelement of Aissearched for B. However, if arelational operator isused to
comparetwoarrays, CandD, thenacomparisonismadebetweeneachcorresponding
element (i.e. Ci & Di, Ci+1 & Di+1, etc) of the two arrays. If the two arrays have
different lengths then a comparison is only made up to the number of elements for
the shorter array.
a=[1,2,3,4,5,5,4,3,2,1] Comparearray, a, and
b=5 scalar, b
result=where(a eq b)
help,result & print,result
RESULT LONG = Array[2] Result=4,5 as expected
4 5
c=[1,2,3,4,5,5,4,3,2,1] Now comparetwo arrays
d=[0,2,4] of different lengths
result=where(c eq d)
help,result & print,result
RESULT LONG = Array[1] Result =1; not what
1 user would expect
See Also
UINT
IDL Reference Guide WIDGET_BASE
WIDGET_BASE
The WIDGET_BASE function is used to create base widgets. Base widgets serve as
containers for other widgets.
Note In most cases, you will want let IDL determine the placement of widgets within the
base widget. Do this by specifying either the COLUMN keyword or the ROW
keyword. See Positioning Child Widgets Within a Base on page1218 for details.
The returned value of this function is the widget ID of the newly-created base.
Calling Sequence
Result = WIDGET_BASE([Parent])
Arguments
Parent
Thewidget ID of theparent widget. To createatop-level base, omit theParent argument.
Keywords
ALIGN_BOTTOM
Set thiskeywordtoalign thenewwidget withthebottomof itsparent base. Totakeeffect,
the parent must be a ROW base.
ALIGN_CENTER
Set thiskeyword to align thenewwidget with thecenter of itsparent base. To takeeffect,
the parent must be a ROW or COLUMN base. In ROW bases, the new widget will be
vertically centered. In COLUMN bases, the new widget will be horizontally centered.
ALIGN_LEFT
Set thiskeywordtoalign thenewwidget withtheleft sideof itsparent base. Totakeeffect,
the parent must be a COLUMN base.
ALIGN_RIGHT
Set this keyword to align the new widget with the right side of its parent base. To take
effect, the parent must be a COLUMN base.
ALIGN_TOP
Set thiskeywordtoalign thenewwidget with thetopof itsparent base. Totakeeffect, the
parent must be a ROW base.
WIDGET_BASE IDL Reference Guide
APP_MBAR
Set thiskeyword toanamed variablethat denesawidget applicationsmenubar. On the
Macintosh, the menubar dened by APP_MBAR becomes the system menubar (the
menubar at the top of the Macintosh screen). On Motif platforms and under Microsoft
Windows, theAPP_MBARistreated in exactly thesamefashion asthemenubar created
with the MBAR keyword. See MBAR on page1209 for details on creating menubars.
Caution You cannot specify both an APP_MBAR and an MBAR for the same top-level base
widget. Doing so will cause an error.
Toapplyactionstriggeredbymenu itemstowidgetsother than thebasethat includesthe
menubar, use the KBRD_FOCUS_EVENTS keyword to keep track of which widget has
(or last had) the keyboard focus.
BASE_ALIGN_BOTTOM
Set thiskeywordtomakeall children of thenewbasealign themselveswiththebottomof
thebaseby default. To takeeffect, you must also set theROWkeyword for thenewbase.
The default can be overridden for individual child widgets by setting a different
ALIGN_XXX keyword when the child widget is created.
BASE_ALIGN_CENTER
Set thiskeyword to makeall children of thenewbasealign themselveswith thecenter of
thebaseby default. To takeeffect, you must also set theCOLUMN or ROWkeyword for
the new base. The default can be overridden for individual child widgets by setting a
different ALIGN_XXX keyword when the child widget is created. In ROW bases, child
widgetswill bevertically centered. In COLUMN bases, child widgetswill behorizontally
centered.
BASE_ALIGN_LEFT
Set this keyword to make all children of the new base align themselves with the left side
of thebasebydefault. Totakeeffect, youmust alsoset theCOLUMNkeywordfor thenew
base. The default can be overridden for individual child widgets by setting a different
BASE_ALIGN_RIGHT
Set thiskeyword to makeall children of thenewbasealign themselveswith theright side
of thebasebydefault. Totakeeffect, youmust alsoset theCOLUMNkeywordfor thenew
base. The default can be overridden for individual child widgets by setting a different
BASE_ALIGN_TOP
Set thiskeyword tomakeall children of thenewbasealign themselveswith thetop of the
baseby default. Totakeeffect, you must alsoset theROWkeyword for thenewbase. The
default can beoverridden for individual childwidgetsbysettingadifferent ALIGN_XXX
keyword when the child widget is created.
COLUMN
If this keyword is included, the base lays out its children in columns. The value of this
keywordspeciesthenumber of columnstobeused. Thenumber of childwidgetsineach
column is calculated by dividing the number of child widgets created by the number of
columns specied. When one column is lled, a new one is started.
Specifying both the COLUMN and ROW keywords causes an error.
Column Width
The width of each column is determined by the width of the widest widget in that
column. If the GRID_LAYOUT keyword is set, all columns are as wide as the widest
widget in the base.
Horizontal Size of Widgets
If any of the BASE_ALIGN_* keywords to WIDGET_BASE is set, each widget has its
natural width, determined either by thevalueof thewidget or by theXSIZEkeyword.
Similarly, if any of thechild widgetsspeciesoneof theALIGN_* keywords, that widget
will haveitsnatural width. If noneof theBASE_ALIGN_* or (ALIGN_*) keywordsare
set, all widgets in the base are as wide as their column.
Vertical Placement
Child widgets are placed vertically one below the other, with no extra space. If the
GRID_LAYOUT keyword is set, each row is as high as its tallest member.
DISPLAY_NAME
Set this keyword equal to a string that species the name of the X Windows display on
which the base should be displayed. This keyword has no effect on Microsoft Windows
and Macintosh platforms.
EVENT_FUNC
widget.
EVENT_PRO
A string containing the name of a procedure to be called by the WIDGET_EVENT
function when an event arrivesfromawidget in thewidget hierarchyrootedat thenewly-
created widget.
Note If thebaseisatop-level basewidget that ismanaged bytheXMANAGERprocedure,
any value specied via the EVENT_PRO keyword is overridden by the value of the
EVENT_HANDLER keyword to XMANAGER. Note also that in this situation, if
EVENT_HANDLER is not specied in the call to XMANAGER, an event-handler
name will be created by appending the string"_event" to the application name
speciedtoXMANAGER. Thismeansthat thereisnoreason tospecifythiskeyword
for a top-level base that will be managed by the XMANAGER procedure.
EXCLUSIVE
Set this keyword to specify that the base can have only button-widget children and that
only onebutton can beset at atime. Thesebuttons, unlikenormal button widgets, have
two statesset and unset.
When oneexclusivebutton ispressed, anyother exclusivebuttons(in thesamebase) that
arecurrentlyset areautomaticallyreleased. Hence, onlyonebutton can ever beset at one
time.
This keyword can be used to create exclusive button menus. See the CW_BGROUP and
CW_PDMENU functions for high-level menu-creation utilities.
FLOATING
Set this keywordalong with the GROUP_LEADER keywordto create a oating
top-level base widget. If the windowing system provides Z-order control, oating base
widgets appear above the base specied as their group leader. If the windowing system
does not provide Z-order control, the FLOATING keyword has no effect.
The iconizing, layering, and destruction behavior of oating bases and their group
leadersisdiscussed in Iconizing, Layering, and DestroyingGroupsof Top-Level Baseson
page1219.
FRAME
Thevalueof thiskeyword speciesthewidth of aframein unitsspecied by theUNITS
keyword (pixelsarethedefault) to bedrawn around thebordersof thewidget. Notethat
this keyword is only a hint to the toolkit, and may be ignored in some instances.
FUNC_GET_VALUE
A stringcontainingthenameof afunction to becalled when theGET_VALUEkeyword
to the WIDGET_CONTROL procedure is called for this widget. Using this technique
allowsyou to changethevaluethat should bereturned for awidget. Compound widgets
use this ability to dene their values transparently to the user.
GRID_LAYOUT
Set this keyword to force the base to have a grid layout, in which all rows have the same
height, and all columns have the same width. The row heights and column widths are
taken from the largest child widget.
GROUP_LEADER
The widget ID of an existing widget that serves as group leader for the newly-created
widget. Widget application hierarchies are dened by group membership relationships
between top-level widget bases. When agroup leader iskilled, for any reason, all widgets
in thegrouparealsodestroyed. Iconizingandlayeringbehavior isdiscussedin Iconizing,
Layering, and DestroyingGroupsof Top-Level Baseson page1219. (Thisisnot available
on the Mac.)
Note If youspecifyaoatingbase(createdwiththeFLOATINGkeyword) asagroupleader,
all member basesmust also haveeither theFLOATINGor MODAL keywordsset. If
you specify a modal base (created with the MODAL keyword) as a group leader, all
member bases must have the MODAL keyword set as well.
Agivenwidget canbeinmorethanonegroup. TheWIDGET_CONTROLprocedurecan
be used to add additional group associations to a widget. It is not possible to remove a
widget from an existing group.
KBRD_FOCUS_EVENTS
Set this keyword to make the base return keyboard focus events whenever the keyboard
focus of the base changes. See the Events section below for more information.
KILL_NOTIFY
Set this keyword to a string that contains the name of a procedure to be called
automatically when the specied widget dies. Each widget is allowed a single such
callback procedure. It can be removed by setting the routine to the null string ('').
Note that the procedure specied is used only if you are not using the XMANAGER
procedure to manage your widgets.
The callback routine is called with the widget identier as its only argument. At that
point, the widget identier can only be used with the WIDGET_CONTROL procedure
to get or set theuser value. All other requeststhat requireawidget ID aredisallowed for
the target widget. The callback is not issued until the WIDGET_EVENT function is
called.
If you usetheXMANAGERproceduretomanageyour widgets, thevalueof thiskeyword
isoverwritten. UsetheCLEANUPkeyword to XMANAGERto specify aprocedureto be
called when a managed widget dies.
MAP
Once a widget hierarchy has been realized, it can be mapped (visible) or unmapped
(invisible). This keyword species the initial map state for the given base and its
descendants. Specifyinganon-zerovalueindicatesthat thebaseshouldbemappedwhen
realized (the default). A zero value indicates that the base should be unmapped initially.
After the base is realized, its map state can be altered using the MAP keyword to the
WIDGET_CONTROL procedure.
Note Modal bases cannot be mapped and unmapped.
Caution Under Microsoft Windows, whenahiddenbaseisrealized, thenmapped, aWindows
resizemessageissent bythewindowingsystem. Thisextra resizeevent isgenerated
before any manipulation of the base widget by the user.
MBAR
Set this keyword to a named variable to cause a menubar to be placed at the top of the
base (the base must be a top-level base). The menubar is itself a special kind of base
widget that can onlyhavebuttonsaschildren. Upon return, thenamed variablecontains
the widget ID of the new menubar base. This widget ID can then be used to ll the
menubar with pulldown menus. For example, thefollowingwidget creation commands
rst create a base with a menubar, then populate the menubar with a simple pulldown
menu (CW_PDMENU could also have been used to construct the pulldown menu):
base = WIDGET_BASE(TITLE = 'Example', MBAR=bar)
file_menu = WIDGET_BUTTON(bar, VALUE='File', /MENU)
file_bttn1=WIDGET_BUTTON(file_menu, VALUE='Item 1',$
UVALUE='FILE1')
file_bttn2=WIDGET_BUTTON(file_menu, VALUE='Item 2',$
UVALUE='FILE2')
Notethat toset XWindowSystemresourcesfor menubarscreatedwiththiskeyword, you
must use the RNAME_MBAR keyword rather than the RESOURCE_NAME keyword.
If you use CW_PDMENU to create a menu for the menubar, be sure to set the MBAR
keyword to that function as well.
Note also that the size returned by the GEOMETRY keyword to WIDGET_INFO does
not include the size of the menubar.
Note Tocontrol thesystemmenubar on theMacintosh, usetheAPP_MBARkeyword. On
Windowsand Motif platformstheMBARand APP_MBARkeywordsareequivalent.
Caution You cannot specify both the MBAR and MODAL keywords for the same widget.
Doing so will cause an error.
Toapplyactionstriggeredbymenu itemstowidgetsother than thebasethat includesthe
menubar, use the KBRD_FOCUS_EVENTS keyword to keep track of which widget has
(or last had) the keyboard focus.
MODAL
Set this keyword to create a modal dialog. Modal dialogs can have default and cancel
buttonsassociatedwiththem. Default buttonsarehighlightedbythewindowsystemand
respond to apresson the Return or Enter keysasif they had been clicked on. Cancel
buttons respond to a press on the Escape key as if they had been clicked on. See the
DEFAULT_BUTTON and CANCEL_BUTTON keywords to WIDGET_CONTROL for
details.
Note Modal dialogs must have a group leader. Specify the group leader for a modal top-
level base via the GROUP_LEADER keyword.
Modal dialogscannot bescrollable, nor cantheysupport menubars. SettingtheSCROLL,
MBAR, or APP_MBARkeywordsinconjunctionwiththeMODALkeywordwill causean
error. Modal dialogs cannot be mapped or unmapped. Setting the MAP keyword on a
modal base will cause an error.
Note On Windowsplatforms, thegroupleader of amodal basemust berealizedbeforethe
modal baseitself can berealized. If thegroup leader hasnot been realized, it will be
realized automatically.
Theiconizing, layering, and destruction behavior of modal basesand their group leaders
is discussed in Iconizing, Layering, and Destroying Groups of Top-Level Bases on
page1219.
NO_COPY
Usually, when settingor gettingwidget user values, either at widget creation or usingthe
SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a
second copy of thedatabeingtransferred. Although thistechniqueisnefor small data,
it can have a signicant memory cost when the data being copied is large.
If the NO_COPY keyword is set, IDL handles these operations differently. Rather than
copy thesourcedata, it takesthedataaway fromthesourceand attachesit directly to the
destination. This feature can be used by compound widgets to obtain state information
fromaUVALUEwithout all thememory copyingthat would otherwiseoccur. However,
it has the side effect of causing the source variable to become undened. On a set
operation (using the UVALUE keyword to WIDGET_BASE or the SET_UVALUE
keyword to WIDGET_CONTROL), thevariablepassed asvaluebecomesundened. On
a get operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of
the widget in question becomes undened.
NONEXCLUSIVE
Set this keyword to specify that the base can only have button widget children. These
buttons, unlike normal button widgets, have two statesset and unset. Non-exclusive
bases allow any number of the toggle buttons to be set at one time. If neither the ROW
nor the COLUMN keyword is specied, the non-exclusive widget base is set to the
column base by default.
NOTIFY_REALIZE
automatically when the specied widget is realized. This callback occurs just once
(becausewidgetsarerealized only once). Each widget isallowed asinglesuch callback
procedure. It can be removed by setting the routine to the null string (''). The callback
routine is called with the widget ID as its only argument.
PRO_SET_VALUE
Astringcontainingthenameof aproceduretobecalled when theSET_VALUEkeyword
allowsyou todesignatearoutinethat setsthevaluefor awidget. Compound widgetsuse
this ability to dene their values transparently to the user.
RESOURCE_NAME
A string containing an X Window System resource name to be applied to the widget.
Oncedened, thisnamecan beused in theusers.Xdefaults leto customizewidget
resourcesnot directlysupportedviatheIDLwidget routines. Thiskeywordisacceptedby
all widget creation routines. Thiskeyword onlyworkswith theX deviceand isignored
on platforms that do not use the X Window System (i.e., IDL for Windows, IDL for
Macintosh).
RESOURCE_NAME allows unrestricted access to the underlying Motif widgets within
the following limitations:
Usersmust havetheappropriateresourcesdenedintheir .Xdefaultsor application
default resource le, or IDL will not see the denitions and they will not take effect.
Motif resourcesaredocumented in theOSF/Motif ProgrammersReferenceManual. To
usethemwith RESOURCE_NAME, theIDL programmer must determinethetypeof
widget beingused by IDL, and then look up theresourcesthat apply to them. Hence,
RESOURCE_NAME requires some programmer-level familiarity with Motif.
Only resources that are not set within IDL can be modied using this mechanism.
Althoughit isnot an error toset resourcesalsoset byIDL, theIDLsettingswill silently
overrideuser settings. ResearchSystemsdoesnot document theresourcesusedbyIDL
since the actual resources used may differ from release to release as the IDL widgets
evolve. Therefore, you should set only thoseresourcesthat areobviously not beingset
byIDL. Amongtheresourcesthat arenot beingset byIDLarethosethat control colors,
menu mnemonics, and accelerator keys.
Example The sample code below produces a pulldown menu named Menu with 2 entries
named Item 1 and Item 2.
UsingtheRESOURCE_NAMEkeyword in conjunction with Xresourcedenitions,
wecan alter Item1 in several waysnot possiblethrough thestandard IDL widgets
interface. Well give Item 1 a red background color. Well also assign I as the
keyboard mnemonic. Notethat Motif automaticallyunderlinesthe I in thetitleto
indicatethis. Well alsoselect Meta-F4asthekeyboardaccelerator for selecting Item
1. If Meta-F4ispressedwhilethepointer isanywhereover thisapplication, theeffect
will be as if the menu was pulled down and Item 1 was selected with the mouse.
PRO test_event, ev Simpleevent handler.
HELP, /STRUCTURE, ev
END
PRO test Simplewidget creation routine.
a = WIDGET_BASE(RESOURCE_NAME = 'test')
Thebasegets theresourcename
test.
b = WIDGET_BUTTON(a, VALUE='Menu', /MENU)
c = WIDGET_BUTTON(b, VALUE='Item 1', $
RESOURCE_NAME='item1') Assign theItem 1 button there-
sourcenameitem1.
c = WIDGET_BUTTON(b, VALUE='Item 2')
WIDGET_CONTROL, /REALIZE, a
XMANAGER, 'test', a
END
Notethat wegavetheoverall application theresourcenametest, and the Item1
button the resource name item1. Now we can use these names in the following
.Xdefaults le entries:
Idl*test*item1*mnemonic: I
Idl*test*item1*accelerator: Meta<Key>F4
Idl*test*item1*acceleratorText: Meta-F4
Idl*test*item1*background: red
Note on Specifying Color Resources
If you wish to specify unique colors for your widgets, it is generally a good idea to use a
color name (red or lightblue, for example) rather than specifying an exact color
match with a color string (such as #b1b122222020 ). If IDL is not able to allocate an
exact color, theentireoperation mayfail. Specifyinganamed color impliesclosest color
match, an operation that rarely fails.
If you need an exact color match and IDL fails to allocate the color, try modifying the
Idl.colors resource in the$IDL_DIR/resource/X11/lib/app-defaults/Idl
le.
RNAME_MBAR
A string containing an X Window System resource name to be applied to the menubar
created by the MBAR keyword. This keyword is identical to the RESOURCE_NAME
keyword except that the resource it species applies only to the menubar.
ROW
If this keyword is included, the base lays out its children in rows. The value of this
keyword species the number of rows to be used. The number of child widgets in each
rowiscalculated by dividingthenumber of child widgetscreated by thenumber of rows
specied. When one row is lled, a new one is started.
Specifying both the COLUMN and ROW keywords causes an error.
Row Height
Theheight of each rowisdetermined bytheheight of thetallest widget in that row. If the
GRID_LAYOUT keyword is set, all rows are as tall as the tallest widget in the base.
Vertical Size of Widgets
If any of the BASE_ALIGN_* keywords to WIDGET_BASE is set, each widget has its
natural height, determined either by thevalueof thewidget or by theYSIZEkeyword.
Similarly, if any of thechild widgetsspeciesoneof theALIGN_* keywords, that widget
will haveitsnatural height. If noneof theBASE_ALIGN_* or (ALIGN_*) keywordsare
set, all widgets in the base are as tall as their row.
Horizontal Placement
Child widgets are placed horizontally one next to the other, with no extra space. If the
GRID_LAYOUT keyword is set, each column is as wide as its widest member.
SCR_XSIZE
Set this keyword to the desired screen width of the widget, in units specied by the
UNITS keyword (pixels are the default). In many cases, setting this keyword is the same
as setting the XSIZE keyword.
SCR_YSIZE
Set this keyword to the desired screen height of the widget, in units specied by the
as setting the YSIZE keyword.
SCROLL
Set this keyword to give the widget scroll bars that allow viewing portions of the widget
contents that are not currently on the screen.
Note For theMacintosh, if you set XSIZEor YSIZEtoavaluelessthan 48, thebasecreated
with the SCROLL keyword will be a minimum of 48x48. If you have not specied
valuesfor XSIZEor YSIZE, thebasewill beset toaminimumof 66x66. If thebaseis
resized, it will jump to the minimum size of 128x64.
Caution You cannot specify both the SCROLL and MODAL keywords for the same widget.
Doing so will cause an error.
SENSITIVE
Set this keyword to control the initial sensitivity state of the widget.
If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive.
When a widget is sensitive, it has normal appearance and can receive user input. For
example, a sensitive button widget can be activated by moving the mouse cursor over it
and pressing a mouse button. When a widget is insensitive, it indicates the fact by
changing its appearance, looking disabled, and it ignores any input.
Sensitivity can beused to control when auser isallowed to manipulatethewidget. Note
that some widgets do not change their appearance when they are made insensitive, but
they cease generating events.
After creating the widget hierarchy, you can change the sensitivity state using the
SENSITIVE keyword with the WIDGET_CONTROL procedure.
SPACE
The space, in units specied by the UNITS keyword (pixels are the default), between
childrenof arowor columnmajor base. Thiskeywordisignoredif either theEXCLUSIVE
or NONEXCLUSIVE keyword is present.
TITLE
A string containing the title to be used for the widget. Base widgets use the title only if
they are top-level widgets.
Notethat if thewidget baseisnot wideenough tocontain thespecied title, thetitlemay
appear truncated. If you must be able to see the full title, you have several alternatives:
Rearrangethewidgetsinthebasesothat thebasebecomesnaturallywideenough. This
is the best solution.
Dont worryabout thisissue. If theuser needstoseetheentirelabel, theycan resizethe
window using the mouse.
Createthebasewithout usingtheCOLUMNor ROWkeywords. Instead, usetheXSIZE
keyword to explicitly set a usable width. This is an undesirable solution that can lead
to strange-looking widget layouts.
TLB_FRAME_ATTR
Set thiskeyword tooneof thevaluesshown in thetablebelowtosuppresscertain aspects
of a top-level bases window frame. This keyword applies only to top-level bases. The
settings are merely hints to the window system and may be ignored by some window
managers. Valid settings are:
This keyword is set bitwise, so multiple effects can be set by adding values together. For
example, tomakeabasethat hasnotitlebar (setting4) andcannot bemoved(setting16),
set the TLB_FRAME_ATTR keyword to 4+16, or 20.
Note For the Macintosh, you can not suppress the title bar; only modal dialogs use a
windowwithout atitlebar. Anyother useof asuppressedtitlebar wouldbecontrary
to Macintosh Human InterfaceGuidelinesand would createan immovablewindow.
TLB_KILL_REQUEST_EVENTS
Set this keyword, usable only with top-level bases, to send the top-level base a
WIDGET_KILL_REQUEST event if a user tries to destroy the widget using the window
manager (by default, widgets are simply destroyed). See the Events section below for
more information.
Usethiskeywordtoperformcomplexactionsbeforeallowingawidget applicationtoexit.
Note that widgets that have this keyword set are responsible for killing themselves after
receivingaWIDGET_KILL_REQUESTeventtheycannot bedestroyedusingtheusual
window system controls.
Useacall to TAG_NAMESwith theSTRUCTURE_NAMEkeyword set to differentiatea
WIDGET_KILL_REQUEST event from other types of widget events. For example:
IF TAG_NAMES(event, /STRUCTURE_NAME) EQ $
'WIDGET_KILL_REQUEST' THEN ...
Value Meaning
1 Base cannot be resized, minimized, or maximized.
2 Suppress display of system menu.
4 Suppress title bar.
8 Base cannot be closed.
16 Base cannot be moved.
Table 9-70: Valid Values for TLB_FRAME_ATTR Keyword
TLB_SIZE_EVENTS
Set thiskeyword, when creatingatop-level base, to makethat basereturn an event when
the base is resized by the user. See the Events section below for more information.
TRACKING_EVENTS
Set thiskeyword tocausewidget trackingeventstobeissued for thewidget whenever the
mousepointer entersor leavestheregion covered by that widget. Widget trackingevents
are returned as structures with the following denition:
{ WIDGET_TRACKING, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }
ID, TOP, and HANDLER are the standard elds found in every widget event. ENTER is
1 if the tracking event is an entry event, and 0 if it is an exit event.
UNAME
Set thiskeyword to astringthat can beused to identify thewidget in your code. You can
associateanamewitheachwidget inaspecichierarchy, andthenusethat nametoquery
the widget hierarchy and get the correct widget ID.
To query the widget hierarchy, use the WIDGET_INFO function with the
FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy
because the FIND_BY_UNAME keyword returns the ID of the rst widget with the
specied name.
UNITS
Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the
default), to1(one) tospecifythat all measurementsarein inches, or to2(two) tospecify
that all measurements are in centimeters.
UVALUE
Each widget can contain a user-specied value of any data type and organization. This
value is not used by the widget in any way, but exists entirely for the convenience of the
IDL programmer. This keyword allows you to set this value when the widget is rst
created.
If UVALUE is not present, the widgets initial user value is undened.
The user value for a widget can be accessed and modied at any time by using the
GET_UVALUE and SET_UVALUE keywords to the WIDGET_CONTROL procedure.
XOFFSET
The horizontal offset of the widget in units specied by the UNITS keyword (pixels are
the default) relative to its parent.
Specifyingan offset relativetoarowor column major basewidget doesnot work because
thosewidgetsenforcetheir own layout policies. Thiskeyword isprimarily of userelative
to a plain base widget. Note that it is best to avoid using this style of widget layout.
XPAD
The horizontal space, in units specied by the UNITS keyword (pixels are the default),
between child widgetsand theedgesof arowor column major base. Thedefault valueof
XPAD is platform dependent. This keyword is ignored if either the EXCLUSIVE or
NONEXCLUSIVE keyword is present.
XSIZE
Thewidth of thewidget in unitsspecied bytheUNITSkeyword (pixelsarethedefault).
Most widgetsattempt tosizethemselvestot thesituation. However, if thedesired effect
is not produced, use this keyword to override it. This keyword is only a hint to the
toolkit and may be ignored in some situations.
X_SCROLL_SIZE
The XSIZE keyword always species the width of a widget. When the SCROLL keyword
is specied, this size is not necessarily the same as the width of the visible area. The
X_SCROLL_SIZE keyword allows you to set the width of the scrolling viewport
independently of the actual width of the widget.
Use of the X_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will
be added in both the horizontal and vertical directions when X_SCROLL_SIZE is
specied. Becausethedefault sizeof thescrollingviewport maydiffer between platforms,
it is best to specify Y_SCROLL_SIZE when specifying X_SCROLL_SIZE.
YOFFSET
The vertical offset of the widget in units specied by the UNITS keyword (pixels are the
default) relativetoitsparent. Thisoffset isspeciedrelativetotheupper leftcorner of the
parent widget.
YPAD
The vertical space, in units specied by the UNITS keyword (pixels are the default),
between child widgetsand theedgesof arowor column major base. Thedefault valueof
YPAD is platform-dependent. This keyword is ignored if either the EXCLUSIVE or
NONEXCLUSIVE keyword is present.
YSIZE
Theheight of thewidget in unitsspeciedbytheUNITSkeyword(pixelsarethedefault).
Y_SCROLL_SIZE
TheYSIZEkeyword alwaysspeciestheheight of awidget. When theSCROLL keyword
is specied, this size is not necessarily the same as the height of the visible area. The
Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport
independently of the actual height of the widget.
Use of the Y_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will
be added in both the horizontal and vertical directions when Y_SCROLL_SIZE is
it is best to specify X_SCROLL_SIZE when specifying Y_SCROLL_SIZE.
Keywords to WIDGET_CONTROL
Anumber of keywordstotheWIDGET_CONTROL procedureaffect thebehavior of base
widgets. In addition tothosekeywordsthat affect all widgets, thefollowingareparticularly
useful: CANCEL_BUTTON, DEFAULT_BUTTON, KBRD_FOCUS_EVENTS.
Keywords to WIDGET_INFO
A number of keywords to the WIDGET_INFO function return information that applies
specificallytobasewidgets. Inadditiontothosekeywordsthat applytoall widgets, thefollowing
are particularly useful: KBRD_FOCUS_EVENTS, MODAL, TLB_KILL_REQUEST_EVENTS.
Exclusive And Non-Exclusive Bases
If the EXCLUSIVE or NONEXCLUSIVE keywords are specied, the base only allows
button widget children.
Positioning Child Widgets Within a Base
Thestandardbasewidget doesnot imposeanyplacement constraintsonitschildwidgets.
Childrenof a bulletinboard base(abasethat wascreatedwithout settingtheCOLUMN
or ROW keywords) have an offset of (0,0) unless an offset is explicitly specied via the
XOFFSETor YOFFSETkeywords. Thismeansthat if youdonot specifyanyof COLUMN,
ROW, XOFFSET, or YOFFSET keywords, child widgets will be placed one on top of the
other in the upper left corner of the base.
However, layingout widgetsusingtheXSIZE, YSIZE, XOFFSET, andYOFFSETkeywords
can beboth tediousanderror-prone. Also, if you want your widget application todisplay
properly on different platforms, you should use the COLUMN and ROW keywords to
inuence child widget layouts instead of explicitly formatting your interfaces.
When theROWor COLUMN keywordsarespecied, thebasedecideshowto lay out its
children, and any XOFFSET and YOFFSET keywords specied for such children are
ignored.
Positioning Top-Level Bases
When locating a new top level window, some window managers ignore the programs
positioning requests and either choose a position or allow the user to choose. In such
cases, theXOFFSET and YOFFSET keywordsto WIDGET_BASEwill not havean effect.
The window manager may provide a way to disable this positioning style. The Motif
window manager (mwm) can be told to honor positioning requests by placing the lines:
Mwm*clientAutoPlace: False
Mwm*interactivePlacement: False
in your .Xdefaults le.
Iconizing,Layering,andDestroyingGroupsofTop-LevelBases
Group membership (dened via the GROUP_LEADER keyword) controls the way top-
level base widgets are iconized, layered, and destroyed.
Note Agroupcan contain sub-groups. Groupbehavior affectsall membersof agroupand
itssub-groups. For example, supposewecreatethreetop-level basewidgetswith the
following group hierarchy:
base1 = WIDGET_BASE()
base2 = WIDGET_BASE(GROUP_LEADER=base1)
base3 = WIDGET_BASE(GROUP_LEADER=base2)
Effectively, two groupsarecreated. Onegroup hasbase2 asitsleader and base3 as
itsmember. Theother group hasbase1 asitsleader and both base2 and base3 as
members. If base1 isiconized, bothbase2 andbase3 areiconizedaswell. If base2
is iconized, base3 is iconized but base1 is not.
Widgetsbehaveslightlydifferentlywhendisplayedondifferent platforms, anddepending
on whether they are oating or modal bases. The following rules apply to groups of
widgetswithin agroupleader/member hierarchy. Widgetsthat donot belongtothesame
group hierarchy cannot inuence each other.
Iconization and Mapping
On Motif and Windows platforms, bases and groups of bases can beiconized (or
minimized) by clicking the system minimize control. Minimization has no meaning on
theMacintosh. On all platforms, basesandgroupsof basescan bemapped(madevisible)
and unmapped (made invisible).
Motif
When agroup leader isiconized or unmapped, all membersof thegroup areiconized or
unmapped as well. Similarly, when a group leader is restored, all members of the group
are restored.
Floating and modal bases cannot be iconized or unmapped independently. When the
group leader of a oating or modal base is iconized, a single icon is created for both the
group leader and the oating or modal base. When the group leader of a oating or
modal base is unmapped, both the group leader and oating or modal base are made
invisible.
Windows
When agroup leader isiconized or unmapped, all membersof thegroup areiconized or
unmapped as well. Similarly, when a group leader is restored, all members of the group
are restored.
When a oating base is iconized, its group leader is iconized as well and a single icon is
created. When a oating base is unmapped, its group leader is unmapped as well.
Modal bases cannot be iconized or unmapped. Other bases cannot be iconized or
unmapped until the modal base is dismissed.
Macintosh
On the Macintosh, iconization has no meaning.
When a oating base is unmapped, its group leader is unmapped as well.
Modal bases cannot be unmapped. Other bases cannot be unmapped until the modal
base is dismissed.
Layering
Layeringis the process by which groups of widgets seem to share the same plane on the
display screen. Within a layer on the screen, widgets have aZ-order, or front-to-back
order, that denes which widgets appear to be on top of other widgets.
Motif
All elements on the screenwidgets, the IDLDE, other Motif applicationsshare a
single layer and have an arbitrary Z-order. There is no special layering of IDL widgets.
Windows and Macintosh
All non-oatingandnon-modal widgetswithin agrouphierarchysharethesamelayer
that is, when onegroup member hastheinput focus, all membersof thegroup hierarchy
are displayed in a layer that appears in front of all other groups or applications. Within
the layer, the widgets can have an arbitrary Z-order.
Widgets that are oating or modal always oat above their group leaders.
Destruction
When a group leader widget is destroyed, either programmatically or by clicking on the
systemclose button, all membersof thegroup and all sub-groupsaredestroyed aswell.
If amodal baseison thedisplay, it must bedismissed beforeanywidget can bedestroyed.
Events
Resize Events
Top-level widget basesreturn thefollowingevent structureonlywhen theyareresized by
the user and the base was created with the TLB_SIZE_EVENTS keyword set:
{ WIDGET_BASE, ID:0L, TOP:0L, HANDLER:0L, X:0, Y:0 }
IDisthewidget IDof thebasegeneratingtheevent. TOPisthewidget IDof thetop level
widget containing ID. HANDLER contains the widget ID of the widget associated with
the handler routine. The X and Y elds return the new width of the base, not including
any frame provided by the window manager.
Keyboard Focus Events
Widget basesreturn thefollowingevent structurewhen thekeyboard focuschangesand
the base was created with the KBRD_FOCUS_EVENTS keyword set:
{ WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }
thehandler routine. TheENTEReld returns1(one) if thebaseisgainingthekeyboard
focus, or 0 (zero) if the base is losing the keyboard focus.
Kill Request Events
Top-level widget bases return the following event structure only when a user tries to
destroy the widget using the window manager and the base was created with the
TLB_KILL_REQUEST_EVENTS keyword set:
{ WIDGET_KILL_REQUEST, ID:0L, TOP:0L, HANDLER:0L }
the handler routine.
See Also
Widgets on page 271 of Building IDL Applications.
WIDGET_BUTTON IDL Reference Guide
WIDGET_BUTTON
The WIDGET_BUTTON function creates button widgets.
The returned value of this function is the widget ID of the newly-created button.
Calling Sequence
Result = WIDGET_BUTTON(Parent)
Arguments
Parent
The widget ID of the parent for the new button widget.
Keywords
ALIGN_CENTER
Set this keyword to center justify the buttons text label.
ALIGN_LEFT
Set this keyword to left justify the buttons text label.
ALIGN_RIGHT
Set this keyword to right justify the buttons text label.
BITMAP
Set this keyword to specify that the bitmap specied with the VALUE keyword is a color
bitmap. Thevalueof awidget button can beabitmap asdescribed belowunder Bitmap
Button Labels. If you specify acolor bitmap with theVALUEkeyword, you must alsoset
the /BITMAP keyword.
DYNAMIC_RESIZE
Set thiskeywordtocreateawidget that resizesitself tot itsnewvaluewhenever itsvalue
ischanged. Notethat thiskeyword doesnot takeeffect when used with theSCR_XSIZE,
SCR_YSIZE, XSIZE, or YSIZE keywords. If one of these keywords is also set, the widget
will be sized as specied by the sizing keyword and will never resize itself dynamically.
EVENT_FUNC
widget.
IDL Reference Guide WIDGET_BUTTON
EVENT_PRO
created widget.
FONT
Thenameof thefont tobeused by thewidget. Thefont specied isadevicefont (an X
Windowsfont onMotif systems; aTrueTypeor PostScript font onWindowsor Macintosh
systems). See About Device Fonts on page72 for details on specifying names for device
fonts. If this keyword is omitted, the default font is used.
Note On Microsoft Windows platforms, if FONT is not specied, IDL uses the system
default font. Different versions of Windows use different system default fonts; in
general, thesystemdefault font isthefont appropriatefor theversion of Windowsin
question.
FRAME
FUNC_GET_VALUE
GROUP_LEADER
widget. When a group leader is killed, for any reason, all widgets in the group are also
destroyed.
HELP
Set thiskeywordtotell thewidget toolkit that thisbuttonisa help buttonfor amenubar
andshouldbegiven that appearance. For example, Motif speciesthat thehelpmenubar
item is displayed on the far right of the menubar. This keyword is ignored in all other
contexts and may be ignored by window managers (including that for the Macintosh)
that have no such special appearance dened.
KILL_NOTIFY
called.
MENU
The presence of this keyword indicates that the button will be used to activate a pull-
downmenu. Suchbuttonscanhavebuttonchildrenthat arethenplacedintoapull-down
menu.
Under Motif, if the value specied for MENU is greater than 1, the button label is
enclosed in a box to indicate that this button is a pull-down menu. See the
CW_PDMENU function for a high-level pull-down menu creation utility.
NO_COPY
copy thesourcedata, it takesthedataaway fromthesourceand attachesit directly tothe
operation (using the UVALUE keyword to WIDGET_BUTTON or the SET_UVALUE
NO_RELEASE
Set thiskeyword tomakeexclusiveand non-exclusivebuttonsgenerateonlyselectevents.
This keyword has no effect on regular buttons.
NOTIFY_REALIZE
PRO_SET_VALUE
RESOURCE_NAME
Astringcontainingan XWindowSystemresourcenameto beapplied to thewidget. See
RESOURCE_NAME on page1211 for a complete discussion of this keyword.
SCR_XSIZE
SCR_YSIZE
SENSITIVE
SEPARATOR
Set thiskeywordtotell thewidget toolkit that thisbuttonispart of apulldownmenupane
and that a separator line should be added directly above this entry. This keyword is
ignored in all other contexts.
TRACKING_EVENTS
mouse pointer enters or leaves the region covered by that widget. For the structure of
tracking events, see TRACKING_EVENTS on page1216 in the documentation for
WIDGET_BASE.
UNAME
specied name.
UNITS
UVALUE
created.
VALUE
The initial value setting of the widget. The value of a widget button is the label for that
button. Thislabel can beastringor abitmap asdescribed belowunder Bitmap Button
Labels. If you specify the lename for a color bitmap, you must also set the /BITMAP
keyword.
Note Under Microsoft Windows, includingtheampersand character (&) in thevalueof a
button widget causesthewindowmanager toplacean underlineunder thecharacter
following the ampersand. (This is a feature of Microsoft Windows, and is generally
used to indicatewhich character isused asakeyboard accelerator for thebutton.) If
you are designing an application that will run on different platforms, you should
avoid the use of the ampersand in button value strings.
X_BITMAP_EXTRA
When creating a bitmap button that is not of a byte-aligned size (i.e., a dimension is
not amultipleof 8), thiskeywordspecieshowmanybitsof thesuppliedbitmapmust be
ignored(withintheendbyte). For example, tocreatea10by8bitmap, youneedtosupply
a 2 by 8 array of bytes and ignore the bottom 6 bits. Therefore, you would specify
X_BITMAP_EXTRA = 6.
XOFFSET
toaplain basewidget. Notethat it isbest toavoidusingthisstyleof widget programming.
XSIZE
YOFFSET
parent widget.
YSIZE
A number of keywords to the WIDGET_CONTROL procedure affect the behavior of
button widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: DYNAMIC_RESIZE, GET_VALUE, INPUT_FOCUS,
SET_BUTTON, SET_VALUE, X_BITMAP_EXTRA.
Some keywords to the WIDGET_INFO function return information that applies
specicallytobutton widgets. In addition tothosekeywordsthat applytoall widgets, the
following are particularly useful: DYNAMIC_RESIZE.
Exclusive And Non-Exclusive Bases
Buttons placed into exclusive or non-exclusive bases (created via the EXCLUSIVE or
NONEXCLUSIVE keywords to WIDGET_BASE procedure) are created as two-state
toggle buttons, which are controlled by such bases.
Events Returned by Button Widgets
Pressing the mouse button while the mouse cursor is over a button widget causes the
widget to generate an event. The event structure returned by the WIDGET_EVENT
function is dened by the following statement:
{WIDGET_BUTTON, ID:0L, TOP:0L, HANDLER:0L, SELECT:0}
ID is the widget id of the button generating the event. TOP is the widget ID of the top
level widget containing ID. HANDLER contains the widget ID of the widget associated
with the handler routine. SELECT is set to 1 if the button was set, and 0 if released.
Normal buttons do not generate events when released, so SELECT will always be 1.
However, togglebuttons(created by parentingabutton to an exclusiveor non-exclusive
base) return separate events for the set and release actions.
Bitmap Button Labels
In addition to using a text string as the label of a button (set via the VALUE keyword), a
button can have a bitmap label. This allows buttons to contain a graphic symbol. The
bitmap isspecied viatheVALUEkeyword. If you specify acolor bitmap, you must also
specify the /BITMAP keyword, like this:
button=WIDGET_BUTTON ( base, VALUE='mybitmap.bmp', /BITMAP )
To modify the color bitmap after creation, use the /BITMAP keyword with
WIDGET_CONTROL, like this:
WIDGET_CONTROL, button. SET_VALUE='mybitmap2.bmp', /BITMAP
You can produce appropriate bitmaps in the following ways:
On Windows, create a color bitmap using the IDL GUIBuilder Bitmap Editor, which
creates 16 color bitmaps for buttons. The Bitmap Editor can read and write bitmap les
(*.bmp). Using the editor, you can create your own bitmaps, or you can open existing
bitmap les and modify them. Open the Bitmap Editor from the Properties dialog for a
createdbutton. For moreinformation, see UsingtheBitmapEditor onpage174of Using
IDL.
Use any color bitmap editor available on your operating system.
Createablack and whitebitmap usingan external bitmap editor, and read it into an IDL
bytearrayusingtheappropriateprocedure(READ_BMP, READ_PICT, etc.) andconvert
the byte array to a bitmap byte array using the CVTTOBM function.
On an X-Window system, use the X11 bitmap utility to create a black and white bitmap
byte array and read it in to IDL using the READ_X11_BITMAP routine.
Createablack and whitebitmap usingtheXBM_EDIT procedure. Thisprocedureoffers
several alternatives for the form of the nal bitmap.
AlthoughIDLplacesnorestrictiononthesizeof bitmapallowed, thevarioustoolkitsmay
prefer certain sizes.
See Also
CW_BGROUP, CW_PDMENU
WIDGET_CONTROL IDL Reference Guide
WIDGET_CONTROL
The WIDGET_CONTROL procedure is used to realize, manage, and destroy widget
hierarchies. It is often used to change the default behavior or appearance of previously-
realized widgets.
Calling Sequence
WIDGET_CONTROL [, Widget_ID]
Arguments
Widget_ID
The widget ID of the widget to be manipulated. This argument is required by all
operations, unless the description of the specic keyword states otherwise. Note that if
Widget_ID is not provided for a keyword that needs it, that keyword is quietly ignored.
Keywords
Not all keywords to WIDGET_CONTROL apply to all combinations of widgets. In the
followinglist, descriptionsof keywordsthat affect onlycertain typesof widgetsincludea
list of the widgets for which the keyword is useful.
ALIGNMENT
This keyword applies to widgets created with the WIDGET_TABLE function.
Set thiskeyword equal toascalar or 2-Darrayspecifyingthealignment of thetext within
each cell. An alignment of 0(thedefault) alignstheleft edgeof thetext with theleft edge
of thecell. An alignment of 2right-justiesthetext, while1resultsin text centeredwithin
the cell. If ALIGNMENT is set equal to a scalar, all table cells are aligned as specied. If
ALIGNMENT is set equal to a 2-D array, the alignment of each table cell is governed by
thecorrespondingelement of thearray. If theUSE_TABLE_SELECT keywordisset, then
the alignment is changed only for the selected cells.
ALL_TABLE_EVENTS
Along with the EDITABLE keyword, ALL_TABLE_EVENTS controls the type of events
generatedbythetablewidget. Set theALL_TABLE_EVENTSkeywordtocausethefull set
of events to be generated. If ALL_TABLE_EVENTS is not set, setting EDITABLE causes
only end-of-line events to be generated (which could be used by the programmer as an
indication to check the cell value or to set the currently selected cell to the next cell). If
EDITABLEisnot set, all eventsaresuppressed. SeeTable9-71for additional details. Note
that the equivalent keyword in the WIDGET_TABLE creation routine is called
ALL_EVENTS.
IDL Reference Guide WIDGET_CONTROL
ALL_TEXT_EVENTS
This keyword applies to widgets created with the WIDGET_TEXT function.
Along with the EDITABLE keyword, ALL_TEXT_EVENTS controls the type of events
generated by the text widget. Set the ALL_TEXT_EVENTS keyword to cause the full set
of events to be generated. If ALL_TEXT_EVENTS is not set, setting EDITABLE causes
onlyend-of-lineeventstobegenerated. If EDITABLEisnot set, all eventsaresuppressed.
See Table 9-72 for additional details. Note that the equivalent keyword in the
WIDGET_TEXT creation routine is called ALL_EVENTS.
AM_PM
FORMAT keyword.
Keywords Effects
ALL_TABLE_EVENTS EDITABLE
Input changes
widget contents?
Type of events
generated.
Not set Not set No None
Not set Set Yes End-of-line insertion
Set Not set No All events
Set Set Yes All events
Table 9-71: Effects of using the ALL_TABLE_EVENTS and EDITABLE keywords.
Keywords Effects
ALL_TEXT_EVENTS EDITABLE
Input changes
widget contents?
Type of events
generated.
Table 9-72: Effects of using the ALL_TEXT_EVENTS and EDITABLE keywords.
APPEND
When usingtheSET_VALUEkeywordtoset thecontentsof atext widget (ascreatedwith
the WIDGET_TEXT procedure), setting this keyword indicates that the supplied text
should be appended to the existing contents of the text widget rather than replace it.
BAD_ID
This keyword applies to all widgets.
If Widget_ID is not a valid widget identier, this WIDGET_CONTROL normally issues
an error and causes program execution to stop. However, if BAD_ID is present and
species a named variable, the invalid ID is stored into the variable, and this routine
quietly returns. If no error occurs, a zero is stored.
CANCEL_BUTTON
This keyword applies to widgets created with the WIDGET_BASE function using the
MODAL keyword.
Set thiskeyword equal to thewidget ID of abutton widget that will bethecancel button
on amodal basewidget. Pressingthe Escape keyon thekeyboardwhen amodal widget
is on the screen is the same as clicking the button. On Motif and Windows platforms,
selecting close from the system menu (generally located at the upper left of the base
widget) generates a button event for the Cancel button.
CLEAR_EVENTS
If set, any events generated by the widget hierarchy rooted at Widget_ID which have
arrivedbut havenot beenprocessed(viatheWIDGET_EVENTprocedure) arediscarded.
COLUMN_LABELS
Set this keyword equal to an array of strings to be used as labels for the columns of the
table. If no label isspecied for acolumn, it receivesthedefault label Column n where
n is the column number. If this keyword is set to the empty string (''), all column labels
are set to be empty.
COLUMN_WIDTHS
Set this keyword equal to an array of widths for the columns of the table widget. The
widths are given in any of the units as specied with the UNITS keyword. If no width is
specied for acolumn, that column isset to thedefault size, which variesby platform. If
COLUMN_WIDTHSisset toascalar value, all of thecolumn widthsareset tothat value.
DAYS_OF_WEEK
FORMAT keyword.
DEFAULT_BUTTON
This keyword applies to widgets created with the WIDGET_BASE function using the
MODAL keyword.
Set thiskeyword equal tothewidget IDof abutton widget that will bethedefault button
onamodal basewidget. Thedefault buttonishighlightedbythewindowsystem. Pressing
the Enter or Return key on thekeyboard when amodal widget ison thescreen isthe
same as clicking the button.
DEFAULT_FONT
Thiskeyword appliesto all widgets. Do not specify aWidgetIDwhen usingthiskeyword.
A string containing the name of the default font to be used.
If thefont tobeused for agiven widget isnot explicitlyspecied (viatheFONT keyword
to the widget creation function), a default supplied by the window system or server is
used. Use this keyword to change the default. See About Device Fonts on page72 for
detailson specifyingnamesfor devicefonts. If thiskeywordisomitted, thedefault font is
used.
Note On Microsoft Windows platforms, IDL uses the system default font. Different ver-
sions of Windows use different system default fonts; in general, the system default
font is the font appropriate for the version of Windows in question.
DELAY_DESTROY
Normally, when the user destroys a widget hierarchy using the window manager, it is
immediatelyremoved. Thiscan causeproblemsfor applicationsthat usethebackground
task facility provided by theXMANAGERprocedureif thehierarchy isdestroyed whilea
background task is using it.
If DELAY_DESTROY is set, attempts to destroy the hierarchy are delayed until the next
attempt to obtain an event for it. Setting DELAY_DESTROY to zero restores the default
behavior.
XMANAGERusesthiskeywordautomaticallywhenmanagingbackgroundtasks. It isnot
expected that applications will need to use it directly.
DELETE_COLUMNS
Set this keyword to delete the currently-selected columns. If the USE_TABLE_SELECT
keyword is given as a four element array, the columns specied are deleted.
Caution You cannot delete columns from a table which displays structure data in
/ROW_MAJOR (default) mode because it would change the structure.
DELETE_ROWS
Set this keyword to delete the currently-selected rows. If the USE_TABLE_SELECT
keyword is given as a four element array, the rows specied are deleted.
Caution You cannot delete rows from a table which displays structure data in
/COLUMN_MAJOR mode because it would change the structure.
DESTROY
Set thiskeyword to destroy thewidget and any child widgetsin itshierarchy. Any further
attempts to use the IDs for these widgets will cause an error.
DRAW_BUTTON_EVENTS
This keyword applies to widgets created with the WIDGET_DRAW function.
Set this keyword to enable button press events for draw widgets. Setting a zero value
disables such events.
DRAW_EXPOSE_EVENTS
Set thiskeyword to enableviewport exposeeventsfor drawwidgets. Settingazero value
Note You must explicitly disable backing store (by setting the RETAIN keyword to
WIDGET_DRAW equal to zero) in order to generate expose events.
DRAW_MOTION_EVENTS
Set this keyword to enable motion events for draw widgets. Setting a zero value disables
such events.
DRAW_VIEWPORT_EVENTS
Set thiskeyword to enableviewport motion eventsfor drawwidgets. Settingazero value
DRAW_XSIZE
Set thiskeywordtoaninteger that speciesthenewhorizontal sizefor thegraphicsregion
(thevirtual size) of adrawwidget in unitsspeciedbytheUNITSkeyword(pixelsarethe
default). For non-scrollable draw widgets, setting this keyword is the same as setting
SCR_XSIZE or XSIZE. However, for scrolling draw widgets DRAW_XSIZE is the only
way to change the width of the drawable area (XSIZE sets the viewport size).
DRAW_YSIZE
Set this keyword to an integer that species the new vertical size for the graphics region
(thevirtual size) of adrawwidget in unitsspeciedbytheUNITSkeyword(pixelsarethe
default). For non-scrollable draw widgets, setting this keyword is the same as setting
SCR_YSIZEor YSIZE. However, for scrollingdrawwidgetsDRAW_YSIZEistheonlyway
to change the height of the drawable area (YSIZE sets the viewport size).
DYNAMIC_RESIZE
ThiskeywordappliestowidgetscreatedwiththeWIDGET_BUTTON, WIDGET_DROPLIST,
and WIDGET_LABEL functions.
Set thiskeyword to activate(if set to 1) or deactivate(if set to 0) dynamicresizingof the
specied WIDGET_BUTTON, WIDGET_LABEL, or WIDGET_DROPLIST widget (see
the documentation for the DYNAMIC_RESIZE keyword to those procedures for more
information about dynamic widget resizing).
EDITABLE
ThiskeywordappliestowidgetscreatedwiththeWIDGET_TABLEandWIDGET_TEXT
functions.
Set this keyword to allow direct user editing of the contents of a text or table widget.
Normally, the text in text and table widgets is read-only. See the descriptions of the
ALL_TABLE_EVENTS and ALL_TEXT_EVENTS keywords for additional details.
EDIT_CELL
Set this keyword equal to a two-element integer array containing the x (row) and
y (column) coordinatesof atablecell to put that cell into edit mode. For example, to put
the top left cell of a table widget into edit mode, use the following command:
WIDGET_CONTROL, table, EDIT_CELL=[0, 0]
wheretableis the Widget ID of the table widget.
EVENT_FUNC
when an event arrives from a widget in the widget hierarchy given by Widget_ID.
This keyword overwrites any event routine supplied by previous uses of the
EVENT_FUNCor EVENT_PROkeywords. Tospecifynoevent routine, set thiskeyword
to a null string ('').
EVENT_PRO
function when an event arrivesfromawidget in thewidget hierarchygiven byWidget_ID.
This keyword overwrites any event routine supplied by previous uses of the
EVENT_FUNCor EVENT_PROkeywords. Tospecifynoevent routine, set thiskeyword
to a null string ('').
FORMAT
Set this keyword equal to a single string or an array of strings that specify the format of
data displayed within table cells. The string(s) are of the same form as used by the
FORMAT keyword to the PRINT procedure, and the default format is the same as that
usedbythePRINT/PRINTFprocedure. If theUSE_TABLE_SELECTkeywordisset, then
the format is changed only for the selected cells.
FUNC_GET_VALUE
to the WIDGET_CONTROL procedure is called for this widget. The function specied
by FUNC_GET_VALUE is called with the widget ID as an argument. The function
speciedbyFUNC_GET_VALUEshouldreturnavaluefor awidget. Usingthistechnique
GET_DRAW_VIEW
Species a named variable which will be assigned the current position of a draw widget
viewport. The position is returned as a 2-element integer array giving the X and Y
position relative to the lower left corner of the graphics area.
GET_UVALUE
Set this keyword to a named variable to contain the current user value of the widget.
Each widget can contain auser set valueof any datatypeand organization. Thisvalueis
not used by the widget in any way, and exists entirely for the convenience of the IDL
programmer. This keyword allows you to obtain the current user value.
Theuser valueof awidget can beset with theSET_UVALUEkeyword to thisroutine, or
with the UVALUE keyword to the routine that created it.
To improve the efciency of the data transfer, consider using the NO_COPY keyword
(described below) with GET_UVALUE.
GET_VALUE
This keyword applies to widgets created with the WIDGET_BUTTON,
WIDGET_DRAW, WIDGET_LABEL, WIDGET_SLIDER, WIDGET_TABLE, and
WIDGET_TEXT functions.
Note If you would like information about the values returned for a specic compound
widgetbeginning with the prex CW_ please refer to the description of the
compound widget, which may also include a section titled, Keywords to
WIDGET_CONTROL and WIDGET_INFO. Compound widgets are described in
theReferenceGuide.
Set thiskeyword toanamed variabletocontain thecurrent valueof thewidget. Thetype
of value returned depends on the widget type:
Button: If thebutton label istext, it isreturnedasastring. Attemptstoobtain thevalue
of a button with a bitmap label is an error.
Draw: Thevalueof adrawwidget dependsonwhether thedrawwidget usesIDLDirect
Graphics or IDL Object Graphics. (The type of graphics used is specied by the
GRAPHICS_LEVEL keyword to WIDGET_DRAW.) The two possibilities are:
1.By default, draw widgets use IDL Direct Graphics. In this case, the value of a draw
widget istheIDL windowID for thedrawingarea. ThisID isused with procedures
such as WSET, WSHOW, etc., to direct graphics to the widget. The window ID is
assigned to drawing area widgets at thetime they are realized. If the widget has not
yet been realized, a value of -1 is returned.
2.If thedrawwidget usesIDLObject Graphics(that is,if theGRAPHICS_LEVELkeyword
to WIDGET_DRAW is set equal to 2), the value of the draw widget is the object
reference of the window object used in the draw widget.
Label: The label text is returned as a string.
Slider: The current value of the slider is returned as an integer.
Table: Normally, the data for the whole table are returned as a two dimensional array
or avector of structures. However, if theUSE_TABLE_SELECTkeywordispresent, the
valuereturnedisasubset of thewholedata. Thismayeither beatwodimensional array
or a vector of (possibly anonymous) structures. If the USE_TEXT_SELECT keyword
isset, thevaluereturned isastringcorrespondingto thecurrently-selected text in the
currently-selected cell.
Text: The current contents of the text widget are returned as a string array. If the
USE_TEXT_SELECT keyword isalso specied, only thecontentsof thecurrent selec-
tion are returned.
Widget types not listed above do not return a value. Attempting to retrieve the value
of such a widget causes an error.
The value of a widget can be set with the SET_VALUE keyword to this routine, or with
the VALUE keyword to the routine that created it.
GROUP_LEADER
destroyed.
HOURGLASS
Set this keyword to turn on an hourglass-shaped cursor for all IDL widgets and
graphicswindows. Thehourglassremainsin placeuntil theWIDGET_EVENT function
attempts to process the next event. Then the previous cursor is reinstated. If an
application starts a time-intensive calculation inside an event-handling routine, the
hourglass cursor should be used to indicate that the system is not currently responding
to events.
ICONIFY
Set thiskeywordtoanon-zerovaluetocausethespeciedwidget tobecomeiconied. Set
this keyword to zero to open an iconied widget.
INPUT_FOCUS
ThiskeywordappliestowidgetscreatedwiththeWIDGET_BUTTON, WIDGET_DRAW,
and WIDGET_TEXT functions.
If Widget_ID is a text widget, you can set this keyword to cause the widget to receive the
keyboard focus. If Widget_IDisabutton widget, set thiskeyword to position themouse
pointer over the button (on Motif ), or set the focus to the button so that it can be
pushed with thespacebar (on Windows). You cannot set theinput focustoabutton in
IDL for Macintosh. If Widget_IDisadrawwidget, set thiskeyword to giveit thefocusin
IDL for Macintosh; this allows you to print from the draw widget. This keyword has no
effect for other widget types.
Note You cannot assign the input focus to an unrealized widget.
INSERT_COLUMNS
Set this keyword to the number of columns to be added to the right of the rightmost
columnof thetable. If theUSE_TABLE_SELECTkeywordisset, thecolumnsareinserted
to the left of the current selection.
Caution You cannot insert columns into a table which displays structure data in
/ROW_MAJOR (default) mode because it would change the structure.
INSERT_ROWS
Set this keyword to the number of rows to be added below the bottommost row of the
table. If theUSE_TABLE_SELECTkeywordisset, therowsareinsertedabovethecurrent
selection.
Caution You cannot insert rows into a table which displays structure data in
/COLUMN_MAJOR mode because it would change the structure.
KBRD_FOCUS_EVENTS
This keyword applies to widgets created with the WIDGET_BASE, WIDGET_TABLE,
and WIDGET_TEXT functions.
Set this keyword to cause widget keyboard focus events to be issued for the widget
whenever the keyboard focus of that widget changes. See the KBRD_FOCUS_EVENTS
keywords to WIDGET_BASE, WIDGET_TABLE, and WIDGET_TEXT for details.
KILL_NOTIFY
Use this keyword to change or remove a previously-specied callback procedure for
Widget_ID. Apreviously-dened callback can beremoved by settingthiskeyword to the
null string ('').
called.
MANAGED
This keyword is used by the XMANAGER procedure to mark those widgets that it is
currently managing. User applications should not use this keyword directly.
MAP
Set thiskeyword to zero to unmap thewidget hierarchy rooted at thewidget specied by
Widget_ID. The hierarchy disappears from the screen, but still exists.
Themappingoperation appliesonly tobasewidgets. If thespecied widget isnot abase,
IDL searches upward in the widget hierarchy until it nds the closest base widget. The
map operation is applied to that base.
Set MAPtoanonzerovaluetore-mapthewidget hierarchyandmakeit visible. Normally,
thewidget isautomaticallymapped when it isrealized, souseof theMAPkeyword isnot
required.
MONTHS
FORMAT keyword.
NO_COPY
operation (using the SET_UVALUE keyword to WIDGET_CONTROL), the variable
passed as value becomes undened. On a get operation (GET_UVALUE keyword to
WIDGET_CONTROL), the user value of the widget in question becomes undened.
Note TheNO_COPYkeywordincreasesefciencywhensendingevent structuresusingthe
SEND_EVENT keyword to WIDGET_CONTROL.
NO_NEWLINE
When setting the value of a multi-line text widget, newline characters are automatically
appended to the end of each line of text. The NO_NEWLINE keyword suppresses this
action.
NOTIFY_REALIZE
procedure. A previously-set callback routine can be removed by setting this keyword to
thenull string(''). Thecallback routineiscalledwiththewidget IDasitsonlyargument.
PRO_SET_VALUE
totheWIDGET_CONTROL procedureiscalled for thiswidget. Theprocedurespecied
by PRO_SET_VALUE is called with 2 arguments a widget ID and a value. Using this
technique allows you to designate a routine that sets the value for a widget. Compound
widgets use this ability to dene their values transparently to the user.
REALIZE
If set, the widget hierarchy is realized. Until the realization step, the widget hierarchy
exists only within IDL. Realization is the step of actually creating the widgets on the
screen (and mapping them if necessary).
When apreviously-realizedwidget getsanewchildwidget, thenewchildisautomatically
realized.
Caution Under Microsoft Windows, whenahiddenbaseisrealized, thenmapped, aWindows
resizemessageissent bythewindowingsystem. Thisextra resizeevent isgenerated
before any manipulation of the base widget by the user.
RESET
Thiskeywordappliestoall widgets. Donot specifyaWidgetIDwhen usingthiskeyword.
Set theRESET keyword todestroyevery currently activewidget. Thiskeyword should be
used with caution.
Caution UsingRESETwhileInsight isrunningwill destroyyour interaction withInsight. You
must restart IDL to run Insight again. If possible, exit Insight before using RESET.
Data can be corrupted or lost during a reset.
ROW_LABELS
Set thiskeyword equal to an array of stringsto beused aslabelsfor therowsof thetable.
If no label is specied for a row, it receives the default label Rown wheren is the row
number. If this keyword is set to the empty string (''), all row labels are set to be empty.
ROW_HEIGHTS
Note This keyword is not supported under Microsoft Windows.
Set thiskeyword equal toan arrayof heightsfor therowsof thetablewidget. Theheights
aregiven in anyof theunitsasspeciedwiththeUNITSkeyword. If noheight isspecied
for arow, that rowisset tothedefault size, which variesbyplatform. If ROW_HEIGHTS
is set to a scalar value, all of the row heights are set to that value.
SCR_XSIZE
Set this keyword to an integer value that represents the widgets new horizontal size, in
unitsspecied by theUNITSkeyword (pixelsarethedefault). Attemptingto changethe
sizeof awidget that ispart of amenubar or pulldown menu causesan error. Notethat, in
many cases, setting this keyword is equivalent to setting the XSIZE keyword. However,
this keyword is useful for resizing table, text, list, and scrolling widgets.
SCR_YSIZE
Set thiskeyword toan integer valuethat representsthewidgetsnewvertical size, in units
speciedbytheUNITSkeyword(pixelsarethedefault). Attemptingtochangethesizeof
awidget that ispart of amenubar or pulldown menu causesan error. Notethat, in many
cases, setting this keyword is equivalent to setting the YSIZE keyword. However, this
keyword is useful for resizing table, text, list, and scrolling widgets.
SEND_EVENT
Set thiskeyword to astructurecontainingavalid widget event to besent to thespecied
widget. Thevalueof SEND_EVENT mustbeastructureand therst threeeldsmust be
ID, TOP, and HANDLER (all of LONG type). Additional elds can be of any type.
with SEND_EVENT.
SENSITIVE
Set this keyword to control the sensitivity state of a widget after creation. This keyword
appliesto all widgets. UsetheSENSITIVEkeyword with thewidget creation function to
control the initial sensitivity state.
instance, a sensitive button widget can be activated by moving the mouse cursor over it
changing its appearance, and ignores any input directed at it. If SENSITIVE is zero, the
widget hierarchy becomes insensitive. If nonzero, it becomes sensitive.
Sensitivitycan beusedtocontrol when auser isallowedtomanipulateawidget. It should
be noted that some widgets do not change their appearance when they are made
insensitive, and simply cease generating events.
SET_BUTTON
This keyword applies to widgets created with the WIDGET_BUTTON function.
This keyword allows changing the current state of toggle buttons. If zero, every toggle
button in the hierarchy specied by Widget_ID is set to the unselected state. If nonzero,
the action depends on the type of base holding the buttons. Normally, all buttons are
selected. However, exclusivebasesmay or may not allowmorethan asinglebutton to be
selected in this manner, depending on the toolkit implementation.
SET_DRAW_VIEW
Ascrollabledrawwidget providesalargegraphicsareawhichisviewedthroughasmaller
viewport. Thiskeywordallowschangingthecurrent positionof theviewport. Thedesired
position is specied as a 2-element integer array giving the X and Y position in units
speciedbytheUNITSkeyword(pixelsarethedefault) relativetothelower left corner of
the graphics area. For example, to position the viewport to the lower left corner of the
image:
WIDGET_CONTROL, widget, SET_DRAW_VIEW=[0, 0]
SET_DROPLIST_SELECT
This keyword applies to widgets created with the WIDGET_DROPLIST function.
Set this keyword to an integer that species the droplist element to be current (i.e., the
element that is displayed on the droplist button). Positions start at zero. If the specied
element is outside the possible range, no new selection is set.
SET_LIST_SELECT
This keyword applies to widgets created with the WIDGET_LIST function.
Set this keyword to an integer scalar or vector that species the list element or elements
tobehighlighted. Thepreviousselection (if thereisaselection) iscleared. Positionsstart
at zero. If thespeciedelement isoutsidethepossiblerange, nonewselection in set. Note
that theMULTIPLEkeywordtoWIDGET_LISTmust havebeen set in morethan asingle
list element is specied.
If theselected position isnot currently on thescreen, thelist widget automatically move
thecurrent scrollingviewport tomakeit visible. Theresultingtopmost visibleelement is
toolkit specic. If you wish to ensure a certain element is at the top of the list, use the
SET_LIST_TOP keyword (described below) to explicitly set the viewport.
SET_LIST_TOP
Set thiskeywordtoaninteger that speciestheelement of thelist widget tothepositioned
at thetopof thescrollinglist. If thespeciedelement isoutsidetherangeof list elements,
nothing happens.
SET_SLIDER_MAX
This keyword applies to widgets created with the WIDGET_SLIDER function.
Set this keyword to a new maximum value for the specied slider widget.
Note Thiskeyworddoesnot applytooating-point sliderscreatedwiththeCW_FSLIDER
function.
SET_SLIDER_MIN
Set this keyword to a new minimum value for the specied slider widget.
Note Thiskeyworddoesnot applytooating-point sliderscreatedwiththeCW_FSLIDER
function.
SET_TABLE_SELECT
Set this keyword to an array of zero-based cell indices, of the form
[ left, top, right, bottom ]
giving the range of cells to select.
If the selected position is not currently on the screen, the table widget automatically
movesthecurrent scrollingviewport tomakeaportion of it visible. Theresultingtop-left
visible cell is toolkit specic. If you wish to ensure a certain element is at the top of the
list, use the SET_TABLE_VIEW keyword to explicitly set the viewport.
SET_TABLE_VIEW
Set thiskeywordtoatwo-element arrayof zero-based cell indicesthat speciesthecell of
the table widget to the positioned at the top-left of the widget. If the specied cell is
outside the range of valid cells, nothing happens.
SET_TEXT_SELECT
functions.
Use this keyword to clear any current selection in the specied table cell or text widget,
and either set a new selection, or simply set the text insertion point. To set a selection,
specifyatwo-element integer arraycontainingthestartingposition and thelength of the
selection. For example, to set a selection covering characters 3 though 23:
WIDGET_CONTROL, widgetID, SET_TEXT_SELECT=[3, 20]
To movethetext insertion point without settingaselection, omit thesecond element, or
set it to zero.
SET_TEXT_TOP_LINE
Set this keyword to the zero-based line number of the line to be positioned on the
topmost visible line in the text widgets viewport. No horizontal scrolling is performed.
Note that this is a line number, not a character offset.
SET_UNAME
Set this keyword to a string that can be used to identify the widget. You can associate a
namewitheachwidget inaspecichierarchy, andthenusethat nametoquerythewidget
hierarchy and get thecorrect widget ID. You can set thenameat creation time, usingthe
UNAME keyword with the creation function.
specied name.
SET_UVALUE
Each widget can contain a user-set value. This value is not used by IDL in any way, and
existsentirelyfor theconvenienceof theIDLprogrammer. Thiskeywordallowsyoutoset
this value.
with SET_UVALUE.
SET_VALUE
This keyword applies to widgets created with the WIDGET_BUTTON,
WIDGET_DROPLIST, WIDGET_LABEL, WIDGET_LIST, WIDGET_SLIDER,
WIDGET_TABLE, and WIDGET_TEXT functions.
Sets the value of the specied widget. The meaning of the value differs between widget
types:
Button: Thelabel to beused for thebutton. Thisvaluecan beeither ascalar string, or
a 2D byte array containing a bitmap.
Droplist: The contents of the droplist widget (string or string array).
Label: The text to be displayed by the label widget.
List: The contents of the list widget (string or string array).
Slider: The current position of the slider (integer).
Table: Normally, thedatafor thewholetableischanged to thegiven datawhich must
be of the form of a two dimensional array or a vector of structures. In this form, the
table is resized to t the given data (unless the TABLE_XSIZE or TABLE_YSIZE
keywords are given).
If the USE_TABLE_SELECT keyword is present, the value given is treated as a subset
of thewholedata, and only thegiven rangeof cellsareupdated. Used in thisform, the
typeof datastored in thetablecannot bechanged. Thedatapassed in isconverted, as
appropriate, to the type of the selected cells. If less data is passed in than ts in the
current selection, the cells outside the range of data (but inside the selection) are left
unchanged. If moredataispassed in than tsin thecurrent selection, theextradatais
ignored.
If the USE_TEXT_SELECT keyword is present, the value must be a string which
replaces the currently-selected text in the currently-selected cell.
Text: The text to be displayed. If the APPEND keyword is also specied, the text is
appended to the current contents instead of instead of completely replacing it (string
or string array). If the USE_TEXT_SELECT keyword is specied, the new string
replaces only the currently-selected text in the text widget.
Widget typesnot listed abovedonot allowthesettingof avalue. Attemptingtoset the
value of such a widget causes an error.
Thevalueof awidget can alsobeset with theVALUEkeyword totheroutinethat created
it.
SHOW
Controls the visibility of a widget hierarchy. If set to zero, the hierarchy containing
Widget_IDispushed behind any other windowson thescreen. If nonzero, thehierarchy
is pulled in front.
TABLE_XSIZE
Set thiskeywordequal tothenumber of datacolumnsin thetablewidget. Notethat if the
table widget was created with row titles enabled (that is, if the NO_HEADERS keyword
to WIDGET_TABLE wasnot set), the table will contain one column more than the
number specied by TABLE_XSIZE.
If the table is made smaller as a result of the application of the TABLE_XSIZE keyword,
thedataoutsidethenewrangepersists, but thenumber of columnsand/or rowschanges
asexpected. If thetableismadelarger, thedatatypeof thecellsin thenewcolumnsisset
according to the following rules:
1. If the table was not created with either the ROW_MAJOR or COLUMN_MAJOR key-
wordsset (if thetableisanarrayrather thanavector of structures), thenewcellshavethe
same type as all the original cells.
2. If theSET_VALUEkeywordisgiven, thetypesof all columnsareset accordingtothe
new structure.
3. If the table was created with the ROW_MAJOR keyword set, and the SET_VALUE
keywordisnot specied, thecellsinthenewcolumnsinherit their typefromthecells
to their left.
4. If the table was created with the COLUMN_MAJOR keyword set, and the
SET_VALUE keyword is not specied, any new columns default to type INT.
TABLE_YSIZE
Set this keyword equal to the number of data rows in the table widget. Note that if the
table widget was created with column titles enabled (that is, if the NO_HEADERS
keyword to WIDGET_TABLEwasnot set), thetablewill contain onerowmorethan the
number specied by TABLE_YSIZE.
If the table is made smaller as a result of the application of the TABLE_YSIZE keyword,
thedataoutsidethenewrangepersists, but thenumber of columnsand/or rowschanges
as expected. If the table is made larger, the data type of the cells in the new rows is set
according to the following rules:
1. If the table was not created with either the ROW_MAJOR or COLUMN_MAJOR key-
wordsset (if thetableisanarrayrather thanavector of structures), thenewcellshavethe
same type as all the original cells.
2. If theSET_VALUEkeywordisgiven, thetypesof all rowsareset accordingtothenew
structure.
3. If the table was created with the COLUMN_MAJOR keyword set, and the
SET_VALUEkeywordisnot specied, thecellsinthenewrowsinherit their typefrom
the cells above.
4. If the table was created with the ROW_MAJOR keyword set, and the SET_VALUE
keyword is not specied, any new rows default to type INT.
TIMER
If this keyword is present, a WIDGET_TIMER event is generated. Set this keyword to a
oating-point valuethat representsthenumber of secondsbeforethetimer event arrives.
Notethat thisevent isidentical to any other widget event except that it containsonly the
3 standard event tags. These event structures are dened as:
{ WIDGET_TIMER, ID:0L, TOP:0L, HANDLER:0L }
It is left to the caller to tell the difference between standard widget events and timer
events. The standard way to do this is to use a widget that doesnt normally generate
events(e.g., abaseor label). Alternately, theTAG_NAMESfunctioncanbecalledwiththe
STRUCTURE_NAME keyword to differentiate a WIDGET_TIMER event from other
types of events. For example:
IF TAG_NAMES(event, /STRUCTURE_NAME) EQ $
'WIDGET_TIMER' THEN ...
UsingtheTIMERkeywordismoreefcient thanthebackgroundtaskfunctionalityfound
in theXMANAGERprocedurebecauseit doesnt poll liketheoriginal backgroundtask
code. Research Systemswill eventuallyeliminatethebackground task functionality from
XMANAGER. We encourage all users to modify their code to use the TIMER keyword
instead.
TLB_GET_OFFSET
Set this keyword to a named variable in which the offset of the top-level base of the
specied widget is returned, in units specied by the UNITS keyword (pixels are the
default). Theoffset ismeasured in devicecoordinatesrelativeto theupper-left corner of
the screen. This offset value does not include the size of the enclosing frame (which is
provided by the window manager).
TLB_GET_SIZE
Set thiskeywordtoanamedvariableinwhichthesizeof thetop-level baseof thespecied
widget isreturned, in unitsspecied by theUNITSkeyword (pixelsarethedefault). The
size is returned as a two-element vector that contains the horizontal and vertical size of
the base in device coordinates.
This keyword applies to widgets created with the WIDGET_BASE function.
Use this keyword to set or clear kill request events for the specied top-level base. For
more information on these events see TLB_KILL_REQUEST_EVENTS on page1215.
TLB_SET_TITLE
Set thiskeyword toascalar stringtochangethetitleof thespecied top-level baseafter it
has been created.
TLB_SET_XOFFSET
Use this keyword to set the horizontal position of the top level base of the specied
widget. Theoffset ismeasured fromtheupper-left corner of thescreen to theupper-left
corner of the base, in units specied by the UNITS keyword (pixels are the default).
TLB_SET_YOFFSET
Use this keyword to set the vertical position of the top level base of the specied widget.
The offset is measured from the upper-left corner of the screen to the upper-left corner
of the base, in units specied by the UNITS keyword (pixels are the default).
TRACKING_EVENTS
Set thiskeyword toanon-zerovaluetoenabletrackingeventsfor thewidget specied by
Widget_ID. Set thekeyword to 0to disabletrackingeventsfor thespecied widget. For a
description of tracking events, see TRACKING_EVENTS on page1216.
UNITS
Use this keyword to specify the unit of measurement used for most widget sizing
operations. Set UNITSequal to0(zero) tospecifythat all measurementsareinpixels(this
is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to
specify that all measurements are in centimeters.
Note Thiskeyworddoesnot affect all sizingoperations. Specically, thevalueof UNITSis
ignored when setting the XSIZE or YSIZE keywords to WIDGET_LIST,
WIDGET_TABLE, or WIDGET_TEXT.
UPDATE
Usethiskeywordtoenable(if set to1) or disable(if set to0) screen updatesfor thewidget
hierarchy to which the specied widget belongs. This keyword is useful for preventing
unwantedintermediatescreenupdateswhenchangingthevaluesof manywidgetsat once
or when adding several widgets to a previously-realized widget hierarchy. When rst
realized, widget hierarchies are set to update.
Note Donot attempt toresizeawidget ontheWindowsplatformwhileUPDATEisturned
off. Doingso may prevent IDL fromupdatingthescreen properly when UPDATEis
turned back on.
USE_TABLE_SELECT
Set this keyword to modify the behavior of the ALIGNMENT,COLUMN_WIDTH,
FORMAT, GET_VALUE, ROW_HEIGHT, and SET_VALUE keywords. If
USE_TABLE_SELECT is set, these other keywords only apply to the currently-selected
cells. Normally, these keywords apply to the entire contents of a table widget.
Note In order to set the format of the currently-selected cells, the value of the FORMAT
keyword must be an array of the same dimensions as the selected area.
This keyword can also be specied as a four-element array, of the form
[ left, top, right, bottom ]
givingthegroup of cellsto act on. In thisusage, thevalue-1isused to refer to therowor
column titles. If row or column titles are selected, this keyword only modies the
behavior of the COLUMN_WIDTH and ROW_HEIGHTS keywords.
Caution You shouldset valuesto-1onlywhen you can changethelabels. For example, on the
Macintosh, only COLUMN_WIDTH and ROW_HEIGHT should be set to -1.
USE_TEXT_SELECT
functions.
Set thiskeyword tomodifythebehavior of theGET_VALUEand SET_VALUEkeywords.
If USE_TEXT_SELECT is set, GET_VALUE and SET_VALUE apply only to the current
text selection. Normally, these keywords apply to the entire contents of a text widget.
X_BITMAP_EXTRA
This keyword applies to widgets created with the WIDGET_BUTTON function.
When thevalueof abutton widget isabitmap, theusual width istaken to be8timesthe
number of columns in the source byte array. This keyword can be used to indicate the
number of bits in the last byte of each row that should be ignored. The value can range
between 0 and 7.
XOFFSET
Set this keyword to an integer value that species the widgets new horizontal offset, in
unitsspecied by theUNITSkeyword (pixelsarethedefault). Attemptingto changethe
offset of awidget that isthechild of aROWor COLUMN baseor awidget that ispart of
a menubar or pulldown menu causes an error.
XSIZE
Set this keyword to an integer or oating-point value that represents the widgets new
horizontal size.
Text and List widgets: Size is specied in characters. The UNITS keyword is ignored.
Tablewidgets: Sizeisspeciedin columns. Thewidthof therowlabelsisautomatically
added to this value. The UNITS keyword is ignored.
All other widgets: If theUNITSkeyword ispresent, sizeisin theunitsspecied. If the
UNITS keyword is not present, the size is specied in pixels.
For most non-scrollable widgets, this size is the same as the screen size that can be set
usingtheSCR_XSIZEkeyword. For scrollablewidgets(e.g., scrollingbasesand scrolling
drawwidgets), thiskeyword adjuststheviewportsize. UsetheDRAW_XSIZEkeyword to
change the width of the drawing area in scrolling draw widgets. Attempting to resize a
widget that is part of a menubar or pulldown menu causes an error.
YOFFSET
Set thiskeyword toan integer valuethat speciesthewidgetsnewvertical offset, in units
specied by theUNITSkeyword (pixelsarethedefault). Attemptingto changetheoffset
of a widget that is the child of a ROW or COLUMN base or a widget that is part of a
menubar or pulldown menu causes an error.
YSIZE
Set this keyword to an integer or oating-point value that represents the widgets new
vertical size
Text and List widgets: Size is specied in lines. The UNITS keyword is ignored.
Tablewidgets: Sizeisspeciedinrows. Theheight of thecolumnlabelsisautomatically
added to this value. The UNITS keyword is ignored.
All other widgets: If theUNITSkeyword ispresent, sizeisin theunitsspecied. If the
UNITS keyword is not present, the size is specied in pixels.
For most non-scrollable widgets, this size is the same as the screen size that can be set
usingtheSCR_YSIZEkeyword. For scrollablewidgets(e.g., scrollingbasesand scrolling
draw and table widgets), this keyword adjusts theviewport size. Use the DRAW_YSIZE
keyword to changetheheight of thedrawingareain scrollingdrawwidgets. Attempting
to resize a widget that is part of a menubar or pulldown menu causes an error.
See Also
WIDGET_DRAW IDL Reference Guide
WIDGET_DRAW
The WIDGET_DRAW function is used to create draw widgets. Draw widgets are
rectangular areas that IDL treats as standard graphics windows. Draw widgets can use
either IDL Direct graphics or IDL Object graphics, depending on the value of the
GRAPHICS_LEVEL keyword. (SeeGraphics on page267of BuildingIDL Applications
for an explanation of IDLsgraphicsmodes.) Any graphical output that can beproduced
by IDL can be directed to a draw widget. Draw widgets can have optional scroll bars to
allow viewing a larger graphics area than could otherwise be displayed in the widgets
visible area.
The returned value of this function is the widget ID of the newly-created draw widget.
Note On some systems, when backing store is provided by the window system (RE-
TAIN=1), readingdatafromawindowusingTVRD( ) maycauseunexpectedresults.
For example, data may be improperly read from the window even when the image
displayed on screen is correct. Having IDL provide the backing store (RETAIN=2)
ensures that the window contents will be read properly.
Calling Sequence
Result = WIDGET_DRAW(Parent)
Arguments
Parent
The widget ID of the parent widget of the new draw widget.
Keywords
APP_SCROLL
Set thiskeyword tocreateascrollabledrawwidget with horizontal and vertical scrollbars
and adrawareacanvaswith thesamesizeastheviewport. You can specify thesizeof the
viewport using the X_SCROLL_SIZE and Y_SCROLL_SIZE keywords, and the virtual
size of the canvas using the XSIZE and YSIZE keywords. If APP_SCROLL is set, the
application generatesexposeand viewport eventssuch aswould occur with EXPOSE=1,
RETAIN=0, and VIEWPORT_EVENTS=1. This allows you to redraw the appropriate
part of the virtual canvas when your application receives expose or viewport events.
Use the APP_SCROLL keyword when displaying images, or anything drawn in device
units or pixels. This keyword is good when you are displaying large images because the
entire images does not have to be redrawn when change viewport events are generated.
UsetheSCROLL keyword when adrawwidget isgoingtodisplaygraphicsdrawn in data
units (e.g., PLOT, CONTOUR, SURFACE).
IDL Reference Guide WIDGET_DRAW
BUTTON_EVENTS
Set this keyword to make the draw widget generate events when the mouse buttons are
pressed or released (and the mouse pointer is in the draw widget). Normally, draw
widgets do not generate events.
COLOR_MODEL
Set this keyword equal to 1 (one) to cause the draw widgets associated IDLgrWindow
object touseindexedcolor. If theCOLOR_MODELkeywordisnot set, or isset toavalue
other than one, the draw widget will use RGB color.
This keyword is only valid when the draw widget uses IDL Object Graphics. (The
graphics type used by a draw widget is determined by setting the GRAPHICS_LEVEL
keyword to WIDGET_DRAW.) For information on using indexed color in Object
Graphics window objects, see Working with Color in Chapter 5 of Object
Graphics.
COLORS
Themaximumnumber of color tableindicestobeused. Thisparameter haseffect onlyif
it is supplied when therst IDL graphics window is created.
If COLORS is not specied when the rst window is created, all or most of the available
color indices are allocated, depending upon the window system in use.
To use monochrome windows on a color display, set COLORS equal to 2 when creating
therst window. Onecolor tableismaintained for all IDL windows. Anegativevaluefor
COLORS species that all but the given number of colors from the shared color table
should be used.
EVENT_FUNC
widget.
EVENT_PRO
created widget.
EXPOSE_EVENTS
Set thiskeyword to makethedrawwidget generateevent when thevisibility of thedraw
widget changes. Thismayoccur when thewidget ishidden behind somethingelseon the
screen, brought to the foreground, or when the scroll bars are moved. Normally, draw
widgets do not generate events.
Note You must explicitly disable backing store (by setting the RETAIN keyword equal to
zero) in order togenerateexposeevents. Additional exposeeventsmay begenerated
if both EXPOSE_EVENTS and RETAIN=1 are turned on.
Caution Largenumbersof eventsmaybegeneratedwhenEXPOSE_EVENTSisspecied. You
may wish to compress the events (perhaps using a timer) and only act on a subset.
FRAME
FUNC_GET_VALUE
GRAPHICS_LEVEL
Set this keyword equal to 2 (two) to use IDL Object Graphics in the draw widget. If the
GRAPHICS_LEVEL keyword is not set, or is set to a value other than two, the draw
widget will use IDL Direct Graphics.
See Graphics on page 267 of Building IDL Applicationsfor information on IDLs
graphics modes.
GROUP_LEADER
destroyed.
KILL_NOTIFY
called.
MOTION_EVENTS
Set thiskeyword tomakethedrawwidget generateeventswhen themousecursor moves
across the widget. Normally, draw widgets do not generate events.
Draw widgets that return motion events can generate a large number of events that can
result in poor performance on slower machines.
Note that it is possible to generate motion events with coordinates outside the draw
widget. If you position themousecursor insidethedrawwidget, pressthemousebutton,
and drag the cursor out of the draw widget, the X and Y elds of the widget event will
specify coordinates outside the draw widget.
NO_COPY
operation (using the UVALUE keyword to WIDGET_DRAW or the SET_UVALUE
NOTIFY_REALIZE
PRO_SET_VALUE
RENDERER
Set this keyword to an integer value indicating which graphics renderer to use when
drawing objects within the window. Valid values are:
0 = Platform native OpenGL
1 = IDLs software implementation
Bydefault, your platformsnativeOpenGLimplementation isused. If your platformdoes
not have a native OpenGL implementation, IDLs software implementation is used
regardless of the value of this property. See Hardware vs. Software Rendering in
Chapter 13 of Object Graphics for details. Your choice of renderer may also affect the
maximumsizeof adrawwidget. See IDLgrWindow in Chapter 17of Object Graphics
for details.
RESOURCE_NAME
RETAIN
Set thiskeyword to0, 1, or 2tospecifyhowbackingstoreshould behandled for thedraw
widget. RETAIN=0 species no backing store. RETAIN=1 requests that the server or
window system provide backing store. RETAIN=2 species that IDL provide backing
storedirectly. SeeBackingStoreon page144for detailson theuseof RETAINwithDirect
Graphics. For more information on the use of RETAIN with Object Graphics, see
IDLgrWindow::Init in Chapter 17 of Object Graphics.
SCR_XSIZE
SCR_YSIZE
SCROLL
Set this keyword to give the draw widget scroll bars that allow viewing portions of the
widget contents that are not currently on the screen.
UsetheSCROLL keyword when adrawwidget isgoingtodisplaygraphicsdrawn in data
units (e.g., PLOT, CONTOUR, SURFACE). Use the APP_SCROLL keyword when
displaying images, or anything drawn in device units or pixels.
SENSITIVE
TRACKING_EVENTS
WIDGET_BASE.
UNAME
specied name.
UNITS
UVALUE
created.
VALUE
The initial value setting of the widget. The value of a draw widget is the IDL window
number for use with Direct Graphics routines, such as WSET. For Object Graphics
routines, it isthedrawwindowobject reference. Thisvaluecannot beset or modied by
the user.
To obtain the window number for a newly-created draw widget, use the GET_VALUE
keyword toWIDGET_CONTROL after thedrawwidget hasbeen realized. Drawwidgets
do not have a window number assigned to them until they are realized. For example, to
return thewindownumber of adrawwidget in thevariablewin_num, usethecommand:
WIDGET_CONTROL, my_drawwidget, GET_VALUE = win_num
wheremy_drawwidget is the widget ID of the desired draw widget.
When using Object Graphics for the widget draw, the following command returns an
object reference to the draw window:
WIDGET_CONTROL, my_drawwidget, GET_VALUE = oWindow
whereoWindow is a window object.
VIEWPORT_EVENTS
Set this keyword to enable viewport motion events for draw widgets.
XOFFSET
XSIZE
toolkit and may be ignored in some situations. By default, draw widgets are 100 pixels
wide by 100 pixels high.
X_SCROLL_SIZE
The XSIZE keyword always species the width of a widget. When the SCROLL keyword
is specied, this size is not necessarily the same as the width of the visible area. The
X_SCROLL_SIZE keyword allows you to set the width of the scrolling viewport
independently of the actual width of the widget.
Use of the X_SCROLL_SIZE keyword implies SCROLL.
YOFFSET
parent widget.
YSIZE
isnot produced, usethiskeyword tooverrideit. Thiskeyword isonlyahint tothetoolkit
and may be ignored in some situations. By default, draw widgets are 100 pixels wide by
100 pixels high.
Y_SCROLL_SIZE
TheYSIZEkeyword alwaysspeciestheheight of awidget. When theSCROLL keyword
is specied, this size is not necessarily the same as the height of the visible area. The
Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport
independently of the actual height of the widget.
Use of the Y_SCROLL_SIZE keyword implies SCROLL.
draw widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: DRAW_BUTTON_EVENTS, DRAW_EXPOSE_EVENTS,
DRAW_MOTION_EVENTS, DRAW_VIEWPORT_EVENTS, DRAW_XSIZE,
DRAW_YSIZE, GET_DRAW_VIEW, GET_VALUE, INPUT_FOCUS,
SET_DRAW_VIEW.
A number of keywords to the WIDGET_INFO function return information that applies
specifically to draw widgets. In addition to those keywords that apply to all widgets, the
following are particularly useful: DRAW_BUTTON_EVENTS, DRAW_EXPOSE_EVENTS,
DRAW_MOTION_EVENTS, DRAW_VIEWPORT_EVENTS.
Widget Events Returned by Draw Widgets
Bydefault, drawwidgetsdonot generateevents. If theBUTTON_EVENTSkeywordisset
when the widget is created, pressing or releasing any mouse button while the mouse
cursor is over the draw widget causes events to be generated. Specifying the
MOTION_EVENTS keyword causes events to be generated continuously as the mouse
cursor movesacrossthedrawwidget. SpecifyingtheEXPOSE_EVENTSkeyword causes
events to be generated whenever the visibility of any portion of the draw window (or
viewport) changes.
The event structure returned by the WIDGET_EVENT function is dened by the
following statement:
{WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0, Y:0,
PRESS:0B, RELEASE:0B, CLICKS:0}
ID, TOP, and HANDLERarethethreestandardeldsfound in everywidget event. TYPE
returnsavaluethat describesthetypeof drawwidget interaction that generatedan event.
The values for TYPE are shown in the table below.
The X and Y elds give the device coordinates at which the event occurred, measured
from the lower left corner of the drawing area. PRESS and RELEASE are bitmasks in
which the least signicant bit represents the leftmost mouse button. The corresponding
bit of PRESSisset when amousebutton ispressed, and in RELEASEwhen thebutton is
released. If the event is a motion event, both PRESS and RELEASE are zero.
The CLICKS eld returns either 1 or 2. If the time interval between two button-press
eventsislessthan thetimeinterval for adouble-click event for theplatform, theCLICKS
eld returns 2. If the time interval between button-press events is greater than the time
interval for adouble-click event for theplatform, theCLICKSeldreturns1. Thismeans
that if you are writing a widget application that requires the user to double-click on a
drawwidget, you will need tohandletwoevents. TheCLICKSeld will return a1on the
rst click and a 2 on the second click.
Note that the CURSOR procedure is only for use with IDL graphics windows. It should
not be used with draw widgets. To obtain the cursor position and button state
information from a draw widget, examine the X, Y, PRESS, and RELEASE elds in the
structures returned by the draw widget in response to cursor events.
Backing Store
Draw widgets with scroll bars rely on backing store to repaint the visible area of the
windowasit ismoved. Their performanceisbest on systemsthat providebackingstore.
However, if your systemdoesnot automaticallyprovidebackingstore, you can makeIDL
supply it with the statement:
DEVICE, RETAIN=2
or by using the RETAIN keyword to WIDGET_DRAW.
Note If youareusinggraphicsacceleration, youmaywishtoturnoff backingstoreentirely
andenableexposeevents(viatheEXPOSE_EVENTSkeyword) andredrawthedraw
widgets contents manually. However, because the number of events generated may
bequitehigh, youmaywishtoenableatimer aswell andonlyredrawthedrawwidget
periodically.
Value Meaning
0 Button Press
1 Button Release
2 Motion
3 Viewport Moved (Scrollbars)
4 Visibility Changed (Exposed)
Table 9-73: Values for the TYPE eld.
See Also
SLIDE_IMAGE, WINDOW
WIDGET_DROPLIST IDL Reference Guide
WIDGET_DROPLIST
The WIDGET_DROPLIST function creates droplist widgets. A droplist widget is a
button with a label that, when selected, reveals a list of options from which to choose.
When the user selects a new option from the list, the list disappears and the button title
displays the currently-selected option. This action generates an event containing the
index of the selected item, which ranges from 0 to the number of elements in the list
minus one, and updates the label on the push-button.
Thereturned valueof thisfunction isthewidget IDof thenewly-created droplist widget.
Calling Sequence
Result = WIDGET_DROPLIST(Parent)
Arguments
Parent
The widget ID of the parent widget for the new droplist widget.
Keywords
DYNAMIC_RESIZE
ischanged. Notethat thiskeyword doesnot takeeffect when used with theSCR_XSIZE,
SCR_YSIZE, XSIZE, or YSIZE keywords. If one of these keywords is also set, the widget
will be sized as specied by the sizing keyword and will never resize itself dynamically.
EVENT_FUNC
widget.
EVENT_PRO
created widget.
FRAME
IDL Reference Guide WIDGET_DROPLIST
FUNC_GET_VALUE
GROUP_LEADER
destroyed.
KILL_NOTIFY
called.
NO_COPY
operation (using the UVALUE keyword to WIDGET_DROPLIST or the SET_UVALUE
NOTIFY_REALIZE
PRO_SET_VALUE
RESOURCE_NAME
SCR_XSIZE
SCR_YSIZE
SENSITIVE
TITLE
Set this keyword to a string to be used as the title for the droplist widget.
TRACKING_EVENTS
WIDGET_BASE.
UNAME
specied name.
UNITS
UVALUE
created.
VALUE
The initial value setting of the widget. The value of a droplist widget is a scalar string or
array of strings that contains the text of the list itemsone list item per array element.
List widgets are sized based on the length (in characters) of the longest item specied in
the array of values for the VALUE keyword.
XOFFSET
XSIZE
The desired width of the droplist widget area, in units specied by the UNITS keyword
(pixels are the default). Most widgets attempt to size themselves to t the situation.
However, if the desired effect is not produced, use this keyword to override it. This
keyword doesnot control thesizeof thedroplist button or of thedropped list. Instead, it
controls the size around the droplist button and, as such, is not particularly useful.
YOFFSET
parent widget.
YSIZE
Thedesired height of thewidget, in unitsspecied by theUNITSkeyword (pixelsarethe
default). Most widgetsattempt tosizethemselvestofit thesituation. However, if thedesired
effect is not produced, use this keyword to override it. This keyword does not control the
size of the droplist button or of the dropped list. Instead, it controls the size around the
droplist button and, as such, is not particularly useful.
droplist widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: DYNAMIC_RESIZE, SET_DROPLIST_SELECT, SET_VALUE.
Anumber of keywordsto theWIDGET_INFOfunction return information that applies
specicallytodroplist widgets. Inadditiontothosekeywordsthat applytoall widgets, the
following are particularly useful: DROPLIST_NUMBER, DROPLIST_SELECT,
DYNAMIC_RESIZE.
Widget Events Returned by Droplist Widgets
Pressingthemousebutton whilethemousecursor isover an element of adroplist widget
causesthewidget tochangethelabel on thedroplist button andtogeneratean event. The
appearanceof anypreviouslyselectedelement isrestoredtonormal at thesametime. The
event structure returned by the WIDGET_EVENT function is dened by the following
statement:
{ WIDGET_DROPLIST, ID:0L, TOP:0L, HANDLER:0L, INDEX:0L }
Therst threeeldsarethestandard eldsfound in every widget event. INDEX returns
theindexof theselecteditem. Thiscanbeusedtoindexthearrayof namesoriginallyused
to set the widgets value.
Note Platform-specicUI toolkitsbehavedifferently if adroplist widget hasonly asingle
element. Onsomeplatforms, selectingthat element againdoesnot generateanevent.
Events are always generated if the list contains multiple items.
See Also
CW_PDMENU, WIDGET_BUTTON, WIDGET_LIST
WIDGET_EVENT IDL Reference Guide
WIDGET_EVENT
The WIDGET_EVENT function returns events for the widget hierarchy rooted at
Widget_ID. Widgets communicate information by generating events. Events are
generated when a button is pressed, a slider position is changed, and so forth.
Note Widget applicationsshould usetheXMANAGERprocedurein preferenceto calling
WIDGET_EVENT directly. SeeWidget Events on page287of BuildingIDL Appli-
cations.
Calling Sequence
Result = WIDGET_EVENT([Widget_ID])
Arguments
Widget_ID
Widget_IDspeciesthewidget hierarchy for which eventsaredesired. Therst available
event for the specied widget or any of its children is returned. If this argument is not
specied, WIDGET_EVENT processes events for all existing widgets.
Widget_ID can also be an array of widget identiers, in which case all of the specied
widget hierarchies are searched.
Note Attemptingtoobtaineventsfor awidget hierarchywhichisnot producingeventswill
hang IDL, unless the NOWAIT keyword is used.
Keywords
BAD_ID
If one of the values supplied viaWidget_ID is not a valid widget identier, this function
normally issues an error and causes program execution to stop. However, if BAD_ID is
present and speciesanamed variable, theinvalid ID isstored into thevariable, and this
routine quietly returns. If no error occurs, a zero is stored.
This keyword can be used to handle the situation in which IDL is waiting within
WIDGET_EVENT when the user kills the widget hierarchy.
This keyword has meaning only if Widget_ID is explicitly specied.
NOWAIT
When no events are currently available for the specied widget hierarchy,
WIDGET_EVENT normally waits until one is available and then returns it. However, if
NOWAITisset andnoeventsarepresent, it immediatelyreturns. In thiscase, theIDeld
of the returned structure will be zero.
IDL Reference Guide WIDGET_EVENT
SAVE_HOURGLASS
Set this keyword to prevent the hourglass cursor from being cleared by
WIDGET_EVENT. This keyword can be of use if a program has to poll a widget
periodically during a long computation.
YIELD_TO_TTY
Unless the NOWAIT keyword is specied, WIDGET_EVENT does not return until the
asked for event is available. If the user should enter a line of input from the keyboard, it
cannot beprocessed until WIDGET_EVENT returns. If theYIELD_TO_TTYkeyword is
specied and the user enters a line of input, WIDGET_EVENT returns immediately. In
this case, the ID eld of the returned structure will be zero.
Note: Thiskeyword issupported under Unix only, and thereareno plansto extend it to
other operating systems. Do not use it if you intend to use non-Unix systems.
Event Processing
All eventsfor agiven widget areprocessed in theorder that theyaregenerated. Theevent
processing performed by WIDGET_EVENT consists of the following steps:
Wait for an event from one of the specied widgets to arrive.
Startingwith thewidget that theevent belongsto, moveup thewidget hierarchy looking
for a widget that has an event handling procedure or function associated with it. Such
routinesareassociatedwithawidget viatheEVENT_PROandEVENT_FUNCkeywords
to the widget creation functions or the WIDGET_CONTROL procedure.
If an event handlingprocedureis found, it is called with the widget ID as its argument.
When the procedure returns, WIDGET_EVENT returns to the rst step. Hence, event
procedures are said to swallow events.
If anevent handlingfunctionisfound, it iscalledwiththewidget IDasitsargument. When
thefunction returns, itsvalueisexamined. If thevalueisanon-structure, it isdiscarded
and WIDGET_EVENT returns to the rst step.
Thisbehavior allowsevent functionsto selectively act likeevent proceduresand swallow
events. If thereturned valueisastructure, it ischecked to ensurethat it hasthestandard
rst 3 elds: ID, TOP, and HANDLER. If not an error is issued. Otherwise the value
replaces the event found in the rst step and WIDGET_EVENT returns to the second
step.
Hence, event functions are said to rewrite events. This ability to rewrite events is the
basis of the compound widget in which several widgets are combined to give the
appearance of a single, more complicated widget.
If an event reaches the top of a widget hierarchy without being swallowed by an event
handler, it is returned as the value of WIDGET_EVENT.
WIDGET_EVENT IDL Reference Guide
Events
A widget event is returned in a structure. The exact contents of this structure vary
depending upon the type of widget involved. The rst three elements of this structure,
however, are always the same. Any other elements vary from widget type to type. The
three xed elements are:
ID
The widget ID of the widget that generated the event.
TOP
The widget ID of the top level base for the widget hierarchy containingID.
HANDLER
When an event ispassed astheargument to an event handlingprocedureor function, as
discussedintheprevioussection, thiseldcontainstheidentier of thewidget associated
with thehandler routine. When an event isreturned fromWIDGET_EVENT, thisvalue
is always zero to indicate that no handler routine was found.
See Also
XMANAGER
IDL Reference Guide WIDGET_INFO
WIDGET_INFO
TheWIDGET_INFOfunction isusedtoobtain information about thewidget subsystem
and individual widgets. The specic area for which information is desired is selected by
setting the appropriate keyword.
Calling Sequence
Result = WIDGET_INFO([Widget_ID])
Arguments
Widget_ID
Usually this argument should be the widget ID of the widget for which information is
desired. If the ACTIVE or VERSION keywords are specied, this argument is not
required.
Widget_ID can also be an array of widget identiers, in which case the result is an array
with the same structure in which information on all the specied widgets is returned.
Keywords
Not all keywords to WIDGET_INFO apply to all combinations of widgets. In the
followinglist, descriptionsof keywordsthat affect onlycertain typesof widgetsincludea
list of the widgets for which the keyword is useful.
ACTIVE
Set thiskeyword to return 1if thereisat least onerealized, managed, top-level widget on
the screen. Otherwise, 0 is returned.
CHILD
Set this keyword to return the widget ID of the rst child of the widget specied by
Widget_ID. If the widget has no children, 0 is returned.
COLUMN_WIDTHS
Set this keyword to return an array of long integers giving the width of each column in
the table. If USE_TABLE_SELECT is set, only the column widths for the currently-
selected cells are returned.
WIDGET_INFO IDL Reference Guide
DRAW_BUTTON_EVENTS
Set this keyword to return 1 if Widget_ID is a draw widget with the BUTTON_EVENTS
attribute set. Otherwise, 0 is returned.
DRAW_EXPOSE_EVENTS
Set this keyword to return 1 if Widget_ID is a draw widget with the EXPOSE_EVENTS
DRAW_MOTION_EVENTS
Set thiskeyword to return 1if Widget_IDisadrawwidget with theMOTION_EVENTS
DRAW_VIEWPORT_EVENTS
Set thiskeywordtoreturn1if Widget_IDisadrawwidget withtheVIEWPORT_EVENTS
DROPLIST_NUMBER
Set this keyword to return the number of elements currently contained in the specied
droplist widget.
DROPLIST_SELECT
Set thiskeyword to return thezero-based number of thecurrently-selected element (i.e.,
the currently-displayed element) in the specied droplist widget.
DYNAMIC_RESIZE
ThiskeywordappliestowidgetscreatedwiththeWIDGET_BUTTON, WIDGET_DROPLIST,
and WIDGET_LABEL functions.
Set this keyword to return a True value (1) if the widget specied by Widget_ID is a
button, droplist, or label widget that has had its DYNAMIC_RESIZE attribute set.
Otherwise, False (0) is returned.
EVENT_FUNC
Set this keyword to return a string containing the name of the event handler function
associated with Widget_ID. A null string is returned if no event handler function exists.
EVENT_PRO
Set this keyword to return a string containing the name of the event handler procedure
associated with Widget_ID. Anull stringisreturned if no event handler procedureexists.
FIND_BY_UNAME
Set thiskeyword toaUNAMEvaluethat will besearched for in thewidget hierarchy, and
if awidget with thegiven UNAMEisin thehierarchy, itsIDisreturned. Thesearch starts
in thehierarchywith thegiven widget IDand travelsdown, and thiskeyword returnsthe
widget ID of the rst widget that has the specied UNAME value.
If a widget is not found, 0 is returned.
GEOMETRY
Set this keyword to return a WIDGET_GEOMETRY structure that describes the offset
and size information for the widget specied by Widget_ID. This structure has the
following denition:
{ WIDGET_GEOMETRY,
XOFFSET:0.0,
YOFFSET:0.0,
XSIZE:0.0,
YSIZE:0.0,
SCR_XSIZE:0.0,
SCR_YSIZE:0.0,
DRAW_XSIZE:0.0,
DRAW_YSIZE:0.0,
MARGIN:0.0,
XPAD:0.0,
YPAD:0.0,
SPACE:0.0 }
With the exception of MARGIN, all of the structures elds correspond to the keywords
of the same name to the various widget routines. MARGIN is the width of any frame
added to the widget, in units specied by the UNITS keyword (pixels are the default).
Therefore, the actual width of any widget is:
SCR_XSIZE + (2* MARGIN)
The actual height of any widget is:
SCR_YSIZE + (2 * MARGIN)
Notealsothat if thetop-level baseincludesamenubar, it isnot possibletodeterminethe
actual height of thebasewidget. CallingWIDGET_INFOwiththeGEOMETRYkeyword
on atoplevel basethat includesamenubar will return ageometrystructurethat contains
zeroes rather than the actual sizes of the widget.
Note Menubars are not included in the size of a top-level base, so the actual height of a
widget that includes a menubar is:
SCR_YSIZE + (2 * MARGIN) + menubar height
It isnot possibleto either determineor changetheheight of amenubar within IDL.
RetrievingtheWIDGET_GEOMETRYstructureof amenubar yieldsastructurewith
all the elds set equal to zero.
KBRD_FOCUS_EVENTS
Set this keyword to return the keyboard focus events status of the widget specied by
Widget ID. WIDGET_INFO returns 1 (one) if keyboard focus events are currently
enabled for the widget, or 0 (zero) if they are not. Only base, table, and text widgets can
generate keyboard focus events.
LIST_MULTIPLE
Set this keyword equal to a named variable that will contain a non-zero value if the list
widget supportsmultipleitemselections. SeetheMULTIPLEkeywordtoWIDGET_LIST
for more on multiple item selections.
LIST_NUMBER
Set this keyword to return the number of elements currently contained in the specied
list widget.
LIST_NUM_VISIBLE
Set this keyword to return the number of elements that can be visible in the scrolling
viewport of the specied list widget. Note that this value can be larger than the total
number of elements actually in the list.
LIST_SELECT
Set this keyword to return the index or indices of the currently-selected (highlighted)
element or elements in the specied list widget. Note that this offset is zero-based. If no
element is currently selected, -1 is returned.
LIST_TOP
Set thiskeyword to return thezero-based offset of thetopmost element currently visible
in the specied list widget.
MANAGED
Set this keyword equal to a named variable. If a single widget ID is specified in the call to
WIDGET_INFO, the variable will contain a True (1) value if the specified widget is
managed, or False(0) otherwise. If nowidget IDisspecifiedin thecall toWIDGET_INFO,
the variable will contain an array containing the widget IDs of all currently-managed
widgets.
MODAL
This keyword applies to widgets created with the WIDGET_BASE function and the
MODAL keyword.
If thiskeyword isset, WIDGET_INFOwill return True(1) if thebasewidget specied by
Widget_ID is a modal base widget, or False (0) otherwise.
NAME
Set this keyword to return the widget type name of the widget specied by Widget_ID.
The returned value will be one of the following strings: BASE, BUTTON, DRAW,
DROPLIST, LABEL, LIST, SLIDER, TABLE, or TEXT. Set the TYPE keyword
to return the widgets type code.
PARENT
Set this keyword to return the widget ID of the parent of the widget specied by
Widget_ID. If the widget is a top-level base (i.e., it has no parent), 0 is returned.
REALIZED
Set thiskeyword to return 1if thewidget specied by Widget_IDhasbeen realized. If the
widget has not been realized, 0 is returned.
ROW_HEIGHTS
Set this keyword to return an array of long integers giving the height of each row in the
table. If USE_TABLE_SELECT isset, only therowheightsfor thecurrently-selected cells
are returned.
SIBLING
Set this keyword to return the widget ID of the rst sibling of the widget specied by
Widget_ID. If the widget is the last sibling in the chain, 0 is returned.
SLIDER_MIN_MAX
Set this keyword to return the current minimum and maximum values of the specied
slider as a two-element integer array. Element 0 is the minimum value and element 1 is
the maximum value.
TABLE_ALL_EVENTS
Set thiskeyword to return 1(one) if Widget_IDisatablewidget with theALL_EVENTS
attribute set. Otherwise, 0 (zero) is returned.
TABLE_EDITABLE
Set this keyword to return 1 (one) if Widget_ID is a table widget that allows user editing
of its contents. Otherwise, 0 (zero) is returned.
TABLE_EDIT_CELL
Set thiskeywordtoreturnatwo-element integer arraycontainingtheXandYcoordinates
of thecurrently editablecell. If noneof thecellsin thetablewidget iscurrently editable,
the array [ -1, -1] is returned.
TABLE_SELECT
Set this keyword to return an array of the form [ left, top, right, bottom] containing the
zero-based indices of the currently-selected (highlighted) cells in the specied table
widget.
TABLE_VIEW
Set thiskeyword toreturn atwo-element arrayof theform[ left, top] containingthezero-
based offsets of the top-left cell currently visible in the specied table widget.
TEXT_ALL_EVENTS
Set thiskeywordtoreturn1if Widget_IDisatext widget withtheALL_EVENTSattribute
set. Otherwise, 0 is returned.
TEXT_EDITABLE
Set this keyword to return 1 if Widget_ID is a text widget that allows user editing of its
contents. Otherwise, 0 is returned.
TEXT_NUMBER
Set thiskeyword to return thenumber of characterscurrently contained in thespecied
text widget.
TEXT_OFFSET_TO_XY
Use this keyword to translate a text widget character offset into column and line form.
The value of this keyword should be set to the character offset (an integer) to be
translated. WIDGET_INFO returns a two-element integer array giving the column
(element 0) and line(element 1) correspondingto theoffset. If theoffset specied isout
of range, the array [ -1,-1] is returned.
TEXT_SELECT
Set this keyword to return the starting character offset and length (in characters) of the
selected (highlighted) text in the specied text widget. WIDGET_INFO returns a two-
element integer array containingthestartingposition of thehighlighted text asan offset
from character zero of the text in the widget (element 0), and length of the current
selection (element 1).
TEXT_TOP_LINE
Set thiskeyword toreturn thezero-based linenumber of thelinecurrentlyat thetop of a
text widgets display viewport. Note that this value is different from the zero-based
character offset of the characters in the line. The character offset can be calculated from
the line offset via the TEXT_XY_TO_OFFSET keyword.
TEXT_XY_TO_OFFSET
Usethiskeyword to translateatext widget position given in lineand column forminto a
character offset. The value of this keyword should be set to a two-element integer array
specifying the column (element 0) and line (element 1) position. WIDGET_INFO
returnsthecharacter offset (asalongword integer) correspondingto theposition. If the
position specied is out of range, -1 is returned.
This keyword applies to widgets created with the WIDGET_BASE function.
Set this keyword to return 1 if the top-level base of the widget specied by Widget_ID is
set to return kill request events. Otherwise, 0 is returned.
TRACKING_EVENTS
Set hiskeywordtoreturnthetrackingeventsstatusfor thewidget speciedbyWidget_ID.
WIDGET_INFO returns 1 if tracking events are currently enabled for the widget.
Otherwise, 0 is returned.
TYPE
Set this keyword to return the type code of the specied Widget_ID. Possible values are
given in Table 9-74. Note that you can set the NAME keyword to return string names
instead.
UNAME
Set this keyword to have the WIDGET_INFO function return the user name of the
widget.
UNITS
Usethiskeywordtospecifytheunit of measurement usedwhenreturningdimensionsfor
most widget types. Set UNITS equal to 0 (zero) to specify that all measurements are in
pixels(thisisthedefault), to 1(one) to specify that all measurementsarein inches, or to
2 (two) to specify that all measurements are in centimeters.
ignoredwhenretrievingtheXSIZEor YSIZEof aWIDGET_LIST, WIDGET_TABLE,
or WIDGET_TEXT.
Value Type
0 Base
1 Button
2 Slider
3 Text
4 Draw
5 Label
6 List
8 Droplist
9 Table
Table 9-74: Widget Type Codes
UPDATE
Set this keyword to return 1 if the widget hierarchy that containsWidget_ID is set to
display updates. Otherwise, 0 is returned. See UPDATE on page1249.
USE_TABLE_SELECT
Set this keyword to modify the behavior of the COLUMN_WIDTHS and
ROW_HEIGHTS keywords. If USE_TABLE_SELECT is set, the COLUMN_WIDTHS
andROW_HEIGHTSkeywordsonlyapplytothecurrently-selectedcells. Normally, these
keywords apply to the entire contents of a table widget.
TheUSE_TABLE_SELECT keyword can also bespecied asafour-element array, of the
form[ left, top, right, bottom] , givingthegroup of cellsto act on. In thisusage, thevalue
-1 is used to refer to the row or column titles.
VALID_ID
Set thiskeyword toreturn 1if Widget_IDrepresentsacurrently-valid widget. Otherwise,
0 is returned.
VERSION
Set this keyword to return a structure that gives information about the widget
implementation. This structure has the following denition:
{ WIDGET_VERSION, STYLE:'', TOOLKIT:'', RELEASE:'' }
STYLE isthestyleof widget toolkit used. TOOLKIT istheimplementation of thetoolkit.
RELEASE istheversion level of thetoolkit. Thiseld can beused to distinguish between
different releases of a given toolkit, such as Motif 1.0 and Motif 1.1.
See Also
WIDGET_LABEL IDL Reference Guide
WIDGET_LABEL
The WIDGET_LABEL function is used to create label widgets.
The returned value of this function is the widget ID of the newly-created label widget.
Calling Sequence
Result = WIDGET_LABEL(Parent)
Arguments
Parent
The widget ID of the parent widget for the new label widget.
Keywords
ALIGN_CENTER
Set this keyword to center justify the label text.
ALIGN_LEFT
Set this keyword to left justify the label text.
ALIGN_RIGHT
Set this keyword to right justify the label text.
DYNAMIC_RESIZE
is changed. Note that this keyword cannot be used with the SCR_XSIZE, SCR_YSIZE,
XSIZE, or YSIZEkeywords. If oneof thesekeywordsisalsoset, thewidget will besizedas
specied by the sizing keyword and will never resize itself dynamically.
FONT
Windowsfont onMotif systems; aTrueTypeor PostScript font onWindowssystems). See
About Device Fonts on page72 for details on specifying names for device fonts. If this
keyword is omitted, the default font is used.
question. This keyword is not supported on the Macintosh.
IDL Reference Guide WIDGET_LABEL
FRAME
FUNC_GET_VALUE
GROUP_LEADER
destroyed.
KILL_NOTIFY
called.
NO_COPY
operation (using the UVALUE keyword to WIDGET_LABEL or the SET_UVALUE
NOTIFY_REALIZE
PRO_SET_VALUE
RESOURCE_NAME
SCR_XSIZE
SCR_YSIZE
SENSITIVE
IDL Reference Guide WIDGET_LABEL
TRACKING_EVENTS
WIDGET_BASE.
UNAME
specied name.
UNITS
UVALUE
created.
VALUE
The initial value setting of the widget. The value of a widget label is a string containing
the text for the label.
XOFFSET
XSIZE
YOFFSET
parent widget.
YSIZE
label widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: DYNAMIC_RESIZE, GET_VALUE, SET_VALUE.
specically to label widgets. In addition to those keywords that apply to all widgets, the
following are particularly useful: DYNAMIC_RESIZE.
Widget Events Returned by Label Widgets
Label widgets do not return an event structure.
See Also
CW_FIELD, WIDGET_TEXT
IDL Reference Guide WIDGET_LIST
WIDGET_LIST
TheWIDGET_LIST function isused to createlist widgets. A list widget offerstheuser a
list of text elements from which to choose. The user can select an item by pointing at it
with the mouse cursor and pressing a button. This action generates an event containing
theindex of theselected item, which rangesfrom0to thenumber of elementsin thelist
minus one.
The returned value of this function is the widget ID of the newly-created list widget.
Calling Sequence
Result = WIDGET_LIST(Parent)
Arguments
Parent
The widget ID of the parent widget for the new list widget.
Keywords
EVENT_FUNC
widget.
EVENT_PRO
created widget.
FONT
question.
WIDGET_LIST IDL Reference Guide
FRAME
FUNC_GET_VALUE
GROUP_LEADER
destroyed.
KILL_NOTIFY
called.
MULTIPLE
Set this keyword to allow the user to select more than one item from the list in a single
operation. Multiple selections are handled using the platforms native mechanism:
Motif
Holding down the Shift key and clicking an item selects the range from the previously
selecteditemtothenewitem. Holdingdown themousebutton when selectingitemsalso
selects a range. Holding down the Control key and clicking an item toggles that item
between the selected and unselected state.
Windows
selecteditemtothenewitem. Holdingdown theControl keyandclickingan itemtoggles
that item between the selected and unselected state.
Macintosh
selected item to the new item. Holding down the Command key and clicking an item
toggles that item between the selected and unselected state.
NO_COPY
operation(usingtheUVALUEkeywordtoWIDGET_LISTor theSET_UVALUEkeyword
to WIDGET_CONTROL), the variable passed as value becomes undened. On a get
operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the
widget in question becomes undened.
NOTIFY_REALIZE
PRO_SET_VALUE
RESOURCE_NAME
SCR_XSIZE
SCR_YSIZE
SENSITIVE
TRACKING_EVENTS
WIDGET_BASE.
UNAME
specied name.
UNITS
ignored when setting the XSIZE or YSIZE keywords to WIDGET_LIST.
UVALUE
created.
VALUE
Theinitial valuesettingof thewidget. Thevalueof alist widget isascalar stringor array
of strings that contains the text of the list itemsone list item per array element. List
widgets are sized based on the length (in characters) of the longest item specied in the
array of values for the VALUE keyword.
Note that the value of a list widget can only be set. It cannot be retrieved using
WIDGET_CONTROL.
XOFFSET
XSIZE
The desired width of the widget, in characters. Most widgets attempt to size themselves
to t the situation. However, if the desired effect is not produced, use this keyword to
override it. Note that the nal size of the widget may be adjusted to include space for
scrollbars (which are not always visible), so your widget may be slightly larger than
specied.
YOFFSET
parent widget.
YSIZE
Thedesired height of thewidget, in number of list itemsvisible. Most widgetsattempt to
sizethemselvestot thesituation. However, if thedesired effect isnot produced, usethis
keyword to override it. Note that the nal size of the widget may be adjusted to include
space for scrollbars (which are not always visible), so your widget may be slightly larger
than specied.
Anumber of keywordstotheWIDGET_CONTROL procedureaffect thebehavior of list
widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: SET_LIST_SELECT, SET_LIST_TOP, SET_VALUE.
specically to list widgets. In addition to those keywords that apply to all widgets, the
following are particularly useful: LIST_MULTIPLE, LIST_NUMBER,
LIST_NUM_VISIBLE, LIST_SELECT, LIST_TOP.
Widget Events Returned by List Widgets
Pressing the mouse button while the mouse cursor is over an element of a list widget
causes the widget to highlight the appearance of that element and to generate an event.
Theappearanceof anypreviouslyselectedelement isrestoredtonormal at thesametime.
The event structure returned by the WIDGET_EVENT function is dened by the
following statement:
{ WIDGET_LIST, ID:0L, TOP:0L, HANDLER:0L, INDEX:0L, CLICKS:0L}
Therst threeeldsarethestandard eldsfound in every widget event. INDEX returns
the index of the selected item. This index can be used to subscript the array of names
originally used to set the widgets value. The CLICKS eld returns either 1 or 2,
dependingupon howthelist itemwasselected. If thelist itemisdouble-clicked, CLICKS
is set to 2.
Note If you arewritingawidget application that requirestheuser todouble-click on alist
widget, you will need to handletwo events. TheCLICKSeld will return a1on the
rst click and a 2 on the second click.
See Also
CW_BGROUP, WIDGET_DROPLIST
IDL Reference Guide WIDGET_SLIDER
WIDGET_SLIDER
The WIDGET_SLIDER function is used to create slider widgets. Slider widgets are used
to indicatean integer valuefromarangeof possiblevalues. They consist of arectangular
region whichrepresentsthepossiblerangeof values. Insidethisregion isaslidingpointer
that displays the current value. This pointer can be manipulated by the user via the
mouse, or from within IDL via the WIDGET_CONTROL procedure.
To indicated oating-point values, see CW_FSLIDER on page377.
The returned value of this function is the widget ID of the newly-created slider widget.
Calling Sequence
Result = WIDGET_SLIDER(Parent)
Arguments
Parent
The widget ID of the parent for the new slider widget.
Keywords
DRAG
Set this keyword to cause events to be generated continuously while the slider is being
dragged by the user. Normally, slider widgets generate position events only when the
slider comes to rest at its nal position and the mouse button is released.
When a slider widget is set to return drag events, a large number of events can be
generated. On slower machines, poor performance can result. Therefore, this option
should only be used when detailed or truly interactive control is required.
Caution Under Microsoft Windows and Macintosh, sliders do not generate DRAG events.
Sliders created with the DRAG keyword behave just like regular sliders.
EVENT_FUNC
widget.
EVENT_PRO
created widget.
WIDGET_SLIDER IDL Reference Guide
FONT
question.
FRAME
FUNC_GET_VALUE
GROUP_LEADER
destroyed.
KILL_NOTIFY
called.
MAXIMUM
The maximum value of the range encompassed by the slider. If this keyword is not
supplied, a default of 100 is used.
MINIMUM
The minimum value of the range encompassed by the slider. If this keyword is not
supplied, a default of 0 is used.
NO_COPY
operation (using the UVALUE keyword to WIDGET_SLIDER or the SET_UVALUE
NOTIFY_REALIZE
PRO_SET_VALUE
RESOURCE_NAME
SCR_XSIZE
SCR_YSIZE
SCROLL
Under the Motif window manager, the value provided for SCROLL species how many
units the scroll bar should move when the user clicks the left mouse button inside the
slider area, but not on the slider itself. This keyword has no effect under other window
systems.
SENSITIVE
SUPPRESS_VALUE
Set this keyword to inhibit the display of the current slider value.
Sliders work only with integer units. This keyword can be used to suppress the actual
valueof aslider sothat aprogramcan present theuser with aslider that seemstowork in
other units (such as oating-point) or with a non-linear scale.
TRACKING_EVENTS
WIDGET_BASE.
TITLE
A string containing the title to be used for the slider widget.
UNAME
specied name.
UNITS
UVALUE
created.
VALUE
Theinitial valuesettingof thewidget. Thevalueof awidget slider isthecurrent position
of the slider.
VERTICAL
Set this keyword to crate a vertical slider. If this keyword is omitted, the slider is
horizontal.
XOFFSET
XSIZE
YOFFSET
parent widget.
YSIZE
slider widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: GET_VALUE, SET_SLIDER_MAX, SET_SLIDER_MIN,
SET_VALUE.
specically to slider widgets. In addition to thosekeywordsthat apply to all widgets, the
following are particularly useful: SLIDER_MIN_MAX.
Slider Widget Events
Slider widgets generate events when the mouse is used to change their value. The event
structure returned by the WIDGET_EVENT function is dened by the following
statement:
{WIDGET_SLIDER, ID:0L, TOP:0L, HANDLER:0L, VALUE:0L, DRAG:0}
ID is the widget ID of the button generating the event. TOP is the widget ID of the top
level widget containing ID. HANDLER contains the widget ID of the widget associated
with the handler routine. VALUE returns the new value of the slider. DRAG returns
integer 1if theslider event wasgenerated aspart of adragoperation, or zero if theevent
was generated when the user had nished positioning the slider. Note that the slider
widget only generateseventsduringthedragoperation if theDRAGkeyword isset, and
if theapplicationisrunningunder Motif. WhentheDRAGkeywordisset, theDRAGeld
can be used to avoid computationally expensive operations until the user releases the
slider.
Known Implementation Problems
Under Motif 1.0, vertical sliders with a title organized in row bases get horizontally
truncated and the slider doesnt show (the title does). Use the XSIZE keyword to work
around this.
See Also
CW_FSLIDER
WIDGET_TABLE IDL Reference Guide
WIDGET_TABLE
The WIDGET_TABLE function creates table widgets. Table widgets display two-
dimensional data and allow in-place data editing. They can have one or more rows and
columns, andautomaticallycreatescroll barswhenviewingmoredatathancanotherwise
be displayed on the screen.
Note on Table Sizing
Table widgets are sized according to the value of the following pairs of keywords to
WIDGET_TABLE, in order of precedence: SCR_XSIZE/SCR_YSIZE, XSIZE/YSIZE,
X_SCROLL_SIZE/Y_SCROLL_SIZE, VALUE. If either dimension remains unspecied
byoneof theabovekeywords, thedefault valueof six (columnsor rows) isusedwhen the
tableiscreated. If thewidth or height specied islessthan thesizeof thetable, scroll bars
are added automatically.
The returned value of this function is the widget ID of the newly-created table widget.
Calling Sequence
Result = WIDGET_TABLE(Parent)
Arguments
Parent
The widget ID of the parent widget for the new table widget.
Keywords
ALIGNMENT
Set thiskeyword equal toascalar or 2-Darrayspecifyingthealignment of thetext within
each cell. An alignment of 0(thedefault) alignstheleft edgeof thetext with theleft edge
of thecell. An alignment of 2right-justiesthetext, while1resultsin text centeredwithin
the cell. If ALIGNMENT is set equal to a scalar, all table cells are aligned as specied. If
ALIGNMENT is set equal to a 2-D array, the alignment of each table cell is governed by
the corresponding element of the array.
ALL_EVENTS
AlongwiththeEDITABLEkeyword, ALL_EVENTScontrolsthetypeof eventsgenerated
by the table widget. Set the ALL_EVENTS keyword to cause the full set of events to be
generated. If ALL_EVENTS is not set, setting EDITABLE causes only end-of-line events
to be generated. If EDITABLE is not set, all events are suppressed. See Table 9-75 for
additional details.
IDL Reference Guide WIDGET_TABLE
AM_PM
FORMAT keyword.
COLUMN_LABELS
Set this keyword equal to an array of strings used as label for the columns of the table
widget. Thedefault labelsareof theformColumn n, wherenisthecolumn number. If
this keyword is set to the empty string (''), all column labels are set to be empty.
COLUMN_MAJOR
This keyword is only valid if the table data is organized as a vector of structures rather
than a two-dimensional array. See the VALUE keyword for details.
Set this keyword to specify that the data should be read into the table as if each element
of the vector is a structure containing one columns data. Note that the structures must
all beof thesametype, and must haveoneeld for each rowin thetable. If thiskeyword
is not set, the table widget behaves as if the ROW_MAJOR keyword were set.
COLUMN_WIDTHS
Set this keyword equal to an array of widths for the columns of the table widget. The
widths are given in any of the units as specied with the UNITS keyword. If no width is
specied for acolumn, that column isset to thedefault size, which variesby platform. If
COLUMN_WIDTHS is set to a scalar value, all columns are set to that width.
DAYS_OF_WEEK
FORMAT keyword.
Keywords Effects
ALL_EVENTS EDITABLE
Input changes
widget contents?
Type of events
generated.
Table 9-75: Effects of using the ALL_EVENTS and EDITABLE keywords
EDITABLE
Set thiskeywordtoallowdirect user editingof thetext widget contents. Normally, thetext
in text widgetsisread-only. SeeTable9-75for adescription of howEDITABLEinteracts
with the ALL_EVENTS keyword.
Note Themethod by which text widgetsareplaced into edit modeisdependent upon the
windowing system. On Microsoft Windows, for instance, a cell must be double-
clicked to be placed into edit mode."
EVENT_FUNC
widget.
EVENT_PRO
created widget.
FONT
A single font is shared by the row and column labels and by all of the cells in the widget.
question.
FORMAT
Set thiskeyword equal to asinglestringor array of stringsthat specify theformat of data
displayed within table cells. The string(s) are of the same form as used by the FORMAT
keyword to thePRINT procedure, and thedefault format isthesameasthat used by the
PRINT procedure.
Caution If theformat speciedisincompatiblewiththedatadisplayedin atablecell, an error
messageisgenerated. Sincetheerror isgenerated for eachcell displayed, thenumber
of messages printed is potentially large, and can slow execution signicantly. Note
also that each time a new cell is displayed (when scroll bars are repositioned, for
example), a new error is generated for each cell displayed.
FRAME
FUNC_GET_VALUE
GROUP_LEADER
destroyed.
KBRD_FOCUS_EVENTS
focusof thebasechanges. SeetheWidget EventsReturnedbyTableWidgetssectionbelow
for more information.
KILL_NOTIFY
called.
MONTHS
FORMAT keyword.
NO_COPY
operation (using the UVALUE keyword to WIDGET_TABLE or the SET_UVALUE
NO_HEADERS
Set this keyword to disable the display of the table widgets header area (where row and
column labels are normally displayed).
NOTIFY_REALIZE
PRO_SET_VALUE
RESIZEABLE_COLUMNS
Set this keyword to allow the user to change the size of columns using the mouse. Note
that if the NO_HEADERS keyword was set, the columns cannot be resized interactively.
RESIZEABLE_ROWS
Set this keyword to allow the user to change the size of rows using the mouse. Note that
if the NO_HEADERS keyword was set, the rows cannot be resized interactively.
Under Microsoft Windows, the row size cannot be changed.
RESOURCE_NAME
ROW_HEIGHTS
Set thiskeyword equal toan arrayof heightsfor therowsof thetablewidget. Theheights
aregiven in anyof theunitsasspeciedwiththeUNITSkeyword. If noheight isspecied
for arow, that rowisset tothedefault size, which variesbyplatform. If ROW_HEIGHTS
is set to a scalar value, all of the row heights are set to that value.
ROW_LABELS
Set thiskeyword equal to an array of stringsto beused aslabelsfor therowsof thetable.
I f no label is specied for a row, it receives the default label Rown, wheren is the row
number. If thiskeyword isset to theempty string(''), all rowlabelsareset to beempty.
ROW_MAJOR
This keyword is only valid if the table data is organized as a vector of structures rather
than a two-dimensional array. See the VALUE keyword for details.
Set this keyword to specify that the data should be read into the table as if each element
of thevector isastructurecontainingonerowsdata. Notethat thestructuresmust all be
of thesametype, and must haveoneeld for each column in thetable. Thisisthedefault
behavior if neither the COLUMN_MAJOR or ROW_MAJOR keyword is set.
SCR_XSIZE
UNITSkeyword(pixelsarethedefault). Notethat thescreen widthof thewidget includes
thewidthof scroll bars, if anyarepresent. SettingSCR_XSIZEoverridesvaluesset for the
XSIZE or X_SCROLL_SIZE keywords. See Note on Table Sizing on page1298.
SCR_YSIZE
UNITSkeyword(pixelsarethedefault). Notethat thescreenheight of thewidget includes
theheight of scroll bars, if anyarepresent. SettingSCR_YSIZEoverridesvaluesset for the
YSIZE or Y_SCROLL_SIZE keywords. See Note on Table Sizing on page1298.
SCROLL
contents that are not currently on the screen. See Note on Table Sizing on page1298
SENSITIVE
TRACKING_EVENTS
WIDGET_BASE.
UNAME
specied name.
UNITS
ignored when setting the XSIZE or YSIZE keywords to WIDGET_TABLE.
UVALUE
created.
If UVALUE is not present, the widget's initial user value is undened.
VALUE
The initial value setting of the widget. The value of a table widget is either a two-
dimensional array or a vector of structures.
If thevalueisspecied asatwo-dimensional array, all datamust beof thesamedatatype.
If the value is specied as a vector of structures, it can be displayed either in column-
major or row-major format by setting either the COLUMN_MAJOR keyword or the
ROW_MAJORkeyword. All of thestructuresmust beof thesametype, andmust contain
oneeld for each column (if COLUMN_MAJORisset) or row(if ROW_MAJORisset)
in the table. If neither keyword is set, the data is displayed in row major format.
If none of [ XY] SIZE, SCR_[ XY] SIZE, or [ XY] _SCROLL_SIZE is present, the size of the
tableisdeterminedbythesizeof thearrayor vector of structuresspeciedbyVALUE. See
Note on Table Sizing on page1298.
XOFFSET
XSIZE
Thewidthof thewidget incolumns. If rowlabelsarepresent, onecolumnisautomatically
added to this value. See Note on Table Sizing on page1298.
X_SCROLL_SIZE
The XSIZE keyword always species the width of a widget, in columns. When the
SCROLL keyword is specied, this size is not necessarily the same as the width of the
visible area. The X_SCROLL_SIZE keyword allows you to set the width of the scrolling
viewport independently of the actual width of the widget. See Note on Table Sizing on
page1298.
Use of the X_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will
be added in both the horizontal and vertical directions when X_SCROLL_SIZE is
it is best to specify Y_SCROLL_SIZE when specifying X_SCROLL_SIZE.
YOFFSET
default) relativetoitsparent. Thisoffset isspeciedrelativetotheupper left corner of the
parent widget.
YSIZE
The height of the widget in rows. If column labels are present, one row is automatically
added to this value. See Note on Table Sizing on page1298.
Y_SCROLL_SIZE
The YSIZE keyword always species the height of a widget. in rows. When the SCROLL
keyword isspecied, thissizeisnot necessarily thesameastheheight of thevisiblearea.
The Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport
independently of the actual width of the widget. See Note on Table Sizing on page1298.
Use of the Y_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will
be added in both the horizontal and vertical directions when Y_SCROLL_SIZE is
it is best to specify X_SCROLL_SIZE when specifying Y_SCROLL_SIZE.
table widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: ALIGNMENT, ALL_TABLE_EVENTS, COLUMN_LABELS,
COLUMN_WIDTHS, DELETE_COLUMNS, DELETE_ROWS, EDITABLE,
EDIT_CELL, FORMAT, GET_VALUE, INSERT_COLUMNS, INSERT_ROWS,
KBRD_FOCUS_EVENTS, ROW_LABELS, ROW_HEIGHTS, SET_TABLE_SELECT,
SET_TABLE_VIEW, SET_TEXT_SELECT, SET_VALUE, TABLE_XSIZE,
TABLE_YSIZE, USE_TABLE_SELECT, USE_TEXT_SELECT.
specically to table widgets. In addition to those keywords that apply to all widgets, the
following are particularly useful: COLUMN_WIDTHS, KBRD_FOCUS_EVENTS,
ROW_HEIGHTS, TABLE_ALL_EVENTS, TABLE_EDITABLE, TABLE_EDIT_CELL,
TABLE_SELECT, TABLE_VIEW, USE_TABLE_SELECT.
Widget Events Returned by Table Widgets
Thereareseveral variationsof thetablewidget event structuredependingon thespecic
event being reported. All of these structures contain the standard three elds (ID, TOP,
and HANDLER) as well as an integer TYPE eld that indicates which type of structure
hasbeen returned. Programsshould alwayscheck theeld typebeforereferencingelds
that are not present in all table event structures. The different table widget event
structures are described below.
Insert Single Character (TYPE = 0)
Thisisthetypeof structurereturnedwhen asinglecharacter istypedintoacell of atable
widget by a user.
{WIDGET_TABLE_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, OFFSET:0L,
CH:0B, X:0L, Y:0L }
OFFSET is the (zero-based) insertion position that will result after the character is
inserted. CH is the ASCII value of the character. X and Y give the zero-based address of
the cell within the table.
Insert Multiple Characters (TYPE = 1)
This is the type of structure returned when multiple characters are pasted into a cell by
the window system.
{WIDGET_TABLE_STR, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, OFFSET:0L,
STR:'', X:0L, Y:0L}
OFFSET is the (zero-based) insertion position that will result after the text is inserted.
STRisthestringtobeinserted. Xand Ygivethezero-based addressof thecell within the
table.
Delete Text (TYPE = 2)
Thisisthetypeof structurereturned when any amount of text isdeleted fromacell of a
table widget.
{WIDGET_TABLE_DEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:2, OFFSET:0L,
LENGTH:0L, X:0L, Y:0L}
OFFSET isthe(zero-based) character position of therst character deleted. It isalso the
insertion position that will result when thenext character isinserted. LENGTH givesthe
number of charactersinvolved. Xand Ygivethezero-based addressof thecell within the
table.
Text Selection (TYPE = 3)
Thisisthetypeof structurereturned when an areaof text isselected (highlighted) bythe
user.
{WIDGET_TABLE_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:3,
OFFSET:0L, LENGTH:0L, X:0L, Y:0L}
The event announces a change in the insertion point. OFFSET is the (zero-based)
character position of the rst character to be selected. LENGTH gives the number of
characters involved. A LENGTH of zero indicates that the widget has no selection, and
that theinsertion position isgiven byOFFSET. XandYgivethezero-basedaddressof the
cell within the table.
Note Text insertion, text deletion, or any changein thecurrent insertion point causesany
current selection to be lost. In such cases, the loss of selection is implied by the text
event reportingtheinsert/delete/movement andaseparatezerolengthselectionevent
is not sent.
Cell Selection (TYPE = 4)
This is the type of structure returned when range of cells is selected (highlighted) or
deselected by the user.
{WIDGET_TABLE_CELL_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:4,
SEL_LEFT:0L, SEL_TOP:0L, SEL_RIGHT:0L, SEL_BOTTOM:0L}
Theevent announcesachangein thecurrentlyselectedcells. Therangeof cellsselectedis
given by the zero-based indices into the table specied by the SEL_LEFT, SEL_TOP,
SEL_RIGHT, and SEL_BOTTOM elds. When cells are deselected (either by changing
the selection or by clicking in the upper left corner of the table) an event is generated in
which the SEL_LEFT, SEL_TOP, SEL_RIGHT, and SEL_BOTTOM elds contain the
value -1.
Note This means that two WIDGET_TABLE_CELL_SEL events are generated when an
existing selection is changed to a new selection. If your code pays attention to
WIDGET_TABLE_CELL_SEL events, be sure to differentiate between select and
deselect events.
Row Height Changed (TYPE = 6)
This is the type of structure returned when a row height is changed by the user.
{WIDGET_TABLE_ROW_HEIGHT, ID:0L, TOP:0L, HANDLER:0L, TYPE:6,
ROW:0L, HEIGHT:0L}
Theevent announcesthat theheight of thegiven rowhasbeen changed by theuser. The
ROWeldcontainsthezero-basedrownumber, andtheHEIGHT eldcontainsthenew
height.
Column Width Changed (TYPE = 7)
This is the type of structure returned when a column width is changed by the user.
{WIDGET_TABLE_COLUMN_WIDTH, ID:0L, TOP:0L, HANDLER:0L, TYPE:7,
COLUMN:0L, WIDTH:0L}
The event announces that the width of the given column has been changed by the user.
The COLUMN eld contains the zero-based column number, and the WIDTH eld
contains the new width.
Invalid Data (TYPE = 8)
This is the type of structure returned when the text entered by the user does not pass
validation, and the user has nished editing the eld (by hitting TAB or ENTER).
{WIDGET_TABLE_INVALID_ENTRY, ID:0L, TOP:0L, HANDLER:0L, TYPE:8,
STR:'', X:0L, Y:0L}
When this event is generated, the cells data is left unchanged. The invalid contents
entered by the user is given as a text string in the STR eld. The cell location is given by
the X and Y elds.
Tablewidgetsreturn thefollowingevent structurewhen thekeyboard focuschangesand
ID isthewidget ID of thetablewidget generatingtheevent. TOPisthewidget ID of the
top level widget containing ID. HANDLER contains the widget ID of the widget
associated with thehandler routine. TheENTEReld returns1(one) if thetablewidget
isgainingthekeyboard focus, or 0(zero) if thetablewidget islosingthekeyboard focus.
See Also
WIDGET_CONTROL
IDL Reference Guide WIDGET_TEXT
WIDGET_TEXT
The WIDGET_TEXT function creates text widgets. Text widgets display text and
optionally get textual input from the user. They can have 1 or more lines, and can
optionallycontain scroll barstoallowviewingmoretext than can otherwisebedisplayed
on the screen.
The returned value of this function is the widget ID of the newly-created text widget.
Calling Sequence
Result = WIDGET_TEXT(Parent)
Arguments
Parent
The widget ID of the parent widget for the new text widget.
Keywords
ALL_EVENTS
AlongwiththeEDITABLEkeyword, ALL_EVENTScontrolsthetypeof eventsgenerated
by the text widget. Set the ALL_EVENTS keyword to cause the full set of events to be
generated. If ALL_EVENTS is not set, setting EDITABLE causes only end-of-line events
to be generated. If EDITABLE is not set, all events are suppressed. See Table 9-76 for
additional details.
Keywords Effects
ALL_EVENTS EDITABLE
Input changes
widget contents?
Type of events
generated.
Table 9-76: Effects of using the ALL_EVENTS and EDITABLE keywords.
WIDGET_TEXT IDL Reference Guide
EDITABLE
Set thiskeywordtoallowdirect user editingof thetext widget contents. Normally, thetext
in text widgetsisread-only. SeeTable9-72for adescription of howEDITABLEinteracts
with the ALL_EVENTS keyword.
EVENT_FUNC
widget.
EVENT_PRO
created widget.
FONT
question.
FRAME
keyword (pixels are the default) to be drawn around the borders of the widget.
Note This keyword is only a hint to the toolkit, and may be ignored in some instances.
Under Microsoft Windows, text widgetsalwayshave frames.
FUNC_GET_VALUE
GROUP_LEADER
destroyed.
KBRD_FOCUS_EVENTS
focusof thebasechanges. SeetheText Widget Eventssectionbelowfor moreinformation.
KILL_NOTIFY
called.
NO_COPY
operation (using the UVALUE keyword to WIDGET_TEXT or the SET_UVALUE
NO_NEWLINE
Normally, when setting the value of a multi-line text widget, newline characters are
automatically appended to the end of each line of text. Set this keyword to suppress this
action.
NOTIFY_REALIZE
PRO_SET_VALUE
RESOURCE_NAME
SCR_XSIZE
SCR_YSIZE
SCROLL
contents that are not currently on the screen.
SENSITIVE
TRACKING_EVENTS
WIDGET_BASE.
UNAME
specied name.
UNITS
ignored when setting the XSIZE or YSIZE keywords to WIDGET_TEXT.
UVALUE
created.
VALUE
The initial value setting of the widget. The value of a text widget is the current text
displayed by the widget.
VALUE can be either a string or an array of strings. Note that variables returned by the
GET_VALUEkeyword to WIDGET_CONTROL arealwaysstringarrays, even if ascalar
string is specied in the call to WIDGET_TEXT.
WRAP
Set thiskeywordtoindicatethat scrollingor multi-linetext widgetsshouldautomatically
break linesbetween wordsto keep thetext fromextendingpast theright edgeof thetext
displayarea. Notethat carriagereturnsarenotautomaticallyenteredwhenlineswrap; the
value of the text widget will remain a single-element array unless you explicitly enter a
carriage return.
XOFFSET
XSIZE
The width of the widget in characters. Note that the physical width of the text widget
dependson both thevalueof XSIZEand on thesizeof thefont used. Thedefault valueof
XSIZE varies according to your windowing system. On Windows and Mac, the default
sizeisroughly 20characters. On Motif, thedefault sizedependson thewidth of thetext
widget.
YOFFSET
parent widget.
YSIZE
The height of the widget in text lines. Note that the physical height of the text widget
dependson both thevalueof YSIZEand on thesizeof thefont used. Thedefault valueof
YSIZE is one line.
Anumber of keywordstotheWIDGET_CONTROLprocedureaffect thebehavior of text
widgets. In addition to those keywords that affect all widgets, the following are
particularly useful: ALL_TEXT_EVENTS, APPEND, EDITABLE, GET_VALUE,
KBRD_FOCUS_EVENTS, INPUT_FOCUS, NO_NEWLINE, SET_TEXT_SELECT,
SET_TEXT_TOP_LINE, SET_VALUE, USE_TEXT_SELECT.
specically to text widgets. In addition to those keywords that apply to all widgets, the
following are particularly useful: KBRD_FOCUS_EVENTS, TEXT_ALL_EVENTS,
TEXT_EDITABLE, TEXT_NUMBER, TEXT_OFFSET_TO_XY, TEXT_SELECT,
TEXT_TOP_LINE, TEXT_XY_TO_OFFSET.
Text Widget Events
Thereareseveral variationsof t1hetext widget event structuredependingon thespecic
event being reported. All of these structures contain the standard three elds (ID, TOP,
and HANDLER) as well as an integer TYPE eld that indicates which type of structure
hasbeen returned. Programsshould alwayscheck thetypeeld beforereferencingelds
that arenot present in all text event structures. Thedifferent text widget event structures
are described below.
Insert Single Character (TYPE = 0)
Thisisthetypeof structurereturnedwhen asinglecharacter istypedor pastedintoatext
widget by a user.
{ WIDGET_TEXT_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, OFFSET:0L, CH:0B }
OFFSET is the (zero-based) insertion position that will result after the character is
inserted. CH is the ASCII value of the character.
Insert Multiple Characters (TYPE = 1)
This is the type of structure returned when multiple characters are pasted into a text
widget by the window system.
{ WIDGET_TEXT_STR, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, OFFSET:0L, STR:'' }
OFFSET is the (zero-based) insertion position that will result after the text is inserted.
STR is the string to be inserted.
Delete Text (TYPE = 2)
This is the type of structure returned when any amount of text is deleted from a text
widget.
{ WIDGET_TEXT_DEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:2, OFFSET:0L,
LENGTH:0L }
OFFSETisthe(zero-based) character positionof therst character tobedeleted. It isalso
the insertion position that will result when the characters have been deleted. LENGTH
givesthenumber of charactersinvolved. ALENGTH of zero indicatesthat no characters
were deleted.
Selection (TYPE = 3)
Thisisthetypeof structurereturned when an areaof text isselected (highlighted) bythe
user.
{ WIDGET_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:3, OFFSET:0L,
LENGTH:0L }
The event announces a change in the insertion point. OFFSET is the (zero-based)
character position of the rst character to be selected. LENGTH gives the number of
charactersinvolved. ALENGTH of zeroindicatesthat nocharactersareselected, and the
new insertion position is given by OFFSET.
Notethat text insertion, text deletion, or anychangein thecurrent insertion point causes
any current selection to be lost. In such cases, the loss of selection is implied by the text
event reportingtheinsert/delete/movement and aseparatezero length selection event is
not sent.
Text widgets return the following event structure when the keyboard focus changes and
ID is the widget ID of the text widget generating the event. TOP is the widget ID of the
top level widget containing ID. HANDLER contains the widget ID of the widget
associated with thehandler routine. TheENTEReld returns1(one) if thetext widget is
gaining the keyboard focus, or 0 (zero) if the text widget is losing the keyboard focus.
See Also
CW_FIELD, XDISPLAYFILE
IDL Reference Guide WINDOW
WINDOW
TheWINDOWprocedurecreatesawindowfor thedisplay of graphicsor text. It isonly
necessary to use WINDOW if more than one simultaneous window or a special size
window is desired because a window is created automatically the rst time any display
procedure attempts to access the window system. The newly-created window becomes
the current window, and the system variable !D.WINDOW is set to that windows
windowindex. (Seethedescriptionof theWSETprocedurefor adiscussionof thecurrent
IDL window.)
The behavior of WINDOW varies slightly depending on the window system in effect. See the
discussion of IDL graphics devices in IDL Graphics Devices on page111 for additional details.
Calling Sequence
WINDOW[, Window_Index]
Arguments
Window_Index
The window index for the newly-created window. A window index is an integer value
between 0and31that isusedtorefer tothewindow. If thisparameter isomitted, window
index 0 is used. If the value of Window_Index species an existing window, the existing
windowisdeleted and anewoneiscreated. If you need tocreatemorethan 32windows,
use the FREE keyword described below.
Keywords
COLORS
The maximum number of color table indices to be used when drawing. This parameter
hasan effect only if supplied when therst windowiscreated. If COLORSisnot present
when the rst window is created, all or most of the available color indices are allocated
depending upon the window system in use.
Tousemonochromewindowsonacolor displayuseCOLORS= 2, whencreatingtherst
window. One color table is maintained for all windows. A negative value for COLORS
species that all but the given number of colors from the shared color table should be
allocated.
FREE
Set thiskeywordtocreateawindowusingthesmallest unusedwindowindex above32. If
this keyword is present, theWindow_Index argument can be omitted. The default
position of the new window is opposite that of the current window. Using the FREE
keyword allows the creation of a large number of windows. The system variable
!D.WINDOW is set to the index of the newly-created window.
WINDOW IDL Reference Guide
PIXMAP
Set thePIXMAPkeywordtospecifythat thewindowbeingcreatedisactuallyan invisible
portion of the display memory called a pixmap.
RETAIN
thewindow. RETAIN=0speciesnobackingstore. RETAIN=1requeststhat theserver or
window system provide backing store. RETAIN=2 species that IDL provide backing
store directly. See Backing Store on page144for details.
TITLE
A scalar string that contains the windows label. If not specied, the window is given a
label of the form IDL n, wheren is the index number of the window. For example, to
create a window with the label IDL Graphics, enter:
WINDOW, TITLE='IDL Graphics'
XPOS
TheXpositionof thewindow, speciedindevicecoordinates. OnMotif platforms, XPOS
speciestheXposition of thelower left corner andismeasuredfromthelower left corner
of the screen. On Windows and Macintosh platforms, XPOS species the X position of
theupper left corner and is measured from the upper left corner of the screen. That is,
specifying
WINDOW, XPOS = 0, YPOS = 0
will create a window in the lower left corner on Motif machines and in the upper left
corner on Windows and Macintosh machines.
If no position is specied, the position of the window is determined from the value of
Window Index using the following rules:
Window 0 is placed in the upper right hand corner.
Even numbered windows are placed on the top half of the screen and odd numbered
windows are placed on the bottom half.
Windows 0,1,4,5,8, and 9 are placed on the right side of the screen and windows 2,3,6,
and 7 are placed on the left.
Note Theorder of precedence(highest tolowest) for positioningwindowsis: XPOS/YPOS
keywords to WINDOW, Tile/Cascade IDE graphics (user system) preferences, op-
tional index argument to WINDOW. Also realize that setting LOCATION is only a
request to the Window manager and may not always be honored due to system
peculiarities.
YPOS
The Y position of the window, specied in device coordinates. See the description of
XPOS for details.
IDL Reference Guide WINDOW
XSIZE
The width of the window in pixels.
YSIZE
The height of the window in pixels.
Example
Create graphics window number 0 with a size of 400 by 400 pixels and a title that reads
Square Window by entering:
WINDOW, 0, XSIZE=400, YSIZE=400, TITLE='Square Window'
See Also
WDELETE, WSET, WSHOW
WRITE_BMP IDL Reference Guide
WRITE_BMP
The WRITE_BMP procedure writes an image and its color table vectors to a Microsoft
Windows Version 3 device independent bitmap le (.BMP).
WRITE_BMP does not handle 1-bit-deep images or compressed images, and is not fast
for 4-bit images. Thealgorithmworksbest on imageswherethenumber of bytesin each
scan-line is evenly divisible by 4.
write_bmp.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_BMP, Filename, Image[, R, G, B]
Arguments
Filename
A scalar string containing the full pathname of the bitmap le to write.
Image
The array to write into the new bitmap le. The array should be scaled into a range of
bytesfor 8- and 24-bit deep images. Scaleto 0-15for 4bit deep images. If theimagehas
3 dimensions and the rst dimension is 3, a 24 bit deep bitmap le is created. Note: for
24-bit images, color interleaving is blue, green, red: Image[0,i,j] = blue, Image[1,i,j] =
green, etc.
R, G, B
Color tables. If omitted, the colors loaded in the COLORS common block are used.
Keywords
FOUR_BIT
Set this keyword to write as a 4-bit device independent bitmap. If omitted or zero, an 8-
bit deep bitmap is written.
IHDR
Set thiskeyword to aBITMAPINFOHEADERstructurecontainingtheleheader elds
that arenot obtained fromtheimageitself. Theeldsin thisstructurethat can beset are:
bi{XY}PelsPerMeter, biClrUsed, and biClrImportant.
HEADER_DEFINE
If thiskeywordisset, WRITE_BMPreturnsan emptyBITMAPINFOHEADERstructure,
containing zeros. No other actions are performed. This structure may be then modied
IDL Reference Guide WRITE_BMP
with the pertinent elds and passed in via the IHDR keyword parameter. See the
Microsoft Windows Programmers Reference Guide for a description of each eld in the
structure.
Note: this parameter must be dened beforethe call. For example:
H = 0
WRITE_BMP, HEADER_DEFINE = H
Examples
Thefollowingcommand capturesthecontentsof thecurrent IDL graphicswindowand
saves it to a Microsoft Windows Bitmap le with the nametest.bmp:
WRITE_BMP, 'test.bmp', TVRD()
Thefollowingcommandsscalean imageto0-15, and then writea4-bit BMPle, usinga
grayscale color table:
r = BYTSCL(INDGEN(16)) Createa ramp from 0 to 255
WRITE_BMP, 'test.bmp', BYTSCL(Image, MAX=15), r, r, r, /FOUR
See Also
READ_BMP, QUERY_* ROUTINES
WRITE_GIF IDL Reference Guide
WRITE_GIF
The WRITE_GIF procedure writes an image and its color table vectors to a Graphics
Interchange Format (GIF) le.
WRITE_GIF produces 8-bit GIF les of the standard type: non-interlaced, global
colormap.
Note TheGraphicsInterchangeFormatistheCopyright property of CompuServ Incor-
porated. GIF(SM) is a Service Mark property of CompuServ Incorporated.
write_gif.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_GIF, Filename, Image[, R, G, B]
Arguments
Filename
A scalar string containing the full pathname of the GIF le to write.
Image
The array to write into the new GIF le.
R, G, B
TheRed, Green, and Bluecolor vectorstobewritten with totheGIFle. If R, G, Bvalues
arenot provided, thelast color tableestablished usingLOADCT issaved, and thetableis
padded to256entries. If nocolor tablehasbeen established, WRITE_GIFcallsLOADCT
to load the grayscale entry (table 0).
Keywords
CLOSE
Set this keyword to close any open les. The CLOSE keyword is only useful if a le
containingmultipleimages(asspecied by theMULTIPLEkeyword) isbeingwritten. If
the CLOSE keyword is specied, nothing is written to the le, and all other parameters
are ignored.
MULTIPLE
Set this keyword to write multiple images to a le. Each call to WRITE_GIF writes the
next image, withtheleremainingopenbetweencalls. TheFilenameargument isignored
after the rst call, but must besupplied. After the rst image has been written, any R, G,
IDL Reference Guide WRITE_GIF
andBcolor vectorssuppliedareignored. All imageswrittentoaGIFlemust bethesame
size.
Example
Thefollowingcommand capturesthecontentsof thecurrent IDL graphicswindowand
saves it to a GIF le named test.gif:
WRITE_GIF, 'test.gif', TVRD()
See Also
READ_GIF, WRITE_JPEG, QUERY_* ROUTINES
WRITE_JPEG IDL Reference Guide
WRITE_JPEG
The WRITE_JPEG procedure writes compressed images to les. JPEG (Joint
Photographic Experts Group) is a standardized compression method for full-color and
gray-scaleimages. Thisprocedureisbasedin part on thework of the Independent JPEG
Group.
AstheIndependent JPEGGroupstates, JPEGisintendedfor real-world scenes(suchas
digitized photographs). Line art, such as drawings or IDL plots, and other unrealistic
imagesarenot itsstrongsuit. Notealso that JPEGisa lossy compression scheme. That
is, the output image isnot identical to the input image. Hence you must not use JPEG if
you have to have identical output bits. However, on typical images of real-world scenes,
verygoodcompressionlevelscanbeobtainedwithnovisiblechange, andamazinglyhigh
compression levelsarepossibleif you can toleratealow-quality image. You can tradeoff
output imagequality against compressed lesizeby adjustingacompression parameter.
Files are encoded in JFIF, the JPEG File Interchange Format (however, such les are
usually simply called JPEG les).
If you need to store images in a compressed format that is not lossy, consider using the
WRITE_GIF procedure. This procedure writes 8-bit (256 color) images in the Graphics
InterchangeFormat. Tostore8-bit or 24-bit imageswithout compression, consider using
theWRITE_BMP(for Microsoft Bitmap format les) or WRITE_TIFF(to writeTagged
Image Format Files) procedures.
For a short technical introduction to the JPEG compression algorithm, see: Wallace,
GregoryK. TheJPEGStill PictureCompressionStandard, CommunicationsoftheACM,
April 1991 (vol. 34, no. 4), pp. 30-44.
To read JPEG les, use the READ_JPEG procedure (page 907).
Note All JPEGlesconsist of bytedata. Input dataisconvertedtobytesbeforebeingwritten
to a JPEG le.
Calling Sequence
WRITE_JPEG[ , Filename], Image
Arguments
Filename
Astringcontainingthenameof letobewritten in JFIF(JPEG) format. If thisparameter
is not present, the UNIT keyword must be specied.
Image
A byte array of either two or three dimensions, containing the image to be written.
Grayscale images must have two dimensions. True-color images must have three
IDL Reference Guide WRITE_JPEG
dimensions with the index of the dimension that contains the color specied with the
TRUE keyword.
Keywords
ORDER
JPEG/JFIF images are normally written in top-to-bottom order. If the image array is in
thestandardIDLorder (i.e., frombottom-to-top) set ORDERto0, itsdefault value. If the
image array is in top-to-bottom order, ORDER must be set to 1.
PROGRESSIVE
Set this keyword to write the image as a series of scans of increasing quality. When used
with a slow communications link, a decoder can generate a low-quality image very
quickly, and then improve its quality as more scans are received.
Caution Not all JPEGapplicationscan handleprogressive JPEGles, and it isup theJPEG
reader to progressively display the JPEG image. For example, IDLs READ_JPEG
routinewill ignoretheprogressivereadout request andreadtheentireimageinat the
rst reading.
QUALITY
Thiskeywordspeciesthequalityindex, in therangeof 0(terrible ) to100(excellent )
for the JPEG le. The default value is 75, to obtain very good quality. Lower values of
QUALITY produce higher compression ratios and smaller les.
TRUE
This keyword species the index, starting at 1, of the dimension over which the color is
interleaved. For example, for an imagethat ispixel interleaved and hasdimensionsof (3,
m, n), set TRUE to 1. Specify 2 for row-interleaved images (m, 3, n); and 3 for band-
interleaved images (m, n, 3). If TRUE is not set, the image is assumed to have no
interleaving (it is not a true-color image).
UNIT
This keyword designates the logical unit number of an already open le to receive the
output, allowing multiple JFIF images per le or the embedding of JFIF images in other
data les. If this keyword is used, Filenameshould not be specied. When using VMS,
open the le with the /STREAM keyword.
Examples
Write the image contained in the array A, using JPEG compression with a quality index
of 25. The image is stored in bottom-to-top order:
WRITE_JPEG, 'test.dat', a, QUALITY=25
Write a true-color image to a JPEG le. The image is contained in the band-interleaved
array A with dimensions (m,n,3). Assume it is stored in top-to-bottom order:
WRITE_JPEG IDL Reference Guide
WRITE_JPEG, 'test1.dat', a, TRUE=3, /ORDER
See Also
READ_JPEG, WRITE_GIF, QUERY_* ROUTINES
IDL Reference Guide WRITE_NRIF
WRITE_NRIF
The WRITE_NRIF procedure writes an image and its color table vectors to an NCAR
Raster Interchange Format (NRIF) rasterle.
WRITE_NRIF only writes 8- or 24-bit deep rasterles of types Indexed Color (8-bit)
and Direct Color integrated (24-bit). The color map is included only for 8-bit les.
See the document NCAR Raster Interchange Format and TAGS Raster Reference
Manual, available from the Scientic Computing Division, National Center for
Atmospheric Research, Boulder, CO, 80307-3000, for information on the structure of
NRIF les.
write_nrif.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_NRIF, File, Image, [R, G, B]
Arguments
File
A scalar string containing the full path name of the NRIF le to write.
Image
Thebytearray to bewritten to theNRIFle. If Imagehasthedimensions(n,m), an 8-bit
NRIFlewith color tablesiscreated. If Imagehasthedimensions(3,n,m), a24-bit NRIF
le is created, where each byte triple represents the red, green, and blue intensities at
(n,m) on ascalefrom0to 255. TheNRIFimagewill berendered frombottomto top, in
accordance with IDL standards.
R, G, B
The Red, Green, and Blue color vectors to be used as a color table with 8-bit images. If
color vectorsaresupplied, they areincluded in theoutput (8-bit imagesonly). If R, G, B
valuesarenot provided, thelast color tableestablished usingLOADCT isincluded. If no
color tablehasbeen established, WRITE_NRIFcallsLOADCTtoloadthegrayscaleentry
(table 0).
Note: WRITE_NRIFdoesnot recognizecolor vectorsloaded directly usingTVLCT, so if
acustomcolor tableisdesired and it isnot convenient to useXPALETTE, includetheR,
G, and B vectors that were used to create the color table.
WRITE_PICT IDL Reference Guide
WRITE_PICT
The WRITE_PICT procedure writes and image and its color table vectors to a PICT
(version 2) format image le. The PICT format is used by Apple Macintosh computers.
Note: WRITE_PICT only works with 8-bit displays
write_pict.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_PICT, Filename[, Image, R, G, B]
Arguments
Filename
A scalar string containing the full pathname of the PICT le to write.
Image
The byte array to be written to the PICT le. If Imageis omitted, the entire current
graphics window is read into an array and written to the PICT le.
R, G, B
TheRed, Green, and Bluecolor vectorstobewritten tothePICT le. If R, G, Bvaluesare
not provided, thelast color tableestablishedusingLOADCT isincluded. If nocolor table
has been established, WRITE_PICT calls LOADCT to load the grayscale entry (table 0).
Example
Create a pseudo screen dump from the current window:
WRITE_PICT, 'test.pict', TVRD()
See Also
READ_PICT, QUERY_* ROUTINES
IDL Reference Guide WRITE_PNG
WRITE_PNG
The WRITE_PNG procedure writes a 2D or 3D IDL variable into aPortable Network
Graphics(PNG) le. Thedatain theleisstored usinglosslesscompression usingeither
8, 16, or 32databitsper channel, based on theinput IDL variabletype. 3DIDL variables
must have the number of channels as their leading dimension (pixel interleaved). For
BYTEformat 2D IDL variables, an optional palettemay bestored in theimagelealong
with a list of pixel values which are to be considered transparent by a reading program.
Calling Sequence
WRITE_PNG, Filename, image[,R G, B]
Arguments
Filename
A scalar string containing the full pathname of the PNG le to write.
Image
The array to write into the new PNG le.
R, G, B
Named variables that will contain the Red, Green, and Blue color vectors if a color table
exists.
Keywords
VERBOSE
Produces additional diagnostic output during the write.
TRANSPARENT
Set thiskeyword toan arrayof pixel index valueswhich aretobetreated astransparent
for the purposes of image display. This keyword is only valid for single channel (color
indexed) images.
Example
CreateanRGBA(16-bits/channel) andaColor Indexed(8-bit/channel) imagewitha
palette.
red = indgen(256)
WRITE_PNG IDL Reference Guide
green = indgen(256)
blue = indgen(256)
;Query and Read the data
IF (ok) THEN BEGIN
HELP,s,/STRUCTURE
ENDIF ELSE BEGIN
HELP,img
ENDELSE
ENDIF ELSE BEGIN
ENDELSE
ENDFOR
END
See Also
READ_PNG, QUERY_* ROUTINES
IDL Reference Guide WRITE_PPM
WRITE_PPM
TheWRITE_PPM procedurewritesan imagetoaPPM (true-color) or PGM (grayscale)
le.
Note WRITE_PPM only writes 8-bit deep PGM/PPM les of the standard type. Images
should be ordered so that the rst row is the top row.
PPM/PGM format is supported by the PBMPLUS toolkit for converting various
image formats to and from portable formats, and by the Netpbm package.
write_ppm.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_PPM, Filename, Image
Arguments
Filename
A scalar string specifying the full pathname of the PPM or PGM le to write.
Image
The 2D (gray scale) or 3D (true-color) array to be written to a le.
Keywords
ASCII
Set thiskeywordtoforceWRITE_PPM touseformattedASCII input/output towritethe
image data. The default is to use the far more efcient binary input/output (RAWBITS)
format.
Example
Supposeyou haveagrayscaleimagearraystored in theIDL variableimage. Towritethis
image to a PGM le, use the following command:
WRITE_PPM, 'file.pgm', image
See Also
READ_PPM, QUERY_* ROUTINES
WRITE_SPR IDL Reference Guide
WRITE_SPR
The WRITE_SPR procedure writes a row-indexed sparse array structure to a specied
le. Row-indexed sparse arrays are created using the SPRSIN function.
Calling Sequence
WRITE_SPR, AS, Filename
Arguments
AS
A row-indexed sparse array created by SPRSIN.
Filename
The name of the le that will contain AS.
Example
A = [[3.,0., 1., 0., 0.],$ Createan array.
[0.,4., 0., 0., 0.],$
[0.,7., 5., 9., 0.],$
[0.,0., 0., 0., 2.],$
[0.,0., 0., 6., 5.]]
A = SPRSIN(A) Convert it to sparsestoragefor-
mat.
WRITE_SPR, A, 'sprs.as' Storeit in thefilesprs.as
See Also
FULSTR, LINBCG, SPRSAB, SPRSAX, SPRSIN, READ_SPR
IDL Reference Guide WRITE_SRF
WRITE_SRF
The WRITE_SRF procedure writes an image and its color table vectors to a Sun Raster
File (SRF).
WRITE_SRF only writes 32-, 24-, and 8-bit-deep rasterfiles of type RT_STANDARD. Use
theUNIXcommandrasfilter8to1 toconvert theselesto1-bit deeples. Seethele
/usr/include/rasterfile.h for the structure of Sun rasterles.
write_srf.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_SRF, Filename[, Image, R, G, B]
Arguments
Filename
A scalar string containing the full pathname of the SRF to write.
Image
The array to be written to the SRF. If Imagehas dimensions (3,n,m), a 24-bit SRF is
written. If Imageisomitted, theentirecurrent graphicswindowisread into an array and
written totheSRFle. Imageshouldbeof bytetype, andin toptobottomscan lineorder.
R, G, B
The Red, Green, and Blue color vectors to be written to the le. If R, G, B values are not
provided, thelast color tableestablished usingLOADCT isincluded. If nocolor tablehas
been established, WRITE_SRF calls LOADCT to load the grayscale entry (table 0).
Keywords
ORDER
Set this keyword to write the image from the top down instead of from the bottom up.
Thissettingisonly necessary when writingalefromthecurrent IDL graphicswindow;
it is ignored when writing a le from a data array passed as a parameter.
WRITE_32
Set this keyword to write a 32-bit le. If the input image is a true color image,
dimensioned (3, n, m), it is normally written as a 24-bit raster le.
WRITE_SRF IDL Reference Guide
Example
WRITE_SRF, 'test.srf', TVRD()
See Also
READ_SRF, QUERY_* ROUTINES
IDL Reference Guide WRITE_SYLK
WRITE_SYLK
TheWRITE_SYLK function writesthecontentsof an IDL variableto aSYLK (Symbolic
Link) format spreadsheet datale. Thefunction returnsTRUEif thewriteoperation was
successful.
Note ThisroutinewritesonlynumericandstringSYLKdata. It cannot handlespreadsheet
and cell formatting information (cell width, text justication, font type, date, time,
monetary notations, etc.). A given SYLK data le cannot be appended with data
blocks through subsequent calls.
write_sylk.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = WRITE_SYLK(File, Data)
Arguments
File
A scalar string specifying the full path name of the SYLK le to write.
Data
A scalar, vector, or 2D array to be written to File.
Keywords
STARTCOL
Set thiskeywordtotherst columnof spreadsheet cellstowrite. If not specied, thewrite
operation begins with the rst column found in the le (column 0).
STARTROW
Set this keyword to the rst row of spreadsheet cells to write. If not specied, the write
operation begins with the rst row of cells found in the le (row 0).
Example
Supposeyou wish to writethecontentsof a2by 2oating-point array, data, to aSYLK
datalecalled bar.slk such that thematrix would appear with itsupper left dataat the
cell in the 10th row and the 20th column. Use the following command:
status = WRITE_SYLK("bar.slk", data, STARTROW = 9, STARTCOL = 19)
The IDL variablestatus will contain the value 1 if the operation was successful.
WRITE_SYLK IDL Reference Guide
See Also
READ_SYLK
IDL Reference Guide WRITE_TIFF
WRITE_TIFF
TheWRITE_TIFFprocedurecanwriteTIFFleswith1to3channelswhereeachchannel
can have 8-bits, 16-bits, 32-bits, or be oating point.
Calling Sequence
WRITE_TIFF, Filename[, Image, Order] [,/APPEND] [,BLUE=b]
[,COMPRESSION=comp] [,GREEN=g] [,/LONG] [,/SHORT] [,/FLOAT] [,/VERBOSE]
[,XRESOL=xr] [,YRESOL=yr] [,RED=r] [GEOTIFF=geo]
Arguments
Filename
A scalar string containing the full pathname of the TIFF to write.
Image
The array to be written to the TIFF. If Imagehas dimensions (3,n,m), a three-channel
TIFFiswritten. Imageshouldbein top tobottomscan lineorder. Bydefault, thisarrayis
converted to byte format before being written (see the LONG, SHORT and FLOAT
keywords below).
Note TheImageargument isoptional if PLANARCONFIGisset to2andtheRED, GREEN,
and BLUE keywords have been set to 2D arrays.
Order
This argument should be 0 if the image is stored from bottom to top (the default). For
images stored from top to bottom, this argument should be 1.
Caution Not all TIFFreadershonor thevalueof theOrderargument. IDLwritesthevalueinto
thele, but manyknownreadersignorethisvalue. Insuchcases, werecommendthat
you convert theimageto top to bottomorder with theREVERSEfunction and then
set Order to 1.
Keywords
APPEND
Speciesthat theimageshould beadded to theexistingle, creatingamulti-imageTIFF
le.
COMPRESSION
Set this keyword to select the type of compression to be used:
0 - none (default), 1 - LZW, 2 - PackBits.
WRITE_TIFF IDL Reference Guide
FLOAT
Write the pixel components as oating point entities (the default is 8 bit).
GEOTIFF
An anonymousstructurecontainingoneeldfor eachof theGeoTIFFtagsandkeystobe
written into the le. The GeoTIFF structure is formed using elds named from the
following table.
TAGS:
"MODELPIXELSCALETAG" DOUBLE[ 3]
"MODELTRANSFORMATIONTAG" DOUBLE[ 4,4]
"MODELTIEPOINTTAG" DOUBLE[ 6,*]
KEYS:
"GTMODELTYPEGEOKEY" INT
"GTRASTERTYPEGEOKEY" INT
"GTCITATIONGEOKEY" STRING
"GEOGRAPHICTYPEGEOKEY" INT
"GEOGCITATIONGEOKEY" STRING
"GEOGGEODETICDATUMGEOKEY" INT
"GEOGPRIMEMERIDIANGEOKEY" INT
"GEOGLINEARUNITSGEOKEY" INT
"GEOGLINEARUNITSIZEGEOKEY" DOUBLE
"GEOGANGULARUNITSGEOKEY" INT
"GEOGANGULARUNITSIZEGEOKEY" DOUBLE
"GEOGELLIPSOIDGEOKEY" INT
"GEOGSEMIMAJORAXISGEOKEY" DOUBLE
"GEOGSEMIMINORAXISGEOKEY" DOUBLE
"GEOGINVFLATTENINGGEOKEY" DOUBLE
"GEOGAZIMUTHUNITSGEOKEY" INT
"GEOGPRIMEMERIDIANLONGGEOKEY" DOUBLE
"PROJECTEDCSTYPEGEOKEY" INT
"PCSCITATIONGEOKEY" STRING
Note If aGeoTIFFkey appearsmultipletimesin ale, only thevaluefor therst instance
of the key is returned.
"PROJECTIONGEOKEY" INT
"PROJCOORDTRANSGEOKEY" INT
"PROJLINEARUNITSGEOKEY" INT
"PROJLINEARUNITSIZEGEOKEY" DOUBLE
"PROJNATORIGINLONGGEOKEY" DOUBLE
"PROJNATORIGINLATGEOKEY" DOUBLE
"PROJFALSEEASTINGGEOKEY" DOUBLE
"PROJFALSENORTHINGGEOKEY" DOUBLE
"PROJFALSEORIGINLONGGEOKEY" DOUBLE
"PROJFALSEORIGINLATGEOKEY" DOUBLE
"PROJFALSEORIGINEASTINGGEOKEY" DOUBLE
"PROJFALSEORIGINNORTHINGGEOKEY" DOUBLE
"PROJCENTERLONGGEOKEY" DOUBLE
"PROJCENTERLATGEOKEY" DOUBLE
"PROJCENTEREASTINGGEOKEY" DOUBLE
"PROJCENTERNORTHINGGEOKEY" DOUBLE
"PROJSCALEATNATORIGINGEOKEY" DOUBLE
"PROJSCALEATCENTERGEOKEY" DOUBLE
"PROJAZIMUTHANGLEGEOKEY" DOUBLE
"PROJSTRAIGHTVERTPOLELONGGEOKEY" DOUBLE
"VERTICALCSTYPEGEOKEY" INT
"VERTICALCITATIONGEOKEY" STRING
"VERTICALDATUMGEOKEY" INT
"VERTICALUNITSGEOKEY" INT
WRITE_TIFF IDL Reference Guide
LONG
Write the pixel components as 32 bit entities (the default is 8 bit).
PLANARCONFIG
Set thiskeyword to 2if you arewritingan RGBimagethat iscontained in threeseparate
images (color planes). The three images must be stored in the variables specied by the
RED, GREEN, and BLUE keywords. Otherwise, omit this parameter (or set it to 1).
RED, GREEN, BLUE
If youarewritingaPalettecolor image, set thesekeywordsequal tothecolor tablevectors,
scaled from 0 to 255.
If you arewritingan RGBinterleaved image(i.e., if thePLANARCONFIGkeyword isset
to 2), set these keywords to the names of the variables containing the three image
components.
SHORT
Write the pixel components as 16 bit entities (the default is 8 bit).
VERBOSE
Produce additional diagnostic output during the write.
XRESOL
The horizontal resolution, in pixels per inch. The default is 100.
YRESOL
The vertical resolution, in pixels per inch. The default is 100.
Example
WRITE_TIFF, 'test.tiff', TVRD()
Writeand read amulti-imageTIFFle. Thefirst imageisa16-bit singlechannel image
stored using compression. The second image is an RGB image stored using 32-
bits/channel uncompressed.
;Writetheimagedata
Read theimagedata back
IF (ok) THEN BEGIN
HELP,t,/STRUCTURE
HELP,img
ENDFOR
ENDIF
See Also
READ_TIFF, QUERY_* ROUTINES
WRITE_WAVE IDL Reference Guide
WRITE_WAVE
The WRITE_WAVE procedure writes a three dimensional IDL array to a.wave or
.bwave lefor usewith theWavefront Advanced DataVisualizer. Notethat thisroutine
only writes one scalar eld for each Wavefront le that it creates.
write_wave.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
WRITE_WAVE, File, Array
Arguments
File
A scalar string containing the full path name of the Wavefront le to write.
Array
A 3D array to be written to the le.
Keywords
BIN
Set this keyword to create a binary le. By default, text les are created.
DATANAME
Set thiskeyword to thenameof thedatainsideof theWavefront le. If not specied, the
name used is idldata.
MESHNAME
Set thiskeyword to thenameof themesh used in theWavefront le. If not specied, the
name used is idlmesh.
NOMESHDEF
Set this keyword to omit the mesh denition from the Wavefront le.
VECTOR
Set thiskeywordtowritethevariableasavector. Thedataiswritten asan arrayof 3-space
vectors. The array may contain any number of dimensions but must have a leading
dimension of 3. If the leading array dimension is not 3, this keyword is ignored.
IDL Reference Guide WRITE_WAVE
See Also
READ_WAVE
WRITEU IDL Reference Guide
WRITEU
The WRITEU procedure writes unformatted binary data from an expression into a le.
This procedure performs a direct transfer with no processing of any kind being done to
the data.
Calling Sequence
WRITEU, Unit, Expr
1
..., Expr
n
Arguments
Unit
The IDL le unit to which the output is sent.
Expr
i
The expressions to be output. For non-string variables, the number of bytes implied by
thedatatypeisoutput. WhenWRITEUisusedwithavariableof typestring, IDLoutputs
exactly the number of bytes contained in the existing string.
Unix Keywords
TRANSFER_COUNT
Set this keyword to a named variable in which to return the number of elements
transferred bytheoutput operation. Notethat thenumber of elementsisnot thesameas
the number of bytes (except in the case where the data type being transferred is bytes).
For example, transferring256oating-point numbersyieldsatransfer count of 256, not
1024 (the number of bytes transferred).
This keyword is useful with les opened with the NOSTDIO keyword to the OPEN
routines. Normally, writingmoredatathan an output devicewill accept causesan error.
Files opened with the NOSTDIO keyword will not generate such an error. Instead, the
programmer must keep track of the transfer count to judge the success or failure of a
WRITEU operation.
VMS Keywords
Note that the obsolete FORWRT routine has been replaced by WRITEU.
REWRITE
When writing data to a le with indexed organization, setting the REWRITE keyword
species that the data should update the contents of the most recently input record
instead of creating a new record.
IDL Reference Guide WRITEU
Example
Create some data to store in a le by entering:
D = BYTSCL(DIST(200))
Open a new le for writing as IDL le unit number 1 by entering:
OPENW, 1, 'newfile'
To write the data in D to the le, enter:
WRITEU, 1, D
Close le unit 1 by entering:
CLOSE, 1
See Also
OPEN, READU
WSET IDL Reference Guide
WSET
The WSET procedure selects the current window. Most IDL graphics routines do not
explicitlyrequiretheIDLwindowtobespecied. Instead, theyusethewindowknown as
the current window. The window index number of the current window is contained in
the read-only system variable !D.WINDOW. WSET only works with devices that have
windowing systems.
Calling Sequence
WSET [, Window_Index]
Arguments
Window_Index
This argument species the window index of the window to be made current. If this
argument is not specied, a default of 0 is used.
If you set Window_Index equal to -1, IDL will try to locate an existing window to make
current, ignoring any managed draw widgets that may exist. If there is no window to
make current, WSET changes the value of the WINDOW eld of the !D system variable
to -1, indicating that there are no current windows.
Example
Create IDL windows 1 and 2 by entering:
WINDOW, 1 & WINDOW, 2
Set the current window to window 1 and display an image by entering:
WSET, 1 & TVSCL, DIST(100)
Set the current window to window 2 and display an image by entering:
WSET, 2 & TVSCL, DIST(100)
See Also
WDELETE, WINDOW, WSHOW
IDL Reference Guide WSHOW
WSHOW
The WSHOW procedure exposes or hides the designated window.
Calling Sequence
WSHOW[, Window_Index [, Show]]
Arguments
Window_Index
The window index of the window to be hidden or exposed. If this argument is not
specied, thecurrent windowisassumed. If thisindexisthewindowIDof adrawwidget,
the widget base associated with that drawable is brought to the front of the screen.
Show
Set Showto0tohidethewindow. Omit thisargument or set it to1toexposethewindow.
Keywords
ICONIC
Set this keyword to iconify the window. Set ICONIC to 0 to de-iconify the window.
Under windowing systems, iconication is the task of the window manager, and client
applicationssuch asIDL haveno direct control over it. TheICONICkeyword servesasa
hint to thewindowmanager, which isfreeto iconify thewindowor ignoretherequest as
it sees t.
Example
To bring IDL window number 0 to the front, enter:
WSHOW, 0
See Also
WDELETE, WINDOW, WSET
WTN IDL Reference Guide
WTN
TheWTN function returnsamulti-dimensional discretewavelet transformof theinput
array A. The transform is based on a Daubechies wavelet lter.
WTN is based on the routinewtn described in section 13.10 of Numerical Recipes in C:
Calling Sequence
Result = WTN(A, Coef)
Arguments
A
The input vector or array. The dimensions of A must all be powers of 2.
Coef
An integer that speciesthenumber of wavelet lter coefcients. Theallowed valuesare
4, 12, or 20. When Coefis4, thedaub4() function (seeNumerical Recipes, section 13.10)
is used. When Coef is 12 or 20, pwt() is called, preceded by pwtset() (seeNumerical
Recipes, section 13.10).
Keywords
COLUMN
DOUBLE
INVERSE
If the INVERSE keyword is set, the inverse transform is computed. By default, WTN
performs the forward wavelet transform.
OVERWRITE
Set theOVERWRITEkeywordtoperformthetransform in place. Theresult overwrites
the original contents of the array.
IDL Reference Guide WTN
Example
This example demonstrates the use of IDLs discrete wavelet transform and sparse array
storage format to compress and store an 8-bit gray-scale digital image. First, an image
selected from thepeople.dat data le is transformed into its wavelet representation
and written to a separate data le using the WRITEU procedure.
Next, the transformed image is converted, using the SPRSIN function, to row-indexed
sparsestorageformat retainingonlyelementswithanabsolutemagnitudegreater thanor
equal to a specied threshold. The sparse image is written to a data le using the
WRITE_SPR procedure.
Finally, the transformed image is reconstructed from the storage le and displayed
alongside the original.
Begin by choosing the number of wavelet coefcients to use and a threshold value:
coeffs = 12 & thres = 10.0
Open thepeople.dat data le, read an image using associated variables, and close the
le.
images = assoc(1, bytarr(192, 192))
image_1 = images[0]
close, 1
Expandtheimagetothenearest power of twousingcubicconvolution, andtransformthe
image into its wavelet representation using the WTN function.
pwr = 256
image_1 = CONGRID(image_1, pwr, pwr, /CUBIC)
wtn_image = WTN(image_1, coeffs)
Write the image to a le using the WRITEU procedure and check the size of the le (in
bytes) using the FSTAT function.
OPENW, 1, 'original.dat'
WRITEU, 1, wtn_image
status = FSTAT(1)
CLOSE, 1
PRINT, 'The size of the file is ', status.size, ' bytes.'
IDL prints:
The size of the file is 262144 bytes.
WTN IDL Reference Guide
Now, weconvert thewavelet representation of theimageto arow-indexed sparsestorage
format using the SPRSIN function, write the data to a le using the WRITE_SPR
procedure, and check the size of the compressed le.
sprs_image = SPRSIN(wtn_image, THRES = thres)
WRITE_SPR, sprs_image, 'sparse.dat'
OPENR, 1, 'sparse.dat'
status = FSTAT(1)
CLOSE, 1
PRINT, 'The size of the file is ', status.size, ' bytes.'
IDL prints:
The size of the file is 69600 bytes.
Determine the number of elements (as a percentage of total elements) whose absolute
magnitudeislessthanthespeciedthreshold. Theseelementsarenot retainedintherow-
indexed sparse storage format.
PRINT, 100.*N_ELEMENTS(WHERE(ABS(wtn_image) LT thres, $
count)) / N_ELEMENTS(image_1)
IDL prints:
87.0331
Thismeansthesparsearray containsonly 13%of theelementscontained in theoriginal
array. Next, read the row-indexed sparse data back from the lesparse.dat using the
READ_SPR function and reconstruct the image from the non-zero data using the
FULSTR function.
sprs_image = READ_SPR('sparse.dat')
wtn_image = FULSTR(sprs_image)
Apply the inverse wavelet transform to the image.
image_2 = WTN(wtn_image, COEFFS, /INVERSE)
Calculate and print the amount of data used in reconstruction of the image.
PRINT, 'The image on the right is reconstructed from:', $
100.0 - (100.* count/N_ELEMENTS(image_1)),$
'% of original image data.'
IDL prints:
The image on the right is reconstructed from:
12.9669% of original image data.
Finally, display the original and reconstructed images side by side.
IDL Reference Guide WTN
WINDOW, 1, XSIZE = pwr*2, YSIZE = pwr, $
TITLE = 'Wavelet Image Compression and File I/O'
TV, image_1, 0, 0
TV, image_2, pwr - 1, 0
Sample Image
The image on the left is the original 256 by 256 image. The image on the right was
compressed by the above process and was reconstructed from 13% of the original data.
Thesizeof thecompressedimagesdataleis26.6%of thesizeof theoriginal imagesdata
le. Note that due to limitations in the printing process, differences between the images
may not be as evident as they would be on a high-resolution printer or monitor.
See Also
FFT
Figure 9-6: Original image (left) and image reconstructed
from 13% of the data (right).
XBM_EDIT IDL Reference Guide
XBM_EDIT
TheXBM_EDIT procedureallowsuserstocreateandedit iconsfor usewith IDL widgets
as bitmap labels for widget buttons.
Theiconscreated with XBM_EDIT can besaved in twodifferent leformats. IDL array
denition les aretext lesthat can beinserted intoIDL programs. Bitmap arrayles
are data les that can be read into IDL programs. Bitmap array les should be used
temporarily until the nal icon design is determined and then they can be saved as IDL
array denitions for inclusion in the nal widget code. This routine does not check the
letypesof thelesbeingread and assumesthat they areof thecorrect sizeand typefor
reading. XBM_EDIT maintains its state in a common block so it is restricted to one
working copy at a time.
xbm_edit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XBM_EDIT
Keywords
BLOCK
FILENAME
Set thiskeyword to ascalar stringthat containsthelenameto beused for thenewicon.
If thisargument isnot specied, thename idl.bm isused. Thelenamecan bechanged
in XBM_EDIT by editing the Filename eld before selecting a le option.
GROUP
Thewidget IDof thewidget that callsXBM_EDIT. When thisIDisspecied, thedeathof
the caller results in the death of XBM_EDIT.
XSIZE
The number of pixels across the bitmap is in the horizontal direction. The default value
is 16 pixels.
YSIZE
Thenumber of pixelsacrossthebitmapisin thevertical direction. Thedefault valueis16
pixels.
IDL Reference Guide XBM_EDIT
See Also
WIDGET_BUTTON
XDISPLAYFILE IDL Reference Guide
XDISPLAYFILE
The XDISPLAYFILE procedure displays an ASCII text le using a widget interface.
xdisplayfile.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XDISPLAYFILE, Filename
Arguments
Filename
Ascalar stringthat containsthelenameof theletodisplay. Filenamecanincludeapath
to that le.
Keywords
BLOCK
FONT
A string containing the name of the font to use. The font specied is a device font (an
X Windows font on Motif systems; a TrueType or PostScript font on Windows or
Macintosh systems). SeeAbout DeviceFontson page72for detailson specifyingnames
GROUP
The widget ID of the widget that calls XDISPLAYFILE. If this keyword is specied, the
death of the group leader results in the death of XDISPLAYFILE.
HEIGHT
Thenumber of text linesthat thewidget shoulddisplayat onetime. If thiskeywordisnot
specied, 24 lines is the default.
MODAL
Set this keyword to create the XDISPLAYFILE dialog as a modal dialog. Setting the
MODAL keyword allows you to call XDISPLAYFILE from another modal dialog.
TEXT
Astringor stringarraytobedisplayedin thewidget insteadof thecontentsof ale. If this
keyword ispresent, theFilenameinput argument isignored (but isstill required). String
arrays are displayed one element per line.
IDL Reference Guide XDISPLAYFILE
TITLE
A string to use as the widget title rather than the le name or XDisplayFile.
WIDTH
The width of the widget display in characters. If this keyword is not specied, 80
characters is the default.
See Also
PRINT/PRINTF, XYOUTS
XFONT IDL Reference Guide
XFONT
The XFONT function creates a modal widget for selecting and viewing an X Windows
font. Thefunctionreturnsastringcontainingthenameof thelast selectedfont. If nofont
is selected, or the Cancel button is clicked, a null string is returned.
Calling XFONT resets the current X Windows font.
xfont.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = XFONT()
Keywords
GROUP
Thewidget IDof thewidget that callsXFONT. When thisIDisspecied, thedeath of the
caller results in the death of XFONT.
PRESERVE
Set thiskeywordtomakeXFONTsavetheserver font directoryincommonblockssothat
subsequent callsto XFONT start-up much faster. If thiskeyword isnot set, thecommon
block is cleaned.
See Also
EFONT, SHOWFONT
IDL Reference Guide XINTERANIMATE
XINTERANIMATE
The XINTERANIMATE procedure displays an animated sequence of images using off-
screen pixmaps or memory buffers. The speed and direction of the display can be
adjusted using the widget interface.
MPEG animation les can be created either programmatically using keywords to open
and save a le, or interactively using the widget interface. Note that the MPEG standard
does not allow movies with odd numbers of pixels to be created.
Note Onlyasinglecopyof XINTERANIMATEcanrunat atime. If youneedtorunmultiple
instancesof theanimation widget concurrently, usetheCW_ANIMATEcompound
widget.
xinteranimate.pro in thelib subdirectory of the IDL distribution.
Using XINTERANIMATE
Displayingan animated seriesof imagesusingXINTERANIMATErequiresat least three
callstotheroutine: onetoinitializetheanimation widget, onetoloadimages, andoneto
display theimages. When initialized usingtheSET keyword, XINTERANIMATEcreates
an approximately square pixmap or memory buffer, large enough to contain the
requested number of frames of the requested size. Images are loaded using the IMAGE
and FRAME keywords. Finally, images are displayed by copying them from the pixmap
or memory buffer to the visible draw widget.
See CW_ANIMATE on page341 for a description of the widget interface controls used
by XINTERANIMATE.
Calling Sequence
XINTERANIMATE[, Rate]
Arguments
Rate
A valuebetween 0and 100that representsthespeed of theanimation asapercentageof
themaximumdisplayrate. Thefastest animation iswith avalueof 100and theslowest is
with a value of 0. The default animation rate is 100. The animation must be initialized
using the SET keyword before calling XINTERANIMATE with a rate value.
XINTERANIMATE IDL Reference Guide
KeywordsInitialization
The following keywords are used to initialize the animation display. The SET keyword
must be provided. Other keywords described in this section are optional; note that they
work only when SET is specied.
SET
Set this keyword to a three-element vector [ Sizex, Sizey, Nframes] to initialize
XINTERANIMATE. Sizex and Sizey represent the width and height of the images to be
displayed, in pixels. Nframesis the number of frames in the animation sequence. Note
that Nframesmust be at least 2 frames.
CYCLE
Normally, framesaredisplayedgoingeither forwardor backwards. If theCYCLEkeyword
isset, theanimation reversesdirection after thelast framein either direction isdisplayed.
MPEG_FILENAME
Set this keyword equal to a string specifying the name of the MPEG le. If no le name
is specied, the default value (idl.mpg) is used.
MPEG_OPEN
Set this keyword to open an MPEG le.
NO_BLOCK
Set this keyword equal to zero to have XMANAGERblock when this application is
registered. By default, NO_BLOCKisset equal to one, providingaccessto thecommand
lineif activecommand lineprocessingisavailable. Notethat settingNO_BLOCK=0will
causeall widget applicationstoblock, not just thisapplication. For moreinformation, see
the documentation for the NO_BLOCK keyword to XMANAGER.
SHOWLOAD
Set this keyword to display each frame and update the frame slider as frames are loaded.
TRACK
Set thiskeyword tocausetheframeslider totrack thecurrent framewhen theanimation
is in progress. The default is not to track.
TITLE
Use this keyword to specify a string to be used as the title of the animation widget. If
TITLE is not specied, the title is set to XInterAnimate.
KeywordsLoading Images
The following keywords are used to load images into the animation display.
IDL Reference Guide XINTERANIMATE
They have no effect when initializing or running animations.
FRAME
Usethiskeyword tospecifytheframenumber when loadingframes. FRAMEmust beset
to a number in the range 0 to Nframes-1.
IMAGE
Usethiskeywordtospecifyasingleimagetobeloadedat theanimationpositionspecied
by the FRAME keyword. (FRAMEmust also be specied.)
ORDER
Set this keyword to display images from the top down instead of the default bottom up.
WINDOW
When this keyword is specied, an image is copied from an existing window to the
animation pixmap or memory buffer. (When usingsomewindowingsystems, usingthis
keyword is much faster than reading from the display and then calling
XINTERANIMATE with a 2D array.)
The value of this parameter is either an IDL window number (in which case the entire
windowiscopied), or avector containingthewindowindex and therectangular bounds
of the area to be copied. For example:
WINDOW = [Window_Number, X0, Y0, Sx, Sy]
KeywordsRunning Animations
The following keywords are used to when running the animation. They have no
effect when initializing the animation or loading images.
CLOSE
Set this keyword to delete the offscreen pixmaps or buffers and the animation widget
itself. This also takes place automatically when the user presses the Done With
Animation button or closes the window with the window manager.
GROUP
Set this keyword to the widget ID of the widget that calls XINTERANIMATE. When
GROUP is specied, the death of the calling widget results in the death of
XINTERANIMATE.
KEEP_PIXMAPS
If this keyword is set, XINTERANIMATE will not destroy the animation pixmaps or
bufferswhenit iskilled. CallingXINTERANIMATEagainwithout goingthroughtheSET
and LOAD steps will play the same animation without the overhead of creating the
pixmaps.
XINTERANIMATE IDL Reference Guide
MPEG_CLOSE
Set this keyword to close and save the MPEG le. This keyword has no effect if
MPEG_OPEN was not used during initialization.
XOFFSET
Use this keyword to specify the horizontal offset, in pixels from the left of the frame, of
the image in the destination window.
YOFFSET
Usethiskeyword to specify thevertical offset, in pixelsfromthebottomof theframe, of
the image in the destination window.
Example
Enter the following commands to open the leABNORM.DAT (a series of images of a
human heart) and animatetheimagesit containsusingXINTERANIMATE. For amore
detailed example of using XINTERANIMATE, see the example in the Using IDL
Widgets chapter of IDL Basics.
OPENR, unit, FILEPATH('abnorm.dat', SUBDIR=['examples','data']), $
/GET_LUN
H = BYTARR(64, 64, 16)
READU, unit, H
CLOSE, unit
H = REBIN(H, 128, 128, 16) Read theimages into variableH.
XINTERANIMATE, SET=[128, 128, 16], /SHOWLOAD
InitializeXINTERANIMATE.
FOR I=0,15 DO XINTERANIMATE, FRAME = I, IMAGE = H[*,*,I]
Load theimages into XINTER-
ANIMATE
XINTERANIMATE, /KEEP_PIXMAPS Play theanimation.
Note Since the KEEP_PIXMAPS keyword was supplied, the same animation can be re-
played (after the animation widget has been destroyed) with the single command:
XINTERANIMATE
See Also
CW_ANIMATE
IDL Reference Guide XLOADCT
XLOADCT
The XLOADCT procedure provides a graphical widget interface to the LOADCT
procedure. XLOADCT displays the current colortable and shows a list of available
predened color tables. Clickingon thenameof acolor tablecausesthecolor tableto be
loaded. Many other options, such as Gamma correction, stretching, and transfer
functions can also be applied to the colortable.
xloadct.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XLOADCT
Keywords
BLOCK
BOTTOM
The rst color index to use. XLOADCT will use color indices from BOTTOM to
BOTTOM+NCOLORS-1. The default is BOTTOM=0.
FILE
If thiskeyword isset, theleby thegiven nameisused instead of thelecolors1.tbl
in the IDL directory.
GROUP
The widget ID of the widget that calls XLOADCT. When this ID is specied, a death of
the caller results in a death of XLOADCT.
MODAL
Set this keyword to block processing of events from other widgets until the user quits
XLOADCT. Agroupleader must bespecied(viatheGROUPkeyword) for theMODAL
keyword to have any effect. By default, XLOADCT does not block event processing.
NCOLORS
Thenumber of colorsto use. Usecolor indicesfrom0to thesmaller of !D.TABLE_SIZE-
1 and NCOLORS-1. The default is all available colors (!D.TABLE_SIZE).
XLOADCT IDL Reference Guide
SILENT
Normally, no informational message is printed when a color map is loaded. If this
keyword is set to zero, the message is printed.
UPDATECALLBACK
Set thiskeywordtoastringcontainingthenameof auser-suppliedprocedurethat will be
called when the color table is updated by XLOADCT. The procedure may optionally
accept a keyword called DATA, which will be automatically set to the value specied by
the optional UPDATECBDATA keyword.
UPDATECBDATA
Set thiskeywordtoavalueof anytype. It will bepassedviatheDATAkeywordtotheuser-
supplied procedure specied via the UPDATECALLBACK keyword, if any. If the
UPDATECBDATA keyword is not set the value accepted by the DATA keyword to the
procedure specied by UPDATECALLBACK will be undened.
USE_CURRENT
Set thiskeywordtousethecurrent color tables, regardlessof thecontentsof theCOLORS
common block.
See Also
LOADCT, XPALETTE, TVLCT
IDL Reference Guide XMANAGER
XMANAGER
TheXMANAGERprocedureprovidesthemain event loop and management for widgets
created using IDL. Calling XMANAGER registers a widget program with the
XMANAGER event handler. XMANAGER takes control of event processing until all
widgets have been destroyed.
BeginningwithIDLversion 5.0, IDLsupportsan activecommandlinethat allowstheIDL
command input line to continue accepting input while properly congured widget
applicationsarerunning. SeeANoteAbout Blockingin XMANAGERon page1365for a
more detailed explanation of the active command line.
xmanager.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XMANAGER[, Name, ID]
Arguments
Name
A string that contains the name of the routine that creates the widget (i.e., the name of
the widget creation routine that is calling XMANAGER).
Note TheNameargument isstored in aCOMMON block for useby theXREGISTERED
routine. The stored name is case-sensitive.
ID
The widget ID of the new widgets top-level base.
Keywords
BACKGROUND
ThiskeywordisobsoleteandisincludedinXMANAGERforcompatibilitywithexistingcode
only.ItsfunctionalityhasbeenreplacedbytheTIMERkeywordtotheWIDGET_CONTROL
procedure.
A string that contains the name of a background task procedure to be called when the
event loop is idle.
CATCH
Set thiskeyword tocauseXMANAGERtocatch anyerrors, usingtheCATCH procedure,
when dispatching widget events. If the CATCH keyword is set equal to zero, execution
haltsand IDL providestraceback information when an error isdetected. Thiskeyword is
set by default (errors are caught and processing continues).
XMANAGER IDL Reference Guide
Do not specify either theNameor ID argument to XMANAGER when specifying the
CATCH keyword(theyareignored). CATCH actsasaswitchtoturn error catchingon and
off for all applicationsmanagedbyXMANAGER. WhenCATCHisspecified, XMANAGER
changes its error-catching behavior and returns immediately, without taking any other
action.
Note BeginningwithIDLversion5.0, thedefault behavior of XMANAGERistocatcherrors
andcontinueprocessingevents. Inversionsof IDLprior toversion5.0, XMANAGER
halted when an error wasdetected. Thischangein default behavior wasnecessary in
order to allowmultiplewidget applications(all beingmanaged by XMANAGER) to
coexist peacefully. When CATCH is set equal to zero, (the old behavior), any error
halts XMANAGER, and thus halts event processing for all running widget applica-
tions.
Notealsothat CATCH isonlyeffectiveif XMANAGERisblockingtodispatcherrors.
If event dispatchingfor an activeIDL command lineisin use, theCATCH keyword
has no effect.
The CATCH=0 setting (errors are not caught and processing halts in XMANAGER
when an error isdetected) isintendedasadebuggingaid. Finishedprogramsshould
not set CATCH=0.
CLEANUP
Set this keyword to a string that contains the name of the routine to be called when the
widget dies. If not specied, no routine is called. The cleanup routine must accept one
parameter which is the widget ID of the dying widget. The routine specied by
CLEANUP becomes the KILL_NOTIFY routine for the application, overriding any
cleanup routines that may have been set previously via the KILL_NOTIFY keyword to
WIDGET_CONTROL.
EVENT_HANDLER
Set thiskeywordtoastringthat containsthenameof aroutinetobecalledwhen awidget
event occurs in the widget program being registered. If this keyword is not supplied,
XMANAGER will construct a default name by adding the _event sufx to the Name
argument. See the example below for a more detailed explanation.
GROUP_LEADER
Thewidget IDof thegroupleader for thewidget beingprocessed. Whentheleader dieseither
by the users actions or some other routine, all widgets that have that leader will also die.
For example, a widget that views a help le for a demo widget would have that demo
widget as its leader. When the help widget is registered, it sets the keyword
GROUP_LEADER to the widget ID of the demo widget. If the demo widget were
destroyed, the help widget led by it would be killed by the XMANAGER.
JUST_REG
Set this keyword to indicate that XMANAGER should just register the widget and return
immediately. This keyword is useful if you want to register a group of related top-level
widgets before beginning event processing and either:
your command-processing front-end does not support an active command line, or
oneor moreof theregisteredwidgetsrequeststhat XMANAGERblock event processing.
(Note that in this case a later call to XMANAGER without the JUST_REG keyword is
necessary to begin blocking.)
(See A Note About Blocking in XMANAGER on page1365 for further discussion of the
active command line.)
Caution JUST_REG is not the same as NO_BLOCK. See JUST_REG vs. NO_BLOCK on
page1366 for additional details.
MODAL
ThiskeywordisobsoleteandisincludedinXMANAGERforcompatibilitywithexistingcode
only. Its functionality has been replaced by theMODAL keyword to theWIDGET_BASE
procedure.
When this keyword is set, the widget that is being registered traps all events and
desensitizes all the other widgets. It is useful when input from the user is necessary to
continue (i.e., blocking dialog boxes). Once the modal widget dies, the others are
resensitized and the normal event processing continues.
NO_BLOCK
Set this keyword to tell XMANAGER that the registering client does not require
XMANAGER to block if active command line event processing is available. If active
command line event processing is availableand every current XMANAGER client
species NO_BLOCK, then XMANAGER will not block and the user will have access to
the command line while widget applications are running.
Caution NO_BLOCK is not the same as JUST_REG. See JUST_REG vs. NO_BLOCK on
page1366 for additional details.
Warning
Although this routine is written in the IDL language, it may change in the future in its
internal implementation. For futureupgradability, it isbest not to modify or even worry
about what this routine does internally.
A Note About Blocking in XMANAGER
Beginning with IDL version 5.0, most versions of IDLs command-processing front-end
are able to support an activecommand linewhile running properly constructed widget
applications. What this means is thatprovided the widget application is properly
conguredthe IDL command input line is available for input while a widget
application is running and widget events are being processed.
There are currently 5 separate IDL command-processing front-end implementations:
Apple Macintosh Integrated Development Environment (IDLDE)
Microsoft Windows IDLDE
Motif IDLDE (Unix and VMS)
Unix plain tty
VMS plain tty
All of thesefront-endsareabletoprocesswidget eventsexcept for theVMSplaintty. VMS
users can still enjoy an active command line by using the IDLDE interface.
If thecommand-processingfront-end can processwidget events(that is, if thefront-end
isnot the VMS plain tty), it is still necessary for widget applications to be well-behaved
with respect to blocking widget event processing. Since in most cases XMANAGER is
usedtohandlewidget event processing, thismeansthat in order for thecommandlineto
remain active, all widget applications must be run with the NO_BLOCK keyword to
XMANAGER set. (Note that since NO_BLOCK isnot the default, it is quite likely that
someapplicationwill block.) If asingleapplicationrunsinblockingmode, thecommand
linewill beinaccessibleuntil theblockingapplication exits. When ablockingapplication
exits, the IDL command line will once again become active.
JUST_REG vs. NO_BLOCK
Although their names imply a similar function, the JUST_REG and NO_BLOCK
keywordsperformverydifferent services. It isimportant tounderstandwhat theydoand
how they differ.
The JUST_REG keyword tells XMANAGER that it should simply register a client and
then return immediately. The result is that the client becomes known to XMANAGER,
and that future calls to XMANAGER will take this client into account. Therefore,
JUST_REG only controls how the registering call to XMANAGER should behave. The
client canstill beregisteredasrequiringXMANAGERtoblock bysettingNO_BLOCK=0.
In this case, futurecalls to XMANAGER will block.
Note JUST_REG is useful in situations where you suspect blocking might occurif the
activecommandlineisnot supportedandyouwishtokeepit activebeforebeginning
event processing, or if blocking will be requested at a later time. If no blocking will
occur or if the blocking behavior is useful, it is not necessary to use JUST_REG.
The NO_BLOCK keyword tells XMANAGER that the registered client does not require
XMANAGER to block if the command-processing front-end is able to support active
commandlineevent processing. XMANAGERremembersthisattributeof theclient until
the client exits, even after the call to XMANAGER that registered the client returns.
NO_BLOCK is just a vote on how XMANAGER should behavethe nal decision is
made by XMANAGER by considering the NO_BLOCK attributes of all of its current
clients as well as the ability of the command-processing front-end in use to support the
active command line.
Blocking vs. Non-blocking Applications
Theissueof blockingin XMANAGERrequiressomeexplanation. IDL widget eventsare
not processed until theWIDGET_EVENT function iscalled to handlethem. Otherwise,
theyarequeuedbyIDLindenitely. Knowinghowandwhen tocall WIDGET_EVENTis
the primary service provided by XMANAGER.
There are two ways blocking is typically handled:
1. Therst call to XMANAGERprocesseseventsby callingWIDGET_EVENT asnecessary
until nomanaged widgetsremain on thescreen. Thisisreferred toas blocking because
XMANAGERdoesnot return to thecaller until it isdone, and theIDL command lineis
not available.
2. XMANAGERdoesnot block, andinstead, thepart of IDLthat readscommandinput also
watches for widget events and calls WIDGET_EVENT as necessary while also reading
command input. This is referred to as non-blocking or active command line mode.
XMANAGER will block unless all of the following conditions are met:
The command-processing front-end is able to process widget events (that is, the front-
end is not the VMS plain tty).
All registered widget applications have the NO_BLOCK keyword to XMANAGER set.
No modal dialogs are displayed. (Modal dialogs always block until dismissed.)
In general, we suggest that new widget applications be written with XMANAGER
blockingdisabled(that is, with theNO_BLOCKkeywordset). Sinceawidget application
that doesblock event processingfor itself will block event processingfor all other widget
applications (and the IDL command line) as well, we suggest that older widget
applicationsbeupgradedtotakeadvantageof thenew, non-blockingbehavior byadding
the NO_BLOCK keyword to most calls to XMANAGER.
Example
The following code creates a widget named EXAMPLE that is just a base widget with a
Done button and registersit with theXMANAGER. Widgetsbeingregistered with the
XMANAGERmust provideat least tworoutines. Therst routinecreatesthewidget and
registers it with the manager and the second routine processes the events that occur
within that widget. An example widget is supplied below that uses only two routines. A
number of other SimpleWidget Examples, can beviewedbyenteringWEXMASTERat
the IDL prompt. These simple programs demonstrate many aspects of widget
programming.
The following lines of code would be saved in a single le, named example.pro:
PRO example_event, ev Begin theevent handler routine
for theEXAMPLE widget.
WIDGET_CONTROL, ev.id, GET_UVALUE = uv Theuservalueis retrieved from a
widget when an event occurs.
if (uv eq 'DONE') THEN WIDGET_CONTROL, ev.top, /DESTROY
If theevent occurred in theDone
button, kill thewidget example.
END End of theevent handler part.
PRO example Thisistheroutinethatcreatesthe
widget and registers it with the
XMANAGER.
base = WIDGET_BASE(TITLE='Example') Createthetop-level basefor the
widget.
done = WIDGET_BUTTON(base, VALUE = 'Done', UVALUE = 'DONE')
CreatetheDonebuttonandsetits
uservalueto DONE.
WIDGET_CONTROL, base, /REALIZE Realizethewidget (i.e., display it
on screen).
XMANAGER, 'example', base, /NO_BLOCK Register thewidget with the
XMANAGER, leavingtheIDL
command lineactive.
END End of thewidget creation part.
First the event handler routine is listed. The handler routine has the same name as the
main routinewith thecharacters _event added. If you would liketo useanother event
handler name, you would need to pass its name to XMANAGER using the
EVENT_HANDLER keyword.
Notice that the event routine is listed before the main routine. This is because the
compiler will not compiletheevent routineif it wasbelowthemain routine. Thisisonly
needed if both routines reside in the same le and the le name is the same as the main
routine name with the.pro extension added.
NoticealsotheNO_BLOCKkeywordtoXMANAGERhasbeenincluded. ThisallowsIDL
to continue processing events and accepting input at the command prompt while the
example widget application is running.
See Also
XMTOOL, XREGISTERED, Widgets in Chapter 15.
IDL Reference Guide XMNG_TMPL
XMNG_TMPL
The XMNG_TMPL procedure is a template for widgets that use the XMANAGER. Use
this template instead of writing your widget applications from scratch. This template
can befoundin thelexmng_tmpl.pro in thelib subdirectoryof theIDLdistribution.
Thedocumentation header should bealtered to reect theactual implementation of the
XMNG_TMPL widget. Use a global search and replace to replace the word XMNG_TMPL
with the name of the routine you would like to use. All the comments with a *** in
front of themshouldberead, decidedupon andremovedfromthenal copyof your new
widget routine.
Calling Sequence
XMNG_TMPL
Keywords
BLOCK
GROUP
Thewidget IDof thewidget that callsXMNG_TMPL. WhenthisIDisspecied, thedeath
of the caller results in the death of XMNG_TMPL.
See Also
CW_TMPL
XMTOOL IDL Reference Guide
XMTOOL
TheXMTOOLproceduredisplaysatool for viewingwidgetscurrentlybeingmanagedby
the XMANAGER. Only one instance of the XMTOOL can run at one time.
xmtool.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XMTOOL
Keywords
BLOCK
GROUP
The widget ID of the widget that calls XMTOOL. If the calling widget is destroyed, the
XMTOOL is also destroyed.
See Also
XLOADCT
IDL Reference Guide XPALETTE
XPALETTE
TheXPALETTEproceduredisplaysawidget interfacethat allowsinteractivecreationand
modication of colortables using the RGB, CMY, HSV, or HLS color systems. Single
colors can be dened or multiple color indices between two endpoints can be
interpolated.
xpalette.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XPALETTE
Keywords
BLOCK
GROUP
The widget ID of the widget that calls XPALETTE. When this ID is specied, a death of
the caller results in a death of XPALETTE.
UPDATECALLBACK
Set thiskeywordtoastringcontainingthenameof auser-suppliedprocedurethat will be
called when the color table is updated by XLOADCT. The procedure may optionally
accept a keyword called DATA, which will be automatically set to the value specied by
the optional UPDATECBDATA keyword.
UPDATECBDATA
Set thiskeywordtoavalueof anytype. It will bepassedviatheDATAkeywordtotheuser-
supplied procedure specied via the UPDATECALLBACK keyword, if any. If the
UPDATECBDATA keyword is not set the value accepted by the DATA keyword to the
procedure specied by UPDATECALLBACK will be undened.
Using the XPALETTE Interface
CallingXPALETTEcausesagraphical interfaceto appear. Theelementsof thisinterface
are described below.
PlotsonLeft Sideof Interface:Threeplotsshowthecurrent red, green, andblue
vectors.
XPALETTE IDL Reference Guide
Status Region: The center of the XPALETTE widget is a status region containing:
The total number of colors.
Thecurrent color index. XPALETTEallowschangingonecolor at atime. Thiscolor is
known as the current color and is indicated in the color spectrum display with a
special marker.
The current mark index. The mark is used to remember a color index. Click the Set
Mark Button to make the current color index the mark index.
A sample of the current color. The special marker used in the color spectrum display
prevents the user from seeing the color of the current index, but it is visible here.
Control Panel: A panel of 8 buttons control common XPALETTE functions:
Done: Click this button to exit XPALETTE. The new color tables are saved in the
COLORS common block and loaded to the display.
Predefined: Click this button to start XLOADCT, allowing selection of one of the
predened color tables. Note that when you change the color map via XLOADCT,
XPALETTE is not always able to keep its display accurate. This problem can be
overcome by pressing the XPALETTE Redraw button after changing the colortable
via XLOADCT.
Help: Click this button to display help information.
Redraw:Click thisbutton toredrawsthedisplay usingthecurrent stateof thecolor
map.
Set Mark: Click this button to set the value of the mark index to the current color
index.
Switch Mark: Click this button to exchange the mark and the current index.
CopyCurrent:Clickthisbuttontomakeeverycolor lyingbetweenthecurrent index
and the mark index (inclusive) the same color as the current color.
Interpolate: Click this button to smoothly interpolate colors between the current
index and the mark index.
Color System Control: This section of the interface allows you to select the color
systemused to modify individual colors. TheSelect Color System pulldown menu lets
you select fromfour different systemsRGB, CMY, HSV, andHLS. Dependingupon the
current system, 3 sliders below the pulldown menu allow you to alter the current color.
RightSideColorSpectrumDisplay:Adisplayontheright sideof theXPALETTE
interfaceshowsthecurrent color map asaseriesof squares. Color index 0isat theupper
left. The color index increases monotonically by rows going left to right and top to
bottom. Thecurrent color indexisindicatedbyaspecial marker symbol. Thereare4ways
to change the current color:
Click on any square in the color map display.
Use the By Index slider to move to the desired color index.
Use the Row Slider to move the marker vertically.
IDL Reference Guide XPALETTE
Use the Column Slider to move the marker horizontally.
A Note about the Colors Used in the Interface
XPALETTE uses two colors from the current color table as drawing foreground and
background colors. These are used for the RGB plots on the left, and the current index
marker on theright. Thismeansthat if theuser set thesetwocolorstothesamevalue, the
XPALETTE display could become unreadable (like writing on black paper with black
ink). XPALETTE minimizes this possibility by noting changes to the color map and
alwaysusingthebrightest availablecolor for theforeground color and thedarkest for the
background. Thus, the only way to make XPALETTEs display unreadable is to set the
entire color map to a single color, which is highly unlikely. The only side effect of this
policy is that you may notice XPALETTE redrawing the entire display after youve
modiedthecurrent color. Thissimplymeansthat thechangehasmadeXPALETTEpick
new drawing colors.
See Also
LOADCT, MODIFYCT, XLOADCT, TVLCT
XREGISTERED IDL Reference Guide
XREGISTERED
The XREGISTERED function returns True if the widget named as its argument is
currently registered with theXMANAGERasan exclusivewidget. Otherwisetheroutine
returns false.
If thenamedwidget isregistered, XREGISTEREDreturnsthenumber of instancesof that
name in the list maintained by XMANAGER. The registered widget is brought to the
front of the desktop unless the NOSHOW keyword is set.
xregistered.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = XREGISTERED(Name)
Arguments
Name
A string containing the name of the widget in question.
Note XREGISTEREDchecksfor NameinaCOMMONblockcreatedbyXMANAGER. The
stored name is case-sensitive.
Keywords
NOSHOW
If the widget in question is registered, it is brought to the front of all the other windows
by default. Set this keyword to keep the widget from being brought to the front.
Example
Supposethat you haveawidget programthat registersitself with theXMANAGERwith
the command:
XMANAGER, 'mywidget', base
You could limit this widget to one instantiation by adding the following line as the rst
line (after the procedure denition statement) of the widget creation routine:
IF XREGISTERED('mywidget') THEN RETURN
See Also
XMANAGER
IDL Reference Guide XSQ_TEST
XSQ_TEST
The XSQ_TEST function computes the Chi-square goodness-of-t test between
observed frequencies and the expected frequencies of a theoretical distribution. The
result is a two-element vector containing the Chi-square test statistic X2 and the one-
tailed probability of obtaining a value of X2 or greater.
Expected frequencies of magnitude less than 5 are combined with adjacent elements
resulting in a reduction of cells used to formulate the chi-squared test statistic. If the
observed frequencies differ signicantly from the expected frequencies, the Chi-square
test statistic will be large and the t is poor. This situation requires the rejection of the
hypothesis that the given observed frequencies are an accurate approximation to the
expected frequency distribution.
xsq_test.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
Result = XSQ_TEST(Obfreq, Exfreq)
Arguments
Obfreq
observed frequencies.
Exfreq
expected frequencies.
Keywords
EXCELL
Set this keyword to a named variable that will contain a vector of expected frequencies
used to formulate the Chi-square test statistic. If each of the expected frequencies
containedin Exfreq, hasamagnitudeof 5or greater, then thisvector isidentical toExfreq.
If Exfreq contains elements of magnitude less than 5, adjacent expected frequencies are
combined. Theidentical combinationsareperformed on thecorrespondingelementsof
Obfreq.
OBCELL
Set this keyword to a named variable that will contain a vector of observed frequencies
used to formulate the Chi-square test statistic. The elements of this vector are often
XSQ_TEST IDL Reference Guide
referred to as the cells of the observed frequencies. The length of this vector is
determined by the length of EXCELL described below.
RESIDUAL
Set this keyword to a named variable that will contain a vector of signed differences
between corresponding cells of observed frequencies and expected frequencies.
RESIDUAL[i] = OBCELL[i] - EXCELL[i].
The length of this vector is determined by the length of EXCELL described above.
Example
Dene the vectors of observed and expected frequencies.
obfreq = [2, 1, 4, 15, 10, 5, 3]
exfreq = [0.5, 2.1, 5.9, 10.3, 10.7, 7.0, 3.5]
Test thehypothesisthat thegiven observed frequenciesarean accurateapproximation to
the expected frequency distribution.
result = XSQ_TEST(obfreq, exfreq)
PRINT, result
IDL prints:
3.05040 0.383920
Since the vector of expected frequencies contains elements of magnitude less than 5,
adjacent expected frequencies are combined resulting in fewer cells. The identical
combinations are performed on the corresponding elements of observed frequencies.
The computed value of 0.383920 indicates that there is no reason to reject the proposed
hypothesis at the 0.05 signicance level.
See Also
CTI_TEST
IDL Reference Guide XSURFACE
XSURFACE
The XSURFACE procedure provides a graphical interface to the SURFACE and
SHADE_SURF commands. Different controls are provided to change the viewing angle
and other plot parameters. The command used to generate the resulting surface plot is
shown in a text window. Note that this procedure does not accept SURFACE or
SHADE_SURF keywords.
xsurface.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XSURFACE, Data
Arguments
Data
The two-dimensional array to display as a wire-mesh or shaded surface.
Keywords
BLOCK
GROUP
Set this keyword to the widget ID of the widget that calls XSURFACE. When GROUP is
specied, the death of the calling widget results in the death of XSURFACE.
Example
z = DIST(30) Makea 2D array.
XSURFACE, z Call XSURFACE. TheXSUR-
FACE widget appears.
See Also
SHADE_SURF, SURFACE
XVAREDIT IDL Reference Guide
XVAREDIT
The XVAREDIT procedure is a widget-based editor for any IDL variable. Use the input
elds to change desired values of the variable or array. Click Accept to write the new
values into the variable. Click Cancel to exit XVAREDIT without saving changes.
xvaredit.pro in thelib subdirectory of the IDL distribution.
Calling Sequence
XVAREDIT, Var
Arguments
Var
The variable to be edited. On output, this variable contains the edited value if the user
selects the Accept button, or the original value if the user selects the Cancel button.
Keywords
NAME
The NAME of the variable. This keyword is overwritten with the structure name if the
variable is a structure.
GROUP
The widget ID of the widget that calls XVAREDIT. When this ID is specied, a death of
the caller results in a death of XVAREDIT.
X_SCROLL_SIZE
Set this keyword to specify the column width of the scrolling viewport. The default is 4.
Y_SCROLL_SIZE
Set this keyword to specify the row width of the scrolling viewport. The default is 4.
IDL Reference Guide XYOUTS
XYOUTS
TheXYOUTSproceduredrawstext on thecurrently-selected graphicsdevicestartingat
the designated coordinate.
ArgumentsX, Y, and Stringcan beany combination of scalarsor arrays. If thearguments
are arrays, multiple strings are output.
If the optional X and Y arguments are omitted, the text is positioned at the end of the
most recently output text string.
Important keywords that control the appearance and positioning of the text include:
ALIGNMENT, the justication of the text; CHARSIZE, the size of the text; FONT,
chooses between vector drawn and hardware fonts; COLOR, the color of the text; and
ORIENTATION, the angle between the baseline of the text and the horizontal. With
hardwarefonts, most of thetext attributes, (e.g., sizeandorientation), arepredetermined
and not changeable.
Note Specify the Z coordinate with the Z keyword when positioning text in three dimen-
sions.
Calling Sequence
XYOUTS, [X, Y,] String
Arguments
X, Y
The horizontal and vertical coordinates used to position the string(s). X and Y are
normally interpreted in datacoordinates. TheDEVICEand NORMAL keywordscan be
used to specify the coordinate units.
X and Y can be arrays of positions if Stringis an array.
String
Thestring(s) to beoutput. Thisargument can beascalar stringor an array of strings. If
this argument is not a string, it is converted prior to use using the default formatting
rules. If Stringis an array, X, Y, and the COLOR keyword can also be arrays so that each
string can have a separate location and color.
Keywords
ALIGNMENT
Species the alignment of the text baseline. An alignment of 0.0 (the default) aligns the
left edge of the text baseline with the given (x, y) coordinate. An alignment of 1.0 right-
justies the text, while 0.5 results in text centered over the point (x, y).
XYOUTS IDL Reference Guide
CHARSIZE
The overall character size for the annotation. A CHARSIZE of 1.0 is normal. Setting
CHARSIZE = -1 suppresses output of the text string. This keyword has no effect when
used with the hardware drawn fonts; for exceptions, see Scaled Hardware Fonts on
page1381.
CHARTHICK
Thelinethicknessof thevector drawn font characters. Thiskeyword hasno effect when
used with the hardware drawn fonts; for exceptions, see Scaled Hardware Fonts on
page1381. The default value is 1.0.
TEXT_AXES
Thiskeywordspeciestheplaneof vector drawn text when three-dimensional plottingis
enabled. By default, text is drawn in the plane of the XY axes. The horizontal text
direction isin theXplane, and thevertical text direction isin theYplane. Valuesfor this
keyword can rangefrom0to 5, with thefollowingeffects: 0for XY, 1for XZ, 2for YZ, 3
for YX, 4 for ZX, and 5 for ZY. The notation ZY means that the horizontal direction of
the text lies in the Z plane, and the vertical direction of the text is drawn in the Y plane.
WIDTH
Set this keyword to a named variable in which to return the width of the text string, in
normalized coordinate units.
not listed above. CLIP, COLOR, DATA, DEVICE, FONT, NOCLIP, NORMAL,
ORIENTATION, T3D, Z.
Example
Print the string This is text at device coordinate position (100,100) by entering:
XYOUTS, 100, 100, 'This is text', /DEVICE
Print an arrayof stringswitheachelement of thearrayprintedat adifferent location. Use
larger text than in the previous example. Enter:
XYOUTS, [0, 200, 250], [200, 50, 100], $
['This', 'is', 'text'], CHARSIZE = 3, /DEVICE
To determine the text size for a window device before opening an on-screen window,
enter:
WINDOW, /FREE, /PIXMAP, XSIZE=myWinXSize, YSIZE=myWinYSize
XYOUTS, Check this out, WIDTH=w
WDELETE
IDL Reference Guide XYOUTS
(wheremyWinXSizeandmyWinYSizearechosen tomatchyour onscreen window.) Since
we can not know the characteristics of a given device (such as character size) until a
windowhasbeen opened, thePIXMAPkeyword to WINDOWon page1317allowsyou
tocomputeappropriatedimensionsfor text withan invisiblewindowbeforedisplayinga
window on your screen.
Scaled Hardware Fonts
Oneexampleof hardwarefontswhich can bescaled arePostScript fonts. If you areusing
PostScript fonts, thekeywordsCHARTHICKandCHARSIZEwill havean effect on acall
to XYOUTS. Of thedevicesweprovidethat support hardwarefonts, only thePostScript
deviceusesscalablePostScript fontsfor its hardware font system. All other devicesuse
a bitmapped font technology.
Scaling is related to whether or not a device supports Hershey formatting commands
when hardware fonts are used. Formatting requires the ability to scale the text on a per-
character basis(i.e. for subscripting). Toseeif agivendevicesupportsHersheyformatting
when hardware fonts are used, look at bit 12 of !D.FLAGS on page 46. You can also use
this indicator to determine whether or not the hardware fonts will be scaled.
See Also
ANNOTATE, PRINT/PRINTF
ZOOM IDL Reference Guide
ZOOM
TheZOOM proceduredisplayspart of an imagefromthecurrent windowenlarged in a
new ( zoom ) window. The cursor is used to mark the center of the zoom area, and
different zoom factors can be specied interactively.
Note ZOOM only works with color systems.
zoom.pro in thelib subdirectory of the IDL distribution.
Using ZOOM
After callingZOOM, placethemousecursor over an imagein an IDL graphicswindow.
Click theleft mousebutton todisplayamagnied version of theimagein anewwindow.
Thezoomedimageiscenteredaroundthepixel selectedin theoriginal window. Click the
middlemousebutton todisplayamenu of zoomfactors. Click theright mousebutton to
exit the procedure.
Using ZOOM with Draw Widgets
Notethat theZOOM procedureisonlyfor usewith IDL graphicswindows. It shouldnot
be used with draw widgets. To obtain a zooming effect in a draw widget, use the
CW_ZOOM function.
Calling Sequence
ZOOM
Keywords
CONTINUOUS
Set this keyword to make the zoom window track the mouse without requiring the user
to press the left mouse button. This feature only works well on fast computers.
FACT
Usethiskeyword tospecifythezoomfactor, which must bean integer. Thedefault zoom
factor is 4.
INTERP
Set this keyword to use bilinear interpolation. The default is to use pixel replication.
KEEP
Set this keyword to keep the zoom window after exiting the procedure.
IDL Reference Guide ZOOM
NEW_WINDOW
Normally, if ZOOM is called with KEEP and then called again, it will use the same
window to display the new zoomed image. Set the NEW_WINDOW keyword to force
ZOOM to create a new window for this purpose.
XSIZE
Use this keyword to specify the X size of the zoom window. The default is 512.
YSIZE
Use this keyword to specify the Y size of the zoom window. The default is 512.
ZOOM_WINDOW
Set this keyword to a named variable that will contain the index of the zoom window.
KEEPmust also beset. If KEEPisnot set, ZOOM_WINDOWwill contain theinteger -1.
See Also
CW_ZOOM, ZOOM_24
ZOOM_24 IDL Reference Guide
ZOOM_24
TheZOOM_24proceduredisplayspart of a24-bit color imagefromthecurrent window
expanded in a new ( zoom ) window, and provides information about cursor location
and color values in an auxiliary (data ) window. The cursor is used to mark the center
of the zoom area, and different zoom factors can be specied interactively.
Note ZOOM only works on 24-bit color systems.
zoom_24.pro in thelib subdirectory of the IDL distribution.
Using ZOOM_24
After callingZOOM_24, windowstitled ZoomedImage (thezoomwindow) and Pixel
Values (the data window) appear on the screen. Place the mouse cursor over a 24-bit
color image in an IDL graphics window and click the left mouse button to display a
magnied version of the image in the zoom window. The zoomed image is centered
around the pixel selected in the original window. Move the mouse cursor in the zoom
window to determine the coordinates (in the original image) and color values of
individual pixels.
With the cursor located in the zoom window, click the right mouse button to return to
selection mode, which allows you to either choose a new zoom center, change the zoom
factor, or exit theprocedure. Movethecursor to theoriginal imageand click themiddle
mousebutton to display amenu of zoomfactors, or click theright mousebutton to exit
the procedure.
Using ZOOM_24 with Draw Widgets
Notethat theZOOM_24procedureisonlyfor usewith IDL graphicswindows. It should
not be used with draw widgets. To obtain a zooming effect in a draw widget, use the
CW_ZOOM function.
Calling Sequence
ZOOM_24
Keywords
FACT
Usethiskeyword tospecifythezoomfactor, which must bean integer. Thedefault zoom
factor is 4.
IDL Reference Guide ZOOM_24
RIGHT
Set this keyword to position the zoom and data windows to the right of the original
window.
XSIZE
Use this keyword to specify the X size of the zoom window. The default is 512.
YSIZE
Use this keyword to specify the Y size of the zoom window. The default is 512.
See Also
CW_ZOOM, ZOOM
ZOOM_24 IDL Reference Guide
1387
Chapter 10
Scientic Data
Formats
IDL Supports four self-describing scientic data formatsCDF (Common Data
Format), HDF (Hierarchical Data Format), HDF-EOS (Earth Observing System
extensions to HDF),and NetCDF (Network Common Data Format). Detailed
information on the scientic data formats is contained in Scientic Data Formats.
Note Although the complete documentation for IDLs scientic data format routines is
availablethrough IDLsonlinehelp system, theprinted version of theScienticData
Formatsis not shipped automatically when you purchase IDL. If you would like to
receive a printed copy of the scientic data formats documentation, return the
business reply card enclosed with your IDL package, or contact your sales represen-
tative.
CDF Common Data Format
The Common Data Format is a le format that facilitates the storage and retrieval of
multi-dimensional scientic data. The current release of IDL supports CDF version
1388 Chapter 10: Scientific Data Formats
HDFHierarchical Data Format IDL Reference Guide
CDF2_6. IDLsCDFroutinesall begin with theprex CDF_. Documentation for these
routines can be found in Scientic Data Formats.
CDFisaproduct of National SpaceScienceDataCenter (NSSDC). General information
about CDF, including the frequently-asked-questions (FAQ) list, software, and CDFs
IDL library (an alternative interface between CDF and IDL) are available on the World
Wide Web at:
http://nssdc.gsfc.nasa.gov/cdf/cdf_home.html
If you do not have access to the WWW you can get CDF information via ftp at:
ftp://nssdc.gsfc.nasa.gov/pub/cdf/FAQ.doc
For assistance via e-mail, send a message to the internet address:
cdfsupport@nssdca.gsfc.nasa.gov
HDF Hierarchical Data Format
The Hierarchical Data Format (HDF) is a multi-object le format that facilitates the
transfer of various types of data between machines and operating systems. HDF is a
product of the National Center for Supercomputing Applications (NCSA). HDF is
designed to be exible, portable, self-describing and easily extensible for future
enhancements or compatibility with other standard formats. The HDF library contains
interfaces for storing and retrieving images and multi-dimensional scientic data. This
version of IDL supports HDF4.0. IDLs HDF routines all begin with the prex HDF_.
Documentation for these routines can be found in Scientic Data Formats.
Further information about HDF can be found on the World Wide Web. The HDF
Frequently-Asked Questions le can be found at:
http://hdf.ncsa.uiuc.edu/HDF-FAQ.html
Alternately, you can send e-mail to hdfhelp@ncsa.uiuc.edu.
HDF-EOS Hierarchical Data Format-Earth Observing System
HDF-EOSisan extension of NCSA(National Center for SupercomputingApplications)
HDF and uses HDF calls as an underlying basis. This API contains functionality for
creating, accessing and manipulating Grid, Point and Swath structures. IDLs HDF-EOS
routinesall begin with theprex EOS_. Documentation for theseroutinescan befound
in Chapter 5 of Scientic Data Formats.
HDF-EOS is a product of NASA, information may be found at:
http://hdfeos.gsfc.nasa.gov
Chapter 10: Scientific Data Formats 1389
IDL Reference Guide NetCDFNetwork Common Data Format
NetCDF Network Common Data Format
The network Common Data Format (netCDF) is a self-describing scientic data access
interfaceandlibrarydevelopedat theUnidataProgramCenter inBoulder, Colorado. The
netCDFinterfaceand library useXDR(eXternal DataRepresentation) to makethedata
format machine-independent. This version of IDL supports netCDF 2.4. IDLs NetCDF
routines all begin with the prex NCDF_. Documentation for these routines can be
found in Scientic Data Formats.
More information about netCDF can be found on Unidatas netCDF World Wide Web
home page which can be found at:
http://www.unidata.ucar.edu/packages/netcdf/
Further information and the original netCDF documentation can be obtained from
Unidata at the following addresses:
UCAR Unidata Program Center
P.O. Box 3000
Boulder, Colorado, USA 80307
(303) 497-8644
e-mail: support@unidata.ucar.edu
1390 Chapter 10: Scientific Data Formats
NetCDFNetwork Common Data Format IDL Reference Guide
1391
Chapter 11
Obsolete Routines
To improve the overall quality and functionality of IDL, Research Systems occasionally
replaces existing routines with new, improved routines. In many cases, existing routines
are improved without changing their existing behaviorthrough improvements of the
underlying algorithms, for example, or by adding keyword functionality. In some cases,
however, the improved methods are incompatible with the old. In these situations, we
consider the routines that we have replaced to beobsolete. Routines that have become
obsolete are listed later in this chapter.
Backwards Compatibility
Research Systemsstrongly recommendsthat you not useobsoleteroutineswhen writing
new IDL code. As IDL continues to evolve, the likelihood that obsolete routines will no
longer function as expected increases. While we will continue to make every effort to
ensurethat obsoleteroutinesshipped with IDL function, in asmall number of casesthis
may not be possible.
1392 Chapter 11: Obsolete Routines
Detecting Use of Obsolete Features IDL Reference Guide
If weconsider an obsoleteroutinetobeunsupportablein thelongterm, wewill schedule
its removal from IDL, providing a minimum of one major releases notice.
IDL Internal Routines
Routines that are built into the IDL executableroutinesnot written in the IDL
languagewill either continue to be included in the executable until the scheduled
removal releaseor will bere-implementedintheIDLlanguage. Inthelatter case, obsolete
routinesmay run slower than theoriginal version. Notethat obsoleteroutinesthat have
been re-implemented in the IDL language may also be scheduled for eventual removal.
Routines Written in IDL
Routines written in the IDL language (.pro les) are contained in the obsolete
subdirectory of the lib directory of the IDL distribution. As long as a given obsolete
routine is included in this subdirectory, it will continue to function as always.
Detecting Use of Obsolete Features
You can search for usageof obsoleteroutines, systemvariables, and syntax by settingthe
elds of the !WARN system variable. Setting !WARN causes IDL to print informational
messages to the command log or console window when it encounters references to
obsolete features. See !WARN on page 41 for details.
Documentation for Obsolete Routines
Routines that became obsolete in IDL version 5.0 or later are documented in a special
online help le named obsolete.hlp, located in thehyperhelp subdirectory of the
help directory of the IDL distribution (Unix and VMS) or in thehelp subdirectory of
theIDL distribution (Windowsand Macintosh). Open theobsoletedocumentation help
le by starting the IDL Online Help, selecting the Contents tab, and double-clicking on
the Obsolete Routines book.
Routinesthat becameobsoletein IDL version 4.0or earlier arenot documentedin ahelp
le. However, if the routine is written in the IDL language, you can inspect the
documentationheader of the.pro le, or usetheDOC_LIBRARYroutine. .pro lesfor
obsolete routines are located in theobsolete subdirectory of thelib directory of the
IDL distribution.
The tables below list routines that have become obsolete, along with the name of the
routine that replaces the obsolete routine (if any) and the name of the.pro le for the
obsolete routine (if any).
Chapter 11: Obsolete Routines 1393
IDL Reference Guide Routines That Became Obsolete in IDL Version 5.1
Routines That Became Obsolete in IDL Version 5.1
The following routines were present in IDL Version 5.0 but became obsolete in IDL
Version 5.1. Documentation for these routines can be found in the online help le
obsolete.hlp.
Routines That Became Obsolete in IDL Version 5.0
The following routines were present in IDL Version 4.0 but became obsolete in IDL
Version 5.0. Documentation for these routines can be found in the online help le
obsolete.hlp.
Routine Replaced by .pro File?
SLICER SLICER3 slicer3.pro
DDE routines n/a
GETHELP OUTPUT keyword to
HELP
HANDLE_CREATE PTR_NEW
HANDLE_FREE PTR_FREE
HANDLE_INFO PTR_VALID
HANDLE_MOVE n/a
HANDLE_VALUE dereference operator
INP, OUTP n/a
.SIZE executive com-
mand
No longer needed
PICKFILE DIALOG_PICKFILE
old RPC API new RPC API
WIDGET_MESSAGE DIALOG_MESSAGE
TIFF_DUMP n/a
TIFF_READ READ_TIFF
TIFF_WRITE WRITE_TIFF
WIDED n/a
Routines That Became Obsolete in IDL Version 4.0 or Earlier IDL Reference Guide
RoutinesThatBecameObsoleteinIDLVersion4.0orEarlier
Thefollowingroutinesbecameobsoletein IDLversion 4.0or earlier. If a.pro lefor the
routineexits, it islocated in theobsolete subdirectory of thelib directory of theIDL
distribution. You can read the documentation header of a routine in theobsolete
directory either by opening the.pro le or using the DOC_LIBRARY routine.
Numerical Recipes
Routines
LUBKSB LUSOL
LUDCMP LUDC
MPROVE LUMPROVE
NR_BETA BETA
NR_BROYDN BROYDEN
NR_CHOLDC CHOLDC
NR_CHOLSL CHOLSOL
NR_DFPMIN DFPMIN
NR_ELMHES ELMHES nr_elmhes.pro
NR_EXPINT EXPINT
NR_FULSTR FULSTR
NR_HQR HQR nr_hqr.pro
NR_INVERT INVERT
NR_LINBCG LINBCG
NR_LUBKSB LUSOL nr_lubksb.pro
NR_LUDCMP LUDC nr_ludcmp.pro
NR_MACHAR MACHAR
NR_MPROVE LUMPROVE
NR_NEWT NEWTON
NR_POWELL POWELL
NR_QROMB QROMB
NR_QROMO QROMO
NR_QSIMP QSIMP
NR_RK4 RK4
IDL Reference Guide Routines That Became Obsolete in IDL Version 4.0 or Earlier
NR_SPLINE SPL_INIT
NR_SPLINT SPL_INTERP
NR_SPRSAB SPRSAB
NR_SPRSAX SPRSAX
NR_SPRSIN SPRSIN nr_sprsin.pro
NR_SVBKSB SVSOL nr_svbksb.pro
NR_SVD SVDC nr_svd.pro
NR_TQLI TRIQL
NR_TRED2 TRIRED
NR_TRIDAG TRISOL
NR_WTN WTN nr_wtn.pro
NR_ZROOTS FZ_ROOTS
SVBKSB SVSOL
SVD SVDC
TQLI TRIQL
TRED2 TRIRED
TRIDAG TRISOL
ZROOTS FZ_ROOTS
Mathematics and
Statistics Routines
ANOVA KW_TEST anova.pro
ANOVA_UNEQUAL KW_TEST anova_uneqal.pro
BETAI IBETA betai.pro
CHI_SQR CHISQR_CVF chi_sqr.pro
CHI_SQR1 CHISQR_PDF chi_sqr1.pro
CONTINGENT CTI_TEST contingent.pro
CORREL_MATRIX CORRELATE correl_matrix.pro
DIFFEQ_23 RK4 diffeq_23.pro
DIFFEQ_45 RK4 diffeq_23.pro
EIGEN_II EIGENVEC eigen_ii.pro
EQUAL_VARIANCE FV_TEST equal_variance.pro
F_TEST F_CVF f_test.pro
F_TEST1 F_PDF f_test1.pro
FRIEDMAN KW_TEST friedman.pro
GAUSS GAUSS_CVF gauss.pro
GOODFIT XSQ_TEST goodfit.pro
JOIN CLUSTER join.pro
KMEANS CLUSTER kmeans.pro
KRUSKAL_WALLIS KW_TEST kruskal_wallis.pro
LISTREP n/a listrep.pro
LISTWISE n/a listwise.pro
MAKETREE CLUSTER maketree.pro
MANN_WHITNEY RS_TEST mann_whitney.pro
MULTICOMPARE HypothesisTestingRou-
tines
multicompare.pro
PARTIAL2_COR P_CORRELATE partial2_cor.pro
PARTIAL_COR P_CORRELATE partical_cor.pro
REGRESS1 REGRESS regress1.pro
REGRESSION REGRESS regression.pro
RSI_GAMMAI IGAMMA rsi_gamma.pro
RUNS_TEST R_TEST runs_test.pro
SIGMA MOMENT sigma.pro
SIGN_TEST S_TEST sign_test.pro
SIMPSON QSIMP or QROMB simpson.pro
SPEARMAN R_CORRELATE sprearman.pro
STDEV MOMENT stdev.pro
STEPWISE REGRESS stepwise.pro
STUDENT1_T T_PDF student1_t.pro
STUDENT_T T_CVF student_t.pro
IDL Reference Guide Routines That Became Obsolete in IDL Version 4.0 or Earlier
STUDRANGE T_PDF studrange.pro
WILCOXON RS_TEST wilcoxon.pro
MiscellaneousRoutines
ADDSYSVAR DEFSYSV addsysvar.pro
ADJCT XPALETTE adjct.pro
C_EDIT XPALETTE c_edit.pro
CALL_VMS CALL_EXTERNAL
COLOR_EDIT XPALETTE color_edit.pro
COSINES n/a cosines.pro
CW_BSELECTOR WIDGET_DROPLIST cw_bselector.pro
CW_LOADSTATE NO_COPY keyword to
WIDGET_CONTROL
cw_loadstate.pro
CW_SAVESTATE NO_COPY keyword to
WIDGET_CONTROL
cw_savestate.pro
FORRD READU
FORRD_KEY READU
FORWRT WRITEU
DISP_TEXT XYOUTS disp_text.pro
FILLCONTOUR FILL keyword to CON-
TOUR
fillcontour.pro
HELP_VM MEMORY keyword to
HELP
help_vm.pro
HSV_TO_R COLOR_CONVERT hsv_to_r.pro
LATLON n/a latlon.pro
LEGO LEGO keyword to SUR-
FACE
lego.pro
LN03 n/a ln03.pro
MENUS WIDGET_DROPLIST,
etc.
menus.pro
MIPSEB_DBLFIXUP n/a mipseb_dblfixup.pro
MOVIE XINTERANIMATE movie.pro
ONLY_8BIT n/a only_8bit.pro
PALETTE XPALETTE palette.pro
PHASER n/a phaser.pro
PM n/a pm.pro
PMF n/a pmf.pro
POLYCONTOUR FILL keyword to CON-
TOUR
polycontour.pro
PROMPT n/a prompt.pro
PWIDGET n/a pwidget.pro
RGB_TO_HSV COLOR_CONVERT rgb_to_hsv.pro
RM n/a rm.pro
RMF n/a rmf.pro
ROT_INT ROT rot_int.pro
SET_NATIVE_PLOT n/a set_native_plot.pro
SET_SCREEN n/a set_screen.pro
SET_VIEWPORT n/a set_viewport.pro
SET_XY n/a set_xy.pro
SURFACE_FIT SFIT surface_fit.pro
TESTCONTRAST n/a testcontrast.pro
TVDELETE WDELETE
TVRDC CURSOR
TVSET WSET
TVSHOW WSHOW
TVWINDOW WINDOW
VMSCODE n/a vmscode.pro
WMENU WIDGET_DROPLIST,
etc.
wmenu.pro
XANIMATE XINTERANIMATE xanimate.pro
XBACKREGISTER TIMER keyword to
WIDGET_CONTROL
xbackregister.pro
XDL n/a xdl.pro
IDL Reference Guide Obsolete System Variables
Obsolete System Variables
The following IDL system variables became obsolete in the change from VAX IDL (IDL
version1) toIDLversion2. Whileit ishighlyunlikelythat youwill ndreferencestothese
systemvariablesin existingcode, weincludethemherebecausetheyareaggedwhen the
OBS_SYSVARS eld of the !WARN structure is set equal to one.
XMANAGERTOOL XMTOOL xmanagertool.pro
XMENU WIDGET_DROPLIST,
etc.
xmenu.pro
XPDMENU WIDGET_DROPLIST,
etc.
xpdmenu.pro
System Variable Replaced by
!BCOLOR BOTTOM keyword to SURFACE
!COLOR !P.COLOR
!CXMAX !X.CRANGE[ 1]
!CXMIN !X.CRANGE[ 0]
!CYMAX !Y.CRANGE[ 1]
!CYMIN !Y.CRANGE[ 0]
!FANCY No direct equivalent. Use !P.FONT and !P.CHARSIZE
!FLIP No equivalent.
!GRID !P.TICKLEN
!HI No equivalent.
!IGNORE !P.NOCLIP
!LINETYPE !P.LINESTYLE
!LO No equivalent.
!MTITLE !P.TITLE
!NOERAS !P.NOERASE
!NORMALCONT FOLLOW keyword to CONTOUR
Obsolete System Variables IDL Reference Guide
!NSUM !P.NSUM
!PSYM !P.PSYM
!SC1 !P.POSITION[ 0] * !D.X_VSIZE if !P.POSITION[ 2] is non-
zero, or !X.WINDOW[ 0] * !D.X_VSIZE otherwise.
zero, or !X.WINDOW[ 1] * !D.X_VSIZE otherwise.
zero, or !Y.WINDOW[ 0] * !D.X_VSIZE otherwise.
zero, or !Y.WINDOW[ 1] * !D.X_VSIZE otherwise.
!TERM DEVICE procedure.
!TYPE !X.TYPE, !X.STYLE, !Y.TYPE, !Y.STYLE, !P.TICKLEN
!XMAX !X.RANGE[ 1]
!XMIN !X.RANGE[ 0]
!XTICKS !X.TICKS
!XTITLE !X.TITLE
!YMAX !Y.RANGE[ 1]
!YMIN !Y.RANGE[ 0]
!YTICKS !Y.TICKS
!YTITLE !Y.TITLE
System Variable Replaced by
1401
Appendix A
VMS Floating-Point
Arithmetic in IDL 5.1
Topics discussed in this appendix include:
VAX Floating-Point Format Background ............................................................... 1402
Transition Issues .................................................................................................. 1403
A Warning About Floating-Point Conversions ...................................................... 1404
A Strategy For Converting VMS IDL Programs ..................................................... 1405
Using CALL_EXTERNAL Under IDL 5.1 and Later ................................................. 1406
A Note on the VMS G Float Format ..................................................................... 1407
1402 Appendix A: VMS Floating-Point Arithmetic in IDL 5.1
VAX Floating-Point Format Background IDL Reference Guide
All VMS versions of IDL through release 5.0 used VAX F and D oating-point formats.
In contrast, all non-VMSversionsof IDLuseadifferent andmoremodern oating-point
standard (IEEE704). With IDL release5.1, VMSIDL hasbeen converted to also support
IEEE oating-point formats rather than the now obsolete VAX formats. This appendix
explainsthehistory behind thesedecisionsand discusseshowto convert older VMSIDL
programs.
VAX Floating-Point Format Background
The oating-point format used by a program such as IDL is determined entirely by the
computer hardwareupon which it runs. In theearly yearsof computingit wascommon
for different machines to have incompatible oating-point formats. In the 1970s and
1980s, PDP-11andVAXminicomputerswerewidelyusedfor scienticcomputation, and
their oating-point format (known asFand Doating) becamethedefactostandard for
science.
Over the years, the computing industry has converged upon a oating-point standard
known asIEEE704, andcommonlyreferredtoas ieeeoating or ieeearithmetic, and
other formats (including the VAX) have diminished in importance. Now, all common
computinghardwareusestheIEEEformats, whichhassignicant advantagesover earlier
ones:
Binary data is portable to almost all current and foreseeable computing hardware and
operating systems, requiring at most simple byte swapping.
Special Innity and Not A Number (NaN) values for undened computations allow
exceptional computations to be carried out in a well dened manner.
This convergence gained momentum in the 1980s as workstations and personal
computers came into prominence. The result is that non-VMS versions of IDL have
always used IEEE oating-pointa signicant difference between them and the VMS
version. VAX/VMSIDLstayedwiththeVAXformatstoprovidebackwardscompatibility
with existing programs and data, and because the VAX hardware does not support the
IEEE formats.
In theearly 1990s, Digital Equipment Corporation released anewhardwarearchitecture
named ALPHA to replace the aging VAX line. The native oating-point format for
ALPHAisIEEE, but it alsosupportstheVAXformatsfor backwardscompatibility. When
IDL was ported to ALPHA/VMS, it was tempting to switch to IEEE oating-point in
order tobringit in linewith all other computers. However, thedecision wasmadetostay
with the VAX formats in order to maximize compatibility with our VMS customers
existing binary data. Since support for the VAX was not discontinued at that time,
Research Systems felt that it was important for all VMS implementations to be
compatible with each other.
Appendix A: VMS Floating-Point Arithmetic in IDL 5.1 1403
IDL Reference Guide Transition Issues
WithIDL5.1, theoating-point format for ALPHA/VMSIDLhasbeen changedtoIEEE.
There are many reasons for this decision:
IDL no longer runs on VAX hardware, and ALPHA supports IEEE natively. There is no
longer a hardware barrier to conversion.
The VAX formats are obsolete and no longer supported by any modern computing
hardware, making an eventual switch inevitable.
Thelack of special NaNand Innityvaluesprevented important IDL featuresfrombeing
useful under VMS, and differences in oating-point precision made some numerical
methods behave differently than on the other platforms.
The ALPHA implementation of VAX D oat has three fewer bits of precision than VAX
hardware, making that format even less attractive.
Unlikethepast, it israrefor computingsitestobeVMS-onlythesedays. Most VMSusers
alsouseUnix workstationsand personal computers, and thosemachinesall usetheIEEE
oating-point representation. Thesesiteshavealreadyaddressedtheissueof movingdata
between theseformats, and arethereforein aposition to moveto IEEEunder VMS. For
most sites, thefact that VMSIDL did not useIEEEoating-point had becomeaprimary
barrier to moving completely beyond the transition to IEEE.
Transition Issues
Most existing VMS applications will work with the IEEE version of VMS IDL without
code changes. The slight differences in precision and range between the VAX and IEEE
formats do not usually cause problems as long as you are aware of the limitations
discussed in A Warning About Floating-Point Conversions on page 1404. Since most
VMSsitesalsousenon-VMScomputers, suchconversionsareprobablyalreadycommon
at your site.
Transition issues therefore center around permanent data kept in disk les and off-line
storage. Within IDL, the focus is therefore on data entering and leaving IDL:
Input/ Output
Programs that read binary data in VAX format will have to convert it to IEEE format
before IDL can understand it. Similarly, programsthat writedatatoalethat issupposed
to contain VAX format data must convert the data to VAX format before writing it. The
BYTEORDER procedure has a number of new keywords designed to perform this
operation. Moreconveniently, theVAX_FLOATkeywordtotheOPENroutinescausesall
binary data input or output via ASSOC, READU, or WRITEU to be automatically
converted to the VAX oating-point format.
A Warning About Floating-Point Conversions IDL Reference Guide
CALL_EXTERNAL
Programs that pass oating-point data to or from code dynamically linked to IDL using
CALL_EXTERNAL may need to be adjusted. Theoptions, in order of preference, are:
1. Recompile the linked code to use the IEEE oating-point format (that is, using the
/IEEE_FLOAT/IEEE_MODE=DENORM compiler options).
2. Use the VAX_FLOAT keyword to CALL_EXTERNAL to automatically translate all data
to and from VAX format as necessary.
3. Convert data to or from VAX format using BYTEORDER.
Again, remember that conversion from one format to another is not without
consequences. Pleaseread AWarningAbout Floating-Point Conversions on page1404
before making a nal decision.
LINKIMAGE
Programs that pass oating-point data to or from code dynamically linked to IDL using
LINKIMAGErequirethat the linked code to be recompiled tousetheIEEEoating-point
format (that is, using the /IEEE_FLOAT/IEEE_MODE=DENORM compiler options).
SAVE and RESTORE
WhiledataalsoentersandleavesIDLviatheSAVEandRESTOREprocedures, thereisno
IEEE transition issue for such data. The portable XDR format of SAVE les is already
compatible with IEEE. Furthermore, RESTORE automatically converts the data in old
VMSformat SAVElestoIEEEformat asit readsthem, allowingdatain theolder format
to be recovered as well.
A Warning About Floating-Point Conversions
TheVAXformatsareobsoleteandIEEEisthestandardfor modern computinghardware.
With or without IDL, you will eventually nd it necessary to convert your existing VAX
data to IEEE format if it is to remain usable. In doing so, you should understand that
translation of oating-point values from one format to the other and back is not a
completely reversible operation, and should be avoided when possible. Two important
differences between the VAX and IEEE formats can lead to data loss:
1. The VAX oating-point format lacks support for the IEEE special oating-point values
NaN and Innity. Their special meaning is lost when they are converted to VAX format,
and the meaning cannot be recovered.
2. Differencesinprecisionandrangecanalsocauseinformationtobelost inbothdirections.
The conversion of existing VAX format data to IEEE cannot be avoided, and the
information lost is usually small. Once the data is converted to IEEE, however, it is best
to keep it and any resultscomputed fromit in IEEEformat and avoid convertingit back
to the VAX format for storage.
IDL Reference Guide A Strategy For Converting VMS IDL Programs
For thisreason, werecommendrecompilingall codecalledviaCALL_EXTERNALtouse
the IEEE oating-point format rather than using the VAX_FLOAT keyword. New data
should be written to les in IEEE format whenever possible.
A Strategy For Converting VMS IDL Programs
Starting with IDL 5.1, all IDL platforms, including ALPHA/VMS, use the IEEE oating-
point format. VMS sites upgrading from a previous version of IDL are faced with the
issue of how to manage this conversion. We recognize that such a conversion cannot
occur all at once, and will instead be carried out gradually. We suggest the following
general approach to making the transition.
Step 1: Ensure the Stability of Existing Operations
To ensure that your applications continue to work, keep IDL 5.0.x installed on your
systems, and useit torun existingapplications. Install theIEEEversion of IDL in parallel
withtheolder 5.0.xversionandkeepbothavailable. Then, shift tothenewer IEEEversion
as applications and data are ported.
Step 2: Use Compatibility Mode To Make The Initial Port
IEEEversionsof VMSIDLcanbestartedwiththe/VAX_FLOATcommandqualier. This
causesthedefault valueof theVAX_FLOAT keywordsto OPEN and CALL_EXTERNAL
to be TRUE instead of FALSE as is usually the case. This is often sufcient to allow
programs that do not use LINKIMAGE to run with IDL 5.1 while preserving the VAX
format of all external data.
Note You can also use the VAX_FLOAT function to check or change the default value of
the keywords to OPEN and CALL_EXTERNAL at runtime.
Step 3: Full Port
Tomoveyour codefullytoIEEEVMSwithout usingthespecial compatibilitymode(the
/VAX_FLOAT command qualier or callsto theVAX_FLOAT function) you will need to
take the following steps:
1. Recompiledynamically linked codeto usetheIEEEoating-point format (that is, using
the /IEEE_FLOAT/IEEE_MODE=DENORM compiler options).
2. If possible, convert data les to IEEE format, using the IEEE version of IDL to read the
VAX format data and then write a new version of the le in IEEE format.
3. If datalescannot beconverted to IEEEformat, adjust theOPEN statementsthat access
them to include the VAX_FLOAT keyword so that IDL converts the data on input and
output.
Using CALL_EXTERNAL Under IDL 5.1 and Later IDL Reference Guide
Using CALL_EXTERNAL Under IDL 5.1 and Later
TheVAX_FLOAT keyword to CALL_EXTERNAL can beused to maketheIEEEversions
of VMS IDL properly pass oating-point data to external code compiled for the VAX
oating-point format. However, IDL 5.0.x and earlier did not accept this keyword. This
makes it difcult to write a CALL_EXTERNAL statement that can be used under both
versions at the same time.
The VAX_CALL_EXT routine shown below can be used to solve this problem. If you
compileanduseVAX_CALL_EXTit insteadof CALL_EXTERNAL, your programwill be
able to specify the VAX_FLOAT keyword in all cases, and the older IDL versions will
simply ignore the keyword as a side effect of keyword inheritance.
Enter thefollowingIDL codein alenamed call_ext.pro and includeit in your IDL
path. Then use the VAX_CALL_EXT function with the VAX_FLOAT keyword wherever
you would otherwise use CALL_EXTERNAL.
FUNCTION vax_call_ext, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, $
a11, a12, a13, a14, a15, a16, _EXTRA=e
CASE N_PARAMS() OF
2: ans = CALL_EXTERNAL(a1,a2,_EXTRA=e)
3: ans = CALL_EXTERNAL(a1,a2,a3,_EXTRA=e)
4: ans = CALL_EXTERNAL(a1,a2,a3,a4,_EXTRA=e)
5: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,_EXTRA=e)
6: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,_EXTRA=e)
7: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,_EXTRA=e)
8: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,a8,_EXTRA=e)
9: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,a8,a9,_EXTRA=e)
10: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,_EXTRA=e)
11: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,_EXTRA=e)
12: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10, $
a11,a12,_EXTRA=e)
13: ans = CALL_EXTERNAL(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,$
a11,a12,a13,_ex,tra=e)
a11,a12,a13,a14,_EXTRA=e)
a11,a12,a13,a14,a15,_EXTRA=e)
a11,a12,a13,a14,a15,a16,_EXTRA=e)
ENDCASE
RETURN, ans
END
Note You do not need to enter the code for VAX_CALL_EXT.PRO by hand. It is included
in themisc subdirectory of theexamples directory of the IDL distribution.
IDL Reference Guide A Note on the VMS G Float Format
A Note on the VMS G Float Format
In addition to the F and D oating-point formats, VMS systems also support a format
known as G oat, which has fewer mantissa bits than D oat and larger range. On the
VAX, this format was little used, and IDL has never supported it. Under ALPHA/VMS,
however, G oat is the default for DEC language compilers. This makes it very easy to
inadvertently build programsthat produceGoat data. Goat offerslittleadvantage, if
any, over double precision IEEE, while causing compatibility issues similar to those
caused by Fand Doat. For thisreason, Research Systemsrecommendsthat you not use
Goat unlessyouhavespecicrequirementsfor it. Tocompileyour programstoproduce
IEEEformat oatingpoint, specifythe/IEEE_FLOATcommandqualier tothecompiler.
There are several levels of compiler support for IEEE math, controlled by the
/IEEE_MODE qualier. IDL is built with the options
/IEEE_FLOAT/IEEE_MODE=DENORM.
If you need to use G oat data with IDL, you will need to manually convert the data to
and from IEEE format. The DTOGFLOAT and GFLOATTOD keywords to the
BYTEORDER procedure can be used for this task.
A Note on the VMS G Float Format IDL Reference Guide
Index-1
Index
Thisindex iscross-referenced for thethreevolumes
of the main IDL documentation setUsing IDL,
Building IDL Applications, Object Graphics, and the
IDL ReferenceGuide. Page numbers for Using IDL
are followed by a U, page numbers for Building
IDLApplicationsarefollowedbya B, pagenumbers
for ObjectGraphicsarefollowed byan O, and page
numbers for theReferenceGuideare followed by an
R.
Symbols
! character 58R
!C system variable 46R
!D system variable 46R
!D.TABLE_SIZE system variable 47R, 1164R
!D.WINDOW system variable 1199R, 1317R, 1346R
!DIR system variable 42R
!DLM_PATH system variable 42R
!DPI system variable 38R
!DTOR system variable 38R
!EDIT_INPUT system variable 24U, 42R
!ERR system variable 38R, 1114R, 1203R
!ERROR_STATE system variable 143B, 149B, 39R,
745R, 780R, 1082R
MSG 147B, 1082R
MSG_PREFIX 745R
SYS_MSG 147B
!EXCEPT system variable 40R
!HELP_PATH system variable 42R
!JOURNAL system variable 43R, 582R
!MAP system variable 359U, 38R
!MAP1 system variable 723R
!MORE system variable 43R
!MOUSE system variable 40R, 332R
!ORDER system variable 382U, 48R, 1154R, 1162R
!P system variable 49R
!P.FONT system variable 66R
!P.MULTI system variable 306U, 162R
!P.T system variable 107R, 323R, 380R, 984R, 985R,
1095R, 1109R
Index Numerics ... AUsing IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-2 Index
!P.T3D system variable 323R
!PATH system variable 43R, 462R
!PI system variable 38R
!PROMPT system variable 45R
!QUIET system variable 45R, 745R
!RADEG system variable 38R
!VALUESsystem variable 38R
!VERSION system variable 45R
!WARN system variable 41R
!X system variable 52R
!Y system variable 52R
!Z system variable 52R
" character 59R
# of Rows/Columns base property 202U
# operator 272U, 430U, 31B
## operator 273U, 431U, 31B
$ character 31U, 59R
& character 59R
' character 58R
* character 60R
. character 59R
.COMPILE executive command 32R
.CONTINUE executive command 33R
.EDIT executive command 33R
.GO executive command 33R
.OUT executive command 33R
.RETURN executive command 33R
.RUN executive command 34R
.SIZE executive command 1393R
.SKIP executive command 35R
.STEP executive command 35R
.STEPOVER executive command 36R
.TRACE executive command 36R
.Xdefaults le 1211R
: character 59R
; character 59R
< operator 272U, 30B
> operator 272U, 30B
>> button 247U
?character 61R
?command 242U
?: ternary operator 36B
@character 32U, 60R
^ character 271U, 29B
Numerics
24-bit images 1155R
2D rendering of 3D volumes 850R
3D
images
reconstructed from 2D arrays 939R
viewing coordinate system 323R
rendering 740R
transformations 343U, 314R, 350R, 380R, 984R,
985R, 1095R, 1109R, 1186R
volume slices 1027R
3D text 82O
64-bit data type
long 12B
unsigned long 12B
64-bit integer
arrays 593R, 686R
data type, converting to 689R
vectors 686R
A
A keyword 587R, 1098R
A_CORRELATE function 423U, 435U, 468U, 187R
abbreviating keywords 111B
aborting IDL 30U
about IDL 9U, 2B, 14O, 23R
ABOVE keyword 733R
ABSfunction 189R
ABSDEV keyword 598R
absolute deviation 755R
ABSOLUTE keyword 444R
absolute value 189R
accuracy
of oating-point operations 427U
of numerical algorithms 426U
ACMODE keyword 1145R
ACOSfunction 190R
action routines, Motif 74U
active command line 289B, 1365R
ACTIVE keyword 1271R
actual parameters 110B, 111B
Add method 182O, 286O, 354O, 389O, 397O
addition
array elements 1123R
operator 270U, 29B
AddPolygon method 376O
address, RSI postal 16U, 9B, 20O, 29R
ADDSYSVAR, seeObsolete Routines
adjacency list, Delaunay triangulation 1131R
ADJCT,seeObsolete Routines
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index A ... A
Index Index-3
Adobe
Font Metrics les 854R
Type Manager 74R, 136R
ADVANCE keyword 725R
AFTER keyword 229R
AITOFF keyword 724R
Aitoff map projection 365U, 724R
Albers
equal area conic map projection 724R
equal-area conic map projection 372U
ALBERSkeyword 724R
ALIASkeyword 286O
aliasing, sampled data analysis 409U
ALIGN_BOTTOM keyword 1205R
ALIGN_CENTER keyword 1205R, 1222R, 1280R
ALIGN_LEFT keyword 1205R, 1222R, 1280R
ALIGN_RIGHT keyword 1205R, 1222R, 1280R
ALIGN_TOP keyword 1205R
aligning text 1379R
Alignment 203U
Alignment base property 203U
Alignment button property 213U
ALIGNMENT keyword 384O, 671R, 1230R, 1298R,
1379R
Alignment label property 221U
alignment of text objects 82O
Alignment table property 234U
ALL keyword 185O, 187O, 208O, 221O, 232O, 240O,
250O, 257O, 263O, 272O, 280O, 290O, 292O,
297O, 304O, 311O, 318O, 326O, 336O, 346O,
356O, 357O, 362O, 371O, 383O, 391O, 394O,
399O, 401O, 405O, 418O, 429O, 273R, 982R
ALL_EVENTSkeyword 368R, 1298R
ALL_KEYSkeyword 537R
ALL_TABLE_EVENTSkeyword 1230R
ALL_TEXT_EVENTSkeyword 1231R, 1309R
ALL_VALUE keyword 246R
ALLOCATE_HEAP keyword 857R, 860R
allocated memory, returning amount of 539R
Allow Closing base property 203U
Allow Moving base property 204U
ALOG function 191R
ALOG10 function 192R
alpha blending 126O
alpha blending (image objects) 115O
alpha channel 114O
ALPHA keyword 529R, 677R
Altura Software 250U
AM_PM keyword 209O
AMBIENT keyword 407O
AMOEBA function 463U, 193R
ampersand 59R
analytic signal 411U
AND operator 274U, 32B
Angstrom symbol 68R
animation 343U
compound widget 275B
ickering images 485R
MPEG les 757R, 758R, 760R, 762R
widget interface 341R, 1357R
ANISOTROPY keyword 251O
ANNOTATE procedure 196R
annotations
help topics 244U
of displayed images 196R
on plots 293U
text objects 81O
anonymous structures 262U, 42B
ANOVA, seeObsolete Routines
ANOVA_UNEQUAL, seeObsolete Routines
ANSI keyword 1001R
apostrophe 58R
APP_KEYPAD keyword 1001R
APP_MBAR keyword 1206R
APP_SCROLL keyword 1252R
APPEND keyword 784R, 1232R, 1337R
AppleScript 438R
applications, written in IDL 2B
approximating models, statistical 282R
arc-cosine 190R
architecture, current version in use 45R
arc-sine 203R
arc-tangent 206R
ARG_PRESENT function 124B, 198R
arguments
checking existence of 198R
described 184R
arguments, described 180O
arithmetic errors 151B
ARRAY keyword 463R, 918R
array operators
CHOLDC 267R
CHOLSOL 268R
COND 290R
CRAMER 319R
DETERM 417R
EIGENVEC 446R
ELMHES 448R
Index A ... A Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-4 Index
GS_ITER 525R
HQR 551R
INVERT 576R
LU_COMPLEX 694R
LUDC 696R
LUMPROVE 697R
LUSOL 699R
NORM 769R
SVDC 1096R
SVSOL 1102R
TRIQL 1140R
TRIRED 1142R
TRISOL 1143R
arrays
and matrices 429U
changing dimensions of 945R
concatenation 273U, 31B
creating
64-bit integer
(L64INDGEN function) 593R
(LON64ARR function) 686R
any type (MAKE_ARRAY function) 705R
byte
(BINDGEN function) 220R
(BYTARR function) 233R
complex
(CINDGEN function) 270R
(COMPLEXARR function) 287R
(DCINDGEN function) 395R
(DCOMPLEXARR function) 398R
double-precision
(DBLARR function) 394R
(DCINDGEN function) 395R
(DCOMPLEXARR function) 398R
(DINDGEN function) 435R
integer
(INDGEN function) 561R
(INTARR function) 570R
longword
(LINDGEN function) 603R
(LONARR function) 687R
single-precision, oating-point
(FINDGEN function) 482R
(FLTARR function) 490R
string
(SINDGEN function) 1020R
(STRARR function) 1073R
unsigned 64-bit
(ULON64ARR function) 1171R
unsigned 64-bit integer
(UL64INDGEN function) 1169R
unsigned integer
(UINDGEN function) 1166R
unsigned longword
(ULINDGEN function) 1170R
(ULONARR function) 1172R
denition 260U
efcient accessing 206B
extracting sub-arrays 467R
lling with a scalar value 949R
nding number of elements in 764R
oating-point 482R
incrementing elements 548R
interactive editing tool (XVAREDIT
procedure) 1378R
memory allocation under VMS 23U
multiplying 430U
of structures 49B, 949R
operators, seearray operators
resizing 291R, 461R, 935R
returning
maximum value 731R
minimum value 747R
subscripts of non-zero elements 1203R
type 1022R
reversing indices 960R
rotating 972R
searching for objects 986R, 989R
shifting elements 1013R
size 1022R
sorting 1046R
sparse 464U
stored in structure form 464U
subscripts
denition 261U
ranges 64B
returning non-zero elements 1203R
summing elements 1123R
symmetric 430U
transposing 1126R
unique elements of (UNIQ function) 1175R
updating 223R
ARROW procedure 200R
ARROW_ANGLE keyword 640R
ARROW_END keyword 640R
ARROW_SIZE keyword 640R
ARROW_START keyword 640R
ARROWSIZE keyword 488R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index B ... B
Index Index-5
AS_STRING keyword 438R
ASCENDING keyword 444R
ASCII keyword 1331R
ASCII_TEMPLATE function 202R
ASIN function 203R
ASPECT keyword 559R, 806R
assignment 258B
operator 270U, 28B
pointers 236B
statement 85B
ASSOC function 157B, 160B, 204R
associated I/O 202B
associated variables 204R
asterisk 60R
at sign (character) 60R
ATAN function 206R
ATOL keyword 692R
atomic graphic objects 28O, 37O
ATTENUATION keyword 281O
Attribute objects 30O, 38O
attribute objects 64O
attributes
draw widget 229U
droplist 224U
label widget 221U
listbox 226U
slider 222U
table widget 234U
autocorrelation 187R
autocovariance 187R
automatic compilation 29U, 100B
automatic structure denition 54B, 252B
autoregressive moving average lters 414U
autoregressive time-series forecasting 1147R, 1149R
AVANTGARDE keyword 116R
average
mean 755R
median 738R
moving 1043R, 1151R
AVERAGE_LINESkeyword 116R
AX keyword 323R, 380R, 984R, 1005R, 1008R, 1091R,
1095R
axes 310U, 74O, 205O, 106R
date labels for 594R
direction 209O
end points 56R
gridstyles 210O, 53R
linear 56R
location 210O
logarithmic 305U, 211O, 56R
[XYZ]LOG keywords 208R, 307R, 801R,
1006R, 1093R
margins 53R
range 290U, 52R, 54R
range (CRANGE, EXACT, EXTEND,
RANGE) 208O
scaling 288U, 54R
style 54R
system variables for 52R
thickness 212O, 55R
thickness, (XYZ)THICK keyword 107R
titles 213O, 56R, 109R
AXISkeyword 442O, 443O
axis object 29O, 205O
axis objects 74O
creating 74O
range values 74O
tick labels 80O
titles 80O
using 74O
AXISprocedure 310U, 207R
AY keyword 323R
AZ keyword 323R, 380R, 984R, 1005R, 1008R, 1091R,
1095R
azimuthal equidistant map projection 365U, 724R
AZIMUTHAL keyword 724R
azimuthal map projections 362U
B
B_LENGTH keyword 225R
B_VALUE keyword 246R
"Back" button 247U
BACK_CHARACTER keyword 402R
BACK_WORD keyword 402R
BACKCAST keyword 1149R
back-face 149O
back-face culling 149O
background color 148R
for graphics windows 451R
BACKGROUND keyword 100R, 210R, 1193R, 1363R
BACKGROUND system variable eld 49R
background tasks 1247R
for widgets 302B
backing store 132R, 144R, 1318R
for draw widgets 351R, 1256R, 1260R
for zoom widgets 391R
IDLDE for Macintosh 130U
Index B ... B Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-6 Index
IDLDE for Motif 62U
IDLDE for Windows 106U
BACKPROJECT keyword 964R
backprojection 963R
back-substitution 1102R
backward index list (for histograms) 546R
BACKWARD keyword 1151R
BAD_ID keyword 1232R, 1268R
bandpass lters 414U
bandstop lters 414U
bar charts 299U, 210R
BAR_PLOT procedure 210R
BARNAMESkeyword 210R
BAROFFSET keyword 210R
BARSPACE keyword 210R
BARWIDTH keyword 210R
base 10 logarithm 192R
base widgets 273B, 1205R
attributes 202U
bulletin board bases 306B, 1218R
changing title of 1248R
column 1207R
column bases 1207R
events 210U
events returned by 1221R
exclusive 1208R
exclusive and non-exclusive 1218R
keyboard focus events 1209R
mapping and unmapping 1240R
nonexclusive 1211R
positioning 1247R
top-level bases 1219R
resize events 1216R
row bases 1213R
top-level 1205R
using 165U
base, setting attributes 202U
base, setting events 210U
BASE_ALIGN_BOTTOM keyword 1206R
BASE_ALIGN_CENTER keyword 1206R
BASE_ALIGN_LEFT keyword 1206R
BASE_ALIGN_RIGHT keyword 1206R
BASE_ALIGN_TOP keyword 1206R
BASE_STYLE keyword 659R
BASELINE keyword 384O
BASELINESkeyword 211R
BASERANGE keyword 211R
batch
mode 32U
processing 60R
batch les 32U
using as startup le 33U
IDLDE for Motif 64U
BEGIN statement 90B
Bell, ringing the terminal 18B
BELOW keyword 733R
benchmarks 1120R
Bernoulli distribution 221R
BESELI function 213R
BESELJ function 214R
BESELY function 215R
Bessel functions
BESELI 213R
BESELJ 214R
BESELY 215R
BETA function 216R
incomplete 554R
BETAI, seeObsolete Routines
big endian byte ordering 235R, 1104R
bi-level images 1118R
bilinear (Tustin) transform 420U
BILINEAR function 445U, 217R
bilinear interpolation 445U, 217R, 935R
BILINEAR keyword 716R, 964R
BIN keyword 1342R
BIN_DATE function 219R
binary interpolation 573R
BINARY keyword 116R, 787R
binary SAVE and RESTORE 982R
binary trees 248B
BINDGEN function 220R
binomial distribution 221R
BINOMIAL function 221R
BINOMIAL keyword 887R, 891R
binomial random deviates 887R, 891R
bins, histogram 546R
BINSIZE keyword 544R, 546R
bit shift operation 581R
bitmap
button labels 1226R, 1228R, 1352R
byte array 340R
les
reading (READ_BMP) 901R
standard le format I/O routines 228B
writing (WRITE_BMP) 1320R
labels, creating 340R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index B ... B
Index Index-7
Bitmap button property 213U
Bitmap Editor 174U
opening 213U
tools 175U
BITMAP keyword 1222R
bitmaps
adding to buttons 174U
BITS_PER_PIXEL keyword 116R
BKMAN keyword 116R
BLAS_AXPY procedure 223R
BLEND_FUNCTION keyword 264O
BLK_CON function 423U, 225R
blob coloring 596R
BLOB keyword 488R
block convolution 225R
BLOCK eld 192O
BLOCK keyword 191O, 199O, 443R, 788R, 1040R,
1082R, 1352R, 1354R, 1361R, 1369R, 1370R,
1371R, 1377R
blocks 90B
BLUE keyword 625R
BLUE_VALUESkeyword 242O, 305O
BMP les
adding to button widgets 174U
displaying on buttons 213U
reading (READ_BMP) 901R
supplied 174U
writing (WRITE_BMP) 1320R
BOLD keyword 117R
BOOK keyword 117R, 781R
Bookman font 116R
bookmark menu (online help) 244U
Boolean operators 274U, 32B
BORDER_GAP keyword 273O
BOTTOM keyword 328O, 363O, 685R, 1091R, 1361R
bottom margin, setting 53R
BOTTOM_STRETCH keyword 304O, 306O
boundaries, specifying for maps 360U
BOUNDSkeyword 407O, 588R, 1052R, 1129R
BOUT keyword 1052R
box charts 299U
BOX_CURSOR procedure 227R
boxcar average 1043R
boxcar lter 417U
BREAKPOINT procedure 229R
breakpoints
debugging with 140U
removing 229R
returning information on 537R
setting 230R
BREAKPOINTSkeyword 537R
BRIGHT keyword 329R
Bristol Technology 28U, 250U
browse << buttons (online help) 247U
BROWSE_LINESkeyword 202R
BROYDEN function 462U, 231R
Broydens method 462U, 231R
bubble sort 245B
BUFFER keyword 612R, 625R, 649R, 665R, 907R
Buffer object 32O
buffer object 216O
buffer objects 138O
creating 139O
buffered output 449R, 491R
buffers 491R
ushing 459R
type-ahead 514R
BUFSIZE keyword 784R
bugs
debugging in IDL 138U
reporting math 426U
reporting problems 13U, 5B
bulletin board bases 306B, 1218R
button
bar(online help system) 247U
groups 354R
labels, creating 340R
mouse with CURSOR procedure 332R
widgets 273B, 1222R
bitmap labels 1226R, 1228R, 1352R
button release events 1224R
groups 354R
setting pointer focus 1238R
toggle 1227R
button widgets
adding menus to 173U
setting attributes 213U
setting properties 212U
using 165U
BUTTON_EVENTSkeyword 1253R
BUTTON_UVALUE keyword 354R
BY_VALUE keyword 579R
BYPASS_TRANSLATION keyword 117R
BYTARR function 233R
byte
arguments and strings 75B
Index C ... C Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-8 Index
arrays 220R, 233R
data type 12B
scaling values into a range of bytes 238R
swapping 235R
swapping short integers 236R
type, converting to 234R
BYTE function 76B, 234R
BYTE keyword 561R, 705R
BYTEORDER procedure 235R
BYTSCL function 384U, 238R
C
C_ANNOTATION keyword 320U, 328U, 301R
C_CHARSIZE keyword 320U, 328U, 301R
C_CHARTHICK keyword 301R
C_COLOR keyword 251O
C_COLORSkeyword 301R
C_CORRELATE function 423U, 435U, 469U, 240R
C_EDIT, seeObsolete Routines
C_FILL_PATTERN keyword 252O
C_LABELSkeyword 320U, 328U, 302R
C_LINESTYLE keyword 252O, 302R
C_ORIENTATION keyword 302R
C_SPACING keyword 302R
C_THICK keyword 252O, 302R
C_VALUE keyword 252O
C0 keyword 587R
C1 keyword 587R
CALDAT procedure 242R
CALENDAR procedure 244R
CALL_EXTERNAL 1404, 1406
CALL_EXTERNAL function 245R
CALL_FUNCTION function 129B, 252R
CALL_PROCEDURE procedure 129B, 253R, 254R
CALL_VMS, seeObsolete Routines
calling
external modules from IDL 245R
IDL functions from a string 252R
IDL methods from a string 253R
IDL procedures from a string 254R
mechanism for procedures 121B
routines written in other languages 245R, 606R
sequence 184R
calling sequence
function methods 180O
procedure methods 180O
CALLSkeyword 148B, 537R
"Cancel" button 1232R
CANCEL keyword 143B, 202R, 255R, 424R, 530R
CANCEL_BUTTON keyword 1232R
caret 271U, 29B
carrot 271U, 29B
case folding 76B
CASE statement 92B
CAST keyword 776R, 858R
CATCH keyword 1363R
CATCH procedure 143B, 255R
catch, C++ language 255R
ccolors
Motif colormapsseecolormaps
CD procedure 257R
CDECL keyword 246R
CDF les 1387R
CEIL function 259R
cell drawing (contour method) 319U
CELL_FILL keyword 303R
CENTER keyword 312R, 964R
CENTIMETERSkeyword 1154R, 1157R
central map projection 363U, 724R
CENTRAL_AZIMUTH keyword 729R
CGM driver 148R
CHANGE keyword 333R
change value event 223U
changing directories 257R
changing widget values 301B
changing working directory, Macintosh 135U
CHANNEL keyword 265O, 100R, 451R, 1154R, 1162R
CHANNEL system variable eld 49R
channels (in image objects) 114O
CHAR_DIMENSIONSkeyword 384O
characters
character sets 79R
non-printable 18B
plotting in graphics windows 1379R
size 1380R
special 26U
CHARSIZE keyword 100R, 711R, 725R, 1380R
CHARSIZE system variable eld 49R, 52R
CHARTHICK keyword 101R, 1380R
CHARTHICK system variable eld 49R
CHEBYSHEV function 260R
CHECK keyword 232R, 417R, 767R
CHECK_MATH function 428U, 151B, 261R
checkbox widgets
creating 212U
laying out 213U
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index C ... C
Index Index-9
checkboxes 212U
using 165U
CHI_SQR, seeObsolete Routines
CHI_SQR1, seeObsolete Routines
CHILD keyword 1271R
children, of widgets 1271R
CHISQ keyword 678R, 1098R
CHISQR keyword 604R
CHISQR_CVF function 265R
CHISQR_PDF function 266R
Chi-square distribution 265R, 266R
Chi-square error statistic, minimizing 604R
Chi-square goodness-of-t test 330R, 1375R
CHOLDC procedure 459U, 267R
Cholesky decomposition 267R, 268R
CHOLSOL function 460U, 268R
chromacoded editor, Windows 112U
CINDGEN function 270R
CIR_3PNT procedure 271R
class 188O
object 250B
structure 251B
structures
zeroed 252B
CLEANUP keyword 1364R
Cleanup method 183O, 189O, 206O, 217O, 229O,
238O, 248O, 256O, 261O, 270O, 278O, 286O,
296O, 302O, 310O, 316O, 324O, 334O, 343O,
354O, 360O, 370O, 377O, 381O, 389O, 397O,
402O, 425O
CLEAR keyword 229R, 846R
CLEAR_EVENTSkeyword 1232R
clearing breakpoints 229R
CLIENTSERVER keyword 680R
CLIP keyword 101R, 725R
CLIP system variable eld 49R
Clipboard object 32O
clipboard object 228O
clipboard objects
creating 139O
clipboard support, graphics windows
Macintosh 120U
Windows 88U
clipping planes 47O
clipping window 49R
clock, system 1105R
CLOSE keyword 117R, 904R, 1322R, 1359R
CLOSE procedure 273R
CLOSE_DOCUMENT keyword 117R
CLOSE_FILE keyword 117R
CLOSED keyword 303R
closing
(image processing) function 433R
contours 303R
les 161B
open le units 273R
graphics output les 117R
CLUST_WTSfunction 476U, 274R
cluster
analysis 274R, 275R
weights 274R
CLUSTER function 476U, 275R
CMY color system 387R
CMY keyword 387R
coastlines 708R
COASTSkeyword 708R
code
IDL GUIBuilder generated 159U
modifying generated 159U
CODE keyword 1082R
COEFF keyword 330R
COEFFICIENTSkeyword 796R
COLD keyword 1201R
COLMAJOR keyword 918R
colon (character) 59R
color 58O
and destination objects 59O
and digital data 58O
indexed 58O
palette objects 60O
RGB 59O
specifying color values 60O
COLOR eld 192O
COLOR keyword 285U, 209O, 218O, 242O, 252O,
282O, 319O, 328O, 338O, 357O, 363O, 373O,
385O, 392O, 426O, 101R, 118R, 200R, 451R, 640R,
656R, 671R, 708R, 711R, 726R, 760R, 908R, 1177R,
1184R, 1201R
color mapping
voxel values 125O
Color Model
draw area property 229U
color model
for windows 135O
printers 140O
color models 58O
COLOR system variable eld 49R
Index-10 Index
color tables 386U
colors1.tbl le 685R, 754R
common block 391U
creating and modifying with XPALETTE 1371R
example 161U
for LJ device 674R
gamma correction 505R
histogram equalization 528R
histogram equalizing 527R
HLS(Hue, Lightness, Saturation) 550R
HSV (Hue, Saturation, Value) 553R
LHB (Lightness, Hue, Brightness) 855R
loading 388U, 1159R
loading into variables(GET keyword) 1160R
loading predened 685R, 1361R
maximum indices for draw widgets 1253R
modifying predened colortable les 754R
obtaining 391U
predened 389U
setting maximum number of indices 1317R
stretching 1075R
switching between devices 392U
Tektronix 4115 1116R
wrapping (MULTI procedure) 763R
COLOR_CONVERT procedure 277R
COLOR_EDIT, seeObsolete Routines
COLOR_INDEX keyword 387R
COLOR_INDICESkeyword 196R
COLOR_MODEL keyword 223O, 234O, 348O, 420O,
432O, 1253R
COLOR_QUAN function 279R
COLOR_VALUESkeyword 358R
colorbar object 30O, 238O
Colorbar objects 116O
COLORBAR_PROPERTIESkeyword 660R
colormaps (Motif IDLDE) 67U
colors
background 49R, 100R, 148R, 451R
converting between color systems 277R
default index 49R
gamma correction (GAMMA_CT) 505R
indices 393U, 121R, 358R, 360R, 387R
luminance of (CT_LUMINANCE function) 329R
manipulation compound widgets 275B
maximum number available 1164R
maximum number for draw widgets 1253R
palette
Macintosh 130U
Windows 114U
pixel depth, Macintosh 130U
quantization 279R
reducing number in an image 944R
reserving for IDL 67U
resources,for widgets 1213R
setting maximum number of indices 1317R
shared colormap 138R
systems 386U, 387R, 1159R
tables, Seecolor tables
COLORScommon block 391U
Colors draw area property 229U
COLORSkeyword 118R, 211R, 280R, 351R, 1253R,
1317R
column bases 1207R
COLUMN keyword 306B, 354R, 368R, 374R, 448R,
551R, 696R, 697R, 699R, 1064R, 1096R, 1102R,
1207R, 1348R
Column Labels table property 234U
COLUMN_LABELSkeyword 1232R, 1299R
COLUMN_MAJOR keyword 1299R
COLUMN_WIDTHSkeyword 1232R, 1271R, 1299R
column-major format 429U
COLUMNSkeyword 273O
combination 473R
combining 51O
combining contour and surface plots 344U
combining transformations 51O
COMFIT function 437U, 282R
COMM keyword 982R
command input buffer, displaying 539R
Command Input Line
anchoring 129U
IDLDE for Motif 41U
command line options, Motif 68U, 74U
command recall 24U
buffer 938R
command stream substitutions, Motif 74U
command-line switches 20U
commands
displaying previously-executed 539R
executive 31R, 46R
.COMPILE 32R
.CONTINUE 33R
.EDIT 33R
.GO 33R
.OUT 33R
.RETURN 33R
Index Index-11
.RUN 34R
.SIZE 1393R
.SKIP 35R
.STEP 35R
.STEPOVER 36R
.TRACE 36R
COMMENT_SYMBOL keyword 898R
comments 85B
common blocks 93B
widgets and 312B
common methods 27O
COMPILE executive command Seecommands
compiling les
IDLDE for Motif 48U
compiling functions and procedures 29U, 952R, 954R
displaying 540R
Macintosh 135U
complex
arrays, creating 270R, 287R, 395R, 398R
arrays, rounding 288R
conjugate 293R
data type 285R, 396R
numbers 258U, 17B
returning imaginary part of 560R
returning real part of 486R
returning the magnitude of 189R
polynomials 502R
complex data type 13B
COMPLEX function 285R
COMPLEX keyword 561R, 705R
COMPLEXARR function 287R
COMPLEXROUND function 288R
Component Sizing common property 197U
Composite classes
Object Graphics 144O
composite classes 144O
COMPOSITE_FUNCTION keyword 407O
compositing 126O
compound widgets 275B, 314B
animation 275B
color manipulation 275B
CW_ANIMATE 341R
CW_ARCBALL 350R
CW_BGROUP 354R
CW_CLR_INDEX 358R
CW_COLORSEL 360R
CW_DEFROI 362R
CW_DICE 366R
CW_FIELD 368R
CW_FORM 371R
CW_FSLIDER 377R
CW_ORIENT 380R
CW_PDMENU 382R
CW_RGBSLIDER 387R
CW_ZOOM 390R
data entry 276B
example 188U
handling events 199U
image manipulation 276B
in IDL GUIBuilder code 188U
orientation 276B
user interface 276B
writing 316B
COMPRESSkeyword 716R
COMPRESSION keyword 1337R
compression, JPEG 907R, 1324R
COMPUTE_MESH_NORMALSfunction 289R
ComputeBounds method 403O
Computed Tomography 963R
ComputeDimensions method 239O, 270O
Computer Graphics Metale 148R
computing inner products 430U
CON_COLOR keyword 726R
concatenation
array 273U, 31B
string 74B
concave polygons 71O, 375O
CONCEALED keyword 998R
COND function 460U, 290R
CONDITION keyword 230R
condition number 454U, 460U, 290R
conditional expression 36B
CONEANGLE keyword 282O
CONFINE keyword 998R
conformal conic map proejction 371U
CONGRID function 291R, 935R
CONGRID keyword 1040R
CONIC keyword 724R
CONJ function 293R
conjugate, complex 293R
CONNECTIVITY keyword 1132R
constants
complex 258U, 17B
decimal 14B
double-precision 258U, 16B
oating-point 258U, 16B
Index-12 Index
hexidecimal 14B
integer 257U, 14B
ivalues 257U, 15B
octal 14B
string 258U, 259U, 17B
CONSTRAIN keyword 442O, 443O
CONSTRAINED_MIN procedure 463U, 294R
container object 182O
"Contents" button (online help system) 247U
contents tab (online help system) 248U
context 30U, 142B
CONTEXT keyword 781R
context number 781R
CONTINENT keyword 359U, 363U, 726R
continental boundaries 708R
continents, drawing 360U
contingency table 330R
CONTINGENT, seeObsolete Routines
CONTINUE executive command Seecommands
CONTINUE keyword 745R, 809R
CONTINUE_ON_ERROR keyword 952R
CONTINUOUSkeyword 1382R
contour object 29O, 247O
contour objects 86O
creating 86O
contour plots 318U, 300R
closing contours 303R
lled (FILL keyword) 303R
lling 330U
indicating direction of grade 331U
labeling 328U
overlaying with images 324U, 559R
polar 815R
smoothing 329U
with images and surface plots 1015R
CONTOUR procedure 318U, 343U, 300R
contrast, gamma correction 505R
control characters
alt-F4 61R
command-period 61R
command-q 61R
control-\ 61R
control-break 61R
control-C 61R
control-D 61R
control-Y 61R
control-Z 61R
CONTROL keyword 402R
Control Panel, IDLDE for Motif 41U
modifying 72U
controlling the device cursor 395U
controlsseewidgets 272B
convergence criterion 768R
CONVERGENCE keyword 678R, 1201R
CONVERT_COORD function 287U, 339U, 309R
converting
colors between color systems 277R
coordinate systems 309R
converting expressions
between host and network byte ordering 235R
to 64-bit integer type 689R
to byte type 234R
to complex type 285R, 396R
to double-precision type 442R
to integer type 484R
to longword type 688R
to single-precision oating-point type 486R
to string type 1077R
to unsigned 64-bit integer type 1174R
to unsigned integer type 1167R
to unsigned longword type 1173R
convex polygons 71O, 375O
CONVOL function 423U, 311R
convolution 225R, 311R
Cooley-Tukey algorithm 411U
COORD2TO3 function 314R
coordinate conversion 51O
coordinate systems and scaling 42O
coordinate transformations 51O
coordinates
3D transformations 314R, 350R, 380R, 984R,
985R, 1095R, 1109R, 1186R
clipping 101R
converting 287U, 339U
2D to 3D 314R
between coordinate systems 338R
map coordinates 723R
systems 309R
data 285U
dening 3D systems 323R
device 286U, 102R
normal 286U, 104R
COPY keyword 118R, 992R
copying help topics 243U
copying pixels from one window to another 118R
COR keyword 964R
CORRECTED keyword 330R
correction, gamma 505R
Index Index-13
CORREL_MATRIX, seeObsolete Routines
CORRELATE function 435U, 476U, 315R
correlation analysis 431U
correlation/covariance matrix 315R
Kendalls tau rank 882R
lagged autocorrelation 187R
lagged crosscorrelation 240R
multiple 701R
partial 795R
Pearsons correlation 315R
Spearmans rho rank 882R
correlation coefcient 431U
CORRELATE 315R
Kendallss 882R
M_CORRELATE 701R
multiple 701R
P_CORRELATE 795R
partial 795R
Pearson 315R
R_CORRELATE 882R
rank 882R
Spearmans 882R
COSfunction 317R
COSH function 318R
cosine 317R
hyperbolic 318R
inverse 190R
COSINES, seeObsolete Routines
count accumulation 548R
COUNT keyword 185O, 192O, 463R, 480R, 771R,
776R, 858R, 898R, 1048R
Count method 184O
COUNTRIESkeyword 708R
country boundaries 708R
COURIER keyword 118R
COVAR keyword 678R, 1098R
COVARIANCE keyword 187R, 241R, 315R, 796R
CRAMER function 460U, 319R
Cramers rule 319R
CRAMV keyword 330R
CRANGE keyword 208O
CRANGE system variable eld 52R
CREATE_INSTANCE keyword 218O, 426O
CREATE_STRUCT function 321R
CREATE_VIEW procedure 323R
creating
heap variables 231B
realizing widgets 1241R
system variables 409R
windows 1317R
creating multiple 212U
CREATOR_TYPE keyword 301O
cross correlation 240R
cross covariance 240R
CROSSP function 326R
CRVLENGTH function 438U, 452U, 327R
CT_LUMINANCE function 329R
CTI_TEST function 448U, 476U, 330R
CUBE keyword 280R
cubic convolution interpolation 573R, 821R
CUBIC keyword 291R, 573R, 821R, 964R, 970R
cubic spline interpolation 445U, 1054R, 1056R
parametric 446U
Culling 149O
current IDL session, returning information on 537R
CURRENT keyword 257R, 505R
current working directory 257R
cursor
box 227R
changing appearance 119R
controlling position 395U
displaying 1157R
graphics on Tektronix terminals 126R
hiding 1157R
hourglass 301B, 1238R
positioning 1157R
reading position of 313U, 894R
returning events from draw widgets 1255R
setting to crosshair 118R
specifying pattern 119R
type 118R
CURSOR procedure 313U, 332R
and Tektronix terminals 126R
CURSOR_CROSSHAIR keyword 118R
CURSOR_IMAGE keyword 119R
CURSOR_STANDARD keyword 119R
CURSOR_XY keyword 120R
curve tting 282R
and surface tting 436U
COMFIT 282R
CRVLENGTH 327R
CURVEFIT 335R
GAUSS2DFIT 508R
GAUSSFIT 511R
LADFIT 598R
LINFIT 604R
LMFIT 677R
MIN_CURVE_SURF 748R
Index D ... D Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-14 Index
POLY_FIT 824R
POLYFITW 831R
REGRESS 947R
SFIT 1002R
SVDFIT 1098R
CURVEFIT function 436U, 437U, 335R
customizing
IDLDE for Motif 57U
cutoff value
Chi-square distribution 265R
F distribution 471R
Gaussian distribution 506R
T distribution 1107R
CUTTING_PLANE keyword 1193R
CUTTING_PLANESkeyword 408O
CV_COORD function 338R
CVTTOBM function 340R
CW_ANIMATE function 341R
CW_ANIMATE_GETP procedure 345R
CW_ANIMATE_LOAD procedure 346R
CW_ANIMATE_RUN procedure 348R
CW_ARCBALL function 350R
CW_BGROUP function 354R
CW_BSELECTOR, seeObsolete Routines
CW_CLR_INDEX function 358R
CW_COLORSEL function 360R
CW_DEFROI function 362R
CW_DICE function 316B, 366R
CW_FIELD function 368R
CW_FORM function 371R
CW_FSLIDER function 377R
CW_LOADSTATE, seeObsolete Routines
CW_ORIENT function 380R
CW_PDMENU function 298B, 382R, 1224R
CW_RGBSLIDER function 387R
CW_SAVESTATE, seeObsolete Routines
CW_TMPL procedure 389R
CW_ZOOM function 390R
CYCLE keyword 346R, 1358R
cyclical uctuation 467U
cylindrical coordinates 338R
cylindrical equidistant map projection 371U, 724R
CYLINDRICAL keyword 724R
cylindrical map projections 368U
D
D keyword 882R, 965R
D_VALUE keyword 246R
dangling references 239B, 255B
DARK keyword 329R
data coordinates 285U
converting to other types 309R
data entry
compound widgets 276B
eld widget 368R
DATAkeyword 265O, 318O, 328O, 338O, 362O, 373O,
101R, 200R, 309R, 333R, 833R, 1201R
data picking 130O, 132O
example 132O
data types
64-bit
long 12B
unsigned long 12B
byte 12B
complex 13B
double-precision complex 13B
double-precision oating-point 13B
oating-point 13B
integer 12B
long integer 12B
string 13B
unsigned
integer 12B
long 12B
data, tabulated 444U
DATA_NAMESkeyword 1027R
DATA_START keyword 899R
DATA_VALUESkeyword 252O
DATA0 keyword 408O
DATA1 keyword 408O
DATA2 keyword 408O
DATA3 keyword 408O
DATANAME keyword 1342R
DATAX keyword 319O, 364O
DATAY keyword 319O
date
converting calendar to Julian 583R
converting from string to binary 219R
converting Julian to calendar 242R
displaying calendars 244R
labeling axes with 594R
returning current 1105R
DATE_FORMAT keyword 594R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index D ... D
Index Index-15
Daubechies wavelet lter 1348R
Davidon-Fletcher-Powell minimization 463U, 420R
day, returning current 1105R
DAYS_OF_WEEK keyword 209O
DBLARR function 394R
DCINDGEN function 395R
DCL interpreter symbols
dening 996R
deleting 411R
DCOMPLEX function 396R
DCOMPLEX keyword 561R, 705R
DCOMPLEXARR function 398R
DDE routines, seeObsolete Routines
deallocated memory, returning amount of 539R
debugging 27U, 138U, 31R, 229R
IDLDE for Motif 48U
Macintosh 119U
PROFILER prcedure 846R
decimal 14B
DECOMPOSED keyword 120R
decomposition
Cholesky 267R, 268R
LU 696R, 699R
singular value 1096R, 1103R
DECREASE keyword 987R, 990R
default button 1233R
default font 64O, 84O, 385O
DEFAULT keyword 246R, 788R
default visual class 172R
DEFAULT_BUTTON keyword 1233R
DEFAULT_CANCEL keyword 424R
DEFAULT_FONT keyword 1233R
DEFAULT_NO keyword 424R
DEFINE_KEY procedure 399R
dening
command or help path 462R
keys 399R
region of interest 407R
dening method routines 261B
note for Windows 3.11 users 263B
DEFROI function 407R
DEFSYSV procedure 409R
DEGREESkeyword 338R, 675R, 742R, 1132R, 1135R
Delaunay triangulation 1131R
DELAY keyword 436R
DELAY_DESTROY keyword 1233R
DELETE keyword 784R
DELETE_CHARACTER keyword 403R
DELETE_COLUMNSkeyword 1233R
DELETE_CURRENT keyword 403R
DELETE_EOL keyword 403R
DELETE_LINE keyword 403R
DELETE_ROWSkeyword 1234R
DELETE_SYMBOL procedure 411R
DELETE_WORD keyword 403R
deleting
DCL interpreter symbols 411R
variables 413R
windows 1199R
DELIMITER keyword 383R, 899R
delimiters, string 258U, 17B
DELLOG procedure 412R
DELVAR procedure 413R
DEMI keyword 121R
DEMO keyword 680R
DEMO_MODE function 414R
density function 546R
DEPTH_CUE keyword 392O, 408O
DEPTH_Q keyword 850R
dereference operator, pointers 236B
DERIV function 415R
derived variables 472U
DERIVSIG function 416R
DESCENT keyword 222O, 233O, 347O, 419O, 430O
de-sensitizing widgets 1242R
destination device 134O
DESTINATION keyword 207O, 249O, 262O, 279O,
289O, 317O, 325O, 335O, 361O, 382O, 404O
Destination objects 31O
destination objects 134O
and color 59O
drawing to 134O
DESTROY keyword 300B, 1234R
destroying
widgets 300B, 1234R
windows 1199R
destroying objects 257B
DETACH keyword 1027R
DETERM function 460U, 417R
determinant of a square matrix 417R
deviation, mean absolute 736R
device
backing store 144R
CGM 148R
coordinates 286U
Index D ... D Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-16 Index
cursor, controlling 395U
display channels 49R
ags 46R
font 124R
for graphics output 111R
graphics
independent 268B
output 111R
height 143R
HP-GL 150R
independent graphics 268B
LJ 151R
Macintosh (MAC) 154R
Microsoft Windows (WIN) 170R
monochrome 145R
name of 46R
Null 154R
number of color table indices 47R
number of colors 46R
offset 142R
PCL 154R
PostScript 156R
Printer 156R
Regis terminals 168R
resolution of 48R
size of display 48R
Tektronix 169R
width 142R
X Windows 171R
Z-buffer 178R
Device fonts 66R
device independent graphics 23O
DEVICEkeyword 102R, 309R, 333R, 538R, 607R, 608R,
1201R
DEVICE procedure 111R, 419R
DF keyword 330R, 592R
DF24 keyword 533R
DFPMIN procedure 463U, 420R
DFR8 keyword 533R
DIAGONAL keyword 987R, 990R
DIALOGkeyword 619R, 623R, 641R, 655R, 656R, 671R
DIALOG_MESSAGE function 423R
DIALOG_PARENT keyword 424R, 426R, 429R, 430R
DIALOG_PICKFILE function 426R
DIALOG_PRINTERSETUP function 277B, 430R
DIALOG_PRINTJOB 140O
DIALOG_PRINTJOB function 277B, 429R
DIALOG_PRINTSETUP 140O
dialogs
le selection 277B
message 277B
message dialog box 423R
modal 423R
printing 277B
dialogs for printing 140O
dice widget 366R
dicer 354U, 1027R
DICOM 151O
DIFFEQ_23, seeObsolete Routines
DIFFEQ_45, seeObsolete Routines
differences among platforms
Macintosh 134U
Windows 112U
differentiation,CONVOL function 311R
digital dissolve effect 436R
digital lters 414U
Digital Imaging Communications in Medicine 151O
digital signal processing 398U
DIGITAL_FILTER function 414U, 423U, 431R
DILATE function 432R
dilation operator 432R
DIMENSION keyword 705R
DIMENSIONSkeyword 223O, 226O, 234O, 242O,
265O, 298O, 346O, 393O, 420O, 432O, 437O,
613R, 623R, 626R, 641R, 649R, 656R, 666R, 1023R
DINDGEN function 435R
Direct Graphics 268B, 23O
clipboard support
Macintosh 120U
Windows 88U
font use 66R
direct manipulation of object graphics 130O
DIRECT_COLOR keyword 121R
DirectColor visuals 120R
direction
light source for shaded surface plots 994R
of grade 331U
DIRECTION keyword 209O, 282O
directories
changing 257R
main directory system variable 42R
popping 837R
printing 843R
pushing 861R
DIRECTORY keyword 426R, 441R
disappearing variables 142B
Discrete Fourier Transform 400U
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index D ... D
Index Index-17
discrete wavelet transform 413U
DISP_TEXT, seeObsolete Routines
DISPLAY environment variable 23U
Display Headers table property 234U
DISPLAY keyword 432O
DISPLAY_NAME keyword 424R, 426R, 429R, 430R,
517R, 1207R
displaying images 381U, 1153R
ickering 485R
true-color 1154R
with intensity scaling 1164R
displaying text
ASCII les 1354R
in a graphics window 1379R
displays
graphics driver, Windows 113U
size 48R
DISSOLVE procedure 436R
DIST function 437R
distributing IDL applications 2B
DITHER keyword 280R, 908R
dithering 144R, 145R
Floyd-Steinberg 124R
ordered 129R
threshold 140R
division operator 271U, 29B
DLffDICOM
DumpElements method 156O
DLffDXF
GetPalette method 199O
DLM keyword 538R
DO statement 91B
DO_APPLE_SCRIPT procedure 438R
DOC_LIBRARY procedure 440R
document windows
documentation headers, extracting 440R
dollar sign 59R
Doppler frequency 1188R
DOTSkeyword 1184R
DOUBLE function 442R
DOUBLE keyword 188R, 216R, 232R, 241R, 267R,
268R, 274R, 275R, 315R, 327R, 417R, 421R, 444R,
446R, 448R, 465R, 475R, 502R, 551R, 556R, 561R,
576R, 590R, 598R, 601R, 604R, 678R, 694R, 696R,
697R, 699R, 704R, 705R, 735R, 736R, 767R, 796R,
824R, 839R, 862R, 864R, 866R, 968R, 1025R,
1054R, 1056R, 1061R, 1063R, 1064R, 1067R,
1069R, 1096R, 1099R, 1102R, 1123R, 1125R,
1140R, 1142R, 1143R, 1148R, 1149R, 1151R,
1179R, 1348R
double-clicks 1290R
double-precision
arrays, creating 394R, 435R
complex data type 13B
oating-point data type 13B
type, converting to 442R
DOWN keyword 333R
DOWNHILL keyword 331U, 252O, 303R
drag events
for oating-point slider widgets 377R
for RGB slider widgets 387R
for slider widgets 1291R, 1296R
in draw widgets 1234R, 1255R
DRAG keyword 377R, 387R, 1291R
Draw method 217O, 229O, 287O, 343O, 416O, 425O
draw widgets 273B, 294B, 135O, 1252R
attributes 229U
backing store 231U, 1260R
changing size 1234R, 1235R
color model 229U
colors used in 229U
events 232U
determining if set 1272R
returned by 1259R
returning 1234R
example application using 156U
graphics type 230U
motion events 1255R
mouse events 232U
mouse motion events 233U
obtaining window number of 1257R
properties 229U
renderer type 230U
returning events 1234R
scrolling 231U
scrolling area 231U
using 166U
view change events 233U
viewport move 233U
viewport, position 1236R, 1243R
DRAW_BUTTON_EVENTSkeyword 1234R, 1272R
DRAW_DIMENSIONSkeyword 613R, 626R, 649R,
666R
DRAW_EXPOSE_EVENTSkeyword 1234R, 1272R
DRAW_INSTANCE keyword 218O, 426O
DRAW_MOTION_EVENTSkeyword 1234R, 1272R
Index E ... E Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-18 Index
DRAW_VIEWPORT_EVENTSkeyword 1234R, 1272R
DRAW_XSIZE keyword 1234R
DRAW_YSIZE keyword 1235R
DRAWABLE keyword 196R
drawing
arrows 200R
continents 708R
lines (PLOTSprocedure) 809R
objects (ANNOTATE procedure) 196R
drawing to a printer object 140O
droplist widgets 274B, 1262R
events 224U
initial value 224U
returning
current selection 1272R
number of elements 1272R
select event 225U
setting 1243R
title 224U
using 165U
DROPLIST_NUMBER keyword 1272R
DROPLIST_SELECT keyword 1272R
DTOGFLOAT keyword 237R
DTOL keyword 523R
DTOVAX keyword 235R
DTOXDR keyword 235R
DXF object 188O
DXF_TYPE eld 192O
dynamic memory, returning amount in use 539R
DYNAMIC_RESIZE keyword 306B, 1222R, 1235R,
1262R, 1272R, 1280R
dynamically loaded modules, keyword 538R
E
E_CONTINENTSkeyword 726R
E_CONTOUR keyword 1015R
E_GRID keyword 726R
E_HORIZON keyword 726R
E_SURFACE keyword 1015R
earth,interpolatingirregularly-sampled dataover 1131R
edge detection,CONVOL function 311R
edge enhancement
ROBERTSfunction 969R
SOBEL function 1045R
EDGE_TRUNCATE keyword 312R, 1043R
EDGE_WRAP keyword 312R
EDIT executive command Seecommands
EDIT keyword 377R
edit menu (online help) 243U
EDIT_CELL keyword 1235R
EDITABLE keyword 1235R, 1300R, 1310R
Editable table property 235U
Editable text property 216U
editor windows, IDLDE
Macintosh 119U
Motif 42U
Windows 87U
efciency
constants 134B
if statements 131B
programming 124B
system functions and procedures 133B
vector and array operations 132B
EFONT procedure 443R
EIGEN_II seeEIGENVEC
EIGEN_II, seeObsolete Routines
EIGENQL function 444U, 444R
eigenvalues 438U, 444R, 446R, 448R, 551R, 1140R
complex 440U
real 439U
repeated 441U, 443U
EIGENVALUESkeyword 796R
EIGENVEC function 444U, 446R
eigenvectors 438U, 444R, 446R, 1140R
complex 440U
real 439U
repeated 443U
EIGENVECTORSkeyword 444R
EIGHT keyword 596R
EIGHTBIT keyword 1001R
EJECT keyword 122R
electronic mail address, RSI 16U, 9B, 20O, 30R
elements, number of 764R
ELLIPSOID keyword 729R
ELMHESfunction 444U, 448R
EMBEDDED keyword 680R
EMPTY procedure 449R
emptying
le buffers 491R
graphics buffers 449R
ENABLE_FORMATTING keyword 385O, 672R
ENCAPSULATED keyword 122R, 1017R
encapsulated PostScript 160R
encapsulation 250B
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index E ... E
Index Index-19
ENCODING keyword 123R
END statement 90B
END_OF_FILE keyword 403R
END_OF_LINE keyword 403R
end-of-le 450R, 1200R
ENTER_LINE keyword 403R
Entering Procedure Denitions 118B
environment variables
adding or changing 997R
DISPLAY 23U
HHLOCAL 245U
HOME 245U
IDL_ARRAY_MEMORY_SIZE 23U
IDL_DEVICE 22U
IDL_DIR 22U
IDL_DLM_PATH 22U
IDL_HELP_PATH 22U
IDL_PATH 22U
IDL_STARTUP 22U, 34U
LM_LICENSE_FILE 23U
PATH 20U
returning 520R
returning value of 519R
setting 520R
TERM 23U
UNIX 519R
used by IDL 22U
EOF function 157B, 450R
EPSkeyword 421R, 465R, 502R, 863R, 865R, 867R
EPSmachine-specic parameter 703R
EPSI les 130R
EPSNEG machine-specic parameter 703R
EPSTOP keyword 296R
EQ operator 277U, 35B
object references 259B
pointers 238B
EQUAL_VARIANCE, seeObsolete Routines
equal-area map projection 372U
equivalence strings 1145R, 1146R
Erase method 218O, 426O
ERASE procedure 451R
erasing IDL windows 451R
ERODE function 452R
erosion operator, morphologic 452R
ERRORkeyword 280R, 424R, 613R, 619R, 623R, 626R,
630R, 641R, 645R, 650R, 655R, 656R, 666R, 672R,
784R
ERROR keyword
621R
ERRORF function 455R
errors
default error-handling mechanism 142B
error bars 456R, 794R, 808R
error function(ERRORF) 455R
oating-point 427U
oating-point underow 151B
handling 142B
CATCH procedure 143B, 255R
input/output 146B
ON_ERROR procedure 145B, 779R
ON_IOERROR procedure 780R
OPEN procedure 784R
input/output 146B
Macintosh 136U
math 151B
messages
generating (MESSAGE procedure) 745R
modal widget dialog 423R
returning text of 1082R
placing error status in variable 784R
signalling(MESSAGE procedure) 147B
system variables 149B
system variables for 149B
ERRPLOT procedure 456R
ESC keyword 1071R
ESCAPE keyword 403R
ESTIMATESkeyword 511R
Euclidean norm 769R
EVEN keyword 738R
event driven programming 272B
EVENT_FUNCkeyword 1207R, 1222R, 1235R, 1253R,
1262R, 1272R, 1285R, 1291R, 1300R, 1310R
EVENT_FUNCT keyword 355R, 358R
EVENT_HANDLER keyword 1364R
EVENT_PRO keyword 1207R, 1223R, 1235R, 1253R,
1262R, 1273R, 1285R, 1291R, 1300R, 1310R
events 237U
basic structure returned by all widgets 1270R
button press 215U
button release 1224R
clearing 1232R
common properties 199U
compound, handling 199U
destruction 200U
draw area mouse 232U
draw area mouse motion 233U
draw area view changes 233U
draw area widget 232U
Index E ... E Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-20 Index
draw viewport move 233U
droplist 224U
droplist select 225U
focus 210U
handling in IDL GUIBuilder code 159U, 181U,
182U, 185U, 191U
interrupting the event loop 311B
keyboard focus 311B
kill request 210U
listbox 227U
listbox selection 227U
post creation 201U
processing 1269R
realize 200U
release for buttons 214U
returned by
button widgets 1228R
draw widgets 1259R
droplist widgets 1266R
list widgets 1290R
slider widgets 1296R
text widgets 1314R
top-level base widgets 1221R
returning
base resize events 1216R
handler procedure name 1272R
keyboard focus events 1209R, 1301R, 1311R
sending to widgets 1242R
setting button 215U
slider 223U
slider change value 223U
table cell select 237U
table column width change 238U
table data invalid 239U
table focus 238U
table insert character 239U
table insert string 239U
table text delete 238U
table text selection 240U
text delete 218U
text focus 218U
text inserts 218U, 219U
text selection 219U
text widget 218U
timer 200U, 302B
top-level base kill events 1215R
tracking 200U
widget 287B
EXACT keyword 210O, 600R
example 146O, 147O
example les
norm_coord.pro 53O
obj_axis.pro 75O
obj_logaxis.pro 76O
obj_plot.pro 100O
obj_tess.pro 71O
obj_vol.pro 122O
penta.pro 69O
rot_text.pro 84O
sel_obj.pro 131O
surf_track.pro 110O, 441O
test_surface.pro 53O
trackball_dene.pro 55O
EXCELL keyword 1375R
exclamation point 58R, 79R
EXCLUSIVE keyword 355R, 1208R
EXECUTE function 129B, 252R, 253R, 254R, 458R
executive commandsSeecommands, executive
EXFREQ keyword 331R
EXIT procedure 130B, 459R
exiting IDL 21U, 459R
EXP function 460R
EXPAND procedure 461R
EXPAND_PATH function 462R
EXPAND_TO_BYTESkeyword 928R
EXPINT function 465R
explicitly formatted I/O 159B, 169B
exponential
integral 465R
natural 460R
random deviates 887R, 891R
EXPONENTIAL keyword 282R, 587R
exponentiation operator 271U, 29B
EXPOSE_EVENTSkeyword 1253R
expressions
efciency of evaluation 130B
structure of 278U, 280U, 37B, 38B
type of 278U, 37B
EXTEND keyword 210O
EXTENDED_LEGO keyword 364O
EXTENDSIZE keyword 788R
external
editors, Motif 80U
sharable object 245R
EXTRA keyword (keyword inheritance) 115B
EXTRA keyword (keyword inheritance) 114B
EXTRAC function 467R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index F ... F
Index Index-21
EXTRACT_SLICE function 469R
EXTRAPOLATE keyword 1128R, 1135R, 1197R
EXTRUSION eld 192O
EYE keyword 393O
eye position 45O
F
F distribution 471R, 472R
F_CVF function 471R
F_PDF function 472R
F_TEST, seeObsolete Routines
F_TEST1, seeObsolete Routines
F_VALUE keyword 246R
F77_UNFORMATTED keyword 785R
FACT keyword 1382R, 1384R
FACTORIAL function 473R
false, denition of 103B
far clipping plane 47O
Fast Fourier Transform 400U
implementation 410U
Fast Fourier transform 474R
FFT function 423U, 474R
eld
plots 488R, 806R
widget 368R
FIELDFONT keyword 368R
FILE keyword 307O, 273R, 426R, 441R, 685R, 754R,
1361R
File menu (online help) 243U
le units 162B
allocating 516R
returning information about 538R
Seealso logical unit numbers
setting le position pointer 813R
le, saving images to 118O
FILE_LUN keyword 1023R
FILE_UNIT keyword 1180R
FILENAME keyword 298O, 301O, 420O, 123R, 623R,
955R, 982R, 1352R
FILEPATH function 478R
les
CDF 1387R
closing 161B, 117R, 273R, 493R
displaying ASCII 1354R
end-of-le 211B, 1200R
le units, Seele units
lenames 123R
Macintosh differences 134U
Windows differences 113U
nding 426R, 480R
nding in IDL distribution 478R
ushing le units 210B
formats
BMP 228B
GIF 228B
Interle 228B
JPEG 228B
NRIF 228B
PICT 228B
PNG 228B
PPM 228B
SRF 228B
TIFF 228B
X11 Bitmap 228B
XWD 228B
freeing logical unit numbers 493R
HDF 1388R
help and information 207B
IDL GUIBuilder
generated 159U
generating code 179U
generating resource 179U
IDL code 179U
regeneration 180U
resource 179U
indexed 221B
input/output 156B
locating 206B
logical unit number 162B
Macintosh path 44R
Macintosh-specic information 227B
manipulation operations 206B
Message-of-the-Day
modifying generated 159U
MPEG 119O
multiple structures 205B
netCDF 1389R
opening 160B, 783R
pointer position 210B
CUR_PTR keyword 495R
POINT_LUN procedure 813R
under Windows 114U
printing to 841R
reading
and writing,Windows 113U
Index F ... F Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-22 Index
ASCII data 898R
binary data from 933R
data 895R
unformatted binary data 933R
record-oriented 219B
returning information on open 537R
selecting 426R
selection dialogs 277B
size of 495R
skipping records 1026R
special functions (IOCTL function) 578R
specifying search path
IDLDE for Macintosh 132U, 133U
IDLDE for Motif 66U
updating records (REWRITE keyword) 1344R
VMS-specic information 217B
Windows-specic information 226B
with indexed organization 896R
writing formatted output 841R
writing unformatted binary data 1344R
FILESkeyword 207B, 538R
FILL keyword 252O, 303R, 1177R
FILL_COLOR keyword 273O
FILL_CONTINENTSkeyword 708R
FILL_DIST system variable eld 46R
FILL_PATTERN keyword 328O, 827R
FILLCONTOUR, seeObsolete Routines
lled contours 330U, 303R
lling
plotting symbols 1177R
polygons 298U, 826R, 829R
FILLVAL keyword 461R
FILTER keyword 426R
ltering
convolution 225R
digital lters 431R
digitial 431R
lenames 426R
frequency domain 474R
Hanning windows 529R
histogram equalization 544R
Lee lter algorithm 600R
mean 1043R
median 738R
morpholigic dilation 432R
morphologic erosion 452R
Roberts 969R
Sobel 1045R
lters
bandpass 414U
bandstop 414U
boxcar 417U
digital 414U
highpass 414U
lowpass 414U
notch 419U
rectangular 417U
nd tab (online help system) 249U
FIND_BY_UNAME keyword 182U, 1273R
FINDFILE function 157B, 206B, 480R
FINDGEN function 482R
Finding an appropriate view volume 47O
nding les 426R
nding text
IDLDE for Motif 46U
nite
impulse response lters 414U
numbers 483R
FINITE function 428U, 153B, 483R
FITA keyword 678R
FIX function 484R
FIX_FILTER keyword 426R
FIXED keyword 788R
xed pixels 326U
FIXED_SIZE keyword 227R
FLAGSsystem variable eld 46R
ashing colormaps 67U
FLICK procedure 485R
FLOAT function 486R
FLOAT keyword 561R, 705R, 1338R
Floating base property 204U
FLOATING keyword 368R, 1208R
oating point conversions 1404
oating-point
accuracy 427U
arithmetic 703R
arrays 482R, 490R
converting type to 486R
data type 13B
errors 151B
mantissa 703R
native format 235R
precision 703R
slider widgets 377R
underow errors 151B
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index F ... F
Index Index-23
XDR format 235R
oating-point format 1402
FLOOR function 487R
ow
control 142R
eld, plotting 488R, 1182R
FLOW3 procedure 488R
FLOYD keyword 124R
FLTARR function 490R
FLUSH procedure 157B, 491R
focusevents 311B, 1209R, 1239R, 1274R, 1301R, 1311R
FOCUSkeyword 282O
folders, Macintosh 44R
FOLLOW keyword 320U, 304R
FONT keyword 273O, 385O, 102R, 124R, 355R, 368R,
383R, 1223R, 1280R, 1285R, 1292R, 1300R, 1310R,
1354R
font object 30O, 256O
FONT property of text objects 84O
modiers 258O
font objects 64O
FONT system variable eld 49R
FONT_INDEX keyword 124R
FONT_SIZE keyword 124R
FONTNAME keyword 672R
fonts
character sets 79R
default for widgets 1233R
device 66R
Direct Graphics 66R
displaying vector fonts 1017R
displaying X Windows fonts 1356R
editing 443R
examples of TrueType fonts 86R
examples of vector fonts 89R
nding current X windows font 124R
nding names of 124R
nding number of 125R
hardware 294U, 66R
Hershey 65R
Object Graphics 66R
outline 65R
positioning commands 81R
PostScript 853R
selecting 294U
specifying
IDLDE for Motif 65U
TrueType 65R, 74R, 136R
vector 65R
FONTSIZE keyword 672R
FOR statement 91B, 96B
FORCE_DEMO keyword 680R
formal parameters 110B, 111B, 181O, 185R
Format Codes 173B
FORMAT keyword 74B, 75B, 298O, 377R, 841R, 896R,
931R, 1077R, 1236R, 1300R
FORMAT_AXIS_VALUESfunction 492R
formatted I/O 158B
forms, creating 371R
FORRD procedureseeREADU
FORRD, seeObsolete Routines
FORRD_KEY procedureseeREADU
FORRD_KEY, seeObsolete Routines
Fortran le formats 785R
FORTRAN keyword 789R
forward difference 1148R
FORWARD keyword 1151R
FORWARD_CHARACTER keyword 403R
FORWARD_FUNCTION statement 101B
FORWARD_WORD keyword 403R
FORWRT procedureseeWRITEU
FORWRT, seeObsolete Routines
FOUR_BITSkeyword 1320R
four-dimensional displays 832R
Fourier transform 400U, 474R
Frame common property 197U
FRAMEkeyword 346R, 351R, 355R, 358R, 361R, 369R,
378R, 380R, 387R, 390R, 760R, 1208R, 1223R,
1254R, 1262R, 1281R, 1286R, 1292R, 1300R,
1310R, 1359R
FRAME_RATE keyword 299O
free format I/O 159B, 165B
FREE keyword 1317R
FREE_LUN procedure 157B, 273R, 493R
freeing pointers 242B
frequency response function 421U
FRIEDMAN, seeObsolete Routines
FROM_CYLIN keyword 338R
FROM_POLAR keyword 338R
FROM_RECT keyword 338R
FROM_SPHERE keyword 338R
FRONT_TYPE keyword 1201R
FSTAT function 157B, 207B, 494R
FSTAT structure 494R
FTOVAX keyword 235R
FTOXDR keyword 235R
Index G ... G Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-24 Index
FULL_PATH keyword 782R
FULL_TRANSLATION keyword 1146R
FULL_WINDOW keyword 1040R
FULSTR function 466U, 496R
FUNC_GET_VALUE keyword 1208R, 1223R, 1236R,
1254R, 1263R, 1281R, 1286R, 1292R, 1301R, 1310R
FUNCT procedure 497R
function denition statement 99B
function keys
dening 399R, 405R
for different keyboards 1000R
returning denitions 537R, 538R
FUNCTION keyword 608R
function methods
calling sequence for 180O
FUNCTION_NAME keyword 193R, 678R, 1099R
FUNCTION_VALUE keyword 194R
functions 29U, 119B
calling sequence for 184R
compiled 975R
dening 99B
denition statements 110B
displaying compiled 540R
forward denition 101B
FUNCTIONSkeyword 975R
FV_TEST function 448U, 498R
FVALUE keyword 1132R
FX_ROOT function 462U, 500R
FZ_ROOTSfunction 462U, 502R
G
gamma correction 505R
GAMMA function 504R
gamma function 504R
incomplete 557R
logarithm of 682R
GAMMA keyword 304O, 306O, 887R, 891R
gamma random deviates 887R, 891R
GAMMA_CT procedure 505R
GAP keyword 273O
garbage collection 536R
GAUSS, seeObsolete Routines
GAUSS_CVF function 506R
GAUSS_PDF function 507R
GAUSS2DFIT function 508R
GAUSSFIT function 438U, 511R
Gaussian
distribution 506R, 507R
elimination method 576R
integral 513R
iterated quadrature 449U, 563R, 566R
two-dimensional t 508R
GAUSSINT function 513R
Gauss-Krueger map projection 369U, 725R
Gauss-Seidel iteration 525R
ge 39R
GE operator 277U, 35B
general perspective map projection 366U, 725R
general triangles 375O
GEOM keyword 250O
GEOMETRIC keyword 282R
GEOMETRY keyword 1273R
geometry of widgets 305B
GEOMX keyword 252O
GEOMY keyword 253O
GEOMZ keyword 253O
GEOTIFF keyword 921R, 1338R
GET keyword 388U, 1160R
Get method 184O
GET_BOUNDS.PRO 48O
GET_CURRENT_FONT keyword 124R
GET_DECOMPOSED keyword 124R
GET_DRAW_VIEW keyword 1236R
GET_FONTNAMESkeyword 124R
GET_FONTNUM keyword 125R
GET_GRAPHICS_FUNCTION keyword 125R
GET_KBRD function 157B, 211B, 514R
GET_LUN keyword 785R
GET_LUN procedure 157B, 273R, 493R, 516R
GET_NAMESkeyword 685R
GET_PATH keyword 427R
GET_SCREEN_SIZE function 517R
GET_SCREEN_SIZE keyword 308B, 125R
GET_SYMBOL function 518R
GET_TRANSLATION keyword 281R
GET_UVALUE keyword 1236R
GET_VALUE keyword 1237R
GET_VISUAL_DEPTH keyword 125R
GET_VISUAL_NAME keyword 125R
GET_WINDOW_POSITION keyword 126R
GET_WRITE_MASK keyword 126R
GetByName method 288O, 355O, 390O, 398O
GetContents method 190O
GetContiguousPixelsmethod 219O, 230O, 344O, 427O
GetCTM method 206O, 248O, 261O, 279O, 289O,
316O, 325O, 335O, 360O, 381O, 404O
GetEntity mehod 192O
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index G ... G
Index Index-25
GETENV function 519R, 520R
GetFontnamesmethod 219O, 231O, 345O, 417O, 427O
GETHELP, seeObsolete Routines
GetPalette method 199O
GetProperty method 207O, 220O, 232O, 240O, 249O,
257O, 262O, 271O, 280O, 290O, 297O, 304O,
311O, 317O, 326O, 336O, 346O, 356O, 361O,
371O, 382O, 391O, 399O, 405O, 418O, 428O
GetRGB method 303O
GetTextDimensionsmethod 221O, 232O, 347O, 418O,
429O
GFLOATTOD keyword 237R
GIF les
reading 904R
writing 1322R
GIN_CHARSkeyword 126R
GLINESTYLE keyword 711R, 726R
GLINETHICK keyword 711R, 726R
GLYPH_WIDTH keyword 273O
GNOMIC keyword 724R
gnomic map projection 363U, 724R
gnomonic map projection 363U, 724R
GO executive command Seecommands
GOMPERTZ keyword 282R
GOODFIT, seeObsolete Routines
GOTO statement 102B
GOURAUD keyword 994R
Gouraud shading 349U, 994R
GOUT keyword 1052R
grade, direction of 331U
GRAPHIC_PROPERTIESkeyword 660R
graphics
clipboard support
Windows 88U
coordinate systems 285U, 335U
cursor positioning 332R
device independent graphics 23O
devices 268B, 23O, 111R
device independent graphics 268B
DEVICE procedure 419R
erasing 451R
returning information about current 538R
setting 992R
driver information, Windows 113U
functions
getting 125R
setting 137R
image le formats
BMP 901R, 1320R
GIF 904R, 1322R
Interle 906R
JPEG 907R, 1324R
NRIF 1327R
PICT 910R, 1328R
SRF 916R, 1333R
TIFF 921R, 1337R
X11 bitmap 928R
XWD 930R
keywords (collected) 99R
modes 268B, 23O
object-oriented 268B, 24O
printing 28U
two-dimensional arrays 318U
windows, IDLDE
backing store
Macintosh 130U
Motif 62U
Windows 106U
changing preferences
Macintosh 130U
Windows 106U
OS clipboard support
Macintosh 120U
Windows 88U
window layout
Macintosh 130U
Motif 43U, 61U
Windows 106U
graphics hierarchy 36O
graphics tree 36O
Graphics Type draw area property 230U
GRAPHICS_TIMESprocedure 1120R
GRAPHICS_TREE keyword 223O, 234O, 348O, 420O,
432O
graphs 86O
graticule 360U
GRAY keyword 433R, 453R
GRAYSCALE keyword 908R
GREEN keyword 626R
GREEN_VALUESkeyword 242O, 306O
GREYSCALE keyword 265O
grid
across a plot (TICKLEN keyword) 108R
for plots (TICKLEN keyword) 302U
GRID keyword 359U, 363U, 574R, 727R
Grid Layout base property 204U
GRID_LAYOUT keyword 1208R
Index H ... H Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-26 Index
GRID3 function 445U, 522R
gridding 1134R
and interpolation 444U
spherical 1052R, 1131R, 1134R
GRIDSTYLE keyword 210O
GRIDSTYLE system variable eld 53R
GROUP keyword 202R, 427R, 443R, 662R, 1027R,
1040R, 1352R, 1354R, 1356R, 1359R, 1361R,
1369R, 1370R, 1371R, 1377R, 1378R
GROUP_LEADER keyword 1208R, 1223R, 1237R,
1254R, 1263R, 1281R, 1286R, 1292R, 1301R,
1310R, 1364R
growth trends 282R
GSkeyword 588R, 1053R, 1129R
GS_ITER function 460U, 525R
GT operator 277U, 36B
guard digits 703R
GUIBuilder
generating les 89U
IDLDE windows 87U
GUIBuilder, SeeIDL GUIBuilder
H
H_EQ_CT function 527R
H_EQ_INT function 528R
halftoning 144R
halting program execution 1070R
HAMMER keyword 724R
Hammer-Aitoff map projection 366U, 724R
Hamming window 408U
HandiHelp 242U
Handle Events common event 199U
HANDLE_CREATE, seeObsolete Routines
HANDLE_FREE, seeObsolete Routines
HANDLE_INFO, seeObsolete Routines
HANDLE_MOVE, seeObsolete Routines
HANDLE_VALUE, seeObsolete Routines
HANNING function 423U, 529R
Hanning window 407U
hardware fonts 66R
HDF (Hierarchical Data Format) les 1388R
HDF_BROWSER function 530R
HDF_READ function 533R
HEADER keyword 899R
HEADER_DEFINE keyword 1320R
heap variables 230B, 254B
creating 231B, 857R
destroying 856R
garbage collection 536R
leakage 239B, 255B
object 230B, 250B, 254B
pointer 233B
saving and restoring 232B
HEAP_GC procedure 536R
HEAP_VARIABLESkeyword 538R
HEIGHT keyword 1354R
Height listbox property 226U
Height text property 216U
help
menu, online help viewer 246U
online 242U
ONLINE_HELP procedure 781R
HELP keyword 384R, 1223R
HELP procedure 252U, 157B, 537R
HELP_VM, seeObsolete Routines
Helper objects 31O, 38O
HELVETICA keyword 126R
Hershey fonts 65O, 65R
Hershey, Dr. A. V. 66R
Hessenberg array or matrix 448R, 551R
Hewlett-Packard Graphics Language, see HP-GL
hexadecimal 14B
HHLOCAL environment variable 245U
hidden line removal 106O
HIDDEN_LINESkeyword 328O, 364O
HIDEkeyword 210O, 242O, 253O, 265O, 274O, 282O,
291O, 319O, 328O, 338O, 364O, 385O, 400O,
409O, 641R, 657R, 672R, 1157R
hiding cursor 1157R
hierarchy 36O
HIFAC keyword 683R
highpass lters 414U
high-resolution continent outlines 377U
HILBERT function 423U, 541R
Hilbert transform 411U
HINTSkeyword 409O
HIRESkeyword 377U, 708R, 727R
HIST_2D function 542R
HIST_EQUAL function 544R
histogram
equalization
H_EQ_CT function 527R
interactive (H_EQ_INT function) 528R
plot 399U
plotting mode 297U, 105R
HISTOGRAM function 546R
HISTOGRAM keyword 319O, 650R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index I ... I
Index Index-27
HLScolor system 277R, 387R, 1159R
HLSkeyword 388U, 388R, 1160R
HLSprocedure 391U, 550R
HLS_RGB keyword 277R
home directory
IDLDE for Motif 66U
HOME environment variable 245U
homogeneous coordinates 334U
HORIZON keyword 727R
HORIZONTAL keyword 1091R
horizontal slider, Seeslider widgets
HOTSPOT keyword 438O
hourglass cursor 301B
(for widgets) 1238R
saving 1269R
HOURGLASSkeyword 301B, 1238R
Householder
method 1142R
reductions 444R
HP9000 keyword 1001R
HP-GL
driver 150R
les 146R
HQR function 444U, 551R
HSIZE keyword 200R
HSV color system 277R, 387R, 1159R
HSV keyword 388U, 388R, 1160R
HSV procedure 391U, 553R
HSV_RGB keyword 277R
HSV_TO_R, seeObsolete Routines
HTHICK keyword 200R
HTML 250U, 251U, 751R
HTONL keyword 236R
HTONSkeywords 236R
hyperbolic
cosine 318R
sine 1021R
tangent 1113R
HYPERBOLIC keyword 283R
HyperHelp 250U
HyperText Markup Language 250U, 251U, 751R
hypothesis testing 446U
Chi-square model validation 1375R
contingency test for independence 330R
F-variances test 498R
Kruskal-Wallis H-test 591R
Lomb frequency test 683R
Mann-Whitney U-test 977R
median delta test 733R
normality test 498R, 1121R
runs test for randomness 884R
sign test 980R
t-means test 1121R
Wilcoxon rank-sum test 977R
I
I/O, seeinput/output
I_VALUE keyword 247R
IBETA function 554R
IBETA machine-specic parameter 703R
IBM keyword 1001R
ICONIC keyword 1347R
ICONIFY keyword 1238R
Iconify method 430O
iconifying
widgets 1238R
windows 1347R
iconifying windows 137O
icons, editing 1352R
IDENTITY function 460U, 556R
IDL
applications,distributing 2B
Code Proler 141U
Development Environment (IDLDE)
Macintosh 118U
Motif 40U
Windows 84U
Direct Graphics 268B, 23O
for Macintosh 154R
for Windows 170R
Object Graphics 268B, 23O
online help 242U
pointers 233B
runtime licensing 2B
statements 84B
IDL documentation 15O
IDL GUIBuilder 150U
# of Rows/Columns property 202U
Alignment property 203U, 213U
Allowing Closing property 203U
Allowing Moving property 204U
base widget attributes 202U
base widget events 210U
Index I ... I Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-28 Index
base widget properties 202U
base widgets, using 165U
Bitmap Editor 174U
Bitmap property 213U
button attributes 213U
button widgets, using 165U
buttons, adding bitmaps 174U
buttons, adding menus 173U
checkbox attributes 213U
checkbox widgets, using 165U
checkboxes, creating 212U
Color Model draw area property 229U
color table example 161U
common events 199U
compiling and running example 162U
Component Sizing property 197U
copying or cutting widgets 177U
creating draw area, example 156U
creating multiple checkboxes 212U
creating multiple radio buttons 212U
dening menus, example 153U
deleting widgets 178U
draw area events 232U
draw widget properties 229U
draw widgets, using 166U
droplist attributes 224U
droplist events 224U
droplist properties 224U
droplists, using 165U
event code, example 191U
event code, handling example 182U
event code, integrating interfaces 185U
event code, understanding 181U
example application 153U
les, generating multiple times 180U
les, IDL code 179U
les, portable resource 179U
Floating property 204U
Frame property 197U
generating code 159U, 179U
generating resource les 179U
Grid layout property 204U
horizontal slider, using 165U
Initial Value droplist property 224U
Initial Value listbox property 226U
Initial Value text property 216U
integrating multiple interfaces 185U
Label property 214U
label widget attributes 221U
label widget properties 221U
label widgets, using 165U
Layout property 205U
listbox attributes 226U
listbox events 227U
listbox properties 226U
listbox widgets, using 165U
Maximum Value slider property 222U
menus, editing 171U
Minimize/Maximize property 206U
Minimum Value slider property 222U
Modal property 206U
modifying code, example 159U
moving widgets 177U
Multiple listbox property 226U
Name property 196U
No Release property 214U
OnButton draw area event 232U
OnButton Press event property 215U
OnCellSelect table event 237U
OnChangeValue slider event 223U
OnColWidth table event 238U
OnDelete table event 238U
OnDelete text event 218U
OnDestroy event property 200U
OnExpose draw area event 233U
OnFocus event property 210U
OnFocus table event 238U
OnFocus text event 218U
OnInsertCh text event 218U
OnInsertChar table event 239U
OnInsertString table event 239U
OnInsertString text event 219U
OnInvalidData table event 239U
OnKillRequest event property 210U
OnMotion draw area event 233U
OnRealize event property 200U
OnSelectValue droplist event 225U
OnSelectValue listbox event 227U
OnSizeChange event property 210U
Index Index-29
OnTextSelect table event 240U
OnTextSelect text event 219U
OnTimer event property 200U
OnTracking event property 200U
OnViewportMoved draw area event 233U
operating on widgets 176U
parent base, changing for widget 177U
pasting widgets 177U
Position slider property 222U
PostCreation event property 201U
Properties dialog 166U
radio button attributes 213U
radio button widgets, using 165U
radio buttons, creating 212U
redoing operations 178U
Renderer draw area property 230U
Resize Columns table property 235U
resizing widgets 177U
Retain draw area property 231U
Row Labels table property 236U
Row/Column Major table property 235U
Scroll draw area property 231U
Scroll property 206U
Scroll table property 236U
Scroll text property 217U
selecting widgets 176U
Sensitive property 198U
setting button events 215U
setting button properties 212U
setting text widget attributes 216U
setting text widget events 218U
slider events 223U
slider properties 222U
smooth example 161U
Space property 207U
starting 151U
Suppress Value slider property 222U
System Menu property 207U
table events 237U
table widget attributes 234U
table widget properties 234U
table widgets, using 166U
test mode 158U
Text label property 221U
text widgets properties 216U
text widgets, using 165U
Title Bar property 208U
Title droplist property 224U
Title property 207U
Title slider property 223U
toolbar 164U
tools 164U
Type property 214U
undoing operations 178U
vertical slider, using 165U
Viewport Columns table property 236U
Viewport Rows table property 237U
Visible property 208U
Widget Browser 191U
Widget Browser, using 169U
widgets, changing parent base of 177U
widgets, cutting, copying or pasting 177U
widgets, deleting 178U
widgets, moving 177U
widgets, resizing 177U
widgets, selecting 176U
Width listbox property 227U
Width text property 217U
Word Wrapping text property 217U
writing event-handling code 159U
X Offset property 198U
X Pad property 208U
X Scroll draw area property 231U
X Scroll property 209U
X Size property 198U
Y Offset property 198U
Y Pad property 209U
Y Scroll draw area property 231U
Y Scroll property 209U
Y Size property 199U
IDL object overview 250B
IDL objects 255B
IDL_ARRAY_MEMORY_SIZE locg 23U
IDL_ARRAY_MEMORY_SIZE logical name 23U
IDL_Container
Add method 182O
class 182O
Cleanup method 183O
Count method 184O
Get method 184O
Init method 185O, 200O
IsContained method 186O
Move method 186O
Remove method 187O
IDL_DEVICE environment variable 22U
IDL_DIR environment variable 22U
IDL_DLM_PATH environment variable 22U
IDL_FONT keyword 220O, 231O, 345O, 417O, 428O
Index-30 Index
IDL_HELP_PATH environment variable 22U
IDL_PATH environment variable 22U
IDL_STARTUP environment variable 22U, 34U
IDL_TREE example routine 248B
IDLDE windows
Editor
Macintosh 119U
Motif 42U
Windows 87U
Graphics
Macintosh 130U
Motif 43U
Windows 106U
GUIBulder 87U
IDLffDICOM
Cleanup method 155O
GetChildren method 157O
GetDescription method 158O
GetElement method 160O
GetGroup method 162O
GetLength method 163O
GetParent method 164O
GetPreamble method 165O
GetReference method 166O
GetValue method 168O
GetVR method 171O
Init method 172O
Read method 173O
IDLffDXF 188O
Cleanup method 189O
GetContents method 190O
GetEntity method 192O
Init method 200O
PutEntity method 200O
Read method 201O
RemoveEntity method 202O
Reset method 202O
SetPalette method 202O
Write method 203O
IDLgrAxis
class 29O, 205O
Cleanup method 206O
GetCTM method 206O
GetProperty method 207O
Init method 208O
SetProperty method 214O
IDLgrBuffer
class 32O
Cleanup method 217O
Draw method 217O
Erase method 218O
GetFontnames method 219O, 231O, 345O, 417O,
427O
GetTextDimensions method 221O
Init method 222O
Pickdata method 224O
Read method 225O
Select method 226O
IDLgrBuffer class 216O
IDLgrClipboard
class 32O
Cleanup method 229O
Draw method 229O
GetContiguousPixels method 230O
Init method 233O
IDLgrClipboard object 228O
IDLgrColorbar
class 30O, 238O
Cleanup method 238O
ComputeDimensions method 239O
Init method 241O
IDLgrColorbar object 238O
IDLgrContour
class 29O
Cleanup method 248O
GetCTM method 248O
Init method 250O
IDLgrContour object 247O
IDLgrFont
class 30O, 256O
Cleanup method 256O
Init method 257O
IDLgrImage
class 29O, 260O
Cleanup method 261O
GetCTM method 261O
Index Index-31
Init method 263O
IDLgrLegend
class 30O
Cleanup method 270O
ComputeDimensions method 270O
Init method 272O
IDLgrLight
class 29O, 278O
Cleanup method 278O
GetCTM method 279O
Init method 281O
IDLgrModel
Add method 286O
class 28O, 285O
Cleanup method 286O
Draw method 287O
GetByName method 288O
GetCTM method 289O
Init method 290O
Remove method 292O
Reset method 293O
Rotate method 293O
Scale method 294O
Translate method 295O
IDLgrMPEG
class 32O
Cleanup method 296O
Init method 298O
Put method 300O
Save method 300O
IDLgrMPEG object 296O
IDLgrPalette
class 31O, 302O
Cleanup method 302O
GetRGB method 303O
Init method 305O
LoadCT method 306O
NearestColor method 307O
SetRGB method 308O
IDLgrPattern
class 31O, 310O
Cleanup method 310O
Init method 312O
IDLgrPlot
class 29O, 315O
Cleanup method 316O
GetCTM method 316O
Init method 318O
IDLgrPolygon
class 29O, 324O
Cleanup method 324O
GetCTM method 325O
Init method 327O
IDLgrPolygon objects 92O
IDLgrPolyline
class 29O, 334O
Cleanup method 334O
GetCTM method 335O
Init method 337O
IDLgrPrinter
class 32O, 342O
Cleanup method 343O
Draw method 343O
GetContiguousPixels method 344O
Init method 347O
NewDocument method 350O
NewPage method 350O
IDLgrScene
Add method 354O
class 28O, 353O
Cleanup method 354O
Init method 356O
Remove method 357O
Index-32 Index
IDLgrSurface
class 30O, 359O
Cleanup method 360O
GetCTM method 360O
Init method 362O
IDLgrSymbol
class 31O, 370O
Cleanup method 370O
Init method 372O
IDLgrTessellator
AddPolygon method 376O
class 31O, 375O
Cleanup method 377O
Init method 377O
Reset method 378O
Tessellate method 378O
IDLgrText
class 30O, 380O
Cleanup method 381O
GetCTM method 381O
Init method 383O
IDLgrView
Add method 389O
class 28O, 388O
Init method 391O
Remove method 394O
IDLgrViewgroup
Add method 397O
class 28O
Cleanup method 397O
Init method 399O
Remove method 400O
IDLgrViewgroup object 396O
IDLgrVolume
class 30O, 402O
Cleanup method 402O
ComputeBounds method 403O
GetCTM method 404O
Init method 406O
PickVoxel method 412O
IDLgrVRML
class 32O
Draw method 416O
Init method 419O
IDLgrVRML object 414O
IDLgrWindow
class 32O, 424O
Cleanup method 425O
Draw method 425O
Erase method 426O
GetContiguousPixels method 219O, 427O
Iconify method 430O
Init method 431O
maximum size 136O, 424O
Read method 435O
Select method 436O
SetCurrentCursor method 437O
SetProperty method 438O, 439O
IDSkeyword 355R, 374R, 384R
IEEE oating point 1402
IEEE standard 256U, 152B, 153B
IEXP machine-specic parameter 703R
IF statement 102B
avoiding 131B
IGAMMA function 557R
IHDR keyword 1320R
IIDLffDICOM
Reset method 174O
IMAGE keyword 438O, 346R, 760R, 1005R, 1009R,
1359R
image object 29O, 260O
image objects 114O
alpha blending 115O
creating 114O
interleaving 116O
palettes 116O
Index Index-33
saving to a le 118O
saving to an MPEG le 119O
using 115O
image processing 429U
IMAGE_CONT procedure 324U, 559R
IMAGE_COORD keyword 827R
IMAGE_DATA keyword 221O, 429O
IMAGE_INDEX keyword 880R, 923R
IMAGE_INTERP keyword 827R
IMAGE_SIZE keyword 362R
images 260O
annotating 196R
bi-level 1118R
color channel 265O
combining with 3D graphics 347U
copying areas 118R
dening region of interest 407R
displaying 381U, 390R, 485R, 1040R, 1153R,
1157R, 1159R, 1161R, 1164R
displaying with intensity scaling 1164R
displaying, Macintosh 130U
dissolve effect 436R
image manipulation compound widgets 276B
JPEG 907R
magnied 1382R, 1384R
monochrome 145R
MPEG les 757R, 758R, 760R, 762R
orientation 382U
overlaying with contour plots 324U
overview 380U
position in display 382U
processing 380U
proling 844R, 848R
raster 380U
reading from display 385U, 395U, 1161R
region labeling 596R
Roberts edge enhancement 969R
rotating 972R
routines 380U
scaling 384U
searching for objects 986R
sharing data 267O
size of display 383U
smoothing 1043R
Sobel edge enhancement 1045R
thinning 1118R
transfer direction 48R
true-color 1162R
warping 820R
warping to maps 715R, 718R
with surface and contour plots 1015R
zooming 390R
IMAGINARY function 560R
imaginary part of complex numbers 560R
implicit self argument 262B
INCHESkeyword 126R, 1154R, 1157R
include les 29U
incomplete
beta function 554R
gamma function 557R
INCREASE keyword 987R, 990R
incrementing array elements 548R
INDEPENDENT keyword 645R, 650R
INDEX keyword 199O, 202O, 705R
index tab (online help system) 248U
INDEX_COLOR keyword 126R
Indexed color model 58O
INDEXED_COLOR keyword 613R, 626R, 650R, 666R
INDGEN function 561R
innite impulse response lters 414U
Innity norm 460U, 769R
innity, undened result 152B
information about objects 259B
INFORMATION keyword 424R
INFORMATIONAL keyword 745R
Informational Routines 124B
inheritance 253B
object 251B
INIT keyword 227R
Init method 185O, 200O, 208O, 222O, 233O, 241O,
250O, 257O, 263O, 272O, 281O, 290O, 298O,
305O, 312O, 318O, 327O, 337O, 347O, 356O,
362O, 372O, 377O, 383O, 391O, 399O, 406O,
419O, 431O, 442O
initialization of objects 33O
INITIALSIZE keyword 789R
inner products (computing) 430U
INP, seeObsolete Routines
INPUT keyword 547R, 1135R
input/output
associated 202B
associated variables 204R
bitmap les 901R
BMP les 1320R
CDF 1387R
Index-34 Index
closing les 273R
emptying buffers 449R, 491R
end of le mark 1200R
error handling 146B
errors 780R
explicit format 159B, 169B
format codes 173B
format reversion 172B
formatted 158B, 841R
free format 159B, 165B
GIF les 904R, 1322R
HDF 1388R
Interle les 906R
JPEG les 907R, 1324R
magnetic tape 224B
netCDF 1389R
NRIF les 1327R
opening les 783R
PGM les 913R, 1331R
PICT les 910R, 1328R
portable 197B
PPM les 913R, 1331R
reading
ASCII les 898R
formatted data 895R
formatted data from a string 931R
from a prompt 896R
from tape unit 1114R
SRF les 916R, 1333R
TIFF les 921R, 1337R
unformatted 158B, 191B
portable 197B
string variables 192B
UNIX FORTRAN unformatted data les 206B
updating records (REWRITE keyword) 1344R
wave les 926R, 1342R
writing
to tape unit 1115R
X11 Bitmaps 928R
XDR 198B
XWD les 930R
INPUT_FOCUSkeyword 1238R
INSERT_COLUMNSkeyword 1238R
INSERT_OVERSTRIKE_TOGGLE keyword 403R
INSERT_ROWSkeyword 1238R
instance
object 250B
Instancing 149O
instancing 137O, 149O
INSTANCING keyword 613R, 626R, 650R, 666R
INT keyword 705R
INT_2D function 450U, 453U, 563R
INT_3D function 450U, 453U, 566R
INT_TABULATED function 453U, 568R
INTARR function 570R
integer 484R
arrays 561R, 570R
constants 257U, 15B
conversions, errors in 154B
data type 12B
INTEGER keyword 369R
integration 449U
bivariate functions 450U
INT_2D 563R
INT_3D 566R
INT_TABULATED 568R
QROMB 862R
QROMO 864R
QSIMP 866R
RK4 967R
tabulated functions 568R
trivariate functions 451U
univariate functions 862R, 864R, 866R
INTENSITY keyword 282O, 505R
interactive graphics 137O
instancing 137O
Interactive Support 242U
Interactive Surface Example 110O
INTERCHANGESkeyword 696R
Interle les
reading 906R
INTERIOR keyword 376O
INTERLACED keyword 299O
INTERLEAVE keyword 266O
interleaving (image objects) 114O
INTERP keyword 292R, 559R, 970R, 1015R, 1382R
INTERPOL function 445U, 571R
INTERPOLATE function 445U, 573R
INTERPOLATE keyword 409O, 993R, 1193R
interpolating
function 445U
interpolation 444U, 573R
bilinear 217R, 935R
cubic convolution 573R, 821R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index J ... K
Index Index-35
cubic spline 1054R, 1058R, 1059R
INTERPOL 571R
irregularly-gridded data 1134R
irregularly-sampled data over earth 1131R
KRIG2D 586R
linear 571R
MIN_CURVE_SURF 748R
of irregularly-gridded data 586R, 748R
POLAR_SURFACE 817R
quintic 1136R
spherical 1052R
SPL_INIT 1054R
SPL_INTERP 1056R
interpolation of voxel values 127O
interpreter symbols, DCL
dening 996R
deleting 411R
returning values 518R
interrupting program execution 30U
INTERVAL keyword 811R, 1059R, 1202R
invalid widget IDs 1268R
inverse
cosine 190R
of a complex array or matrix 694R
sine 203R
subspace iteration 446R
tangent 206R
INVERSE keyword 475R, 694R, 1348R
INVERT function 460U, 576R
IOCTL function 578R
IOERROR keyword 745R
IRND machine-specic parameter 703R
IRREGULAR keyword 304R
irregularly-gridded data 1131R, 1134R
ISA keyword 185O
IsContained method 186O
ISHFT function 581R
ISO Latin 1 encoding 68R
ISOLATIN1 keyword 127R
isosurfaces, displaying 351U, 1010R
ISOTROPIC keyword 360U, 304R, 729R, 800R
ISSUE_ERROR keyword 1146R
IT machine-specic parameter 703R
ITALIC keyword 127R
ITEM_COLOR keyword 274O
ITEM_LINESTYLE keyword 274O
ITEM_NAME keyword 274O
ITEM_OBJECT keyword 274O
ITEM_THICK keyword 274O
ITEM_TYPE keyword 275O
ITER keyword 421R, 602R, 678R, 839R
iterative
biconjugate gradient 601R
Gaussian quadrature 563R, 566R
improvement of a solution 697R
ITMAXkeyword 232R, 421R, 446R, 465R, 602R, 678R,
768R, 839R
ITOL keyword 601R
J
JFIF, seeJPEG
JMAX keyword 683R, 863R, 865R, 867R
JOIN, seeObsolete Routines
JOURNAL procedure 35U, 582R
journaling 35U
JPEG les
reading 907R
writing 1324R
JULDAY function 583R
Julian date
converting from calendar 583R
converting to calendar 242R
JUST_REG keyword 1364R
K
K keyword 863R, 865R
Kaiser lter 414U
KBRD_FOCUS_EVENTSkeyword 1209R, 1239R,
1274R, 1301R, 1311R
KEEP keyword 1382R
KEEP_PIXMAPSkeyword 1359R
KENDALL keyword 882R
Kendalls tau rank correlation 882R
kernel, convolving an array with 311R
KEY_ID keyword 896R, 934R
KEY_MATCH keyword 896R, 934R
KEY_VALUE keyword 896R, 934R
keyboard
dening keys 399R
focus events 311B, 1209R, 1239R, 1274R, 1301R,
1311R
numeric keypads 1001R
returning characters from 514R
shortcuts
IDLDE for Motif 55U
Index L ... L Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-36 Index
KEYED keyword 789R
KEYSkeyword 538R
keys, dening for different keyboards 1000R
KEYWORD_SET function 124B, 125B, 585R
keywords
arguments,checking existence of 198R
described 181O, 185R
graphics 99R
identifying as set 585R
inheritance 114B
meaning of slash character 181O, 185R
parameters 111B
passing 113B
searching 781R
setting 111B, 181O, 185R
KEYWORDSkeyword 608R
KILL_ANYWAY keyword 345R
KILL_NOTIFY keyword 1209R, 1223R, 1239R, 1254R,
1263R, 1281R, 1286R, 1292R, 1301R, 1311R
killing widgets 300B
KMEANS, seeObsolete Routines
KRIG2D function 445U, 586R
kriging 445U, 586R
KRUSKAL_WALLIS, seeObsolete Routines
Kruskal-Wallis H-Test 591R
kurtosis 590R, 755R
KURTOSISfunction 590R
KW_TEST function 448U, 476U, 591R
KX keyword 1002R
L
L64 keyword 561R
L64_VALUE keyword 247R
L64INDGEN function 593R
L64SWAP keyword 236R
Label button property 214U
LABEL keyword 351R, 358R, 711R, 727R
label widgets 274B, 1280R
attributes, setting 221U
using 165U
LABEL_DATE function 594R
LABEL_LEFT keyword 355R
LABEL_REGION function 596R
LABEL_TOP keyword 355R
labeling regions 596R
LADFIT function 438U, 598R
lagged
Laguerres method 502R
LAMBERT keyword 724R
Lamberts conformal conic map projection 371U, 724R
Lamberts equal-area map projection 365U, 724R
LANDSCAPE keyword 348O, 127R
landscape orientation 159R
for IDL plots (LANDSCAPE keyword) 127R
laser printers 157R
LAST_MESSAGE keyword 538R
LAT0 keyword 719R
LAT1 keyword 719R
LATALIGN keyword 711R, 727R
LATDEL keyword 363U, 712R, 727R
LATLAB keyword 712R, 727R
LATLON, seeObsolete Routines
LATMAX keyword 716R
LATMIN keyword 716R
LATNAMESkeyword 712R
LATSkeyword 712R
LAYER eld 192O
LAYER keyword 192O, 199O
Layout base property 205U
LE operator 277U, 36B
leakage (in freqency plots) 405U
least absolute deviation 438U, 598R
least squares t 437U, 438U, 335R, 511R, 824R, 831R,
1098R
LEEFILT function 600R
legend object 30O
legend objects 97O
LEGEND_PROPERTIESkeyword 662R
LEGENDRE keyword 1099R
LEGO keyword 1091R
LEGO, seeObsolete Routines
LEN keyword 488R
LENGTH keyword 388R, 766R, 806R, 1182R, 1184R
length of strings 1080R
LEVELSkeyword 328U, 304R
license manager 414R
lifecycle
methods 255B
routines 255B
LIGHT keyword 127R, 994R
light object 29O, 278O
light objects 104O, 107O
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index L ... L
Index Index-37
creating 108O
types of lights 108O
using 108O
light source 278O
changing parameters of 350U
shading 349U, 994R
lighting 126O, 149O
LIGHTING keyword 291O
LIGHTING_MODEL keyword 410O
LIMIT keyword 360U, 729R
LIMSER keyword 296R
LINBCG function 466U, 601R
LINDGEN function 603R
line
drawing
method for contours 300R
PLOTS procedure 809R
editing 24U
enabling and disabling 42R
interval 46R
styles 103R
LINE keyword 650R
LINE_FILL keyword 827R
linear
algebra, See linear algebra 431U
correlation 431U
interpolation 573R
linear-log plots 801R
regression 438U, 947R
systems 453U
overdetermined 454U
underdetermined 456U
linear algebra
CHOLDC 267R
CHOLSOL 268R
COND 290R
CRAMER 319R
DETERM 417R
EIGENVEC 446R
ELMHES 448R
GS_ITER 525R
HQR 551R
INVERT 576R
LINBCG 601R
LU_COMPLEX 694R
LUDC 696R
LUMPROVE 697R
LUSOL 699R
NORM 769R
SVDC 1096R
SVSOL 1102R
TRIQL 1140R
TRIRED 1142R
TRISOL 1143R
LINEAR keyword 1128R
LINESTYLE eld 192O
LINESTYLE keyword 319O, 329O, 338O, 364O, 102R,
641R, 657R
LINESTYLE system variable eld 49R
linestyles, table of 103R
LINFIT function 438U, 604R
linked lists 242B
using pointers to create 242B
LINKIMAGE 1404
LINKIMAGE procedure 245R, 606R
LIST keyword 789R
list widgets 274B, 1285R
determining
currently selected element
LIST_SELECT keyword 1274R
topmost element
LIST_TOP keyword 1274R
double-clicks 1290R
number 1274R
selecting multiple items 1274R, 1286R
setting 1243R
LIST_NUM_VISIBLE keyword 1274R
LIST_NUMBER keyword 1274R
LIST_SELECT keyword 1274R
LIST_TOP keyword 1274R
listbox widgets
attributes 226U
events 227U
initial value 226U
multiple selections, allowing 226U
selection events 227U
setting height 226U
using 165U
width 227U
LISTREP, seeObsolete Routines
LISTWISE, seeObsolete Routines
little endian byte ordering 1104R
LIVE_CONTOUR procedure 612R
LIVE_CONTROL procedure 619R
LIVE_DESTROY procedure 621R
LIVE_EXPORT procedure 623R
Index L ... L Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-38 Index
LIVE_IMAGE procedure 625R
LIVE_INFO procedure 630R
LIVE_LINE procedure 640R
LIVE_LOAD procedure 644R
LIVE_OPLOT procedure 645R
LIVE_PLOT procedure 649R
LIVE_PRINT procedure 655R
LIVE_RECT procedure 656R
LIVE_STYLE procedure 659R
LIVE_SURFACE procedure 665R
LIVE_TEXT procedure 671R
LJ device
color tables for 674R
LJ driver 151R
LJLCT procedure 674R
LL_ARC_DISTANCE function 675R
LM_LICENSE_FILE environment variable 23U
LMFIT function 677R
LMGR function 680R
LMHOSTID keyword 681R
LN03, seeObsolete Routines
LNGAMMA function 682R
LNP_TEST function 448U, 683R
LOAD_FILE keyword 197R
LoadCT method 306O
LOADCT procedure 389U, 685R
loading color tables 1159R
LOCATION keyword 210O, 266O, 282O, 393O, 432O,
613R, 626R, 641R, 650R, 657R, 666R, 672R
location of graphics 42O
location of text 81O
location of widgets 306B
LOCATIONSkeyword 385O
LOG keyword 211O
logarithm
base 10 192R
natural 191R
of the gamma function 682R
logarithmic
axes, [ XYZ] LOG keywords 208R, 307R, 801R,
1006R, 1093R
scaling 305U
logarithmic plots 76O
logging an IDL session 582R
logical names (VMS)
dening 998R
deleting 412R
searching tables 1145R
logical names, seeenvironment variables
logical unit numbers 162B
!D system variable eld 47R
allocating 516R
for journal le 43R
freeing 493R
FSTAT function 494R
getting 785R
obtaining status information 494R
returning information about 538R
setting le position pointer 813R
LOGIN.COM le 20U
LOGISTIC keyword 283R
log-linear plots 208R, 307R, 801R, 1006R, 1093R
LOGSQUARE keyword 283R
Lomb Normalized Periodogram 683R
LON0 keyword 719R
LON1 keyword 719R
LON64ARR function 686R
LONALIGN keyword 712R, 727R
LONARR function 687R
LONDEL keyword 363U, 712R, 727R
LONG function 688R
long integer data type 12B
LONG keyword 369R, 561R, 706R, 1340R
LONG64 function 689R
longjmp, C language 255R
longword
arrays 603R, 687R, 1171R
unsigned arrays 1170R
LONLAB keyword 713R, 727R
LONMAX keyword 716R
LONMIN keyword 716R
LONNAMESkeyword 713R
LONSkeyword 713R
lossy compression 907R, 1324R
LOW keyword 352U, 1011R
lower margin, setting 53R
LOWER_ONLY keyword 1091R
lowercase, converting strings to 1081R
lowpass lters 414U
LPF_BAND keyword 987R, 990R
LSODE function 690R
LSWAP keyword 236R
LT operator 278U, 36B
LU decomposition 694R, 696R, 699R
LU_COMPLEX function 460U, 694R
LUBKSB, seeObsolete Routines
LUDC procedure 460U, 696R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index M ... M
Index Index-39
LUDCMP, seeObsolete Routines
luminance 329R
LUMPROVE function 460U, 697R
LUNs (logical unit numbers) 162B, 493R
LUSOL function 460U, 699R
M
M_CORRELATE function 435U, 476U, 701R
MACCREATOR keyword 787R, 1048R
MACHAR function 428U, 703R
MACHEP machine-specic parameter 703R
machine-specic parameters 703R
Macintosh
backing store 130U
color palette 130U
compiling functions and procedures 135U
display device (MAC) 112R, 154R
displaying images 130U
editor windows 119U
errors 136U
IDLDE 118U
changing working directory 135U
LUN (logical unit number) differences 136U
mouse differences 134U
optimizing performance with memory 133U
path specication 44R
pixel depth 130U
positioning le pointers 136U
reading and writing les 136U
saving/restoring les 136U
specifying le search path 132U, 133U
using batch les 132U
MACTYPE keyword 787R
magnetic tape 224B
magnifying arrays 935R
magnitude
of a complex number 189R
of spectra 404U
magnitude-based ranks 892R
main
directory
IDLDE for Motif 66U
programs 29U
window, setting preferences
IDLDE for Motif 58U
IDLDE for Windows 59U, 104U
MAJOR keyword 211O, 243O
MAKE_ARRAY function 705R
Maker Interchange Format 250U
MAKETREE, seeObsolete Routines
MANAGE_STYLE keyword 613R, 626R, 650R, 666R
MANAGED keyword 1239R, 1275R
managing the state of a widget application 312B
MANN_WHITNEY, seeObsolete Routines
Mann-Whitney U-Test 977R
MAP keyword 355R, 1209R, 1239R
map projections 358U, 723R
Aitoff 365U, 724R
Albers equal area conic 724R
Albers equal-area conic 372U
azimuthal 362U
azimuthal equidistant 365U, 724R
boundaries, specifying 360U
cylindrical 368U
cylindrical equidistant 371U, 724R
drawing boundaries over 708R
drawing continent boundaries 359U, 726R
drawing parallels and meridians 711R
gnomonic(central, gnomic) 363U, 724R
Hammer-Aitoff 366U, 724R
high-resolution outlines 377U
Lamberts conformal conic 371U, 724R
Lamberts equal area 365U, 724R
Mercator 369U, 724R
Miller 724R
Miller cylindrical 371U
Mollweide 374U, 725R
orthographic 362U, 725R
Robinson 373U
satellite 366U, 725R
sinusoidal 373U, 725R
stereographic 362U, 725R
Transverse Mercator (UTM) 369U, 725R
warping images to maps 375U, 715R, 718R
MAP_ALL keyword 281R
MAP_CONTINENTSprocedure 358U, 360U, 708R
MAP_GRID procedure 358U, 360U, 711R
MAP_IMAGE function 358U, 715R
MAP_PATCH function 718R
MAP_PROJ_INFO routine 721R
MAP_SET procedure 358U, 723R
mapping widgets 1209R
MARGIN system variable eld 53R
Index M ... M Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-40 Index
margins, setting 53R
marquee selector 227R
MASK keyword 438O
MATCH_PREVIOUSkeyword 402R
math errors 151B
mathematical operators 270U, 28B
mathematics 426U
matrices, multiplying 272U, 31B
MATRIX keyword 1186R
matrix operators
CHOLDC 267R
CHOLSOL 268R
COND 290R
CRAMER 319R
DETERM 417R
EIGENVEC 446R
ELMHES 448R
GS_ITER 525R
HQR 551R
INVERT 576R
LU_COMPLEX 694R
LUDC 696R
LUMPROVE 697R
LUSOL 699R
NORM 769R
SVDC 1096R
SVSOL 1102R
TRIQL 1140R
TRIRED 1142R
TRISOL 1143R
Seealso sparse arrays
MAX function 731R
MAX keyword 238R, 390R, 547R, 747R
MAX_ARGSkeyword 608R
MAX_VALUE keyword 309U, 253O, 320O, 365O,
304R, 716R, 719R, 792R, 800R, 1005R, 1092R,
1135R
MAXEXP machine-specic parameter 703R
MAXIMIZE keyword 296R
maximum intensity projection 126O
MAXIMUM keyword 378R, 1293R
maximum operator 272U, 30B
maximum size of drawable 136O, 424O
maximum value
for slider widgets 1293R
of an array 731R
MAXIMUM_INTENSITY keyword 1193R
MAXV keyword 544R
MAXVAL keyword 461R, 878R, 913R
MBAR keyword 384R, 1209R
MD_TEST function 448U, 733R
MDC keyword 733R
MDEV keyword 756R
mean
MOMENT function 755R
of distribution 591R
MEAN function 735R
MEANABSDEV function 736R
median
Median Delta Test 733R
smoothing 738R
MEDIAN function 423U, 738R
MEDIAN keyword 736R
MEDIUM keyword 127R
memory
allocation under VMS 23U
conserving by using temporary variables 1117R
dynamic memory in use 539R
graphics system use 269B, 24O
optimizing performance
MEMORY keyword 539R
menu bars 1206R, 1209R
Menu Editor
opening 92U
Menu Editor, using 171U
MENU keyword 1224R
menus 295B
editing in IDL GUIBuilder 171U
menu items
IDLDE for Motif 43U
online help 242U
pulldown 298B, 1224R
system, using 207U
MENUS, seeObsolete Routines
MERCATOR keyword 724R
Mercator map projection 369U, 724R
meridians, drawing 359U, 711R, 727R
mesh plots 1090R
MESH_OBJ procedure 740R
MESHNAME keyword 1342R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index M ... M
Index Index-41
MESHNAMESkeyword 927R
message dialogs 277B, 423R
MESSAGE keyword 227R
MESSAGE procedure 147B, 745R
message widgets 274B
message-of-the-Day le
MESSAGESkeyword 539R
messages,suppressing informational 45R
METHOD keyword 557R
method overriding 263B
methods 261B
dening routines 261B
Windows 3.11 263B
invocation 258B
object 250B
Microsoft Windows
mouse differences 113U
Microsoft Windows display device (WIN) 112R, 170R
MIDEXP keyword 865R
MIDINF keyword 865R
MIDPNT keyword 865R
MIDSQL keyword 865R
MIDSQU keyword 865R
MIF 250U
Miller cylindrical map projection 371U
MILLER keyword 724R
Miller map projection 724R
MIN function 747R
MIN keyword 238R, 391R, 547R, 731R
MIN_ARGSkeyword 608R
MIN_CURVE_SURFfunction 329U, 445U, 300R, 748R
MIN_VALUEkeyword 253O, 320O, 365O, 304R, 716R,
792R, 800R, 1005R, 1092R, 1136R
MINEXP machine-specic parameter 703R
minimization 462U, 420R, 838R
downhill-simplex method. 463U
Seealso optimization
Minimize/Maximize base property 206U
minimum and maximum values of plot data 95O
minimum curvature surface 445U, 748R
MINIMUM keyword 378R, 1293R
minimum operator 272U, 30B
minimum value
for slider widgets (MINIMUM keyword) 1293R
of an array 747R
MINOR keyword 211O, 243O
MINOR system variable eld 53R
MINUS_ONE keyword 292R
MINV keyword 544R
MIPSkeyword 1001R
MIPSEB_DBLFIXUP, seeObsolete Routines
missing data 309U
in CONTOUR plots 304R
in irregular grids 1129R, 1136R
in map projections 716R
in plots 792R, 800R, 1005R, 1092R
in reconstruced images 941R
in rotated images 971R
in velocity elds 1185R
in warped images 821R
MISSING keyword 592R, 717R, 719R, 821R, 941R,
971R, 1129R, 1136R, 1185R
MISSING_VALUE keyword 899R
MK_HTML_HELP procedure 251U, 751R
MLINESTYLE keyword 709R, 728R
MLINETHICK keyword 709R, 728R
Modal base property 206U
modal dialogs, creating 206U
MODALkeyword 1028R, 1210R, 1275R, 1354R, 1361R,
1365R
MODE keyword 941R
model object 28O, 285O
model objects 37O
MODIFYCT procedure 391U, 754R
modules
compiled 540R
dynamically loaded 538R
modulo operator 271U, 30B
MOLLWEIDE keyword 725R
Mollweide map projection 374U, 725R
MONTHSkeyword 211O, 595R
MORE keyword 785R
morphology
dilation operator 432R
erosion operator 452R
Mosaic 251U, 751R
MOTION_EVENTSkeyword 1255R
mouse
double-clicks 1290R
emulating three-button 113U, 134U
reading position of 313U, 894R
readingpositon withtheCURSORprocedure 332R
returning events from draw widgets 1255R
Index N ... N Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-42 Index
mouse cursor, setting 137O
MOUSE keyword 442O, 443O
Move method 186O
MOVIE, seeObsolete Routines
movies
MPEG 757R, 758R, 760R, 762R
moving averages 1043R, 1151R
lters 414U
MPEG object 32O, 296O
MPEG objects 119O
MPEG_CLOSE keyword 1360R
MPEG_CLOSE procedure 757R
MPEG_FILENAME keyword 1358R
MPEG_OPEN function 758R
MPEG_OPEN keyword 1358R
MPEG_PUT procedure 760R
MPEG_SAVE procedure 762R
MPROVE, seeObsolete Routines
MSE keyword 1147R
MT_OFFLINE keyword 579R
MT_REWIND keyword 579R
MT_SKIP_FILE keyword 579R
MT_SKIP_RECORD keyword 579R
MT_WEOF keyword 579R
Mllers method 500R
MULTI keyword 441R
MULTI procedure 763R
MULTI system variable eld 50R
MULTICOMPARE, seeObsolete Routines
multidimensional minimzation 463U
multiple correlation coefcient 433U, 701R
Multiple Document Panel
IDLDE for Motif 41U
MULTIPLE keyword 904R, 905R, 1286R, 1322R
multiple plots on a page 306U, 50R
MULTIPLE_FILESkeyword 427R
multiplication operator 271U, 29B
multiplying arrays and matrices 430U
multivariate analysis
Kruskal-Wallis H-test 591R
multiple correlation 701R
partial correlation 795R
multivariate functions
CTI_TEST 330R
KW_TEST 591R
M_CORRELATE 701R
P_CORRELATE 795R
MUST_EXIST keyword 427R
N
N keyword 806R
N_CLUSTERSkeyword 274R, 275R
N_COLORSkeyword 223O, 234O, 304O, 420O
N_COLORSsystem variable eld 46R
N_DIMENSIONSkeyword 1023R
N_ELEMENTSfunction 112B, 124B, 125B, 764R
N_ELEMENTSkeyword 1023R
N_ITERATIONSkeyword 274R
N_LEVELSkeyword 253O
N_PARAMSfunction 112B, 124B, 126B, 765R
N_TAGSfunction 766R
N0 keyword 884R
N1 keyword 884R
Name common property 196U
NAMEkeyword 211O, 243O, 253O, 258O, 266O, 275O,
282O, 291O, 306O, 312O, 320O, 329O, 339O,
346O, 365O, 373O, 385O, 400O, 410O, 539R,
613R, 627R, 641R, 645R, 651R, 657R, 663R, 666R,
672R, 1082R, 1275R, 1378R
NAME system variable eld 46R
named
structures 262U, 42B
variables 184R, 185R
named variables 181O
names
of structure tags 1111R
of variables 265U, 21B
NaN (not-a-number) 152B
NAN keyword 238R, 547R, 590R, 731R, 735R, 736R,
747R, 756R, 1025R, 1044R, 1069R, 1123R, 1165R,
1179R
NaN values 1402
NARROW keyword 127R
native format (oating-point values) 235R
natural exponential funciton 460R
natural logarithm 191R
Navigate menu (online help) 246U
Navigation Dialog (online help) 248U
NCALLSkeyword 194R
NCAR binary encoding 127R, 128R
NCAR keyword 127R
NCAR Raster Interchange Format les, writing 1327R
NCOLORSkeyword 348O, 432O, 358R, 685R, 1361R
NCOLSkeyword 919R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index N ... N
Index Index-43
NCOPIESkeyword 349O
NE operator 278U, 36B
object references 259B
pointers 238B
near and far clipping planes 47O
NearestColor method 307O
negation operator 271U, 29B
NEGATIVE keyword 509R
NEGEP machine-specic parameter 703R
nesting of procedures and functions 537R, 540R
netCDF 1389R
Netscape 251U, 751R
new page 451R
new page (printing) 141O
NEW_AXESkeyword 646R
NEW_WINDOW keyword 1383R
NewDocument method 350O
NewPage method 350O
NEWTON function 462U, 767R
Newtons method 461U, 568R, 767R
NEXT_LINE keyword 404R
NFRAMESkeyword 348R
NGRD machine-specic parameter 703R
NLAT keyword 1053R
NLEVELSkeyword 305R
NLON keyword 1053R
NMAX keyword 194R
No Release button property 214U
NO_ALIASkeyword 998R
NO_BALANCE keyword 448R
NO_BLOCK keyword 1358R, 1365R
NO_COPYkeyword 266O, 410O, 857R, 1186R, 1211R,
1224R, 1240R, 1255R, 1263R, 1281R, 1287R,
1293R, 1301R, 1311R
NO_DIVIDE keyword 1186R
NO_DRAW keyword 614R, 619R, 621R, 627R, 642R,
646R, 651R, 657R, 667R, 672R
NO_HEADER keyword 1302R
NO_KILL keyword 342R
NO_NEWLINE keyword 1240R, 1311R
NO_POLISH keyword 502R
NO_RELEASE keyword 355R, 374R, 1224R
NO_STATUSkeyword 614R, 627R, 651R, 667R
NO_TOOLBAR keyword 614R, 627R, 651R, 667R
NOAUTOMODE keyword 787R
NOBORDER keyword 728R
NOCLIP keyword 103R
NOCLIP system variable eld 51R
NOCLISYM keyword 1049R
NODATA keyword 104R
NOECHO keyword 402R
NOEDIT keyword 369R
NOERASE keyword 104R, 728R
NOERASE system variable eld 51R
NOFILL keyword 407R
noise, ltering 738R
NOLATIN keyword 853R
NOLOGNAM keyword 1049R
NOMARK keyword 844R
NOMESHDEF keyword 1342R
NONAME keyword 745R
NONE keyword 789R
NONEXCLUSIVE keyword 355R, 1211R
noninteractive mode 32U, 34U
nonlinear equations 461U
BROYDEN 231R
CONSTRAINED_MIN 294R
FX_ROOT 500R
FZ_ROOTS 502R
NEWTON 767R
nonparametric tests 447U
LNP_TEST 683R
MD_TEST 733R
R_TEST 884R
RS_TEST 977R
S_TEST 980R
XSQ_TEST 1375R
non-printable characters 18B
NOPREFIX keyword 745R
NOPRINT keyword 746R
NOREGION keyword 407R
NORM function 460U, 769R
NORM keyword 1202R
norm_coord.pro (example le) 53O
normal
coordinates 286U
distribution (Gaussian) 506R, 507R
random deviates 891R
Normal Computations 148O
normal computations 92O
NORMAL keyword 104R, 309R, 333R, 833R
NORMALIZED keyword 200R
normally-distributed random numbers 886R
NORMALSkeyword 329O
NOSHELL keyword 1048R
NOSHOW keyword 1374R
NOSTDIO keyword 787R
Index O ... O Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-44 Index
and TRANSFER_COUNT 1344R
NOT operator 274U, 32B
notch lter 419U
NOTEXT keyword 211O
NOTIFY keyword 1049R
NOTIFY_REALIZE keyword 1211R, 1224R, 1240R,
1255R, 1264R, 1282R, 1287R, 1293R, 1302R, 1311R
NOTTYRESET keyword 1048R
NOWAIT keyword 333R, 1049R, 1268R
NOZERO keyword 233R, 287R, 398R, 490R, 570R,
686R, 687R, 706R, 778R, 860R, 1168R, 1171R,
1172R
NR_BETA, seeObsolete Routines
NR_BROYDN, seeObsolete Routines
NR_CHOLDC, seeObsolete Routines
NR_CHOLSL, seeObsolete Routines
NR_DFPMIN, seeObsolete Routines
NR_ELMHES, seeObsolete Routines
NR_EXPINT, seeObsolete Routines
NR_FULSTR, seeObsolete Routines
NR_HQR, seeObsolete Routines
NR_INVERT, seeObsolete Routines
NR_LINBCG, seeObsolete Routines
NR_LUBKSB, seeObsolete Routines
NR_LUDCMP, seeObsolete Routines
NR_MACHAR, seeObsolete Routines
NR_MPROVE, seeObsolete Routines
NR_NEWT, seeObsolete Routines
NR_POWELL, seeObsolete Routines
NR_QROMB, seeObsolete Routines
NR_QROMO, seeObsolete Routines
NR_QSIMP, seeObsolete Routines
NR_RK4, seeObsolete Routines
NR_SPLINE, seeObsolete Routines
NR_SPLINT, seeObsolete Routines
NR_SPRSAB, seeObsolete Routines
NR_SPRSAX, seeObsolete Routines
NR_SPRSIN, seeObsolete Routines
NR_SVBKSB, seeObsolete Routines
NR_SVD, seeObsolete Routines
NR_TQLI, seeObsolete Routines
NR_TRED2, seeObsolete Routines
NR_TRIDAG, seeObsolete Routines
NR_WTN, seeObsolete Routines
NR_ZROOTS, seeObsolete Routines
NRIF
les, writing 1327R
NROWSkeyword 919R
NSTEPSkeyword 488R, 1182R
NSUM keyword 320O, 792R, 801R
NSUM system variable eld 51R
NTERMSkeyword 511R
NTOHL keyword 236R
NTOHSkeyword 236R
Null display device (NULL) 154R
NUM_KEYPAD keyword 1001R
NUM_RECORDSkeyword 899R
number of array elements 764R
numbers, random 886R, 890R
numeric keypads 1001R
numerical integration 449U, 866R
Numerical Recipes 426U
NVARIABLESkeyword 797R
NVECSkeyword 488R, 1182R
NX keyword 588R, 1130R, 1136R
NY keyword 588R, 1130R, 1136R
Nyquist frequency 409U
O
OBCELL keyword 1375R
OBJ keyword 536R, 706R
obj_axis.pro (example le) 75O
OBJ_CLASSfunction 259B, 771R
OBJ_DESTROY function 257B
OBJ_DESTROY procedure 772R
OBJ_ISA function 260B, 773R
obj_logaxis.pro (example le) 76O
OBJ_NEW function 256B, 774R
obj_plot.pro (example le) 100O
obj_tess.pro (example le) 71O
OBJ_VALID function 260B, 776R
obj_vol.pro (example le) 122O
OBJARR function 257B, 778R
object
class 250B
class structures 251B
encapsulation 250B
heap variables 250B
inheritance 251B, 253B
instances 250B
lifecycle 255B
method routines 261B
naming conventions 27O
persistence 251B
polymorphism 251B
Object Graphics 22O
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index O ... O
Index Index-45
object graphics 148O
Expose Events 148O
Object Graphics 149O
object heap variables 254B
object oriented programming 250B
objects
creating 774R
arrays 778R
destroying 257B, 772R
determining
class names 771R
subclasses 773R
Object Graphics 268B, 23O
clipboard support
Macintosh 120U
Windows 88U
font use 66R
object-oriented
graphics 268B, 24O
references for heap variables 230B
testing existence 776R
OBJECTSkeyword 539R
OBLIQUE keyword 337U, 128R, 1109R
obsolete routines and system variables 1391R
Obtaining Traceback Information 148B
OCCLUDED keyword 1202R
octal 14B
Oetli, Thomas 377U
OFAC keyword 683R
OFFSET keyword 362R
OMARGIN system variable eld 53R
OMAX keyword 547R
OMIN keyword 547R
ON_ERROR procedure 142B, 145B, 745R, 779R
ON_IOERROR procedure 780R
OnButton Press event property 215U
ONCE keyword 230R
OnDestroy property 200U
one-tailed hypothesis tests 447U
OnFocus event property 210U
ONGLASSkeyword 385O
OnKillRequest event property 210U
online help 242U, 440R, 751R
"Back" button 247U
annotate 244U
bookmark menu 244U
browse buttons 247U
button bar 247U
calling from programs 781R
contents button 247U
contents tab 248U
copying a topic 243U
edit menu 243U
extending 249U
File menu 243U
nd tab 249U
help menu 246U
index tab 248U
menus 242U
Navigate menu 246U
Navigation dialog 248U
printing 243U
view menu 246U
ONLINE_HELP procedure 250U, 781R
ONLY_8BIT, seeObsolete Routines
OnRealize event property 200U
OnSizeChange event property 210U
on-the-glass text 82O
OnTimer event property 200U
OnTracking event property 200U
opacities 1192R
OPACITY keyword 403O
opacity table 124O
OPACITY_TABLE0 keyword 410O
OPACITY_TABLE1 keyword 410O
OPAQUE keyword 851R
OPEN procedures 783R
Index P ... P Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-46 Index
OPEN_FUNC keyword 342R
opening les 160B, 783R
getting information on open les 537R
opening operation, in image processing 433R
OpenVMSseeVMS
operating system
commands, issuing 31U
current version in use 45R
operations on objects 258B
operations on pointers 235B
operators 270U, 28B
addition 270U, 29B
AND 274U, 32B
array concatenation 273U, 31B
assignment 270U, 28B
Boolean 274U, 32B
division 271U, 29B
EQ 277U, 35B
exponentiation 271U, 29B
GE 277U, 35B
GT 277U, 36B
LE 277U, 36B
LT 278U, 36B
mathematical 270U, 28B
matrix multiplication 272U, 31B
maximum 272U, 30B
minimum 272U, 30B
modulo 271U, 30B
multiplication 271U, 29B
NE 278U, 36B
NOT 274U, 32B
OR 274U, 32B
parentheses 270U, 28B
precedence 268U, 26B
relational 275U, 34B
square brackets 270U, 28B
subtraction and negation 271U, 29B
XOR 274U, 33B
OPLOT procedure 287U, 292U, 792R
OPLOTERR procedure 794R
optimization 462U
AMOEBA function 193R
CONSTRAINED_MIN 294R
DFPMIN 420R
POWELL 838R
OPTIMIZE keyword 128R
optional parameters in user-written functions 765R
OR operator 274U, 32B
ORDERkeyword 266O, 346R, 362R, 436R, 623R, 760R,
848R, 908R, 923R, 1041R, 1151R, 1154R, 1162R,
1325R, 1333R, 1359R
ORDERED keyword 129R
ordinary differential equations
LSODE function 690R
ordinary differential equations, RK4 967R
ORIENTATION keyword 312O, 104R, 709R, 713R
orientation, 3-dimensional 276B
ORIGIN system variable eld 47R
ORTHOGRAPHIC keyword 725R
orthographic map projection 362U, 725R
OUT executive command Seecommands
OUT_VAL keyword 470R
outer margins, setting 53R
outline fonts 65R
OUTLINE keyword 211R
OUTLINE_COLOR keyword 275O
OUTLINE_THICK keyword 275O
outlines of continents 708R
outlying data regression 598R
OUTP, seeObsolete Routines
output
BMP les 1320R
GIF les 1322R
JPEG les 1324R
NRIF les 1327R
PGM les 1331R
PICT les 1328R
PPM les 1331R
SRF les 1333R
TIFF les 1337R
wave les 1342R
OUTPUT keyword 129R, 539R, 846R
Output Log
IDLDE for Motif 41U
OUTPUT_SIZE keyword 1197R
OUTPUTSkeyword 441R
overow, integer 154B, 703R
overlaying images and contour plots 324U
OVERPLOT keyword 211R, 305R
overplotting 792R
OVERWRITE keyword 444R, 476R, 945R, 1348R
P
P_CORRELATE function 435U, 476U, 795R
P0 keyword 194R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index P ... P
Index Index-47
P0LAT keyword 359U
P0LON keyword 359U
P1 - P5 keywords 742R
PACKED keyword 204R
page break 451R
PAIRED keyword 1121R
PALATINO keyword 129R
PALETTE keyword 205O, 223O, 234O, 243O, 247O,
266O, 315O, 329O, 349O, 359O, 380O, 420O,
433O
palette object 31O, 302O
palette objects 60O, 66O
PALETTE, seeObsolete Routines
palettes 116O
pan offset 47R
parallel projection 44O
parallels, drawing 359U, 711R, 727R
parameters
actual 110B, 111B
copying 112B
nding number of 765R
formal 110B, 111B, 181O, 185R
passing mechanism 110B, 120B
PARAMETERSkeyword 975R
parametric hypothesis tests 447U
PARENT keyword 208O, 240O, 250O, 263O, 272O,
281O, 290O, 318O, 327O, 337O, 362O, 383O,
391O, 399O, 405O, 1275R
PARENT_BASE keyword 614R, 627R, 651R, 667R
parentheses 270U, 28B
parents, of widgets 1275R
partial correlation coefcient 433U, 795R
PARTIAL_COR, seeObsolete Routines
PARTIAL2_COR, seeObsolete Routines
passing parameters 120B
path
denition string 462R
IDLDE for Motif 65U
on a Macintosh 134U, 44R
PATH environment variable 20U
PATH keyword 207O, 222O, 225O, 233O, 236O, 240O,
249O, 262O, 271O, 280O, 289O, 317O, 326O,
336O, 347O, 352O, 361O, 382O, 404O, 413O,
419O, 422O, 430O, 435O, 427R, 441R
PATH_DATA_COORDSkeyword 305R
PATH_FILENAME keyword 320U, 305R
PATH_INFO keyword 306R
PATH_XY keyword 306R
PATTERN keyword 312O, 827R
pattern object 31O, 310O
pattern objects 66O
PCL
driver 154R
les 146R
PCOMP function 476U, 796R
Pearson correlation coefcient 315R
penta.pro (example le) 69O
performance
analyzing 141U
optimizing with memory
performance tuning with object graphics 145O
period (character) 59R
permutation 473R
persistence 251B
PERSP keyword 323R
perspective 1109R
PERSPECTIVE keyword 337U, 1109R
perspective projection 44O
PGM les 913R, 1331R
phase 206R
of spectra 404U
PHASER, seeObsolete Routines
Pickdata method 224O, 235O, 351O, 421O, 434O
PICKFILE, seeObsolete Routines
PickVoxel method 412O
PICT les
reading 910R
writing 1328R
PID keyword 1048R
PIVOT keyword 971R
pixels 380U
depth 121R
xed 326U
reading value of 894R
scalable 325U, 383U
PIXELSkeyword 129R, 1005R
PIXMAP keyword 1318R
pixmap objects
using 136O
PIXMAPSkeyword 342R
PLANAR keyword 254O
PLANARCONFIG keyword 924R, 1340R
plane of vector-drawn text 1380R
Index-48 Index
PLIST keyword 1009R
plot object 29O, 315O
plot objects 93O
averaging points 96O
creating 93O
minimum and maximum values 95O
plotting symbols 95O
using 94O
PLOT procedure 287U, 312U, 343U, 800R
PLOT_3DBOX procedure 803R
PLOT_FIELD procedure 806R
PLOT_IO, SeeYLOG keyword to PLOT
PLOT_OI, SeeXLOG keyword to PLOT
PLOT_OO, See(XY)LOG keywords to PLOT
PLOT_TO keyword 129R
PLOTERR procedure 808R
plots 86O
contour 318U
lled contour 330U
logarithmic 305U, 76O
margins 53R
outer margins 53R
overplotting 292U
shaded surface 349U
surface 331U
X versus Y 287U
PLOTSprocedure 809R
PLOTTER_ON_OFF keyword 129R
plotting 284U, 800R
2D elds 806R
3D elds 488R
3D transformations 107R, 314R, 350R, 380R,
984R, 985R, 1095R, 1109R, 1186R
annotation 293U
axes 310U
scaling 288U
thickness 107R
titles 109R
bar plots 210R
closing les (CLOSE_FILE keyword) 117R
combining images with graphics 347U
contour plots 300R, 559R
drawing axes (AXISprocedure) 207R
error bars 456R, 794R, 808R
lename for output (FILENAME keyword) 123R
ow eld 488R
font selection 294U
functions of 2 variables 803R
height of output 143R
histogram 105R
histogram style 297U
keyword parameters 284U
line thickness 52R, 107R
lines 809R
linestyles 49R, 102R
location on page 307U
logarithmic axes
linear-log 801R
log-linear 208R, 307R, 801R, 1006R, 1093R
missing data 309U
MAX_VALUE keyword 792R, 800R
multi-dimensional arrays 318U
multiple plots on a page 306U, 50R, 162R
output, positioning 148R
overplotting 292U, 559R, 792R
points 809R
polar 312U, 793R, 801R
portrait orientation 130R
position of window 51R, 104R
region 51R
selecting a plotting device 992R
shaded surfaces 1004R
subtitles 51R, 106R
symbol size 106R
symbols 295U, 296U, 51R, 105R
text 1379R
three-dimensional lines 810R
titles 289U, 52R, 109R
two-dimensional arrays 318U
user-dened symbols 1177R
velocity eld 488R
velocity elds 1184R
weather fronts 1201R
width of output 142R
wire-mesh surfaces 1090R
without data 104R
without erasing 51R, 104R
XY plots 800R
Z-coordinate for 110R
PM, seeObsolete Routines
PMF, seeObsolete Routines
PNG les
PNT_LINE function 811R
POINT_LUN procedure 157B, 813R
pointer heap variables 254B
pointers 230B, 254B
Index Index-49
creating 857R
creating arrays 860R
destroying 856R
examples 242B
examples of using 242B
le positioning
Macintosh 136U
le positoning
Windows 114U
freeing 242B
testing existence 858R
validity 241B
POISSON keyword 887R, 891R
Poisson random deviates 887R, 891R
POLAR keyword 320O, 651R, 793R, 801R
polar plots 312U, 801R
contours 815R
coordinates 338R, 817R
POLAR_CONTOUR procedure 815R
POLAR_SURFACE function 445U, 817R
polishing of roots 502R
political boundaries 708R
POLY function 819R
POLY_2D function 820R
POLY_AREA function 823R
POLY_FIT function 438U, 824R
POLY_SHADESkeyword 833R
POLYCONTOUR, seeObsolete Routines
POLYFILL keyword 130R
POLYFILL procedure 826R
POLYFILLV function 829R
POLYFITW function 438U, 831R
polygon lling 298U, 826R, 829R
with HP plotters 130R
Polygon mesh optimization 145O
polygon object 29O, 324O
polygon objects 88O
creating 88O
pattern lls 89O
rendering style 89O
shading 89O
texture mapping 90O
using 89O
POLYGONSkeyword 254O, 330O, 376O
polyline object 29O, 334O
polyline objects 92O
creating 93O
shading and coloring 93O
using 93O
using symbols 93O
POLYLINESkeyword 339O
polymorphism
objects 251B
polynomial warping 820R
POLYSHADE function 832R
POLYWARP procedure 835R
POPD procedure 257R, 837R
PORTABLE keyword 247R
portable unformatted I/O 197B
PORTRAIT keyword 130R
portrait orientation 159R
for IDL output (PORTRAIT keyword) 130R
POSITION keyword 183O, 185O, 187O, 286O, 292O,
354O, 358O, 389O, 395O, 397O, 401O, 104R
position of graphics 42O
POSITION system variable eld 51R
positional parameters 111B, 180O, 184R
returning number of 765R
positioning
child widgets within a base 1218R
commands 81R
cursor 1157R
graphics cursor 332R
PostScript output 159R
top level base widgets 1247R
widget bases 1219R
windows (XPOSand YPOSkeywords) 1318R
positioning objects 42O
PostCreation event property 201U
PostScript
color 158R
device 156R
encapsulated 122R, 160R
EPSI (Encapsulated PostScript Interchange)
les 130R
les 146R
les with preview headers 130R
font index 124R
fonts 158R, 853R
importing graphics into other programs 163R
importing into another document 122R
multiple plots on a single page 162R
pixel bit depth 116R
positioning output 159R
scaling entire plot (SCALE_FACTOR
keyword) 132R
Index-50 Index
true-color images 158R
writing 24-bit images 159R, 1155R
Powell minimization (POWELL procedure) 463U, 838R
POWELL procedure 463U
power spectrum 406U
PPM les 913R, 1331R
preferences, setting
IDLDE for Motif 57U
PREFIX keyword 530R, 534R
PREMULTIPLY keyword 294O, 295O
PRESERVE keyword 1356R
PREVIEW keyword 130R
PREVIOUS_LINE keyword 404R
PRIMESfunction 840R
principal components analysis 472U, 796R
PRINT keyword 261R, 440R, 789R, 1077R
PRINT procedure 158B, 841R
PRINT_FILE keyword 131R
PRINT_QUALITY keyword 349O
PRINTD procedure 257R, 843R
Printer Control Language, see PCL
PRINTER device 156R
printer object 32O, 342O
starting a new page 141O
submitting print jobs 141O
printer objects 139O
color model 140O
creating 139O
dialogs 140O
drawing to 140O
PRINTF procedure 158B, 841R
printing 28U, 156R
closing les (CLOSE_FILE keyword) 117R
dialog 277B, 429R
lename for output (FILENAME keyword) 123R
graphics output les 146R
help topics 243U
IDLDE for Motif 44U
printer set up 147R
properties 277B, 430R
setup dialog 277B, 430R
to le units 841R
to standard output 841R
printing dialogs 277B
PRINTNAMESexample routine 244B
PRO_SET_VALUE keyword 1211R, 1225R, 1241R,
1255R, 1264R, 1282R, 1287R, 1293R, 1302R, 1312R
PROB keyword 604R
probability
bivariate distributions 544R
density distribution 546R
Gaussian distribution 513R
Histogram function 546R
probability functions
binomial distribution 221R
Chi-square distribution 265R, 266R
F distribution 471R, 472R
Gaussian distribution 506R, 507R
students T distribution 1107R, 1108R
PROBD keyword 883R
procedure methods
calling sequence for 180O
procedures 29U
call stack, returning 537R
call statement 104B
calling
mechanism 121B
sequence for 184R
compiled 975R
denition statements 110B
DEVICE 111R
DFPMIN 463U
displaying compiled 540R
POWELL 463U
SET_PLOT 111R
PROFILE function 844R
PROFILER procedure 846R
PROFILESprocedure 848R
proling 141U
program
les 29U
listings 34R
Program Control Routines 128B
programming
displaying traceback information 540R
format of program les 28U
identifying keywords as set 585R
main programs 29U
preparing and running programs 28U
routines 124B
stopping programs 1070R
suspending execution of programs 1196R
Index Index-51
traceback information 538R
PROGRESSIVE keyword 624R, 1325R
PROJECT_VOL function 850R
projection 43O
parallel 44O
perspective 44O
PROJECTION keyword 393O
projection matrix 455U
projections
2D from 3D datasets 850R
Aitoff 365U, 724R
Albers equal-area conic 372U
Albers 724R
azimuthal 362U
azimuthal equidistant 365U, 724R
backprojection 963R
cylindrical 368U
cylindrical equidistant 371U, 724R
gnomonic (central, gnomic) 363U, 724R
Hammer-Aitoff 366U, 724R
Lamberts conformal conic 371U, 724R
Lamberts equal area 365U, 724R
Mercator 369U, 724R
Miller 724R
Miller cylindrical 371U
Mollweide 374U, 725R
orthographic 362U, 725R
Robinson 373U
satellite 366U, 725R
sinusoidal 373U, 725R
stereographic 362U, 725R
Transverse Mercator (UTM) 369U, 725R
prompt
changing default 45R
reading from 896R
PROMPT keyword 896R
PROMPT, seeObsolete Routines
properties
draw area widget 229U
entering multiple strings 169U
label widget 221U
retrieving 33O
setting 33O
table widget 234U
text widget 216U
Properties dialog 166U
# of Rows/Columns base property 202U
Alignment base property 203U
Alignment button property 213U
Allow Moving base property 204U
Allowing Closing base property 203U
Bitmap button property 213U
Color Model draw area property 229U
Component Sizing common property 197U
draw area events 232U
draw area widget properties 229U
droplist widgets 224U
entering multiple strings 169U
Floating base property 204U
Frame common property 197U
Grid Layout base property 204U
Label button property 214U
Layout base property 205U
listbox events 227U
Minimize/Maximize base property 206U
Modal base property 206U
Name common property 196U
No Release button property 214U
OnButtonPress button event 215U
OnDestroy common event 200U
OnFocus base event 210U
Index Q ... Q Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-52 Index
OnKillRequest base event 210U
OnRealize common event 200U
OnSizeChange base event 210U
OnTimer common event 200U
OnTracking common event 200U
opening 92U, 167U
PostCreation common event 201U
Scroll base property 206U
Sensitive common property 198U
setting label widget properties 221U
Space base property 207U
System Menu base property 207U
table events 237U
table widget properties 234U
Title Bar base property 208U
Title base property 207U
Type button property 214U
Visible base property 208U
X Offset common property 198U
X Pad base property 208U
X Scroll base property 209U
X Size common property 198U
Y Offset common property 198U
Y Pad base property 209U
Y Scroll base property 209U
Y Size common property 199U
PROPERTIESkeyword 620R, 630R
properties of objects 33O
PS_SHOW_FONTSprocedure 853R
PSAFM procedure 854R
PSEUDO procedure 391U, 855R
PSEUDO_COLOR keyword 131R
pseudo-color images, converting from true-color 279R
pseudo-color PostScript images 158R
pseudocylindrical map projections 373U
PSYM keyword 295U, 105R, 808R, 1202R
PSYM system variable eld 51R
PTR keyword 536R, 706R
PTR_FREE procedure 856R
PTR_NEW function 857R
PTR_VALID function 858R
PTRARR function 860R
pulldown menu 382R, 1224R
PUSHD procedure 257R, 861R
Put method 300O
PutEntity method 200O
PWIDGET, seeObsolete Routines
Q
QL algorithm 1140R
QL method (computing eigenvalues) 444R
QROMB function 453U, 862R
QROMO function 453U, 864R
QSIMP function 453U, 866R
Quad strips 146O
quadrature function 411U
QUALITY keyword 223O, 234O, 299O, 420O, 624R,
1325R
QUALITY keywprd 349O, 433O
quantizing colors 279R
QUERY_* routines 868R
QUERY_BMP routine 870R
QUERY_DICOM 177O, 871R
QUERY_GIF routine 873R
QUERY_JPEG routine 874R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index R ... R
Index Index-53
QUERY_PICT routine 875R
QUERY_PNG routine 876R
QUERY_PPM routine 878R
QUERY_SRF routine 879R
QUERY_TIFF routine 880R
QUESTION keyword 424R
question mark
character 61R
online help system 242U
QuickHelp 250U
QUIET keyword 379O, 952R
quintic interpolation 1136R
QUINTIC keyword 1136R, 1197R
QUIT keyword 782R
quitting IDL 21U, 459R
quotas 139B
quotation marks 258U, 17B, 59R
R
R keyword 884R
R_CORRELATE function 435U, 448U, 882R
R_TEST function 448U, 884R
RADIANSkeyword 323R, 470R
radio button widgets
creating 212U
creating multiple 212U
laying out 213U
using 165U
radix 703R
Radon transform 963R
random deviates
binomial 887R, 891R
exponential 887R, 891R
gamma 887R, 891R
normal 891R
Poisson 887R, 891R
random 891R
random numbers
normally-distributed 886R
uniformly-distributed 890R
RANDOMN function 886R
RANDOMU function 890R
RANGE keyword 211O, 654R
RANGE system variable eld 54R
rank correlation coefcient 882R
RANKSfunction 892R
rank-sum test 977R
raster images 380U
RDPIX procedure 894R
READ keyword 427R
Read method 201O, 225O, 435O
READ procedure 158B, 895R
READ_ASCII function 898R
READ_BMP function 901R
READ_DICOM 176O, 903R
READ_GIF procedure 904R
READ_INTERFILE procedure 906R
READ_JPEG procedure 907R
READ_KEY procedure 896R
READ_PICT procedure 910R
READ_PNG function 911R
READ_PPM procedure 913R
READ_SPR function 466U, 915R
READ_SRF procedure 916R
READ_SYLK function 918R
READ_TABLESkeyword 329R
READ_TIFF function 921R
READ_WAVE procedure 926R
READ_X11_BITMAP procedure 928R
READ_XWD function 930R
READF procedure 158B, 895R
reading
ASCII les 898R
BMP les 901R
current color table 1160R
cursor position 894R
data from a string 931R
les (OPENR procedure) 783R
formatted data 895R
from a prompt 896R
from tapes 1114R
GIF les 904R
images from the display 385U, 1161R
Interle les 906R
JPEG les 907R
mouse position 332R
PGM les 913R
PICT les 910R
pixel values 894R
PPM les 913R
SRF les 916R
TIFF les 921R
wave les 926R
X11 bitmaps 928R
Index R ... R Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-54 Index
XWD les 930R
reading and writing les, Macintosh differences 136U
READNAMESexample routine 242B
read-only system variables 409R
READSprocedure 213B, 931R
READU procedure 158B, 933R
real part of complex numbers 486R
REALIZE keyword 1241R
REALIZED keyword 1275R
realizing widgets 300B, 1241R
REBIN function 935R
recall buffer
command 938R
RECALL keyword 404R
RECALL_COMMANDSfunction 938R
RECALL_COMMANDSkeyword 539R
recent les
in IDLDE for Macintosh 121U
in IDLDE for Motif 44U
in IDLDE for Windows 90U
RECOMPUTE_DIMENSIONSkeyword 386O
RECON3 function 939R
reconstructions
3D from 2D images 939R
Tomographic 963R
RECORD_START keyword 899R
recording an interactive IDL session 582R
record-oriented les 219B
records
length of 495R
updating 1344R
rectangular
lter 417U
recursion 122B
RED keyword 627R
RED keyword, GREEN keyword, BLUE keyword 1340R
RED_VALUESkeyword 243O, 306O
REDRAW keyword 404R
reduce operator 452R
REDUCE_COLORSprocedure 944R
_REF_EXTRA keyword (keyword inheritance) 115B
reference, parameters passed by 120B
REFERENCE_OUT keyword 615R, 628R, 642R, 646R,
652R, 657R, 667R, 672R
REFORM function 945R
reformatting arrays 945R
region
labeling 596R
of interest 362R, 407R
REGION system variable eld 51R, 54R
Regis device 168R
REGISTER keyword 1041R
REGRESSfunction 438U, 947R
REGRESS1, seeObsolete Routines
regression analysis 947R
REGRESSION, seeObsolete Routines
REGULAR keyword 587R, 1129R
REJECT keyword 330O, 994R
relational operators 275U, 34B
relaxed structure assignment 55B, 956R, 1087R
RELAXED_STRUCTURE_ASSIGNMENT
keyword 955R
release, current version in use 45R
Remove method 187O, 292O, 357O, 394O, 400O
REMOVE_ALL keyword 77B, 1071R, 1074R
RemoveEntity method 202O
removing breakpoints 229R
RENDER_STEP keyword 410O
RENDERER keyword 135O, 433O, 615R, 628R, 652R,
668R, 1255R
rendering 135O
3D objects 740R
3D volumes as 2D images 850R
hardware vs. software 135O
voxel 1192R
Rendering Process
rendering 38O
rendering speed of volumes 127O
repeat statement 107B
REPEATSkeyword 1133R
REPLACE keyword 615R, 628R, 646R, 652R, 668R
replacing text
IDLDE for Motif 47U
REPLICATE function 346U, 949R
REPLICATE_INPLACE procedure 950R
REPORT keyword 296R, 846R
reserved words 63R
reserving colors 67U
RESET keyword 337U, 404O, 746R, 846R, 1110R,
1241R
Reset method 202O, 293O, 378O, 443O
RESET_DATAkeyword 267O, 321O, 330O, 339O, 365O
RESET_STRING keyword 131R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index R ... R
Index Index-55
resetting widgets 1241R
RESIDUAL keyword 331R, 444R, 446R, 1376R
RESIZEABLE_COLUMNSkeyword 1302R
RESIZEABLE_ROWSkeyword 1302R
resizing arrays 291R, 461R, 935R
RESOLUTION 429O
RESOLUTION keyword 223O, 235O, 346O, 421O,
429O, 131R, 132R, 517R, 624R
resolution, CIA World map database 377U
RESOLVE_ALL procedure 952R
RESOLVE_ROUTINE procedure 954R
resource les, editing 67U
resource names for IDL widgets 1211R, 1225R, 1256R,
1264R, 1282R, 1287R, 1293R, 1312R
RESOURCE_NAME keyword 424R, 429R, 430R,
1211R, 1225R, 1256R, 1264R, 1282R, 1287R,
1293R, 1302R, 1312R
resources, X Window 66U
RESTORE keyword 362R, 408R
RESTORE procedure 34U, 955R, 1404
RESTORED_OBJECTSkeyword 956R
restoring IDL save les 955R
restoring structures 57B
RESULT keyword 438R
RESULT_ACMODE keyword 1146R
RESULT_TABLE keyword 1146R
RETAIN keyword 433O, 132R, 351R, 391R, 1041R,
1256R, 1318R
Retained Graphics 148O
RETALL command 957R
RETALL procedure 30U
RETURN command 958R
RETURN executive command Seecommands
RETURN procedure 30U
RETURN_EVENTSkeyword 369R
RETURN_FULL_NAME keyword 384R
RETURN_ID keyword 355R, 384R
RETURN_INDEX keyword 355R, 384R
RETURN_NAME keyword 356R, 384R
RETURN_TYPE keyword 247R
returning
subscripts of non-zero array elements 1203R
widget information 1271R
REVERSE function 960R
reverse index list (for histograms) 546R
REVERSE_INDICESkeyword 547R
reversing array indices 960R
REWIND procedure 962R
REWRITE keyword 842R, 1344R
RGB color model 58O, 59O
RGB color system 386U, 277R, 387R, 1159R
RGB keyword 388R, 901R
RGB_HLSkeyword 277R
RGB_HSV keyword 277R
RGB_TABLE0 keyword 410O
RGB_TABLE1 keyword 410O
RGB_TO_HSV, seeObsolete Routines
Rich Text Format 249U
RIEMANN procedure 963R
RIGHT keyword 1385R
right-handed coordinate system 335U
rivers 708R
RIVERSkeyword 709R
RK4 function 967R
RM, seeObsolete Routines
RMF, seeObsolete Routines
RMSblock mode 788R
RNAME_MBAR keyword 1213R
Roberts edge enhancement 969R
ROBERTSfunction 969R
Robinson map projection 373U
Romberg integration 862R, 864R
ROOT_DIR keyword 478R
roots 500R, 502R
ROT function 970R, 972R
ROT keyword 359U
ROT_INT, seeObsolete Routines
rot_text.pro (example le) 84O
ROTATE function 972R
ROTATE keyword 337U, 211R, 1110R
Rotate method 293O
rotate method 49O
rotating
arrays 336U, 972R
images 336U, 350R
by arbitrary amounts 970R
the viewing matrix 1109R
views 343U
rotation 48O, 49O
ROUND function 974R
rounding 703R
ceiling function 259R
oor function 487R
to nearest integer 974R
ROUTINE_INFO function 975R
routines
Index S ... S Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-56 Index
accessing 29U
obsolete 1391R
saving as binary les 982R
ROUTINESkeyword 540R, 982R
row bases 1213R
ROW keyword 306B, 356R, 369R, 965R, 1213R
ROW_HEIGHTSkeyword 1241R, 1275R, 1302R
ROW_LABELSkeyword 1241R, 1303R
ROW_MAJOR keyword 1303R
row-indexed sparse storage method 464U
row-major format 429U
RS_TEST function 448U, 977R
RSI electronic mail address 16U, 9B, 20O, 30R
RSI postal address 16U, 9B, 20O, 29R
RSI telephone and fax numbers 16U, 9B, 20O, 29R
RSI_GAMMAI, seeObsolete Routines
RSTRPOSfunction 979R
RTF 249U
RTOL keyword 692R
RUN executive command Seecommands
Runge-Kutta method 967R
run-length encoding 829R
running IDL 20U
runs test for randomness 884R
RUNS_TEST, seeObsolete Routines
runtime IDL 2B
RUNTIME keyword 681R
S
Ssystem variable eld 54R
S_TEST function 448U, 980R
S_VALUE keyword 247R
SAMPLE keyword 391R, 470R, 935R
sampled data analysis, aliasing 409U
SAT_P keyword 729R
SATELLITE keyword 725R
satellite map projection 366U, 725R
SAVE keyword 207R, 663R, 1006R, 1092R
Save method 300O
SAVE procedure 34U, 982R, 1404
save/restore
binary les 982R
les 955R
Windows differences 114U
heap variables 232B
SAVE_DIVIDE keyword 1186R
SAVE_HOURGLASSkeyword 1269R
saved commands, displaying 539R
saving
les
IDLDE for Motif 44U
IDL routines as binary les 982R
IDL variables 982R
variables 983R
saving and restoring heap variables 232B
saving and restoring windows 137O
scalable pixels 325U, 383U, 149R
SCALEkeyword 337U, 360U, 299O, 194R, 391R, 716R,
730R, 1110R
Scale method 294O
scale method 50O
SCALE_FACTOR keyword 132R
SCALE3 procedure 338U, 984R
SCALE3D procedure 985R
scaling 335U, 48O, 50O, 1109R
axes 288U
factors 54R
images 384U
values into range of bytes 238R
SCATTER keyword 653R
scene object 28O, 353O
scene objects 36O
SCHOOLBOOK keyword 133R
SCR_XSIZE keyword 306B, 1213R, 1225R, 1242R,
1256R, 1264R, 1282R, 1287R, 1293R, 1303R, 1312R
SCR_YSIZE keyword 306B, 1214R, 1225R, 1242R,
1256R, 1264R, 1282R, 1288R, 1294R, 1303R, 1312R
screen size, nding 308B
SCREEN_DIMENSIONSkeyword 221O, 232O, 429O
scripts, AppleScript 438R
scroll bars
for draw widgets 1256R
for text widgets 1309R, 1312R
Scroll base property 206U
SCROLL keyword 356R, 378R, 1214R, 1256R, 1294R,
1303R, 1312R
scroll offset 47R
SDEV keyword 604R, 756R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index S ... S
Index Index-57
search path
IDLDE for Motif 66U
SEARCH2D function 986R
SEARCH3D function 989R
searching, within strings 1084R
seasonal effect 467U
segmentation 596R
SEGMENTED keyword 789R
sel_obj.pro (example le) 131O
Select method 226O, 436O
SELECT_TARGET keyword 291O
selection 130O
example 131O
graphic atoms 131O
IDLgrWindow object 130O
model objects 131O
views 130O
self argument (objects) 262B
semicolon 85B, 59R
semi-logarithmic plots 208R, 307R, 801R, 1006R,
1093R
SEND_EVENT keyword 1242R
Sensitive common property 198U
SENSITIVE keyword 1214R, 1225R, 1242R, 1256R,
1264R, 1282R, 1288R, 1294R, 1303R, 1312R
sensitizing widgets 301B, 1242R
SEPARATOR keyword 1225R
SET keyword 230R, 1358R
SET_BUTTON keyword 1242R
SET_CHARACTER_SIZE keyword 133R
SET_COLORMAP keyword 133R
SET_DRAW_VIEW keyword 1243R
SET_DROPLIST_SELECT keyword 1243R
SET_FONT keyword 134R
SET_GRAPHICS_FUNCTION keyword 137R
SET_LIST_SELECT keyword 1243R
SET_LIST_TOP keyword 1243R
SET_NATIVE_PLOT, seeObsolete Routines
SET_PLOT procedure 111R, 992R
SET_RESOLUTION keyword 138R
SET_SCREEN, seeObsolete Routines
SET_SHADING procedure 350U, 832R, 994R
SET_SLIDER_MAX keyword 1243R
SET_SLIDER_MIN keyword 1244R
SET_STRING keyword 138R
SET_SYMBOL procedure 996R
SET_TABLE_SELECT keyword 1244R
SET_TABLE_VIEW keyword 1244R
SET_TEXT_SELECT keyword 1244R
SET_TEXT_TOP_LINE keyword 1244R
SET_TRANSLATION keyword 138R
SET_UNAME keyword 1245R
SET_UVALUE keyword 1245R
SET_VALUE keyword 356R, 1245R
SET_VIEW.PRO 48O
SET_VIEWPORT, seeObsolete Routines
SET_WRITE_MASK keyword 139R
SET_XY, seeObsolete Routines
SetCurrentCursor method 437O
SETENV procedure 520R, 997R
setjmp, C language 255R
SETLOG procedure 998R
SetPalette method 202O
SetProperty method 214O, 227O, 245O, 255O, 259O,
268O, 276O, 284O, 294O, 301O, 308O, 313O,
322O, 333O, 341O, 352O, 358O, 368O, 373O,
387O, 395O, 401O, 413O, 422O, 438O, 439O
SetRGB method 308O
setting
breakpoints 230R
keywords 111B, 181O, 185R, 585R
properties 33O
properties at initialization 33O
properties of existing objects 33O
the current window 1346R
values 1245R
setting the cursor in a window object 137O
SETUP keyword 655R
SETUP_KEYSprocedure 399R, 1000R
SFIT function 438U, 1002R
SGI keyword 1001R
SGML 250U
SH keyword 1049R
SHADE_RANGE keyword 330O, 365O
SHADE_SURF procedure 1004R
SHADE_SURF_IRR procedure 1008R
SHADE_VOLUME procedure 351U, 834R, 1010R
shaded surfaces 1004R
changing position of light source 994R
from polygons 832R
plotting 349U
The SHADE_SURF Procedure 349U
SHADESkeyword 352U, 833R, 1006R, 1011R, 1092R
shading 349U, 994R
changing position of light source 994R
parameters 350U
Index-58 Index
volumes 832R
SHADING keyword 330O, 339O, 365O
SHARE_DATA keyword 267O, 321O, 331O, 340O,
365O
shared colormap 138R, 140R
Motif IDLDE 67U
SHARED keyword 789R
sheet feeder 122R
shells, spawning 1047R
SHIFT function 1013R
shifting
array elements 1013R
bit 581R
SHORT keyword 1340R
short word swap 236R
shortcuts, keyboard
IDLDE for Motif 55U
SHOW keyword 1246R
SHOW_AXISkeyword 243O
SHOW_FILL keyword 275O
SHOW_FULL keyword 1041R
SHOW_OUTLINE keyword 243O, 275O
SHOW_SKIRT keyword 366O
SHOW3 procedure 1015R
SHOWFONT procedure 1017R
showing
images 1153R
windows 1347R
SHOWLOAD keyword 1358R
shrink operator 452R
shrinking
arrays 935R
windows 1347R
SIBLING keyword 1275R
SIG_AB keyword 605R
SIGMA keyword 283R, 678R, 1099R
SIGMA, seeObsolete Routines
sign test 980R
SIGN_TEST, seeObsolete Routines
signal
analysis transforms 400U
ltering 225R
processing 398U
CONVOL function 311R
SIGNED keyword 823R
signicant bits 121R
SILENT keyword 685R, 1362R
simple polygons 71O, 375O
SIMPLEX keyword 194R
SIMPSON, seeObsolete Routines
Simpsons rule 866R
simultaneous linear equations, solving 453U
SIN function 1019R
SINDGEN function 1020R
sine 1019R
hyperbolic 1021R
inverse 203R
single-precision
arrays 482R, 490R
converting values to 486R
SINGULAR keyword 1099R
Singular Value Decomposition 438U, 454U, 1096R,
1103R
SINH function 1021R
SINKSORT example routine 245B
SINUSOIDAL keyword 725R
sinusoidal map projection 373U, 725R
SIZ keyword 436R
size
of arrays 1022R
of widgets 306B
SIZE executive command 1393R
SIZE function 124B, 127B, 1022R
SIZE keyword 259O, 373O, 351R, 706R
sizing widgets 304B
sizing windows
graphics
IDLDEfor Macintosh 130U
IDLDEfor Motif 61U
skeletons of bi-level images 1118R
skewness 755R, 1025R
SKEWNESSfunction 1025R
SKIP executive command Seecommands
SKIPF procedure 1026R
SKIRT keyword 366O, 1093R
skirts (surface objects) 106O
slash character 181O, 185R
SLICER procedure 354U, 522R
SLICER, seeObsolete Routines
SLICER3 procedure 1027R
SLIDE_IMAGE procedure 1040R
SLIDE_WINDOW keyword 1041R
slider widgets 223U, 274B, 1291R
changing maximum value 1243R
changing minimum value 1244R
displayed values 222U
Index Index-59
drag events 1296R
draggable 1291R
oating-point 377R
initial position 222U
maximum value 222U, 1293R
minimum value 222U, 1293R
properties 222U
returning minimum and maximum values 1276R
setting events 223U
title 223U
using 165U
SLIDER_MIN_MAX keyword 1276R
smearing (in frequency plots) 405U
SMOOTH function 423U, 469U, 1043R
smoothing 1043R
contours 329U
CONVOL function 311R
example 161U
median 738R
MIN_CURVE_SURF function 300R
SOBEL function 1045R
SOLID keyword 200R
SOLID_WALLSkeyword 804R
SORT function 1046R
sorting
arrays 1046R
SINKSORT example 245B
SOURCE keyword 976R
SOURCE_FILESkeyword 540R
Space base property 207U
SPACE keyword 356R, 1214R
spaces, removing from a string 77B
SPACING keyword 313O, 709R, 827R
sparse arrays 464U
FULSTR 496R
LINBCG 601R
READ_SPR 915R
SPRSAB 1061R
SPRSAX 1063R
SPRSIN 1064R
WRITE_SPR 1332R
SPARSE keyword 694R
spawining a shell process 1047R
SPAWN procedure 31U, 1047R
SPEARMAN, seeObsolete Routines
Spearmans rho rank correlation 882R
special characters 26U
displaying in plots 68R
special functions
BETA 216R
IBETA 554R
Specifying the Location of a Plot 307U
SPH_4PNT procedure 1051R
SPH_SCAT function 1052R
SPHERE keyword 1133R, 1136R
spherical coordinates 338R
spherical gridding 1052R, 1131R, 1134R
spherical interpolation 1052R
SPHERICAL keyword 587R
spherical triangulation 1131R
SPL_INIT function 445U, 1054R
SPL_INTERP function 445U, 1056R
spline
cubic interpolation 1054R, 1058R, 1059R
thin-plate surface 748R
SPLINE function 445U, 1058R
SPLINE keyword 320U
SPLINE_P procedure 446U, 1059R
spreadsheet data les 918R, 1335R
SPRSAB function 466U, 1061R
SPRSAX function 466U, 1063R
SPRSIN function 466U, 1064R
SQRT function 1066R
square brackets 270U, 28B
Seearrays, concatenation
square root 1066R
SRF les
reading 916R
writing 1333R
SSCALE keyword 1016R
SSWAP keyword 236R
stacked histogram plots (LEGO keyword) 1091R
standard
deviation 755R
image le formats 227B
input 514R
standard deviation 1069R
Standard Generalized Markup Language, SGML 250U
STANDARD keyword 438O
STANDARD_PARALLELSkeyword 730R
STANDARDIZE function 476U, 1067R
STANDARDIZE keyword 797R
standardized variables 472U, 1067R
START_COLOR keyword 358R
START_OF_LINE keyword 404R
Index-60 Index
STARTCOL keyword 919R, 1335R
starting IDL 20U
STARTROW keyword 919R, 1335R
startup
le 33U
IDLDE for Motif 64U
preferences
IDLDE for Motif 64U
switches 20U
statement labels 84B
statements 84B
STATIC_COLOR keyword 139R
STATIC_GRAY keyword 139R
stationarity 467U
STATIONARY keyword 1202R
statistics 426U
approximating models 282R
tting data
growth trends 282R
least absolute deviation regression 598R
moving averages 1043R
multiple linear regression 947R
nonlinear least-squares regression 335R
outlying data regression 598R
kurtosis 590R
testing 446U
tools
Chi-square error, minimizing 604R
combinations 473R
cumulative sum 1123R
factorial 473R
frequency tables 546R
histogram 546R
kurtosis 590R, 755R
Lomb normalized periodogram 683R
magnitude-based ranking 892R
maximum 731R
mean 735R, 755R
mean absolute deviation 736R
median 755R
minimum 747R
number generators 840R, 886R, 890R
permutations 473R
skewness 755R, 1025R
sort 1046R
standard deviation 755R, 1069R
T-statistic, Students 1121R
variance 755R, 1179R
STATISTICSkeyword 299O
Status Bar
IDLDE for Motif 42U
STDDEV function 1069R
STDEV, seeObsolete Routines
STEP executive command Seecommands
STEP keyword 1193R
step plot 399U
STEPMAX keyword 232R, 421R, 768R
STEPOVER executive command Seecommands
stepping through, debugging 139U
STEPWISE, seeObsolete Routines
STEREOGRAPHIC keyword 725R
stereographic map projection 362U, 725R
STIRLING keyword 473R
STOP keyword 348R
STOP procedure 130B, 1070R
stopping program execution 30U, 229R, 1070R
STR_SEP function 1071R
STRARR function 1073R
STRCOMPRESSfunction 77B, 78B, 1074R
STREAM keyword 789R
streamlines 1182R
STRETCH procedure 391U, 1075R
string data type 13B
STRING function 74B, 75B, 212B, 1077R
STRING keyword 369R, 561R, 706R
strings 258U, 259U, 17B
calling
IDL functions from 252R
IDL methods from 253R
IDL procedures from 254R
case folding 76B
concatenation 74B
converting to lowercase 1081R
converting to uppercase 1089R
creating arrays 1020R
creating string arrays 1073R
executing contents of 458R
extracting substrings from 1083R
nding substrings within 979R, 1084R
formatting data 74B
Index Index-61
inserting strings into 1085R
length of 79B, 1080R
nonstring arguments to routines 73B
operations 72B, 979R, 1071R
reading data from 931R
removing whitespace from 1074R, 1086R
separating into parts 1071R
substrings 79B
whitespace 77B
STRINGSkeyword 386O
STRLEN function 79B, 1080R
STRLOWCASE function 76B, 1081R
STRMESSAGE function 1082R
STRMID function 79B, 81B, 1083R
STRPOSfunction 79B, 1084R
STRPUT procedure 79B, 80B, 1085R
STRTRIM function 77B, 78B, 1086R
STRUCT_ASSIGN procedure 55B, 1087R
STRUCTURE keyword 1023R
Structure objects 28O
structure of subarrays 65B
STRUCTURE_NAME keyword 1111R
structures
advanced 53B
arrays of 49B
arrays stored in structure form 464U
automatic denition 54B, 252B
concatenating 321R
creating and dening 262U, 42B, 54B, 321R
creating arrays of 949R
denition 55B, 1087R
displaying information on currently-dened 540R
FSTAT 494R
input/output 51B
introduction to 262U, 42B
number of elds in 53B
parameter passing 264U, 47B
references 263U, 45B
relaxed denition 956R, 1087R
relaxed dention 55B
restoring 57B
returned by widgets 1270R
returning length of 766R
returning number of tags 766R
tag names 321R, 1111R
using help with 264U, 47B
zeroed 43B, 252B
STRUCTURESkeyword 540R
structuring element 432R
STRUPCASE function 76B, 1089R
STUDENT keyword 681R
STUDENT_T, seeObsolete Routines
Students t distribution 1107R, 1108R
Students T-statistic 1121R
STUDENT1_T, seeObsolete Routines
STUDRANGE, seeObsolete Routines
STYLEkeyword 313O, 331O, 366O, 616R, 629R, 653R,
669R
STYLE system variable eld 54R
STYLESkeyword 220O, 231O, 345O, 417O, 428O
SUB_RECT keyword 924R
SUBDIRECTORY keyword 478R
SUBMIT keyword 790R
submitting a print job 141O
subscripts 60B
array valued 66B
arrays 261U
examples 61B
of scalars 63B
ranges 64B
ranges, combined with arrays 67B
subscript arrays 87B, 89B
SUBSTITUTE keyword 259O
substrings 79B
SUBTICKLEN 211O
SUBTICKLEN keyword 211O, 243O
SUBTITLE keyword 106R
SUBTITLE system variable eld 51R
subtraction operator 271U, 29B
SUBTYPE keyword 647R
summation, array elements 1123R
SUN keyword 1001R
Sun raster les
reading 916R
writing 1333R
SUPERCLASSkeyword 771R
SUPERSEDE keyword 790R
SUPPRESS_ERROR keyword 579R
SUPPRESS_VALUE keyword 378R, 1294R
suppressing information messages 45R
surf_track.pro (example le) 110O, 441O
surface tting 436U
SFIT 1002R
surface object 30O, 359O
surface objects 104O
creating 104O
example 110O
Index-62 Index
hidden line removal 106O
rendering style 105O
shading 105O
skirts 106O
texture mapping 107O
using 105O
surface plots 331U, 1377R
with images and contours 1015R
SURFACE procedure 331U, 1090R
duplicating tranformations 1095R
SURFACE_FIT, seeObsolete Routines
surfaces, shaded 740R, 1004R, 1008R
SURFR procedure 1095R
suspending execution 140U
SVBKSB, seeObsolete Routines
SVD, seeObsolete Routines
SVDC procedure 460U, 1096R
SVDFIT function 438U, 1098R
SVSOL function 460U, 1102R
SWAP_ENDIAN function 1104R
SWAP_ENDIAN keyword 786R
SWAP_IF_BIG_ENDIAN keyword 236R, 786R
SWAP_IF_LITTLE_ENDIAN keyword 236R, 786R
swapping the order of bytes 235R
switches, command-line 20U
SX keyword 488R, 848R
SY keyword 488R, 848R
SYLK les 918R, 1335R
SYM_HT keyword 1202R
SYM_LEN keyword 1202R
SYMBOL keyword 321O, 340O, 139R
symbol object 31O, 370O
symbol objects 67O
symbolic link les 918R, 1335R
symbols, plotting 295U, 296U, 51R, 105R, 1177R
symmetric
array or matrix 1140R, 1142R
arrays 430U
SYMSIZE keyword 106R
system
clock 1105R
les 139B
SYSTEM keyword 846R, 976R
System Menu base property 207U
system variable elds
BACKGROUND 49R
BLOCK 39R
CHANNEL 49R
CHARSIZE 49R, 52R
CHARTHICK 49R
CLIP 49R
CODE 39R
COLOR 49R
CRANGE 52R
FILL_DIST 46R
FLAGS 46R
FONT 49R
GRIDSTYLE 53R
LINESTYLE 49R
MARGIN 53R
MINOR 53R
MSG 39R
MSG_PREFIX 39R
MULTI 50R
N_COLORS 46R
NAME 39R, 46R
NOCLIP 51R
NOERASE 51R
NSUM 51R
OMARGIN 53R
ORIGIN 47R
POSITION 51R
PSYM 51R
RANGE 54R
REGION 51R, 54R
S 54R
STYLE 54R
SUBTITLE 51R
SYS_CODE 39R
SYS_MSG 39R
T 51R
T3D 51R
TABLE_SIZE 47R
THICK 52R, 55R
TICKFORMAT 55R
TICKLEN 52R, 55R
TICKNAME 55R
TICKS 56R
TICKV 56R
TITLE 52R, 56R
TYPE 56R
UNIT 47R
WINDOW 48R, 56R
X_CH_SIZE 48R
X_PX_CM 48R
X_SIZE 48R
X_VSIZE 48R
Y_CH_SIZE 48R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index T ... T
Index Index-63
Y_PX_CM 48R
Y_SIZE 48R
Y_VSIZE 48R
ZOOM 48R
system variables 266U, 22B, 37R
!C 46R
!D 46R
!D.TABLE_SIZE 1164R
!D.WINDOW 1199R, 1317R, 1346R
!EDIT_INPUT 24U
!ERR 1114R, 1203R
!ERROR_STATE 149B, 745R, 1082R
!JOURNAL 582R
!MAP 359U
!MAP1 723R
!MOUSE 332R
!ORDER 382U, 48R, 1154R, 1162R
!P 49R
!P.MULTI 162R
!P.T 107R
!QUIET 745R
!X 52R
!Y 52R
!Z 52R
creating 409R
displaying information on currently-dened 540R
for axes 52R
for errors 149B
for graphics 46R
obsolete 1391R
read-only 409R
saving 983R
SYSTEM_VARIABLESkeyword 540R, 983R
SYSTIME function 1105R
SZ keyword 488R
T
T system variable eld 51R
T_CVF function 1107R
T_PDF function 1108R
T3D keyword 107R, 310R, 833R, 1009R
T3D procedure 336U, 1109R
T3D system variable eld 51R
TABLE keyword 998R, 1146R
table widgets 237U, 275B, 1298R
alignment of text 234U
attributes 234U
cell select events 237U
column labels 234U
column width change events 238U
data invalid events 239U
data transfer to 235U
editing cells 235U
events 237U
focus events 238U
heading display 234U
height 235U
insert character events 239U
insert string events 239U
row labels 236U
scroll height 237U
scroll width 236U
scrolling 236U
sizing columns 235U
text delete events 238U
text selection events 240U
using 166U
width 235U
TABLE_ALL_EVENTSkeyword 1276R
TABLE_EDIT_CELL keyword 1276R
TABLE_EDITABLE keyword 1276R
TABLE_SELECT keyword 1276R
TABLE_SIZE system variable eld 47R
TABLE_VIEW keyword 1276R
TABLE_XSIZE keyword 1246R
TABLE_YSIZE keyword 1246R
tabs, removing from a string 77B
tabulated data 444U
TAG_NAMESfunction 1111R
tags, number in a structure 766R
TAN function 1112R
TAN0 keyword 1059R
TAN1 keyword 1060R
tangent 1112R
hyperbolic 1113R
inverse 206R
TANH function 1113R
tapes
reading from 1114R
rewiding 962R
skipping records 1026R
writing data to 1115R
writing EOF mark 1200R
TAPRD procedure 1114R
TAPWRT procedure 1115R
TEK_COLOR procedure 1116R
Index T ... T Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-64 Index
TEK_COLORSkeyword 197R
TEK4014 keyword 139R
TEK4100 keyword 140R
Tektronix device 169R
telephone and fax numbers for RSI 16U, 9B, 20O, 29R
TEMP_DIRECTORY keyword 299O
TEMPLATE keyword 533R, 899R
TEMPORARY function 137B, 1117R
temporary variables 1117R
TERM environment variable 23U
TERMINAL keyword 478R, 998R
TERMINATE keyword 402R
ternary operator, ?: 36B
tesselation 1131R
Tessellate method 378O
tessellator object 31O, 375O
tessellator objects 71O
test functions 683R
CTI_TEST 330R
FV_TEST 498R
KW_TEST 591R
LNP_TEST 683R
MD_TEST 733R
R_TEST 884R
RS_TEST 977R
S_TEST 980R
TM_TEST 1121R
XSQ_TEST 1375R
test mode, IDL GUIBuilder 158U
test_surface.pro (example le) 53O
TESTCONTRAST, seeObsolete Routines
text
aligning 1379R
character
height 48R
size 49R
thickness 49R, 1380R
width 48R
displaying 1354R
font index 102R
font selection 49R
plane of 1380R
plotting in graphics windows 1379R
positioning 81R
replacing
IDLDE for Motif 47U
searching for
IDLDE for Motif 46U
selecting, IDLDE for Windows 111U
size 100R
size of characters 1380R
widgets, Seetext widgets
width of 1380R
TEXT keyword 1354R
text object 30O, 380O
text objects 80O
3D 82O
alignment 82O
baseline and upward direction 82O
creating 81O
font 84O
location 81O
on the glass 82O
using 81O
text widgets 275B, 1309R
appending text to 1232R
changing selected text 1249R
converting
character offsets to column/line form 1277R
line/column positions to character
offsets 1277R
delete events 218U
determining
if all events are being returned 1276R
if text widget is editable 1276R
editable 1310R
making editable after creation 1235R
events returned by 1231R, 1309R, 1314R
focus events 218U
properties 216U
returning
line number of top line in viewport 1277R
number of characters 1277R
offsets of text selection 1277R
selected text 1249R
selection events 219U
setting
text selection 1244R
top line 1244R
setting editable state 216U
setting height 216U
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index T ... T
Index Index-65
setting initial displays 216U
setting keyboard focus to 1238R
setting scrolling 217U
setting width 217U
setting word wrapping 217U
string insert events 219U
suppressing newline characters 1240R
text insert events 218U
using 165U
TEXT_ALL_EVENTSkeyword 1276R
TEXT_AXESkeyword 1380R
TEXT_COLOR keyword 275O
TEXT_EDITABLE keyword 1276R
TEXT_NUMBER keyword 1277R
TEXT_OFFSET_TO_XY keyword 1277R
TEXT_SELECT keyword 1277R
TEXT_TOP_LINE keyword 1277R
TEXT_XY_TO_OFFSET keyword 1277R
TEXTANGLE keyword 673R
TEXTPOSkeyword 211O
texture mapping 107O
TEXTURE_COORD keyword 331O, 366O
TEXTURE_INTERP keyword 331O, 366O
TEXTURE_MAP keyword 331O, 367O
THICK keyword 212O, 243O, 313O, 321O, 332O,
340O, 367O, 373O, 107R, 201R, 642R, 646R, 652R,
657R, 658R, 793R, 801R, 1202R
THICK system variable eld 52R, 55R
THICKNESSeld 192O
THICKNESSkeyword 259O
thickness of characters 1380R
THIN function 1118R
thinning images 1118R
thin-plate-spline surface 748R
THREED keyword 244O
THREED procedure 1119R
three-dimensional
graphics 334U
transformations
array transforms 1186R
duplicating SURFACE transforms 1095R
implementing transforms 1109R
matrices 335U
PLOT and CONTOUR 343U
plotting 314R, 380R
scaling 984R, 985R
specifying orientation 350R
T3D keyword 51R
THRESH keyword 1061R, 1064R
THRESHOLD keyword 140R, 340R
throw, C++ language 255R
tick labels 80O
tick marks 302U
annotation 55R, 109R
data values for 56R, 109R
getting values of 109R
intervals 56R, 109R
length 52R, 108R
length on individual axes 55R, 108R
linestyles 302U, 102R
minor 53R, 103R
string labels for 55R
styles 53R
suppressing 56R, 109R
TICKDIR keyword 212O
TICKFORMAT keyword 212O, 244O
TICKFORMAT system variable eld 55R
TICKFRMTDATA keyword 212O, 244O
TICKINTERVAL keyword 254O
TICKLEN keyword 302U, 213O, 244O, 254O, 108R
TICKLEN system variable eld 52R, 55R
TICKNAME system variable eld 55R
TICKSsystem variable eld 56R
TICKTEXT keyword 213O, 244O
TICKV system variable eld 56R
TICKVALUESkeyword 213O, 244O
TIFF les
reading 921R
writing 1337R
TIFF_DUMP, seeObsolete Routines
TIFF_READ, seeObsolete Routines
TIFF_WRITE, seeObsolete Routines
TILT keyword 509R
time
converting from string to binary 219R
returning current 1105R
TIME_TEST procedure 1120R
timed demo mode 414R
timer events (for widgets) 302B
TIMER keyword 302B, 1247R
TIMESkeyword 140R
time-series analysis 466U
autocovariance 187R
autoregressive modeling 1147R, 1149R
Index T ... T Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-66 Index
cross covariance 240R
forward differencing 1148R
Title Bar base property 208U
Title base property 207U
TITLEkeyword 213O, 244O, 275O, 434O, 109R, 211R,
296R, 369R, 374R, 378R, 380R, 424R, 427R, 429R,
430R, 616R, 629R, 653R, 669R, 728R, 806R, 1041R,
1119R, 1182R, 1214R, 1264R, 1294R, 1318R,
1355R, 1358R
TITLE system variable eld 52R, 56R
titles 74O
titles, multiline 289U
TLB_FRAME_ATTR keyword 1215R
TLB_GET_OFFSET keyword 1247R
TLB_GET_SIZE keyword 1248R
TLB_KILL_REQUEST_EVENTSkeyword 1215R,
1248R, 1277R
TLB_LOCATION keyword 616R, 629R, 653R, 669R
TLB_SET_TITLE keyword 1248R
TLB_SET_XOFFSET keyword 1248R
TLB_SET_YOFFSET keyword 1248R
TLB_SIZE_EVENTSkeyword 1216R
TM_TEST function 448U, 1121R
t-means test 1121R
TMP keyword 478R
TNAME keyword 1023R
TO_CYLIN keyword 338R
TO_DATA keyword 310R
TO_DEVICE keyword 310R
TO_NORMAL keyword 310R
TO_POLAR keyword 339R
TO_RECT keyword 339R
TO_SPHERE keyword 339R
toggle buttons 1227R
TOL keyword 602R, 679R
TOLF keyword 232R, 768R
TOLMIN keyword 232R, 768R
TOLX keyword 232R, 421R, 768R
Tomographic reconstructions 963R
toolbars
IDL GUIBuilder 164U
IDLDE for Motif 41U, 72U
TOP keyword 207O, 249O, 262O, 280O, 289O, 317O,
326O, 336O, 361O, 382O, 405O, 238R, 544R, 833R,
1165R
top margin, setting 53R
TOP_ID keyword 1041R
TOP_STRETCH keyword 304O, 306O
top-level base 1205R
TOTAL function 1123R
TQLI, seeObsolete Routines
TRACE executive command Seecommands
TRACE function 460U, 1125R
traceback information 148B
displaying 540R
returning 538R
TRACEBACK keyword 540R, 746R
TRACK keyword 342R, 391R, 1358R
TrackBall
class 31O
Trackball
Init method 442O
Reset method 443O
Update method 444O
TrackBall object 440O
trackball_dene.pro (example le) 55O
TRACKING_EVENTSkeyword 1216R, 1225R, 1248R,
1257R, 1264R, 1277R, 1283R, 1288R, 1294R,
1303R, 1312R
tranformations
rotation 49O
TRANSkeyword 851R
TRANSFER_COUNT keyword 933R, 1344R
TRANSFORM keyword 292O
transformation matrices 335U, 51R
transformations 50O, 51O
coordinate 51O
example 53O
model objects 48O
rotation 48O
scaling 48O
translation 48O, 49O
transforms
Fourier 400U, 474R
Hilbert 411U
wavelet 413U
TRANSLATE keyword 337U, 1110R
Translate method 295O
translate method 49O
translation 335U, 48O, 49O, 1109R
TRANSLATION keyword 140R, 281R
translation tables, bypassing 117R
transparency of voxels 124O
TRANSPARENT keyword 357O, 393O, 828R, 911R,
1329R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index U ... U
Index Index-67
TRANSPOSE function 430U, 1126R
transposing arrays 1126R
Transverse Mercator map (UTM) projection 369U,
725R
TRANSVERSE_MERCATOR keyword 725R
TRED2, seeObsolete Routines
tree 36O
TREE_EXAMPLE example routine 248B
trees 242B
binary 248B
trend analysis 467U
TRI_SURF function 1128R
TRIAL keyword 681R
Triangle Fans 146O
Triangle strips 147O
TRIANGULATE keyword 719R
TRIANGULATE procedure 446U, 1131R
triangulation 1131R, 1134R
spherical 1131R
TRIANGULATION keyword 307R
TRIDAG, seeObsolete Routines
tridiagonal array or matrix 1140R, 1142R, 1143R
TRIGRID function 446U, 1134R
trilinear interpolation 573R
TRIM keyword 1071R
trimming strings 1086R
TRIQL procedure 444U, 1140R
TRIRED procedure 444U, 1142R
TRISOL function 460U, 1143R
TRNLOG function 1145R
TRUE keyword 908R, 1154R, 1162R, 1325R
true map scale, setting 360U
true, denition of 103B
TRUE_COLOR keyword 141R
true-color
displays 392U
images
converting to pseudo-color 279R
displaying 1154R
PostScript 158R
reading 1162R
visuals 120R
TrueType 74R, 136R
TrueType fonts 64O, 65R, 86R
TRUNCATE_ON_CLOSE keyword 790R
TS_COEF function 469U, 1147R
TS_DIFF function 469U, 1148R
TS_FCAST function 469U, 1149R
TS_SMOOTH function 469U, 1151R
TT_FONT keyword 141R, 1017R
TTY keyword 141R
TUMBLE_CNT keyword 366R
TUMBLE_PERIOD keyword 366R
TV procedure 381U, 1153R
TVCRSprocedure 395U, 1157R
TVDELETE, seeObsolete Routines
TVLCT procedure 388U, 1159R
TVRD function 385U, 395U, 1161R
TVRDC, seeObsolete Routines
TVSCL procedure 381U, 1164R
TVSET, seeObsolete Routines
TVSHOW, seeObsolete Routines
TVWINDOW, seeObsolete Routines
TWO_PASS_QUANTIZE keyword 908R
TWO_SIDED keyword 410O
two-dimensional Gaussian t 508R
two-tailed hypothesis tests 447U
Type button property 214U
type conversion
to 64-bit integer 689R
to byte 234R
to complex 285R, 396R
to double-precision 442R
to integer 484R
to longword 688R
to single-precision, oating-point 486R
to string 1077R
to unsigned 64-bit integer 1174R
to unsigned integer 1167R
to unsigned longword 1173R
TYPE keyword 282O, 411R, 518R, 561R, 624R, 706R,
808R, 1024R, 1278R
TYPE system variable eld 56R
type-ahead buffer 514R
typestyle 84O
typographical conventions 27O
U
UDF_BLOCK keyword 790R
UI_VALUE keyword 247R
UINDGEN function 1166R
UINT function 1167R
UINT keyword 562R
UINTARR function 1168R
UL_VALUE keyword 247R
UL64 keyword 562R
UL64_VALUE keyword 247R
Index V ... V Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-68 Index
UL64INDGEN function 1169R
ULINDGEN function 1170R
ULON64ARR function 1171R
ULONARR function 1172R
ULONG function 1173R
ULONG keyword 562R
ULONG64 function 1174R
UNAMEkeyword 1216R, 1226R, 1257R, 1265R, 1278R,
1283R, 1288R, 1294R, 1304R, 1313R
unconstrained minimizer 462U
underow errors 151B
UNEQUAL keyword 1122R
unformatted binary data 933R, 1344R
unformatted I/O 158B, 191B
uniform random deviates 891R
uniformly-distributed random numbers 890R
UNIQ function 1175R
UNIT keyword 909R, 1049R, 1325R
unit number, logical 785R
UNIT system variable eld 47R
UNITSkeyword 224O, 226O, 235O, 349O, 393O,
421O, 434O, 437O, 624R, 1216R, 1226R, 1248R,
1257R, 1265R, 1278R, 1283R, 1288R, 1295R,
1304R, 1313R
Unix
environment variables 519R
UNIX, OS-specic le I/O information 213B
unmapping widgets 1209R
UNRESOLVED keyword 976R
unsharp masking 384U
unsigned 64-bit integer
arrays 1169R
unsigned arrays
longword 1170R
unsigned data type
integer 12B
long 12B
unsigned integer
arrays 1166R
UNSIGNED keyword 924R
unsigned longword
arrays 1172R
UP keyword 333R
UPDATE keyword 309B, 351R, 1249R, 1279R
Update method 444O
UPDATE_DATA keyword 620R
updating les (OPENU procedure) 783R
UPDIR kwyword 386O
upper margin, setting 53R
UPPER_ONLY keyword 1093R
uppercase, converting strings to 1089R
USA keyword 709R, 728R
USE_CURRENT keyword 1362R
USE_TABLE_SELECT keyword 1249R, 1279R
USE_TEXT_COLOR keyword 213O
USE_TEXT_SELECT keyword 1249R
USE_TRIANGLESkeyword 367O
USE_ZVALUE keyword 321O
USEDOUBLESkeyword 919R
USELONGSkeyword 919R
user interface compound widgets 276B
user values
for widgets 286B
setting 1245R
USER_FONT keyword 141R
user-dened plotting symbols 1177R
USERSYM procedure 296U, 1177R
using external modules 245R
UTM (Transverse Mercator) map projection 369U,
725R
UVALUE keyword 213O, 224O, 235O, 244O, 254O,
259O, 267O, 275O, 283O, 292O, 306O, 313O,
321O, 340O, 350O, 357O, 367O, 373O, 386O,
394O, 400O, 411O, 421O, 434O, 342R, 351R, 356R,
358R, 361R, 366R, 369R, 374R, 378R, 380R, 384R,
388R, 391R, 1216R, 1226R, 1257R, 1265R, 1283R,
1288R, 1295R, 1304R, 1313R
UX keyword 977R
UY keyword 978R
V
VALID_DATA keyword 406O
VALID_ID keyword 1279R
value
parameters passed by 120B
widgets 284B
VALUEkeyword 247R, 351R, 369R, 378R, 706R, 1226R,
1257R, 1265R, 1283R, 1289R, 1295R, 1304R, 1313R
VALUESkeyword 434R, 453R, 994R
VARIABLE keyword 790R
Variable Watch Window 145U
VARIABLE_WTSkeyword 274R
variables 264U, 21B
associated 204R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index V ... V
Index Index-69
attributes of 264U, 21B
deleting 413R
derived 472U
disappearing 142B
displaying current 145U
interactive editing tool (XVAREDIT
procedure) 1378R
named 181O, 184R, 185R
names of 265U, 21B
reading display images into (TVRD
function) 1161R
saving 983R
standardized 472U
system 266U, 22B
temporary 1117R
VARIABLESkeyword 976R, 983R
variance 498R, 755R
VARIANCE function 1179R
VARIANCE keyword 1099R
VARIANCESkeyword 797R
VAX_CALL_EXT routine 1406
VAX_FLOAT function 1180R
VAX_FLOAT keyword 247R, 786R, 1406
VAXTOD keyword 236R
VAXTOF keyword 236R
VECTOR keyword 1342R
vector-drawn fonts 65R, 89R
! character 81R
displaying 1017R
editing (EFONT procedure) 443R
special characters 68R
vectors
drawing arrowheads 200R
subscripting 64B
VEL procedure 1182R
velocity eld, plotting 488R, 1182R, 1184R
VELOVECT procedure 1184R
VERBOSE keyword 536R, 899R, 911R, 924R, 956R,
983R, 1011R, 1088R, 1329R, 1340R
VERSION keyword 1279R
VERT_COLORSkeyword 321O, 332O, 340O, 367O
VERT_T3D function 1186R
VERTICAL keyword 378R, 388R, 1295R
vertical slider, Seeslider widgets
VERTICAL_ALIGNMENT keyword 386O
view area 42O
view menu (online help viewer) 246U
view object 28O, 388O
view objects 37O
view volume 46O
nding an appropriate 47O
viewgroup object 28O, 396O
viewgroup objects 37O
viewplane rectangle 46O
VIEWPLANE_RECT 46O
routine for determining 47O
viewport 42O
VIEWPORT_EVENTSkeyword 1258R
virtual memory 124B, 135B
minimizing 137B
running out of 136B
system parameters 138B
Visible base property 208U
Visible property 208U
VISUALIZATION_IN keyword 624R, 642R, 647R,
658R, 673R
VISUALIZATION_PROPERTIESkeyword 663R
VMS
Open VMS
virtual memory performance
VMSle I/O information 217B
VMSlogical name 412R
VMSlogical name tables 1145R
VMSlogical tables 1146R
VMStext libraries 462R
VMSCODE, seeObsolete Routines
VOIGT function 1188R
volume object 30O, 402O
volume objects 122O
attributes 124O
color values 125O
compositing 126O
creating 122O
interpolating values 127O
lighting 126O
opacity table 124O
rendering speed 127O
using 122O
zbuffering 126O
volume slices 1027R
VOLUME_SELECT keyword 411O
volumes
extracting slices 469R
rendering 850R
searching for objects 989R
Index W ... W Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-70 Index
visualizing 351U, 832R, 850R, 1010R, 1192R
VOLUMESkeyword 404O
volumetric reconstruction 939R
VORONOI procedure 446U, 1190R
voxel rendering 1192R
voxel values (volume object) 122O
VOXEL_PROJ function 1192R
VRML object 32O, 414O
VRML objects 141O
creating 141O
VT200 keyword 1001R
VT240 keyword 141R
VT240 terminal 168R
VT330 terminal 168R
VT340 keyword 141R
VT340 terminal 168R
W
WAIT keyword 333R
WAIT procedure 130B, 1196R
WARM keyword 1202R
WARP_TRI function 1197R
warping
images 820R
to maps 715R, 718R
polynomial 820R
using the Z-buffer 828R
Wavefront Advanced Data Visualizer 926R, 1342R
Wavefront les
reading 926R
writing 1342R
wavelet transform 413U, 1348R
WDELETE procedure 144R, 1199R
weather fronts, plotting 1201R
WEIGHT keyword 1099R
WEIGHTSkeyword 283R, 679R
WEOF procedure 1200R
WF_DRAW procedure 1201R
WHERE function 1203R
while statement 108B
whitespace, removing from strings 77B, 1074R, 1086R
WIDED, seeObsolete Routines
Widget Browser 169U, 191U
WIDGET_BASE function 306B, 1205R
WIDGET_BUTTON function 1222R
WIDGET_CONTROL procedure 300B, 301B, 1230R
WIDGET_DRAW function 1252R
WIDGET_DROPLIST function 1262R
WIDGET_EVENT function 1268R
WIDGET_INFO function 1271R
WIDGET_KILL_REQUEST event 1215R
WIDGET_LABEL function 1280R
WIDGET_LIST function 1285R
WIDGET_MESSAGE, seeObsolete Routines
WIDGET_SLIDER function 1291R
WIDGET_TABLE function 1298R
WIDGET_TEXT function 1309R
widgets 202U, 210U, 272B
3D orientation 276B
aligning (ALIGN_XXX keywords) 1205R
animation 341R
annotation 196R
application
errors 282B
tips 315B
background tasks (TIMER keyword) 1247R
base 273B, 1205R
base focus events 210U
base, alignment 203U
base, allow moving 204U
base, allowing closing 203U
base, displaying titlebars 208U
base, oating 204U
base, grid layouts 204U
base, kill request events 210U
base, layouts 205U
base, menus, using system 207U
base, modal 206U
base, resizing 206U
base, rows and columns 202U
base, scroll area size 209U
base, scrolling 206U
base, setting properties 202U
base, spacing of contained widgets 207U
base, spacing of widgets in 208U, 209U
base, titles 207U
base, visibility 208U
bases, using 165U
blocking (MODAL keyword) 1365R
Browser 169U
button, press events 215U
button, release events 214U
button, setting properties 212U
buttons 273B, 1222R
bitmap labels 928R
groups 354R
release events 1224R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index W ... W
Index Index-71
buttons, adding menus 173U
buttons, displaying bitmaps 213U
buttons, labels 214U
buttons, using 165U
callbacks 1209R, 1211R
changing appearance of 1211R, 1225R, 1256R,
1264R, 1282R, 1287R, 1293R, 1312R
changing values 301B
checkboxes, using 165U
color
index 358R, 387R
resources 1213R
selection 360R
common blocks and 312B
common events 199U
compound 276B, 314B, 316B, 341R, 350R, 354R,
358R, 360R, 362R, 366R, 368R, 377R, 380R,
382R, 387R, 390R
template for creating 389R
compound, adding 188U
compound, example 188U
compound, handling events for 199U
controlling 300B
controlling visibility 191U
creating in IDL GUIBuilder 164U
creating with IDL GUIBuilder 150U
default font for 1233R
destroy events 200U
destroying 1234R
determining if widgets are realized
(ACTIVE keyword) 1271R
(REALIZED keyword) 1275R
disabling and enabling screen updates (UPDATE
keyword) 1249R
displaying 191U
draw 273B, 294B, 1252R
draw area properties 229U
draw area, color model 229U
draw events 232U
draw, attributes 229U
draw, backing store 231U
draw, changing view events 233U
draw, colors used in 229U
draw, graphic type 230U
draw, mouse events 232U
draw, mouse motion events 233U
draw, render type 230U
draw, scrolling 231U
draw, scrolling area 231U
draw, using 166U
draw, viewport move events 233U
droplist 274B, 1262R
droplist attributes 224U
droplist properties 224U
droplist, select events 225U
droplist, title 224U
droplists, initial value 224U
droplists, using 165U
dynamic resizing 306B
enabled or disabled state 198U
events 287B, 1268R
CLEAR_EVENTS keyword 1232R
examples 278B
exclusive buttons 1208R
explicit size 305B
eld 368R
nding screen size 308B
form 371R
frames, using 197U
geometry 305B
getting user values 1236R
height 199U
help buttons 1223R
hiding and showing 1246R
hierarchies 300B
horizontal size, changing 1242R, 1250R
hourglass cursor 301B
iconifying 1238R
interrupting the event loop 311B
invalid IDs 1232R, 1268R
killing hierarchies 300B
label 274B, 1280R
label, setting properties 221U
labels, using 165U
lifecycle 281B
list 274B, 1285R
listbox attributes 226U
listbox events 227U
listbox, height 226U
listbox, initial value 226U
listbox, multiple selections 226U
listbox, selection events 227U
listbox, using 165U
listbox, width 227U
location 306B
main event loop for 1363R
Index W ... W Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-72 Index
managing the state of applications 312B
mapping 1209R
mapping and unmapping 1239R
menus 295B
message 274B
message dialog box 423R
modal 423R
modal dialogs 206U
naming 196U
natural size 305B
non-exclusive buttons 1211R
portability 316B
positioning 198U, 1218R, 1219R
post creation events 201U
preventing layout icker 308B
properties for IDL GUIBuilder 166U
pulldown menu 382R
pulldown menus 298B
separators 1225R
radio buttons, using 165U
realize events 200U
realizing 1241R
hierarchies 300B
region of interest 362R
registered 1374R
registering with XMANAGER 1363R
resetting all widgets 1241R
resizing (DYNAMIC_RESIZE keyword) 1222R,
1262R, 1280R
restarting after an error 282B
retreiving values 301B
returning
children of 1271R
information about 1271R
name of event handler procedure 1273R
parent of 1275R
siblings of 1275R
size of (GEOMETRY keyword) 1273R
tracking event status 1278R
type of 1275R, 1278R
validity of 1279R
sending event to (SEND_EVENT keyword) 1242R
sensitizing 301B
sensitizing and de-sensitizing 1214R, 1225R,
1242R, 1256R, 1264R, 1282R, 1288R, 1294R,
1303R, 1312R
setting button events 215U
setting buttons 1242R
setting label attributes 221U
showing and hiding 1246R
size 306B
changing
horizontal 1242R, 1250R
vertical 1242R, 1250R
dynamic resizing 306B
explicit 305B
natural 305B
sizing 304B
sizing, default or explicit 197U
slider 274B, 377R, 1291R
slider attributes 222U
slider properties 222U
slider, change value events 223U
slider, displayed values 222U
slider, initial position 222U
slider, maximum value 222U
slider, minimum value 222U
slider, setting events 223U
slider, title 223U
slider, using 165U
space between children 1214R
table 275B, 1298R
table attributes 234U
table events 237U
table properties 234U
table, alignment 234U
table, cell select events 237U
table, column labels 234U
table, column width events 238U
table, data transfer to 235U
table, editing 235U
table, focus events 238U
table, heading display 234U
table, height 235U
table, insert character events 239U
table, insert string events 239U
table, invalid data events 239U
table, row labels 236U
table, scroll height 237U
table, scroll width 236U
table, scrolling 236U
table, sizing columns 235U
table, text delete events 238U
table, text selection events 240U
table, using 166U
table, width 235U
template for creating 1369R
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index W ... W
Index Index-73
text 275B, 1309R
text, character inserts 218U
text, delete event 218U
text, editable 216U
text, events 218U
text, focus events 218U
text, height 216U
text, initial display 216U
text, scrolling 217U
text, selection events 219U
text, string inserts 219U
text, using 165U
text, width 217U
text, word wrapping 217U
timer events 200U, 302B
tracking events 200U, 1216R
types 273B
unmapping 1209R, 1239R
user values 286B
values 284B, 1237R
user 286B
version of implementation 1279R
vertical size, changing 1242R, 1250R
viewing widgets managed by XMANAGER 1370R
width 198U
XMANAGER procedure 1268R
zoom 390R
WIDTH keyword 456R, 786R, 1355R, 1380R
width of text 1380R
Wilcoxon Rank-Sum Test 977R
WILCOXON, seeObsolete Routines
WINDOW keyword 197R, 347R, 760R, 1359R
window object 32O, 424O
window objects 137O
color model 135O
creating 134O
erasing 136O
exposing or hiding 136O
iconifying 137O
in draw widgets 135O
maximum size 136O, 424O
saving and restoring 137O
setting the cursor 137O
using 134O, 136O
WINDOW procedure 144R, 1317R
WINDOW system variable eld 48R, 56R
WINDOW_INkeyword 616R, 621R, 624R, 629R, 630R,
642R, 648R, 653R, 655R, 658R, 669R, 673R
WINDOW_SCALE keyword 559R
WINDOW_STATE keyword 141R
windowing
Hamming windowed signal 408U
HANNING function 407U
windows
backing store 132R, 144R, 1318R
clipboard support for graphics 88U, 120U
copying areas 118R
copying pixels from 118R
creating 1317R
deleting 1199R
display size 48R
draw widgets 1252R
erasing 451R
exposing 1347R
nding screen size 308B
height 1319R
hiding 1347R
iconifying 1347R
ID for draw widgets 1257R
index of currently open 48R
number of colors 46R
pixmaps 1318R
position of 51R, 126R
positioning 1318R
selecting current 1346R
systems 143R
visible area of display 48R
width 1319R
Windows display device (WIN) 112R
WinHelp 249U
WINX keyword 324R
WINY keyword 324R
wire-mesh surface plots 1090R
WK1 keyword 683R
WK2 keyword 684R
WMENU, seeObsolete Routines
WOLRDTITLE keyword 421O
WORDSkeyword 1155R, 1162R
working directory, changing, Macintosh 135U
World Wide Web 751R
WORLDINFO keyword 421O
WRAP keyword 1313R
wrapper routines 114B
WRITE keyword 427R
write mask 126R, 139R
Index X ... X Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-74 Index
Write method 203O
WRITE_32 keyword 1333R
WRITE_BMP procedure 1320R
WRITE_GIF procedure 1322R
WRITE_JPEG procedure 1324R
WRITE_NRIF procedure 1327R
WRITE_PICT procedure 1328R
WRITE_PNG function 1329R
WRITE_PPM procedure 1331R
WRITE_SPR procedure 466U, 1332R
WRITE_SRF procedure 1333R
WRITE_SYLK function 1335R
WRITE_TIFF procedure 1337R
WRITE_WAVE procedure 1342R
WRITEU procedure 158B, 1344R
writing
a compound widget 316B
BMP les 1320R
les (OPENW procedure) 783R
GIF les 1322R
JPEG les 1324R
NRIF les 1327R
PGM les 1331R
PICT les 1328R
PPM les 1331R
SRF les 1333R
TIFF les 1337R
wave les 1342R
WSET procedure 144R, 1346R
WSHOW procedure 144R, 1347R
WSIZE keyword 848R
WTN function 423U, 1348R
X
X keyword 300R
X Offset common property 198U
X Pad base property 208U
X resources 66U
widget colors 1213R
X Scroll base property 209U
X Size common property 198U
X vs. Y Plots 287U
X Windows
bitmap les, reading 928R
Dump les, reading 930R
fonts 1356R
resource names 1211R, 1225R, 1256R, 1264R,
1282R, 1287R, 1293R, 1312R
X Windows device 171R
DirectColor visual 121R
PseudoColor visual 131R
StaticColor visual 139R
StaticGray visual 139R
TrueColor visual 141R
visuals 171R
X_BITMAP_EXTRA keyword 1226R, 1250R
X_CH_SIZE system variable eld 48R
X_PX_CM system variable eld 48R
X_SCROLL_SIZEkeyword 356R, 391R, 1217R, 1258R,
1305R, 1378R
X_SIZE system variable eld 48R
X_TICKNAME keyword 617R, 648R, 654R, 670R
X_VSIZE system variable eld 48R
X_ZSIZE keyword 391R
X0 keyword 408R, 436R
X11 Bitmap, standard le format I/O routines 228B
XANIMATE, seeObsolete Routines
XAXISkeyword 207R
XAXIS_IN keyword 648R
XAXIS_PROPERTIESkeyword 664R
XBACKREGISTER, seeObsolete Routines
XBM_EDIT procedure 1228R, 1352R
XCHARSIZE keyword 100R
XCOORD_CONV keyword 213O, 245O, 254O, 267O,
275O, 283O, 321O, 332O, 340O, 367O, 386O,
411O
XDICE procedure 323B
XDISPLAYFILE procedure 1354R
XDL, seeObsolete Routines
XDR 197B
XDR les 160B, 983R
XDR format (oating point values) 235R
XDR keyword 786R, 983R
XDRTOD keyword 237R
XDRTOF keyword 237R
XFONT function 1356R
XGRID keyword 587R, 1129R, 1136R
XGRIDSTYLE keyword 102R
XINDEPENDENT keyword 616R, 669R
XINTERANIMATE procedure 1357R
XLOADCT procedure 390U, 1361R
XLOG keyword 208R, 307R, 617R, 653R, 669R, 801R,
1006R, 1093R
XMANAGER procedure 289B, 292B, 315B, 1268R,
1363R
XMANAGERTOOL, seeObsolete Routines
Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index Index Y ... Y
Index Index-75
XMARGIN keyword 103R, 728R
XMAX keyword 324R, 1182R
XMAX machine-specic parameter 703R
XMENU, seeObsolete Routines
XMIN keyword 324R
XMIN machine-specic parameter 703R
XMINOR keyword 302U, 103R
XMNG_TMPL procedure 1369R
XMTOOL procedure 1370R
XOFFSET keyword 306B, 142R, 159R, 347R, 356R,
361R, 384R, 1216R, 1226R, 1250R, 1258R, 1265R,
1283R, 1289R, 1295R, 1304R, 1313R, 1360R
XON_XOFF keyword 142R
XOR operator 274U, 33B
XPAD keyword 356R, 1217R
XPALETTE procedure 391U, 1371R
XPDMENU, seeObsolete Routines
XPOSkeyword 1318R
XRANGE keyword 290U, 208O, 241O, 250O, 263O,
272O, 322O, 327O, 337O, 362O, 383O, 406O,
106R, 617R, 669R, 984R, 1011R
XREGISTERED function 292B, 1374R
XRESOL keyword 1340R
XSIZE keyword 306B, 142R, 356R, 359R, 369R, 378R,
380R, 391R, 719R, 833R, 1042R, 1155R, 1193R,
1217R, 1227R, 1250R, 1258R, 1265R, 1283R,
1289R, 1295R, 1305R, 1314R, 1319R, 1352R,
1383R, 1385R
XSQ_TEST function 448U, 1375R
XSTART keyword 719R, 844R
XSTYLE keyword 106R
XSURFACE procedure 1377R
XTHICK keyword 302U, 107R
XTICK_GET keyword 109R
XTICKFORMAT keyword 107R
XTICKFORMAT keyword, YTICKFORMAT keyword,
ZTICKFORMAT keyword 302U
XTICKLEN keyword 108R
XTICKNAME keyword 303U, 109R
XTICKSkeyword 303U, 109R
XTICKV keyword 303U, 109R
XTITLE keyword 109R, 211R, 1119R
XVALUESkeyword 588R, 1129R
XVAREDIT procedure 1378R
XVISIBLE keyword 1042R
xwd les
reading 930R
654R
XY_PLANE keyword 804R
XYEXCH keyword 337U, 1110R
XYOUTSprocedure 293U, 1379R
Seealsopositioning
XYSTYLE keyword 804R
XZ_PLANE keyword 804R
XZEXCH keyword 337U, 1110R
XZSTYLE keyword 804R
Y
Y keyword 301R
Y Offset common property 198U
Y Pad base property 209U
Y Scroll base property 209U
Y Size common property 199U
Y_CH_SIZE system variable eld 48R
Y_PX_CM system variable eld 48R
Y_SCROLL_SIZE keyword 357R, 391R, 1217R, 1259R,
1305R, 1378R
Y_SIZE system variable eld 48R
Y_TICKNAME 617R, 654R
Y_TICKNAME keyword 648R, 670R
Y_VSIZE system variable eld 48R
Y_ZSIZE keyword 392R
Y0 keyword 408R, 436R
YAXISkeyword 207R
YAXIS_IN keyword 648R
YAXIS_PROPERTIESkeyword 664R
YCHARSIZE keyword 100R
YCOORD_CONV keyword 214O, 245O, 255O, 267O,
276O, 283O, 322O, 332O, 340O, 368O, 387O,
411O
YFIT keyword 283R, 679R, 1100R
YGRID keyword 588R, 1129R, 1136R
YGRIDSTYLE keyword 102R
YIELD_TO_TTY keyword 1269R
YINDEPENDENT keyword 616R, 669R
YLOG keyword 208R, 307R, 617R, 653R, 669R, 801R,
1006R, 1093R
YMARGIN keyword 103R, 728R
YMAX keyword 324R
YMIN keyword 324R
YMINOR keyword 302U, 103R
YNOZERO keyword 208R, 801R
YOFFSET keyword 306B, 142R, 159R, 347R, 356R,
361R, 384R, 1217R, 1227R, 1250R, 1258R, 1266R,
1284R, 1289R, 1295R, 1305R, 1314R, 1360R
Index Z ... Z Using IDL, Building IDL Applications, Object Graphics, Reference Guide Index
Index-76 Index
YP0 keyword 1054R
YPAD keyword 356R, 1217R
YPN_1 keyword 1054R
YPOSkeyword 1318R
YRANGE keyword 290U, 208O, 241O, 250O, 263O,
272O, 322O, 327O, 337O, 362O, 383O, 406O,
106R, 617R, 669R, 984R, 1011R
YRESOL keyword 1340R
YSIZE keyword 306B, 143R, 356R, 359R, 370R, 378R,
380R, 391R, 719R, 834R, 1042R, 1155R, 1194R,
1217R, 1227R, 1250R, 1258R, 1266R, 1284R,
1289R, 1296R, 1305R, 1314R, 1319R, 1352R,
1383R, 1385R
YSTART keyword 719R, 844R
YSTYLE keyword 106R
YTHICK keyword 302U, 107R
YTICK_GET keyword 109R
YTICKFORMAT keyword 107R
YTICKLEN keyword 108R
YTICKNAME keyword 303U, 109R
YTICKSkeyword 303U, 109R
YTICKV keyword 303U, 109R
YTITLE keyword 109R, 211R, 1119R
YVALUESkeyword 588R, 1129R
YVISIBLE keyword 1042R
YZ_PLANE keyword 804R
YZEXCH keyword 338U, 1110R
YZSTYLE keyword 804R
Z
Z keyword 110R, 300R
ZAPFCHANCERY keyword 143R
ZAPFDINGBATSkeyword 143R
ZAXISkeyword 207R, 307R, 1093R
ZAXIS_PROPERTIESkeyword 664R
Z-buffer
closing 117R
using with POLYFILL 827R
using with POLYSHADE 832R
warping images to polygons 828R
Z-buffer device 178R
ZBUFFER keyword 412O, 1194R
ZBUFFER_DATA keyword 221O
zbuffering, volume objects 126O
ZCHARSIZE keyword 100R
ZCLIP keyword 394O
ZCOORD_CONV keyword 214O, 245O, 255O, 267O,
276O, 283O, 322O, 332O, 341O, 368O, 387O,
412O
ZD keyword 883R
ZDIFF keyword 980R
ZERO keyword 417R
ZERO_OPACITY_SKIP keyword 412O
zeroed structures 43B, 252B
zeroing byte arrays 233R
ZFAC keyword 324R
ZGRIDSTYLE keyword 102R
ZLOG keyword 1093R
ZMARGIN keyword 103R
ZMAX keyword 324R
ZMIN keyword 324R
ZMINOR keyword 302U, 103R
ZOOM keyword 324R, 363R, 408R
ZOOM procedure 1382R
ZOOM system variable eld 48R
zoom widget 390R
ZOOM_24 procedure 1384R
ZOOM_WINDOW keyword 1383R
ZPIXELSkeywords 1194R
ZRANGE keyword 290U, 208O, 241O, 250O, 263O,
272O, 318O, 327O, 337O, 362O, 383O, 406O,
106R, 984R, 1011R
ZROOTS, seeObsolete Routines
ZSTYLE keyword 106R
ZTHICK keyword 302U, 107R
ZTICK_GET keyword 109R
ZTICKFORMAT keyword 107R
ZTICKLEN keyword 108R
ZTICKNAME keyword 303U, 109R
ZTICKSkeyword 303U, 109R
ZTICKV keyword 303U, 109R
ZTITLE keyword 109R
ZVALUE keyword 344U, 322O, 110R

Ref Book

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Ref Book

Hochgeladen von

Copyright:

Verfügbare Formate

Reference

software program and the accompanying procedures, functions, and

is a trademark of Research Systems Inc., registered in the United States

software program and the accompanying procedures, functions, and

is a trademark of Research Systems Inc., registered in the United States

-------------------------------------------------------------------------------- - For L < 0

Chapter 9: IDL Routines 505

514 Chapter 9: IDL Routines

964 Chapter 9: IDL Routines

1124 Chapter 9: IDL Routines

Das könnte Ihnen auch gefallen