ReferenceGuideVolume 1Routines A - L

IDL Version 4.0October, 1995 EditionCopyright Research Systems, Inc.All Rights Reserved

IDL Version 5.2November, 1998 EditionCopyright Research Systems, Inc.All Rights Reserved

Restricted Rights NoticeThe IDL software program and the accompanying procedures, functions, anddocumentation described herein are sold under license agreement. Their use,duplication, and disclosure are subject to the restrictions stated in the licenseagreement.

Limitation of WarrantyResearch Systems, Inc. makes no warranties, either express or implied, as to anymatter not expressly set forth in the license agreement, including withoutlimitation the condition of the software, merchantability, or fitness for anyparticular purpose.

Research Systems, Inc. shall not be liable for any direct, consequential, or otherdamages suffered by the Licensee or any others resulting from use of the IDLsoftware package or its documentation.

Most Current DocumentationBecause changes may be made to IDL after documentation has gone to press,please consult IDLs hypertext online help system for the most current version ofthis document.

Permission to Reproduce this ManualPurchasers of IDL licenses are given limited permission to reproduce this manualprovided such copies are for their use only and are not sold or distributed to thirdparties. All such copies must contain the title page and this notice page in theirentirety.

AcknowledgmentsIDL is a trademark of Research Systems Inc., registered in the United StatesPatent and Trademark Office, for the computer program described herein. Allother brand or product names are trademarks of their respective holders.

Numerical Recipes is a trademark of Numerical Recipes Software. NumericalRecipes routines are used by permission.

GRG2 is a trademark of Windward Technologies, Inc. The GRG2 software fornonlinear 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 minimum20% post-consumer waste content and meets all EPA guidelines.

ReferenceGuideVolume 2Routines M - Z

IDL Version 5.2November, 1998 EditionCopyright Research Systems, Inc.All Rights Reserved

Restricted Rights NoticeThe IDL software program and the accompanying procedures, functions, anddocumentation described herein are sold under license agreement. Their use,duplication, and disclosure are subject to the restrictions stated in the licenseagreement.

Limitation of WarrantyResearch Systems, Inc. makes no warranties, either express or implied, as to anymatter not expressly set forth in the license agreement, including withoutlimitation the condition of the software, merchantability, or fitness for anyparticular purpose.

Research Systems, Inc. shall not be liable for any direct, consequential, or otherdamages suffered by the Licensee or any others resulting from use of the IDLsoftware package or its documentation.

Most Current DocumentationBecause changes may be made to IDL after documentation has gone to press,please consult IDLs hypertext online help system for the most current version ofthis document.

Permission to Reproduce this ManualPurchasers of IDL licenses are given limited permission to reproduce this manualprovided such copies are for their use only and are not sold or distributed to thirdparties. All such copies must contain the title page and this notice page in theirentirety.

AcknowledgmentsIDL is a trademark of Research Systems Inc., registered in the United StatesPatent and Trademark Office, for the computer program described herein. Allother brand or product names are trademarks of their respective holders.

Numerical Recipes is a trademark of Numerical Recipes Software. NumericalRecipes routines are used by permission.

GRG2 is a trademark of Windward Technologies, Inc. The GRG2 software fornonlinear 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 minimum20% post-consumer waste content and meets all EPA guidelines.

vContents

Chapter 1:

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23About IDL .................................................................................................................. 23IDL Documentation .................................................................................................. 24Typographical Conventions ...................................................................................... 26Reporting Problems ................................................................................................... 26

Chapter 2:

Executive Commands . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 3:

System Variables . . . . . . . . . . . . . . . . . . . . . . . . . 37Constant System Variables ........................................................................................ 37

vi Contents

Contents IDL Reference Guide

Error Handling and Informational System Variables ............................................... 38IDL Environment System Variables .......................................................................... 42Graphics System Variables ......................................................................................... 46

Chapter 4:

Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 5:

Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Chapter 6:

Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Fonts in IDL Direct vs. Object Graphics ................................................................... 66About the Vector Fonts .............................................................................................. 66About the TrueType Fonts ........................................................................................ 68About Device Fonts ................................................................................................... 72Choosing a Font Type ................................................................................................ 77Embedded Formatting Commands ........................................................................... 79Formatting Command Examples .............................................................................. 82TrueTypeFont Samples ............................................................................................. 86Vector Font Samples .................................................................................................. 89

Chapter 7:

Graphics Keywords . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 8:

IDL Graphics Devices . . . . . . . . . . . . . . . . . . . . . . 111Keywords Accepted by the IDL Devices .................................................................. 112Window Systems ....................................................................................................... 143Printing Graphics Output Files ................................................................................ 146The CGM Device ...................................................................................................... 148The HP-GL Device ................................................................................................... 150The LJ Device ............................................................................................................ 151The Macintosh Display Device ................................................................................ 154The Null Display Device ........................................................................................... 154The PCL Device ........................................................................................................ 154The Printer Device .................................................................................................... 156The PostScript Device .............................................................................................. 156The Regis Terminal Device ...................................................................................... 168

Contents vii

IDL Reference Guide Contents

The Tektronix Device .............................................................................................. 169The Microsoft Windows Device .............................................................................. 170The X Windows Device ........................................................................................... 171The Z-Buffer Device ................................................................................................ 178

Chapter 9:

IDL Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183How to Use this Chapter ......................................................................................... 183A_CORRELATE ....................................................................................................... 187ABS ............................................................................................................................ 189ACOS ........................................................................................................................ 190ALOG ........................................................................................................................ 191ALOG10 .................................................................................................................... 192AMOEBA .................................................................................................................. 193ANNOTATE ............................................................................................................. 196ARG_PRESENT ....................................................................................................... 198ARROW .................................................................................................................... 200ASCII_TEMPLATE .................................................................................................. 202ASIN ......................................................................................................................... 203ASSOC ...................................................................................................................... 204ATAN ........................................................................................................................ 206AXIS .......................................................................................................................... 207BAR_PLOT ............................................................................................................... 210BESELI ...................................................................................................................... 213BESELJ ...................................................................................................................... 214BESELY ..................................................................................................................... 215BETA ......................................................................................................................... 216BILINEAR ................................................................................................................. 217BIN_DATE ............................................................................................................... 219BINDGEN ................................................................................................................ 220BINOMIAL ............................................................................................................... 221BLAS_AXPY ............................................................................................................. 223BLK_CON ................................................................................................................ 225BOX_CURSOR ........................................................................................................ 227BREAKPOINT ......................................................................................................... 229BROYDEN ................................................................................................................ 231BYTARR ................................................................................................................... 233BYTE ......................................................................................................................... 234BYTEORDER ........................................................................................................... 235BYTSCL .................................................................................................................... 238C_CORRELATE ....................................................................................................... 240CALDAT ................................................................................................................... 242

viii Contents

Contents IDL Reference Guide

CALENDAR .............................................................................................................. 244CALL_EXTERNAL ................................................................................................... 245CALL_FUNCTION .................................................................................................. 252CALL_METHOD ..................................................................................................... 253CALL_PROCEDURE ............................................................................................... 254CATCH ..................................................................................................................... 255CD ............................................................................................................................. 257CEIL ........................................................................................................................... 259CHEBYSHEV ............................................................................................................ 260CHECK_MATH ....................................................................................................... 261CHISQR_CVF .......................................................................................................... 265CHISQR_PDF ........................................................................................................... 266CHOLDC .................................................................................................................. 267CHOLSOL ................................................................................................................. 268CINDGEN ................................................................................................................. 270CIR_3PNT ................................................................................................................. 271CLOSE ....................................................................................................................... 273CLUST_WTS ............................................................................................................ 274CLUSTER .................................................................................................................. 275COLOR_CONVERT ................................................................................................ 277COLOR_QUAN ........................................................................................................ 279COMFIT .................................................................................................................... 282COMPLEX ................................................................................................................ 285COMPLEXARR ........................................................................................................ 287COMPLEXROUND ................................................................................................. 288COMPUTE_MESH_NORMALS ............................................................................. 289COND ....................................................................................................................... 290CONGRID ................................................................................................................ 291CONJ ......................................................................................................................... 293CONSTRAINED_MIN ............................................................................................ 294CONTOUR ............................................................................................................... 300CONVERT_COORD ............................................................................................... 309CONVOL .................................................................................................................. 311COORD2TO3 ........................................................................................................... 314CORRELATE ............................................................................................................ 315COS ........................................................................................................................... 317COSH ........................................................................................................................ 318CRAMER ................................................................................................................... 319CREATE_STRUCT ................................................................................................... 321CREATE_VIEW ........................................................................................................ 323CROSSP ..................................................................................................................... 326CRVLENGTH ........................................................................................................... 327CT_LUMINANCE .................................................................................................... 329

Contents ix

IDL Reference Guide Contents

CTI_TEST ................................................................................................................. 330CURSOR ................................................................................................................... 332CURVEFIT ............................................................................................................... 335CV_COORD ............................................................................................................ 338CVTTOBM ............................................................................................................... 340CW_ANIMATE ....................................................................................................... 341CW_ANIMATE_GETP ........................................................................................... 345CW_ANIMATE_LOAD .......................................................................................... 346CW_ANIMATE_RUN ............................................................................................. 348CW_ARCBALL ........................................................................................................ 350CW_BGROUP ......................................................................................................... 354CW_CLR_INDEX .................................................................................................... 358CW_COLORSEL ...................................................................................................... 360CW_DEFROI ........................................................................................................... 362CW_DICE ................................................................................................................ 366CW_FIELD ............................................................................................................... 368CW_FORM .............................................................................................................. 371CW_FSLIDER .......................................................................................................... 377CW_ORIENT ........................................................................................................... 380CW_PDMENU ........................................................................................................ 382CW_RGBSLIDER .................................................................................................... 387CW_TMPL ............................................................................................................... 389CW_ZOOM ............................................................................................................. 390DBLARR ................................................................................................................... 394DCINDGEN ............................................................................................................. 395DCOMPLEX ............................................................................................................ 396DCOMPLEXARR ..................................................................................................... 398DEFINE_KEY ........................................................................................................... 399DEFROI .................................................................................................................... 407DEFSYSV .................................................................................................................. 409DELETE_SYMBOL (VMS Only) ............................................................................ 411DELLOG (VMS Only) ............................................................................................. 412DELVAR ................................................................................................................... 413DEMO_MODE ........................................................................................................ 414DERIV ....................................................................................................................... 415DERIVSIG ................................................................................................................ 416DETERM .................................................................................................................. 417DEVICE .................................................................................................................... 419DFPMIN ................................................................................................................... 420DIALOG_MESSAGE ............................................................................................... 423DIALOG_PICKFILE ................................................................................................ 426DIALOG_PRINTJOB .............................................................................................. 429DIALOG_PRINTERSETUP .................................................................................... 430

x Contents

Contents IDL Reference Guide

DIGITAL_FILTER .................................................................................................... 431DILATE ..................................................................................................................... 432DINDGEN ................................................................................................................ 435DISSOLVE ................................................................................................................ 436DIST .......................................................................................................................... 437DO_APPLE_SCRIPT ................................................................................................ 438DOC_LIBRARY ........................................................................................................ 440DOUBLE ................................................................................................................... 442EFONT ...................................................................................................................... 443EIGENQL .................................................................................................................. 444EIGENVEC ............................................................................................................... 446ELMHES .................................................................................................................... 448EMPTY ...................................................................................................................... 449EOF ............................................................................................................................ 450ERASE ....................................................................................................................... 451ERODE ...................................................................................................................... 452ERRORF .................................................................................................................... 455ERRPLOT .................................................................................................................. 456EXECUTE ................................................................................................................. 458EXIT .......................................................................................................................... 459EXP ............................................................................................................................ 460EXPAND ................................................................................................................... 461EXPAND_PATH ...................................................................................................... 462EXPINT ..................................................................................................................... 465EXTRAC .................................................................................................................... 467EXTRACT_SLICE .................................................................................................... 469F_CVF ....................................................................................................................... 471F_PDF ........................................................................................................................ 472FACTORIAL ............................................................................................................. 473FFT ............................................................................................................................ 474FILEPATH ................................................................................................................ 478FINDFILE .................................................................................................................. 480FINDGEN ................................................................................................................. 482FINITE ...................................................................................................................... 483FIX ............................................................................................................................. 484FLICK ........................................................................................................................ 485FLOAT ....................................................................................................................... 486FLOOR ...................................................................................................................... 487FLOW3 ...................................................................................................................... 488FLTARR ..................................................................................................................... 490FLUSH ....................................................................................................................... 491FORMAT_AXIS_VALUES ....................................................................................... 492FREE_LUN ............................................................................................................... 493

Contents xi

IDL Reference Guide Contents

FSTAT ....................................................................................................................... 494FULSTR .................................................................................................................... 496FUNCT ..................................................................................................................... 497FV_TEST .................................................................................................................. 498FX_ROOT ................................................................................................................ 500FZ_ROOTS ............................................................................................................... 502GAMMA ................................................................................................................... 504GAMMA_CT ............................................................................................................ 505GAUSS_CVF ............................................................................................................ 506GAUSS_PDF ............................................................................................................ 507GAUSS2DFIT ........................................................................................................... 508GAUSSFIT ................................................................................................................ 511GAUSSINT ............................................................................................................... 513GET_KBRD .............................................................................................................. 514GET_LUN ................................................................................................................ 516GET_SCREEN_SIZE ............................................................................................... 517GET_SYMBOL (VMS Only) ................................................................................... 518GETENV ................................................................................................................... 519GRID3 ....................................................................................................................... 522GS_ITER ................................................................................................................... 525H_EQ_CT ................................................................................................................. 527H_EQ_INT ............................................................................................................... 528HANNING ............................................................................................................... 529HDF_BROWSER ..................................................................................................... 530HDF_READ .............................................................................................................. 533HEAP_GC ............................................................................................................... 536HELP ......................................................................................................................... 537HILBERT .................................................................................................................. 541HIST_2D .................................................................................................................. 542HIST_EQUAL .......................................................................................................... 544HISTOGRAM .......................................................................................................... 546HLS ........................................................................................................................... 550HQR .......................................................................................................................... 551HSV ........................................................................................................................... 553IBETA ....................................................................................................................... 554IDENTITY ................................................................................................................ 556IGAMMA ................................................................................................................. 557IMAGE_CONT ........................................................................................................ 559IMAGINARY ............................................................................................................ 560INDGEN ................................................................................................................... 561INT_2D .................................................................................................................... 563INT_3D .................................................................................................................... 566INT_TABULATED .................................................................................................. 568

xii Contents

Contents IDL Reference Guide

INTARR .................................................................................................................... 570INTERPOL ................................................................................................................ 571INTERPOLATE ........................................................................................................ 573INVERT ..................................................................................................................... 576IOCTL ....................................................................................................................... 578ISHFT ........................................................................................................................ 581JOURNAL ................................................................................................................. 582JULDAY .................................................................................................................... 583KEYWORD_SET ...................................................................................................... 585KRIG2D ..................................................................................................................... 586KURTOSIS ................................................................................................................ 590KW_TEST ................................................................................................................. 591L64INDGEN ............................................................................................................. 593LABEL_DATE ........................................................................................................... 594LABEL_REGION ...................................................................................................... 596LADFIT ..................................................................................................................... 598LEEFILT .................................................................................................................... 600LINBCG .................................................................................................................... 601LINDGEN ................................................................................................................. 603LINFIT ...................................................................................................................... 604LINKIMAGE ............................................................................................................. 606LIVE_Tools ............................................................................................................... 611LIVE_CONTOUR .................................................................................................... 612LIVE_CONTROL ..................................................................................................... 619LIVE_DESTROY ...................................................................................................... 621LIVE_EXPORT ......................................................................................................... 623LIVE_IMAGE ........................................................................................................... 625LIVE_INFO ............................................................................................................... 630LIVE_LINE ............................................................................................................... 640LIVE_LOAD ............................................................................................................. 644LIVE_OPLOT ........................................................................................................... 645LIVE_PLOT .............................................................................................................. 649LIVE_PRINT ............................................................................................................. 655LIVE_RECT .............................................................................................................. 656LIVE_STYLE ............................................................................................................. 659LIVE_SURFACE ....................................................................................................... 665LIVE_TEXT .............................................................................................................. 671LJLCT ........................................................................................................................ 674LL_ARC_DISTANCE ............................................................................................... 675LMFIT ....................................................................................................................... 677LMGR ........................................................................................................................ 680LNGAMMA .............................................................................................................. 682LNP_TEST ................................................................................................................ 683

Contents xiii

IDL Reference Guide Contents

LOADCT .................................................................................................................. 685LON64ARR .............................................................................................................. 686LONARR .................................................................................................................. 687LONG ....................................................................................................................... 688LONG64 ................................................................................................................... 689LSODE ...................................................................................................................... 690LU_COMPLEX ........................................................................................................ 694LUDC ........................................................................................................................ 696LUMPROVE ............................................................................................................. 697LUSOL ...................................................................................................................... 699M_CORRELATE ...................................................................................................... 701MACHAR ................................................................................................................. 703MAKE_ARRAY ........................................................................................................ 705MAP_CONTINENTS .............................................................................................. 708MAP_GRID .............................................................................................................. 711MAP_IMAGE ........................................................................................................... 715MAP_PATCH .......................................................................................................... 718MAP_PROJ_INFO ................................................................................................... 721MAP_SET ................................................................................................................. 723MAX .......................................................................................................................... 731MD_TEST ................................................................................................................ 733MEAN ....................................................................................................................... 735MEANABSDEV ........................................................................................................ 736MEDIAN .................................................................................................................. 738MESH_OBJ .............................................................................................................. 740MESSAGE ................................................................................................................. 745MIN .......................................................................................................................... 747MIN_CURVE_SURF ............................................................................................... 748MK_HTML_HELP .................................................................................................. 751MODIFYCT ............................................................................................................. 754MOMENT ................................................................................................................ 755MPEG_CLOSE ......................................................................................................... 757MPEG_OPEN .......................................................................................................... 758MPEG_PUT ............................................................................................................. 760MPEG_SAVE ............................................................................................................ 762MULTI ...................................................................................................................... 763N_ELEMENTS ......................................................................................................... 764N_PARAMS ............................................................................................................. 765N_TAGS ................................................................................................................... 766NEWTON ................................................................................................................. 767NORM ...................................................................................................................... 769OBJ_CLASS ............................................................................................................ 771OBJ_DESTROY ...................................................................................................... 772

xiv Contents

Contents IDL Reference Guide

OBJ_ISA ................................................................................................................. 773OBJ_NEW .............................................................................................................. 774OBJ_VALID ........................................................................................................... 776OBJARR ................................................................................................................. 778ON_ERROR .............................................................................................................. 779ON_IOERROR ......................................................................................................... 780ONLINE_HELP ........................................................................................................ 781OPEN ........................................................................................................................ 783OPLOT ...................................................................................................................... 792OPLOTERR ............................................................................................................... 794P_CORRELATE ........................................................................................................ 795PCOMP ..................................................................................................................... 796PLOT ......................................................................................................................... 800PLOT_3DBOX .......................................................................................................... 803PLOT_FIELD ............................................................................................................ 806PLOTERR .................................................................................................................. 808PLOTS ....................................................................................................................... 809PNT_LINE ................................................................................................................ 811POINT_LUN ............................................................................................................ 813POLAR_CONTOUR ................................................................................................ 815POLAR_SURFACE ................................................................................................... 817POLY ......................................................................................................................... 819POLY_2D .................................................................................................................. 820POLY_AREA ............................................................................................................. 823POLY_FIT ................................................................................................................. 824POLYFILL ................................................................................................................. 826POLYFILLV .............................................................................................................. 829POLYFITW ............................................................................................................... 831POLYSHADE ............................................................................................................ 832POLYWARP .............................................................................................................. 835POPD ........................................................................................................................ 837POWELL ................................................................................................................... 838PRIMES ..................................................................................................................... 840PRINT/PRINTF ........................................................................................................ 841PRINTD .................................................................................................................... 843PROFILE ................................................................................................................... 844PROFILER ................................................................................................................. 846PROFILES ................................................................................................................. 848PROJECT_VOL ........................................................................................................ 850PS_SHOW_FONTS .................................................................................................. 853PSAFM ...................................................................................................................... 854PSEUDO ................................................................................................................... 855PTR_FREE ............................................................................................................. 856

Contents xv

IDL Reference Guide Contents

PTR_NEW .............................................................................................................. 857PTR_VALID ........................................................................................................... 858PTRARR ................................................................................................................. 860PUSHD ..................................................................................................................... 861QROMB .................................................................................................................... 862QROMO ................................................................................................................... 864QSIMP ...................................................................................................................... 866QUERY_* ROUTINES ............................................................................................ 868QUERY_BMP ........................................................................................................... 870QUERY_DICOM ..................................................................................................... 871QUERY_GIF ............................................................................................................. 873QUERY_JPEG .......................................................................................................... 874QUERY_PICT .......................................................................................................... 875QUERY_PNG ........................................................................................................... 876QUERY_PPM ........................................................................................................... 878QUERY_SRF ............................................................................................................ 879QUERY_TIFF ........................................................................................................... 880R_CORRELATE ....................................................................................................... 882R_TEST ..................................................................................................................... 884RANDOMN ............................................................................................................. 886RANDOMU ............................................................................................................. 890RANKS ...................................................................................................................... 892RDPIX ....................................................................................................................... 894READ/READF .......................................................................................................... 895READ_ASCII ............................................................................................................ 898READ_BMP ............................................................................................................. 901READ_DICOM ........................................................................................................ 903READ_GIF ............................................................................................................... 904READ_INTERFILE .................................................................................................. 906READ_JPEG ............................................................................................................. 907READ_PICT ............................................................................................................. 910READ_PNG .............................................................................................................. 911READ_PPM .............................................................................................................. 913READ_SPR ............................................................................................................... 915READ_SRF ............................................................................................................... 916READ_SYLK ............................................................................................................. 918READ_TIFF .............................................................................................................. 921READ_WAVE .......................................................................................................... 926READ_X11_BITMAP .............................................................................................. 928READ_XWD ............................................................................................................ 930READS ...................................................................................................................... 931READU ..................................................................................................................... 933REBIN ....................................................................................................................... 935

xvi Contents

Contents IDL Reference Guide

RECALL_COMMANDS .......................................................................................... 938RECON3 ................................................................................................................... 939REDUCE_COLORS ................................................................................................. 944REFORM ................................................................................................................... 945REGRESS ................................................................................................................... 947REPLICATE .............................................................................................................. 949REPLICATE_INPLACE ........................................................................................... 950RESOLVE_ALL ......................................................................................................... 952RESOLVE_ROUTINE .............................................................................................. 954RESTORE .................................................................................................................. 955RETALL ..................................................................................................................... 957RETURN ................................................................................................................... 958REVERSE .................................................................................................................. 960REWIND ................................................................................................................... 962RIEMANN ................................................................................................................ 963RK4 ............................................................................................................................ 967ROBERTS .................................................................................................................. 969ROT ........................................................................................................................... 970ROTATE .................................................................................................................... 972ROUND .................................................................................................................... 974ROUTINE_INFO ..................................................................................................... 975RS_TEST ................................................................................................................... 977RSTRPOS .................................................................................................................. 979S_TEST ...................................................................................................................... 980SAVE .......................................................................................................................... 982SCALE3 ..................................................................................................................... 984SCALE3D .................................................................................................................. 985SEARCH2D ............................................................................................................... 986SEARCH3D ............................................................................................................... 989SET_PLOT ................................................................................................................ 992SET_SHADING ........................................................................................................ 994SET_SYMBOL .......................................................................................................... 996SETENV (Unix and Windows Only) ...................................................................... 997SETLOG (VMS Only) .............................................................................................. 998SETUP_KEYS ......................................................................................................... 1000SFIT ......................................................................................................................... 1002SHADE_SURF ........................................................................................................ 1004SHADE_SURF_IRR ................................................................................................ 1008SHADE_VOLUME ................................................................................................. 1010SHIFT ...................................................................................................................... 1013SHOW3 ................................................................................................................... 1015SHOWFONT .......................................................................................................... 1017SIN ........................................................................................................................... 1019

Contents xvii

IDL Reference Guide Contents

SINDGEN ............................................................................................................... 1020SINH ....................................................................................................................... 1021SIZE ........................................................................................................................ 1022SKEWNESS ............................................................................................................ 1025SKIPF ...................................................................................................................... 1026SLICER3 ................................................................................................................. 1027SLIDE_IMAGE ....................................................................................................... 1040SMOOTH ............................................................................................................... 1043SOBEL ..................................................................................................................... 1045SORT ...................................................................................................................... 1046SPAWN ................................................................................................................... 1047SPH_4PNT ............................................................................................................. 1051SPH_SCAT ............................................................................................................. 1052SPL_INIT ................................................................................................................ 1054SPL_INTERP .......................................................................................................... 1056SPLINE ................................................................................................................... 1058SPLINE_P ............................................................................................................... 1059SPRSAB ................................................................................................................... 1061SPRSAX .................................................................................................................. 1063SPRSIN ................................................................................................................... 1064SQRT ...................................................................................................................... 1066STANDARDIZE ..................................................................................................... 1067STDDEV ................................................................................................................. 1069STOP ....................................................................................................................... 1070STR_SEP ................................................................................................................. 1071STRARR .................................................................................................................. 1073STRCOMPRESS ..................................................................................................... 1074STRETCH ............................................................................................................... 1075STRING .................................................................................................................. 1077STRLEN .................................................................................................................. 1080STRLOWCASE ....................................................................................................... 1081STRMESSAGE ........................................................................................................ 1082STRMID ................................................................................................................. 1083STRPOS .................................................................................................................. 1084STRPUT .................................................................................................................. 1085STRTRIM ............................................................................................................... 1086STRUCT_ASSIGN ................................................................................................. 1087STRUPCASE .......................................................................................................... 1089SURFACE ............................................................................................................... 1090SURFR .................................................................................................................... 1095SVDC ...................................................................................................................... 1096SVDFIT ................................................................................................................... 1098SVSOL ..................................................................................................................... 1102

xviii Contents

Contents IDL Reference Guide

SWAP_ENDIAN ..................................................................................................... 1104SYSTIME ................................................................................................................. 1105T_CVF ..................................................................................................................... 1107T_PDF ..................................................................................................................... 1108T3D .......................................................................................................................... 1109TAG_NAMES ......................................................................................................... 1111TAN ......................................................................................................................... 1112TANH ...................................................................................................................... 1113TAPRD .................................................................................................................... 1114TAPWRT ................................................................................................................. 1115TEK_COLOR .......................................................................................................... 1116TEMPORARY ......................................................................................................... 1117THIN ....................................................................................................................... 1118THREED ................................................................................................................. 1119TIME_TEST2 .......................................................................................................... 1120TM_TEST ................................................................................................................ 1121TOTAL .................................................................................................................... 1123TRACE .................................................................................................................... 1125TRANSPOSE ........................................................................................................... 1126TRI_SURF ............................................................................................................... 1128TRIANGULATE ..................................................................................................... 1131TRIGRID ................................................................................................................. 1134TRIQL ..................................................................................................................... 1140TRIRED ................................................................................................................... 1142TRISOL ................................................................................................................... 1143TRNLOG ................................................................................................................. 1145TS_COEF ................................................................................................................ 1147TS_DIFF .................................................................................................................. 1148TS_FCAST ............................................................................................................... 1149TS_SMOOTH ......................................................................................................... 1151TV ............................................................................................................................ 1153TVCRS ..................................................................................................................... 1157TVLCT .................................................................................................................... 1159TVRD ...................................................................................................................... 1161TVSCL ..................................................................................................................... 1164UINDGEN .............................................................................................................. 1166UINT ....................................................................................................................... 1167UINTARR ............................................................................................................... 1168UL64INDGEN ........................................................................................................ 1169ULINDGEN ............................................................................................................ 1170ULON64ARR .......................................................................................................... 1171ULONARR .............................................................................................................. 1172ULONG ................................................................................................................... 1173

Contents xix

IDL Reference Guide Contents

ULONG64 .............................................................................................................. 1174UNIQ ...................................................................................................................... 1175USERSYM ............................................................................................................... 1177VARIANCE ............................................................................................................ 1179VAX_FLOAT .......................................................................................................... 1180VEL ......................................................................................................................... 1182VELOVECT ............................................................................................................ 1184VERT_T3D ............................................................................................................. 1186VOIGT .................................................................................................................... 1188VORONOI ............................................................................................................. 1190VOXEL_PROJ ........................................................................................................ 1192WAIT ...................................................................................................................... 1196WARP_TRI ............................................................................................................ 1197WDELETE .............................................................................................................. 1199WEOF ..................................................................................................................... 1200WF_DRAW ............................................................................................................ 1201WHERE .................................................................................................................. 1203WIDGET_BASE ..................................................................................................... 1205WIDGET_BUTTON .............................................................................................. 1222WIDGET_CONTROL ........................................................................................... 1230WIDGET_DRAW .................................................................................................. 1252WIDGET_DROPLIST ........................................................................................... 1262WIDGET_EVENT ................................................................................................. 1268WIDGET_INFO ..................................................................................................... 1271WIDGET_LABEL ................................................................................................... 1280WIDGET_LIST ...................................................................................................... 1285WIDGET_SLIDER ................................................................................................. 1291WIDGET_TABLE .................................................................................................. 1298WIDGET_TEXT .................................................................................................... 1309WINDOW .............................................................................................................. 1317WRITE_BMP ......................................................................................................... 1320WRITE_GIF ........................................................................................................... 1322WRITE_JPEG ......................................................................................................... 1324WRITE_NRIF ......................................................................................................... 1327WRITE_PICT ......................................................................................................... 1328WRITE_PNG ......................................................................................................... 1329WRITE_PPM ......................................................................................................... 1331WRITE_SPR ........................................................................................................... 1332WRITE_SRF ........................................................................................................... 1333WRITE_SYLK ........................................................................................................ 1335WRITE_TIFF .......................................................................................................... 1337WRITE_WAVE ...................................................................................................... 1342WRITEU ................................................................................................................. 1344

xx Contents

Contents IDL Reference Guide

WSET ....................................................................................................................... 1346WSHOW ................................................................................................................. 1347WTN ........................................................................................................................ 1348XBM_EDIT ............................................................................................................. 1352XDISPLAYFILE ...................................................................................................... 1354XFONT .................................................................................................................... 1356XINTERANIMATE ................................................................................................ 1357XLOADCT .............................................................................................................. 1361XMANAGER ........................................................................................................... 1363XMNG_TMPL ........................................................................................................ 1369XMTOOL ................................................................................................................ 1370XPALETTE .............................................................................................................. 1371XREGISTERED ....................................................................................................... 1374XSQ_TEST .............................................................................................................. 1375XSURFACE ............................................................................................................. 1377XVAREDIT ............................................................................................................. 1378XYOUTS ................................................................................................................. 1379ZOOM ..................................................................................................................... 1382ZOOM_24 ............................................................................................................... 1384

Chapter 10:

Scientific Data Formats . . . . . . . . . . . . . . . . . . . 1387CDFCommon Data Format ............................................................................... 1387HDFHierarchical Data Format .......................................................................... 1388HDF-EOSHierarchical Data Format-Earth Observing System ....................... 1388NetCDFNetwork Common Data Format ......................................................... 1389

Chapter 11:

Obsolete Routines . . . . . . . . . . . . . . . . . . . . . . . 1391Backwards Compatibility ....................................................................................... 1391Detecting Use of Obsolete Features ....................................................................... 1392Documentation for Obsolete Routines ................................................................. 1392Routines That Became Obsolete in IDL Version 5.1 ............................................ 1393Routines That Became Obsolete in IDL Version 5.0 ............................................ 1393Routines That Became Obsolete in IDL Version 4.0 or Earlier ........................... 1394Obsolete System Variables ..................................................................................... 1399

Chapter 12:

VMS Floating-Point Arithmetic in IDL 5.1 . . . . . . 1401VAX Floating-Point Format Background ............................................................. 1402

Contents xxi

IDL Reference Guide Contents

Transition Issues .................................................................................................... 1403A Warning About Floating-Point Conversions ................................................... 1404A Strategy For Converting VMS IDL Programs ................................................... 1405Using CALL_EXTERNAL Under IDL 5.1 and Later ........................................... 1406A Note on the VMS G Float Format ..................................................................... 1407

Index

xxii Contents

Contents IDL Reference Guide

23

Chapter 1

Overview

This chapter includes information about IDL, the IDL documentation set, and aboutcontacting Research Systems regarding problems with IDL.

About IDLIDL is a complete computing environment for the interactive analysis and visualizationof data. IDL integrates a powerful, array-oriented language with numerous mathematicalanalysis and graphical display techniques. Programming in IDL is a time-savingalternative to programming in FORTRAN or Cusing IDL, tasks which require days orweeks of programming with traditional languages can be accomplished in hours. You canexplore data interactively using IDL commands and then create complete applications bywriting IDL programs.

Advantages of IDL include:

IDL is a complete, structured language that can be used both interactively and to createsophisticated 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.

Immediate compilation and execution of IDL commands provides instant feedback andhands-on interaction.

Rapid 2D plotting, multi-dimensional plotting, volume visualization, image display, andanimation 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 flexible 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, andXWD) and scientific data formats (CDF, HDF, and NetCDF).

IDL widgets can be used to quickly create multi-platform graphical user interfaces to yourIDL programs.

IDL programs run the same across all supported platforms (Unix, VMS, MicrosoftWindows, and Macintosh systems) with little or no modification. This application port-ability allows you to easily support a variety of computers.

Existing FORTRAN and C routines can be dynamically-linked into IDL to add specializedfunctionality. Alternatively, C and FORTRAN programs can call IDL routines as a sub-routine library or display engine.

IDL DocumentationIDLs Online Help system gives you access to the complete IDL documentation set inelectronic, 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 theIDL Development Environment user interface.

Research Systems provides a subset of the complete IDL documentation set in printedform along with your copy of the IDL software. We do not ship the full printeddocumentation set because some volumes cover specialized topics, which are of limitedinterest to some of our customers. Shipping only the volumes of greatest general interestin printed form allows us to provide the highest quality documentation set possible whileminimizing the impact of our documentation on the environment. In addition to beingavailable on-line, volumes not automatically shipped with new or upgrade orders areavailable for purchase; use the order sheet included with your shipment or consult yoursales representative or distributor for details.

The IDL documentation set consists of the following volumes:

Using IDLUsing IDL explains IDL from an interactive users point of view. It contains informationabout the IDL environment, the structure of IDL, and how to use IDL Direct Graphics toanalyze your data.

Chapter 1: Overview 25

IDL Reference Guide IDL Documentation

Building IDL ApplicationsBuilding IDL Applications explains how to use the IDL language to write programs from simple procedures to large, complex applications. It contains information on thestructure of the IDL language, programming techniques, IDL Direct Graphics, and IDLsuser-interface toolkit.

IDL Reference GuideThe Reference Guide (this book) is a two-volume set that contains detailed informationabout all of IDLs non-object oriented procedures, functions, system variables, andcommands. Information on IDLs object-oriented features is contained in Building IDLApplications; information on IDL Object Graphics is contained in Object Graphics.

Object GraphicsObject Graphics contains a complete discussion of IDL Object Graphics. This volume alsocontains the complete reference to IDLs object class libraries.

Note Each of the above books includes a comprehensive index that covers all four volumes.

Using InsightUsing Insight contains information on IDL Insight, the graphical interface to IDLsanalysis capabilities. Insight allows you to import, analyze, and visualize data withoutprogramming in the IDL language.

External Development GuideThe External Development Guide explains how to use IDL in concert with yourcomputers operating system or with programs written in other programming languages.

Scientific Data FormatsScientific Data Formats contains detailed information about IDLs routines for dealingwith Common Data Format (CDF), Hierarchical Data Format (HDF), Earth ObservingSystem extensions to HDF (HDF-EOS), and Network Common Data Format (NetCDF)files.

IDL DataMiner GuideThe DataMiner Guide contains information on using IDL to interact with databases usingthe Open Database Connectivity (ODBC) interface.

Note The DataMiner option must be purchased separately.

IDL HandiGuideThe HandiGuide is a handy quick reference that contains calling-sequence informationon all IDL routines.

26 Chapter 1: Overview

Typographical Conventions IDL Reference Guide

Typographical ConventionsThe following typographical conventions are used throughout the IDL documentation set:

UPPER CASEIDL functions, procedures, and keywords are displayed in UPPER CASE type. For exam-ple, the calling sequence for an IDL procedure looks like this:

CONTOUR, Z [, X, Y]

Mixed CaseIDL object class and method names are displayed in Mixed Case type. For example, thecalling sequence to create an object and call a method looks like this:

object = OBJ_NEW('IDLgrPlot')

object -> GetProperty, ALL=properties

Italic typeArguments to IDL procedures and functions data or variables you must provide aredisplayed 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 areoptional. Do not type the brackets. In the above CONTOUR example, X and Y are optionalarguments. Square brackets are also used to specify array elements.

Courier typeIn examples or program listings, things that you must enter at the command line or in afile are displayed in courier type. Results or data that IDL displays on your computerscreen are shown in courier bold type. An exampl