You can also execute personal startup files to further customize your session. These are usually batch files (see "Program Execution" below), executed by typing @[filename]

During an interactive session, your command line entries are stored in a command recall buffer (as in UNIX tcsh). You can use the "up arrow" ("down arrow") keys to move backwards (forwards) thru the command buffer to recall or edit commands. Use EMACS-like editing commands (see Chapter 2 of Using IDL). The default for the command buffer length is 20 commands. (It is useful to set this to a higher number by defining the system variable !EDIT_INPUT=100 in the startup file. This is done by default in the MOUSSE startup files.) Recall/edit is an exceptionally useful means of iteration during an IDL session.
In editing, be careful not to give the ^d command on an empty line, since this will terminate your session!

find=where(x gt 100, count) & print,count.

3. HELP

[Up to Contents]

Documentation: IDL is thoroughly documented in electronic and printed manuals. RSI issues a full set of manuals in PDF format with each license. If the PDF versions have been installed on your computer system, they can be accessed through the UNIX command idlman. The most important manuals are Using IDL, The IDL HandiGuide/Quick Reference, Building IDL Applications, and The IDL Reference Guide. These are accessible on-line from within an IDL session through a Hyperhelp facility.

The current introductory IDL guide is called Getting Started with IDL---click for a PDF version. The printed versions of the older IDL Basics for V.3 and 4 take you through a number of interesting sample applications and provide helpful hints.
The best way to remind yourself quickly of the operation of intrinsic IDL routines is to keep a copy of the printed IDL Handiguide at hand.

Learn by Example: One of the best ways to learn how to write and use IDL programs is simply to inspect existing IDL programs in the AstUseLib directories. You can more them in UNIX, or use the AstUseLib getpro routine to copy them to your local directory. To view public routines during an IDL session, type .run -t [routine name].

• To access documentation for IDL_5.1 in HTML using a Web browser, click here. and bookmark the page.

• Another source for IDL PDF documentation: IDL Online Guide (UCI)

• idlhelp or idlman: given from the UNIX prompt, these commands open the PDF versions of the standard IDL manuals (if they are loaded on your system).

• ? : given from within IDL, this invokes the IDL HyperHelp facility. V.6 employs an Adobe Acrobat Reader to search/display the PDF versions of the full set of IDL manuals. Unfortunately, this approach is more awkward and less efficient than the customized V.5 HyperHelp interface. However, all the information you need is available at several levels of specialization.

• ?[command] : provides HyperHelp information on the given intrinsic IDL command. Does not work for user-supplied routines. Note: no space (or quote mark) between ? and name.

• [command without arguments] : Most AstUseLib and other user-supplied procedures are coded such that if you enter the name of the routine without arguments, a list of expected arguments is printed on your screen. Does not work for intrinsic IDL routines (but see help,/rou below). Does not work on most functions (as opposed to procedures).
  This is a useful convention to code into your own programs. Use the n_params function to sense the absence of input parameters, as in the following:

    if (n_params(0) eq 0) then begin
           print,'CALLING SEQUENCE: program_name,var1,var2,var3'
           return
         endif
    

• man: The man command without arguments produces a graphics menu display similar to that generated by ? but which provides information on AstUseLib, MOUSSE, and other user-written routines. man is a program distributed by Wayne Landsman from: http://idlastro.gsfc.nasa.gov/ftp/contrib/landsman/help/.
  Note: the topics included are only those "pro" files which have been parsed by a special documentation extraction routine (mk_library_help) and placed in a special help directory. This is usually done by the person who maintains your IDL system.

• man,[command-name-string]: This version of the man command, in which you enter a string containing the name of the command you want information on, prints the information header of the routine in your IDL command window. It works on any properly formatted IDL routine in the IDL_PATH. For instance, if you want information on the AstUseLib STRD command, you would type:

  man,'strd

  Note that the argument of MAN must be an IDL string---i.e. it must be quoted (but the trailing quote mark can be omitted). If you already know the name of the command of interest, this is faster and more convenient than using the graphics version.
  The man function operates by finding the first file with the name "[command].pro" in the IDL_PATH and listing all those lines in the file between the two lines starting with ";+" and ";-" in the first column.
  It is strongly recommended that you place headers of this type in your own *.pro routines. There is a standard header format adopted by most IDL coders, though you do not have to follow this in your own routines.
  Unfortunately, intrinsic IDL routines cannot be accessed by man.

• $more [directory/command.pro] : lists any local program. You can define UNIX shell variables named $MOUSSE_DIR, $ASTUSE_LIB, etc, to point to the appropriate directories to avoid having to remember which these are.

• getpro,[command] : writes a copy of any non-proprietary procedure file to the current directory. Does not work on intrinsic IDL software. You can display or edit the procedure to modify its function as desired. If you do not alter the name, and place it in the IDL path ahead of its original location, then your version will be compiled and executed instead of the nominal one. It may be safer to change the name (both the file name and the procedure name within the file) to prevent inadvertent errors.

  Note: one deficiency of current user-supplied procedure documentation is that the dependencies (routines called by a given procedure) are not listed. If you use getpro to obtain and edit a supplied routine to behave differently, this may have unintended consequences for the functioning of other procedures. One method of looking for such interactions would be to grep the library directories for other references to the routine you intend to change. A quick way to identify what subroutines are called by a given program is to .run the program as the first step in an IDL session. Each subroutine is listed on the screen as it is compiled.

• .run -t [command] : an alternative way of obtaining a listing of a routine. This will compile [command.pro] and simultaneously send a listing to the screen with line numbers appended (same numbers as printed in IDL error statements, so is useful for debugging). To save the listing in a file, use the form: .run -l (filename) [command].

• print,[variable]: display the value of any active variable on your terminal. Works for any variable type, but beware in the case of large arrays(!)
  Formatting: row vectors are printed across the screen, column vectors are printed down the screen.
  [Note: The printf command is used to send output to a selected file or other external unit.]

• help : lists all active variables, their characteristics, active programs, information on storage areas, etc.; various options. But does not explain commands. There are many optional keywords for use with help. Examples are given below. To get a full list, type ?help.
  • help,/rou : prints argument list for all active procedures. Lists procedure and functions separately.

  • help,/sy : prints current values of all "system variables", which are special variables known to all routines. Names of these begin with a "!", e.g. !dir, !path, etc.

  • help,/rec : prints contents of command recall buffer in reverse order

  • help,/dev : prints parameter settings for current graphics device

  • help,/mem : lists current memory usage

• print,!d or print,!p : print the system variables which control the device display and the plotting environment, respectively. See the IDL manuals for details.

• print,!path : print the current path list of directories searched for *.pro routines. Since many instances of failed or missing software occur because your path is incorrectly set, it is useful to remember to check !path if you run into trouble. If the !path string is too long to print, use the strmid routine to make and print extractions from it.

• $ printenv : will list all default shell parameters, including the IDL directory defaults, if defined.

• tvstatus : a MOUSSE routine that lists properties of active windows

• journal,[filename]: the journal utility records in a file all entries you make and most IDL responses. Certain responses (e.g. to help requests) are not recorded to prevent cluttering up the file. Some user routines also disable journal output.
  Any text you enter on a given line preceded by a semicolon will be ignored by the compiler and included in the file as a comment---so you can annotate your session on-line to your heart's content.
  Your journal file will be written and closed when you type journal again or exit your IDL session.
  If you edit out the blunders and undesirable clutter of your journal files, you will have a handy running record of your research.
  It is hard to exaggerate the value of keeping IDL journal files for serious work. It is good practice always to use a journal file so that you can check or reproduce what you have done, recover errors, and so forth.
  Journal files permit rapid re-creation of an IDL session. For instance, you can cut and paste between a window with a more listing of a journal file and an active IDL command window to re-create the old session. Alternatively, you can edit the journal file and save the result as a main program, subroutine, or script.
  Compared to the inevitably "blind" programming with languages like FORTRAN or C, the interactive environment of IDL coupled with its journal and command recall/edit facilities is a tremendously more efficient way of writing reliable code.
  Warning: the journal routine will overwrite existing files with the given [filename] without warning. Use unique names for each session. Also, the journal file may be lost in the case of an IDL crash or a system failure (e.g. power outage). For long sessions, you may want to plan for more than one journal file.

4. PROGRAM EXECUTION

[Up to Contents]

NOTE: all IDL procedures/functions are assumed to be in files with the explicit extension '.pro'.

• .run [name] : compiles the IDL procedure(s) or function(s) in the file [name].pro. If this is a main program, also executes it.
  IDL will locate the first file with this name in the IDL path. Beware of using names for your own procedures which are the same as those of intrinsic or supplied library routines (unless you specifically intend to replace those).

  You do not have to give a separate .run command in order to execute a routine which is in your path and has a file name identical with its procedure name except for the '.pro' extension. Simply type the command's name, with all required parameters, and IDL will automatically search the path for such a file and execute it. If the file name does not match the procedure name it contains, then you must .run the file separately.

  Program files can contain more than one IDL program. Simply contatenate programs together. All will be compiled by the .run command and recognized separately in future calls. However, it is not recommended that you combine programs this way. Among other things, you lose the capability of reading internal headers with the man command (see above).
  You must re-run any command whose procedure file you have edited during your session or the revisions will not take effect.
  You do have to use a .run [name] command to execute a main program the first time. To re-execute, you can use .go.
  The .run [name] command will compile but not execute a procedure or function file.

• @[name] : Execute the "batch" file [name].pro containing a list of IDL commands in the same form as they would be entered from the keyboard. Can be used to run a large background job or as a user-specific initialization file at the beginning of a session. Perhaps most useful is to execute a batch file that duplicates a set of commands derived from an earlier IDL session. Such a set is called a "script".
  Each line is executed separately so that multiple line commands involving do-loops etc. cannot be included. (But subroutines which are called from the batch file can, of course, include such features.)
  You can set up common blocks, compile procedures, and so forth in this mode. Text after a semicolon (;) on a given line is ignored by the compiler.

• An efficient way to update or execute parts of a script---e.g. a command sequence captured using the journal utility---is to run an editor on the script in one window while executing IDL in another and cutting-and-pasting snatches of code between them. This method is especially useful when you have a large number of options you may or may not wish to execute (e.g. doing statistics, histograms, and plots on a data file containing many different variables).

• .con : Continue a program interrupted by a pre-programmed stop command.

• .go : Restart a previously compiled main program from beginning.

• Main programs: a main program is simply a file of IDL commands which can be executed interactively by a .run command. They behave just as though you were typing the same commands from the keyboard except that you have full access to multiple line entries, blocks, loops, etc, which can't be used from the terminal. Main programs will recognize any variables or routines already active in your interactive session, and these remain active when the program completes. Main programs cannot be executed by a procedure or function, however.
  Main program files do not have a special header. Simply start with the first executable statement. A main program file must close with an end statement.

• Procedures: IDL "procedures" perform like subroutines in FORTRAN. All inputs and outputs must be specified on the command line which calls the routine (or passed through common blocks or IDL system variables). Procedures can be called from the main level or by any other procedure. Procedure calls look like this (note the absence of parentheses):

  PROCEDURE_NAME,input1,input2...output1,output2...keyword1=value1,$
             keyword2=value2....   

  • Parameters for input/output are separated by commas. If the parameter sequence is too long for a single line, break into several lines using the dollar sign continuation convention (as here). Information can also be passed by common blocks or system variables.

  • Procedures (and functions) cannot recognize variables active in your interactive session unless they are passed as parameters, in common blocks, or as system variables.

  • As in FORTRAN, ordinary parameters must be entered in the specified order. Trailing parameters can be omitted, if there are defaults for them coded into the subroutine.

  • Keywords are parameters that pass information to subroutines, but unlike the standard parameters such as those listed in the preceding example (input1,input2...output1,output2..), they are optional. They do not have to appear in the subroutine call, and if present they can appear in any order. They therefore represent a powerful extension to the rigid subroutine call conventions of FORTRAN and are especially useful in the case of complex interactive data processing subroutines. Values of keywords are usually determined by assignment statements:

    PROCEDURE_NAME,parm1,parm2.....KEYWORD1=100.,KEYWORD2='dumbo',...

    Alternatively, in the case of switches, keywords can be set to a value of 1 by using the following syntax:

    NAME,parm1,parm2...../KEYWORD1,.....

    The keyword_set(name) function is used within a subroutine to sense whether a particular keyword was set by the user in the current call to the subroutine.
    IDL allows keyword "inheritance" such that keywords which may not actually be defined in the procedure declaration can be passed on to other procedures that do recognize them. This adds considerable flexibility to writing interactive software.

  • Procedure files must start with a special header line, as follows:

    PRO Name,parm1,parm2,...

    and must close with a return and an end statement.

• Functions: IDL "functions" perform like functions in FORTRAN. They return output to a single variable which appears on the left hand side of an assignment statement:

  result = FUNCTION_NAME(parm1,parm2...keyword1=keyword1...)

  • The parentheses are required, and parameters within them must be separated by commas.

  • Don't be misled by the format of the function call. Functions can return a large amount of information. The variable on the left hand side can be an array or structure. The parameters can also be used to return output (as in the where function). Information can also be passed by common blocks or system variables.

  • Note the potential confusion which can arise because the format of a function call is similar to an assignment statement involving an array on the right hand side. In IDL V.5, the default format for specifying indices in arrays now uses brackets, rather than parentheses (e.g. array[i,j,k]), although V.5 still permits the use of parentheses. In older versions of IDL, the way to avoid confusion between arrays and functions is to pre-compile (non-intrinsic) functions using .run before you compile any procedures which use them or attempt to use them interactively. You will get an "Undefined Variable" error message if you neglect to do this.

  • Function files must start with a special header line, as follows:

    FUNCTION Name,parm1,parm2,...

    and must close with a return,[output] and an end statement.

• retall : important utility which returns you to the MAIN program if an error occurs in a subroutine. The default in this case is to remain under control of the subroutine (so that you can debug the routine by examining the current values of its variables, for instance).
  The danger if you do not return to MAIN is that you will perform other tasks (e.g. reading in new data) under control of the subroutine but later exit the routine, leading to the disposal of all such data. Type retall to escape the subroutine.
  An alternative is to set on_error,1 at the beginning of a session, which automatically returns to the MAIN level after an error. on_error,0 sets the default mode (stay in the subroutine).
  You can check where you are by typing help, which prints your current location.

• To create variables: simply use them in an assignment statement. Memory for each is automatically set aside and expands indefinitely. E.g.:
  • name = "Maxwell" creates a string
    
  • z = 1.0e-8 creates a scalar
    
  • testdata = fltarr(512,512) creates a 512x512 2-D array with zero entries
    
  • a = [1,2,3] & a = [a,4] creates and then expands a vector

• To delete variables (e.g. when you have too much memory in use), use delvar. Another way to flush arrays is to simply set them equal to a scalar (e.g. a=0). If you use a lot of files, it is also good to prevent file quota errors by occasionally giving a close,/all command.

• If using the cursor, remember to place it on the active window (defined by the wset or chan routine); errors result otherwise. Return the cursor to the command window when finished with cursor function.

• Importing software. There are dozens of sites on the Web that distribute IDL programs. To use these, all you need do is download them, unpack (if necessary) to source-file format (ASCII), and place them in a directory in your IDL path. The path-search protocol described above under the .run command will then locate and execute each program file when you ask for it.
  You can do this before or during an interactive IDL session (though you cannot change your IDL path during a session). You must, of course, be sure you have all the subsidiary programs needed by the new software also in your path.

5. IMAGE RETRIEVAL

[Up to Contents]

• sd,[directory] or cd,[directory] : change directory to the image directory, like cd in UNIX. The directory name must be a string--i.e. it must be quoted, unless it is a pre-defined string variable. Example: sd,'datadir (the trailing quote mark can be omitted). sd, without an argument, is equivalent to $pwd. Note: a $cd command to the shell will not change your default IDL directory.

• dir, fitsdir, stdir: list directory contents in various forms; the latter two routines list FITS files and SDAS files, respectively.

• strd,[image variable name],[header variable name]: routine to read an SDAS image and header file from disk into current variables in memory. A pop-up menu window appears listing headers available in the current directory. Alternatively, enter the file name as a string (extensions not needed) as the third parameter. Image and header files must be in SDAS format (extensions .hhd and .hhh respectively). Use normal UNIX conventions for identifying the files in the directory tree (current directory is default).

  Example: strd,m87,hdm87,'m87_nucleus'
  reads the image data in the SDAS image file m87_nucleus.hhd in the current directory into active variable m87 and the corresponding header file (m87_nucleus.hhh) into active string array variable hdm87. m87 will have the characteristics (byte, integer, float, etc.) of the *.hhd file.

  If the header does not contain parameters which properly match the file (e.g. NAXIS, BITPIX, DATATYPE), then an error message will appear. However, you can create a dummy header which does match the data in this case and store it on the image directory; see "Image Storage" below.

• FITS file information utilities:
  To obtain a brief file description from the header of a FITS file on disk without reading the entire file, use fits_info. This can be important to confirm the type of file (image, table, etc.) you are dealing with.
  To read the full header of a FITS file (without reading the data) into an IDL variable use headfits. You can display the contents of the header with either the print or hprint commands (the latter intended for FITS headers). headfits will work on compressed files (*.Z or *.gz).
  E.g.: hprint,headfits('m87_nucleus.fits.gz')

• fits_read,[filename],[image variable name],... : read a FITS disk file into IDL image and header variables.

  Example: fits_read,'m87_nucleus.fits',m87,hdm87,/noscale

  The noscale keyword used here prevents the (default) automatic scaling that converts the image values to fluxes using calibration parameters in the header. For many purposes, the scaling is a nuisance.
  fits_read can handle extensions and groups in FITS files. There are several alternative sets of routines for reading/writing FITS files, but fits_read is the best current choice for HST data sets for instance. See http://idlastro.gsfc.nasa.gov/ftp/pro/fits/README for more details.
  There is an entire suite of Astronomy User's Library routines to read, write, or manipulate FITS ASCII or binary tables. For instance, to read a FITS file containing a binary table of sources and extract coordinate information:

   
         fits_read,'sources_file.fits',table,hdtable
  
         tbhelp,hdtable     ; List contents of each field 
                            ;   from the header
  
                 ; Extract RA and DEC information, based on
                 ;   tbhelp listing:
  
         rad    =  tbget(hdtable,table,1)
         decd   =  tbget(hdtable,table,2)
            

• irafrd... : like strd, but reads IRAF disk images (extensions .pix and .imh).

• hprint,[header variable]: print header to terminal.

• FITS header keyword extraction/manipulation: There are many commands, mostly starting with the prefix sx, that permit extraction and manipulation of FITS keywords.
  For instance, to extract and print the name of a target from a FITS image header:
  targ = sxpar(hdm87,'TARGNAME') & print,targ.
  To add a history comment to a FITS header variable:
  sxaddhist,'22 AUG 2004: Subtracted mean sky background',hdm87

• Other formats: IDL users have produced IDL routines to read most of the other standard image storage formats. See: read_gif, read_jpeg, read_srf, tiff_read, etc. There are corresponding write routines for all of these.

6. IMAGE DISPLAY

[Up to Contents]

There are two steps in displaying an image on your computer screen.

• First, you must transfer the image to a buffer. For a pseudo-color display (the most widely available), the buffer is only one byte deep (values between 0 and 255); it matches the display window in format. This transfer usually involves scaling between the values in the original image and the buffered array.

• Second, you must define the color lookup tables which convert between the byte values in the buffer and the displayed intensities (and colors) on the screen. In a pseudo-color display, color tables are three vectors, each 256 elements long, containing values between 0 and 255. The three vectors R,G,B determine intensities in the red, green, and blue guns, respectively, on your computer display. If a given pixel in the buffer contains the value n, the three guns at that pixel are set to the values [R(n),G(n),B(n)].

The default color table is a linear grey-scale runnning from 0 to 255.
The command to change ("load") the individual color tables is tvlct,R,G,B, where you must have defined the three vectors beforehand.
To capture the current color tables to vectors (e.g. to inspect them or as a basis for revising them), use tvlct,rr,gg,bb,/get.
A set of 41 predefined color tables is supplied with IDL; these can be loaded with the loadct,N command. The default grey-scale is loaded by the command loadct,0.
Warning: manipulation of multiple-byte color tables (as in TrueColor) can take a long time!

The number of available colors: On your workstation, the number of "shared" color values available for IDL to use will normally be less than 256. Other values will have been reserved by other applications (X-windows, Netscape, CDE, Acrobat, etc). If you have an 8-bit display, the maximum number of colors available for all applications is 256. When IDL is invoked, it will normally be able to obtain only a fraction of these, say 215, for its use from your windows manager. The number will vary depending on the number of competing applications. The standard transfer and display routines like ctvscl and tvlct take this into account by using the smaller number of color levels but adjusting them to the full dynamic range possible on your terminal display. For instance, the color tables may be only 215 elements long, but these will range in value from 0 to 255. The number of colors available is contained in the system variable !d.n_colors or can be displayed with help,/dev---but only after the first IDL window has been opened on your terminal.
"Color Flashing:" if the rest of your terminal display blinks out or changes color when you move the cursor into an IDL window, then IDL is using a "private color table" which gets applied to your whole screen when the cursor activates it. This probably means IDL is attempting to use more colors than were free in the shared color table. To ameliorate the problem, try this:

               Exit IDL
               Restart IDL
               As the very first two commands, type:
	           device,pseudo_color=8
                   window,0,col=k

...where k is the minimum number of color levels you think you will be able to use (probably not more than 100).
For more information on IDL's use of color displays, see http://www.dfanning.com/documents/tips.html#UsingColors.

• chan,n: select window n for display. This becomes the "active" window, i.e. available for I/O. The cursor will only work on the active window. Creates the window if it did not exist before. n can be between 0 and 31. [Although a display window will be automatically opened by any display procedure the first time it is called, you should use the chan procedure first if you want to take advantage of Mousse functionality. It is also a good idea to keep plotting and image display windows separate.]

• cdel,n: Delete window n. You can also quit or close (i.e. iconify) windows during an IDL session by using the regular window manager functions.

• ctv,image: display image in current window (or window 0 if no other window has been opened) without scaling by transferring image pixel values directly to the window buffer. The image buffer will contain byte(image)---i.e. values between 0 and 255 only---and will "wrap" for values of 256 and higher. Only N different values can be displayed, where N is the number of color levels possible (!d.n_colors). [N on a black-and-white display is 255. On a color workstation, N depends on the number of display levels IDL was able to acquire from your windows manager and is usually in the range 210-245.] Among other things, ctv can be useful for locating low contrast data in an image with a large dynamic range.

• ctvscl,image: as for ctv except that the buffer values are scaled linearly between the sky value (set to screen pixel value 0) and a high point determined by the variance of the fluxes in the image. There is no wrapping. The maximum number of color levels displayed on the screen is !d.n_colors. ctvscl is generally much more useful than ctv.
  If you don't like the defaults, you can specify the high and low values by using the optional keywords max and min. E.g.

  ctvscl,m87,min=30,max=8000

  [From this example you can see the advantages of rescaling images to convenient values in the range 0 to a few thousand rather than using actual flux values. To rescale, use commands like m87 = 1.0e15*m87. In fact, if the quality of the display is your only concern, there is no point in retaining actual flux values in your working image set. Just remember not to use the scaled image for computations where the units matter.]

  ctvscl is one of the most used routines in image processing; it has a number of other options you should become familiar with.

• loadct,[n]: load pre-defined color table set n. n=0 to 40. 0 = B&W (and is the default if no color table is explicitly loaded). The other tables are all varieties of pseudo-color transformations.
  The appearance of images will change dramatically depending on the color table and contrast settings. There is a set of about 20 routines to adjust or customize the color tables.
  There are various ways to reverse the standard white-on-black color table 0 to the black-on-white sense preferred by astronomers, which is more sensitive to faint features. One is the following; another is to use contrast.

     
                loadct,0
                tvlct,rr,gg,bb,/get
                rr=reverse(rr)
                tvlct,rr,rr,rr    

• contrast: A MOUSSE routine which interactively adjusts, using the cursor, the color tables without affecting entries in the image buffer. Adjusts a linear transform function in zero point and slope. The appearance on the screen of the result of contrast is identical to specifying the MIN and MAX parameters in ctvscl, although the means by which this is achieved is different. The cursor must be placed in the current active window.
  Note that on workstations, changes in the color tables apply to all image display windows. In order to compare images with different ranges of values, load them using ctvscl or the equivalent with different low/high windowing cuts or with non-linear transforms (see below) before using contrast. Color tables adjusted by contrast remain in effect unless they are explicitly reset (e.g. by using the loadct command). If a new image looks strange, it may be because you have forgotten to reset the color tables.
  You can "flip" the color table using the mouse buttons during contrast.
  Note that the type of linear transformation between the image value and the display value adjusted by contrast is only one of a very large set of possibly useful transformation functions. You may want to experiment with various logarithmic, powerlaw, segmented, and other types of transforms to find the best display for your image.
  The "color-map adjust" feature in ATV is similar to contrast.

• refscl... : A MOUSSE routine which displays a reference scale for the current color tables. Shows the response of the display to a buffer containing a linear range of values between 0 and 255. Setting keyword over places the scale in the current window. Useful when making fine adjustments in color tables and in making images for publication.

• Other useful displays:
  • To display logarithmically stretched images: ctvscl,alog10(image). Obviously, you need to insure that image does not contain zero or negative numbers. A quick way to truncate low values in this kind of command is to use the syntax alog10(image > k). where k is a scalar. The notation (x > y) means "the maximum of the pair x,y."

  • Use a pre-defined lookup table to transform image values, e.g. to their logarithms. Faster than actually converting values using the alog function. E.g.: for integer image arrays with values in the range 0 to 1000, try this:

      
                t=findgen(1000)  & t(0) = 1
                quiklog=alog10(t)
                ctvscl,quiklog(image)   

    Note: In IDL, the form array1(array2) returns the values of array1 in the elements specified by the values in array2. array2 must be an integer or longword integer array.

  • The same technique works with other forms of nonlinear displays: e.g. power laws with fractional exponents (0.3, 0.5) to increase dynamic range; arctangents, etc.

  • To display a smoothed image in one line: ctvscl,smooth(image,5).

• image=tvrd() : Read the (byte) contents of the active window buffer into an image variable. Note the empty parentheses (if you wish to copy the whole window). Often useful in the process of making hardcopies of graphics displays. Warning: make the desired window active first, by using the chan,N command, and be sure the window is fully visible on your terminal screen before calling tvrd.
  tvrd is useful in preserving the appearance of an image after you have used contrast or another color table adjustment routine, annotated the display, and so forth. You may wish to save the resulting image so you do not have to adjust it manually in the future. For black and white images, do the following. First, copy the buffered byte version of the displayed image as follows: pix=tvrd(). Then, save the color tables with tvlct,rr,gg,bb,/get. Then, transform the copied image with new = rr(pix); this reproduces what you saw on the screen. To display the result, simply ctv,new, being sure to reset the color tables to their default values.

• blink,windowlist : blink between windows. Windowlist is a vector containing numbers of windows to blink (in order). E.g. blink,[0,2,1]. To compare different exposures of the same field (e.g. two different filters), you will want to adjust the scaling of the two independently with ctvscl before calling blink. To terminate, you must type in the command window, which may require you to use the window manager to bring it up. Blink rate is adjustable.

• tvbox...; tvcircle...; tvellipse...; etc : draw various shapes in active window, e.g. to locate point sources identified by other routines. To remove these, you must re-load the image in the window. Adjust the color or darkness of the overlays by using the color keyword.

• xyouts... : write text to active window. A variety of fonts are available. To remove previously-written text, you must re-load the window.

• curs,type : select graphics cursor type

• To read the cursor position on an active window: use the cursor routine.

• set_plot,[device-name] : allows you to change the current output device. On a Sun workstation, you will normally be using X-windows graphical output, for which the command is set_plot,'x. (This will be set by default when you begin your IDL session.) If you are using VT100 or Tektronix-type terminal emulation, you should type set_plot,'tek before using graphics commands. The only other output device type you would commonly deal with is a PostScript file. You can switch output to a PostScript file by typing set_plot,'ps . Return to X-windows by typing set_plot,'x . (The chan command automatically returns you to the X-windows default.) You can determine the currently assumed device parameters by typing help,/dev.

• ATV is an IDL widgit-based display program written by Aaron Barth which combines much of the functionality just described with many of the image inspection capabilities described in the next section. Its appearance and behavior is like SAOimage (example here).

• ATV is a quick and easy way of inspecting images (brightnesses, x or y profiles, morphology, etc.) and doing rough analysis like getting FWHM's and aperture photometry of sources. Oriented toward CCD data. ATV was written by Aaron Barth.

• At UVa, ATV software is kept in /astro8/idl/atv and is included by default in your IDL path.

• To display an existing image array in ATV, simply type atv,image

• To display a FITS file image in ATV, type atv,[filename.fits]

• ATV Links (UCI)
  General info
  Instructions on how to use ATV

7. IMAGE INSPECTION & MANIPULATION

[Up to Contents]

• print,max(a); print,min(a); print,minmax(a); print,mean(a); print,variance(a); print,median(a); print,moment(a): print various statistical properties of image array. (moment prints first four moments.)

• curval,image : read off image values in each pixel interactively with cursor in current window. Option to convert to fluxes, RA, DEC using the image header.

• tvlist,image : prints matrix of image values in vicinity of cursor location in current window. Options to write to file. imlist is similar, but coordinates are typed in (does not use the window/cursor).

• zoom : displays an enlarged segment of image in current window centered on cursor. Middle mouse button changes zoom factor. Right button exits. Works by copying currently displayed window buffer, not original image values. Zoomed window vanishes on exit. Keyword /continuous can be used to follow the motion of the cursor, but you may want to restrict the region displayed, depending on the speed of your computer.

• To extract and examine a subarray, you can use standard IDL array notation. E.g.

  
       part=image(100:200,150:250)

  extracts a 101x101 subarray from the image.

• To enlarge (or compress) an array: new=rebin(image,N,N). N must be an integer multiple of the current dimensions of image, (assumed square here). Compression is often needed with images which are too large to fit on your CRT display (typically limited to about 1000x900). Packages like ATV and SAOIMAGE do this compression automatically (but possibly in a non-optimal fashion).
  For magnification, add the keyword /sample if you want to preserve the original pixel structure. This substitutes nearest neighbor sampling for the bilinear interpolation which is the default.
  To regrid an image to non-integer multiples of its original format, use frebin or congrid If you intend to make flux measures from the compressed or expanded images, be sure to scale the result so that flux is conserved in a given region of the original image. For example, if you use rebin to compress an MxM image to an NxN image using sample=0, each pixel in the resulting image will contain the average of the corresponding pixels in the original, so that the total flux is a factor of k² smaller than in the original, where k=M/N.

• To plot a column: plot,image(N,*).

• To plot a row: plot,image(*,N).

• To interactively select & plot rows or columns with the cursor: try profiles.

• To plot the mean of 5 adjacent columns: plot,avg(image(c0:c4,*),0). For 5 adjacent rows: plot,avg(image(*,r0:r4),1).

• To extract an image slice with arbitrary start and end points (selected by the cursor from the active window and marked with "rubber band"): slice=profile(image). You can then plot the extraction.

• To estimate the background level, use sky.
  sky works by estimating the mode of the image values. It therefore assumes there are many more pixels near the sky background level than there are source pixels. It will not work well in the case of very low sky backgrounds where the sky histogram is not smoothly continuous.

• surface,image: produces surface plot (projected 3-D) of image. Slow for larger images, so test on extractions. See the IDL manuals for many enhancements available in surface plotting.

• plothist,image: evaluate histogram of pixel values in the image and plot the result. The default histogram runs from the minimum to the maximum of the array. But it is assumed that the array contains integer values, and the default bin size is 1.0 unit. Beware when the array contains erroneous values which are very large or very small. Optional parameters adjust cutoffs and binning.

• contour,image: plot a contour diagram. To specify the contour levels, use the levels keyword. E.g. to plot 10 contour levels at values of 25, 50, 100, 200...:

  
                     nup = findgen(10)
                     clev = 25.*2^nup
                     contour,image,levels=clev 

• Flagging values in given range: use the where function. E.g.: to highlight pixels containing a -666 flag:

  
  
         tx=image          ; create temporary copy (unless you don't 
                           ;   mind corrupting the original array)
         finder=where(tx eq -666) ; create a list of relevant pixels
         tx(finder)=10000  ; highlight them (we assume normal tx values
                           ;   are << 10000)
         ctvscl,tx,min=0,max=9000  ; flagged pixels will now stand out
     

• To convert coordinates between decimal and sexigesimal form, use sixty [decimal to sexigesimal], ten [sexigesimal to decimal], or radec [RA and DEC from degrees to sexigesimal]. For instance:
  radegrees=15.0*ten(22,30,17.5)

• ATV includes the abilities to zoom an image and to roam around parts of an image too large for direct display. It produces row, column, surface, or contour plots using keyboard commands. In the ImExam mode, it also offers evaluation of source structures & crude photometry. Does aperture photometry, shows source profile, integrated flux, background. Intended for point sources.

• You can operate on image arrays using any IDL routine which accepts 2-D inputs, including the full range of standard arithmetic and other mathematical functions. Most such routines are array-oriented and do not require you to worry about do-loops or element structure in arrays.

• Most IDL mathematical functions behave sensibly and give you the results you intuitively expect. E.g. if a and b are arrays with the same dimensions, then c = a*b produces an array with the same dimensions in which each element is the product of the corresponding elements in a and b. (There are separate functions--#,##---for other types of matrix multiplication.)

• Many kinds of image manipulation can be executed with one-line commands in IDL. E.g.:
  Edge detection: ctvscl, a-shift(a,1,1)
  Unsharp masking: ctvscl, a-smooth(a,k) displays the difference between the original image and a boxcar-smoothed version with a smoothing length of k pixels. This is fast, but the smoothed image includes the effects of any sharp structures (like stars). Better, though slower to execute, is ctvscl, a-median(a,k).

• Changes are, of course, made to the temporary data sets stored in RAM. The original files from which the data was transferred into your IDL session are not affected (unless you call special file manipulation routines). However, this also means that permanent versions of the modified images are not kept at the end of your IDL session unless you deliberately save the dataset or write new output files (see next section).

• If you want to maintain the applicability of the image header to the manipulated image, then you must update the header after each change. You can add comments to the existing header by using the sxaddhist routine. Changes which don't affect the keywords included in the header (e.g. sky subtraction, excision of foreground stars) can be simply documented this way. However, changes in the flux scale or, especially, the image format (through extraction, rotation, rebinning, etc) usually require that the keywords be changed in order that later routines will function properly. A special set of AstUseLib routines, including hextract, hrot, hastrom, hrebin, etc. will do standard manipulations on images and image headers simultaneously. Astrometric information, for instance, will be preserved.

8. IMAGE STORAGE

[Up to Contents]

• stwrt,[image variable],[header variable],[filename]: Write images to disk in SDAS format. The resulting files will have the [filename].hhh and [filename].hhd extensions.
  If the images have been manipulated and you did not employ the AstUseLib header-tracking commands such as hextract, hrot, hastrom, hrebin, and so forth, then you must create a new header (use mkhdr) or update the existing one to properly match the stored image. stwrt will optionally produce a simple header, or you can use the sx* commands, such as sxaddhist or sxaddpar to do this. (Although headers in SDAS are ASCII files, they cannot be edited with standard text editors because of blocking conventions.) It is particularly important to be sure that the parameters BITPIX, NAXIS*, and DATATYPE are properly entered. stwrt writes to the current directory.

• FITS files: To write a FITS file from IDL variables, use fits_write. See comments on header tracking under stwrt above. File transfer between SDAS format and FITS format can be troublesome since not all modes have been carefully tested. This is true in both IDL and IRAF/STSDAS. Always check results to be sure.

• IRAF files: To write IRAF-style output files (*.imh, *.pix) from IDL variables, use irafwrt. Alternatively, and preferably, use fits_write and then use IRAF FITS-reading routines.

• Other formats: other popular, but not specifically astronomical, file formats are supported by IDL. See write_gif, write_jpeg, write_srf, tiff_write, etc. GIF format is a good way to store processed images with special color tables embedded, although there is no way to save header information in a GIF. GIF and JPEG are the most widely used default formats for Internet browsers.

• save... : The intrinsic IDL save command will save variables and programs from the current session in a specially formatted binary file. All this material can be restored in a later IDL session with a single command. Delete all redundant or otherwise uninteresting variables (especially large arrays) before calling save. Review the save keywords before use. On a UNIX system, the output file will be in a universal XDR format which can be ported to non-UNIX computers. Use the restore command to read a save file.
  save can be very useful for storage of intermediate results, but is not recommended for permanent records. Why? For one thing, it's too easy to forget what all the variables mean; if you are forced to write SDAS, FITS, or ASCII files, you are more likely to document the work. For another, save encourages soaking up mass storage with redundant copies of arrays which may be only slightly changed from their original values. It is more efficient to save and then rerun a script which makes relatively simple changes in images rather than to store the intermediate versions. Finally, the restoration of save files depends on the availability of IDL---not guaranteed if you move somewhere else. Standard IDL FITS or ASCII file-writing routines are preferable for permanent data.
  The default name of the output file is idl.dat, and this file name will be overwritten on the next save. Best to change to something informative like ngc1068.sav.

• Image transfer between computers: The most foolproof way to transport astronomical images between environments is to use FITS files. However, always verify the transportability of the FITS files you write before you invest effort in a major data conversion.
  FTP readily transfers SDAS images from one SUN machine to another. Transfer the header (*.hhh) and data (*.hhd) files using BINARY protocol. You may also readily transfer data this way between VAX/VMS machines and SUNs as long as the data is in INTEGER or LONG format. The problem is that VAX and SUN have reversed byte storage conventions. You can read such images using STRD, but before using them, you must use the byteswap function. [The symptom of a non-byteswapped image is that it will contain very large values, such as 1.0e+38.] You cannot successfully transfer floating point arrays between SUN and VAX. Beware of similar incompatibilities between SUNs and other computers.

9. IMAGE PHOTOMETRY

[Up to Contents]

• Native IDL lends itself to rectangular aperture photometry through simple commands such as mean=total(array)/n_elements(array), where array is a piece of a larger image (defined, for example, using the simple index notation: array=bigarray(x1:x2,y1:y2)). Refined versions of this simplest approach may be found in avg.

• Point Source Photometry: The AstUseLib contains an IDL version of the DAOPHOT 1987 FORTRAN release, described at http://idlastro.gsfc.nasa.gov/contents.html#C2. This performs aperture photometry and PSF-fitting photometry on point sources. It is functionally very similar to DAOPHOT-87 but offers the added versatility of the IDL interactive environment. The basic routines find and aper are especially useful. The IDL source code is available. None of these routines include the improved features of the DAOPHOT 1991 or later releases. To do PSF-fitting deconvolution of blended images where you want maximum software firepower, you should use the more recent stand-alone DAOPHOT or DOPHOT releases. However, IDL remains very useful in preliminary assessment of data frames prior to setting loose the mechanical scroungers and in analyzing the results. (The output files of standard photometry programs can easily be read back into IDL.) It is also an excellent way to create synthetic data sets with known properties on which to verify photometry package operation.

• Surface Photometry: A number of basic routines such as dist_circle and dist_ellipse are available to support surface photometry, but there are no "official" AstUseLib surface photometry programs. Several individual users, including RWO, have their own routines which others may use on an "at your own risk" basis.

• The ATV image viewer contains a circular aperture photometry utility which is very useful for exploring fluxes, FWHM's, and backgrounds of point sources. It does not, however, operate from a pre-defined list of coordinates or produce output files.

• A number of other user-written photometry packages, mostly for point sources, are available through the AstUseLib site (at http://idlastro.gsfc.nasa.gov/idlfaq.html#B4.)

10. ASCII FILES

[Up to Contents]

The best way to save small data sets (e.g. photometry output) is in the form of ASCII files, since these are easily edited and transported. Intrinsic IDL supports reading and writing ASCII files; see the IDL manuals. A sample script to write a file containing target names, coordinates, and brightnesses might look like the following:

       get_lun,unit
       openw,unit,'OutputFile'
       form='(a15,3x,f9.5,3x,f9.5,3x,f6.2)'
       for i=0,numtarg-1 do printf,unit,format=form,$
               targid(i),radeg(i),decdeg(i),vmag(i)
       close,unit

 

Note: you can check the output formatting by doing a test print to your terminal, using statements like:

       form='(a15,3x,f9.5,3x,f9.5,3x,f6.2)'
       for i=0,numtarg-1 do print,format=form,$
               targid(i),radeg(i),decdeg(i),vmag(i)

    

11. DATABASE ACCESS

[Up to Contents]

   dbopen,'[data base name]
             dbhelp,1
             dbprint,[10,100,1000],'*

12. PLOTS

[Up to Contents]

The basic IDL commands for making plots are plot, for creating a new plot, and oplot, for overplotting on an existing plot. Plots can be made to a terminal graphics window or to a variety of external devices.

This, however, is only the tip of an immense iceberg. IDL contains many options for making plots---so many, in fact, that the hardest part of the job can be keeping track of the multiplicity of optional parameters. Options in the form of keywords can be specified in the calls to the plotting functions or they can be invoked in the form of system variables, such as !p.title, which will apply to all later plot calls until changed.

• Standard plotting and graphics keywords are explained on-line by typing ? and then selecting "Graphics Keywords."

• The most frequently used plotting keywords and system variables follow. All are optional. Examples of use are given below.
  psym or !p.psym: determines symbol type. A value of 0 (the default) produces a solid line with no discrete point symbols; values 1 through 10 select other types of (unconnected) symbols. 8 indicates that the user has defined a special symbol using the usersym procedure.
  xrange and yrange: 2-element vectors giving the minimum and maximum for each axis. If not defined, autoscaling will occur.
  linestyle: selects style of line drawn (solid, dotted, dash-dot, etc) if psym=0.
  xstyle and ystyle: set axis options (e.g. exact range rather than rounded up)
  !p.title,!x.title, and !y.title: strings for the plot title (centered over upper x-axis), x-axis title, y-axis title.

The IDL defaults are not as "nice" as those in SUPERMONGO, for example. However, you can quickly customize to obtain as sophisticated a plotting style as you like. All the functionality of SUPERMONGO and other astronomical graphics packages is inherent in IDL. Many of the 2-D and 3-D graphics routines are illustrated in the IDL Demos which come with the system.

Color tables for plots:

The plot commands accept the keywords background, which sets the background color of a plot, and color, which determines the color used for lines and symbols. By default on a pseudo-color X-windows display, background is set to index 0 and color is set to index 255. These therefore display the "bottom" and "top" of your current color table, respectively. [Color tables are explained under Image Display.] The actual appearance of your plot will then depend on what color table you have loaded (e.g. with loadct,N). The default table (N=0) produces a black background and white symbols. Your display will change if you use a different color table or plot/background indices. You can create a special set of color tables to produce a defined set of, say, 10 standard colors for your plots.

Sample plotting scripts for displaying plots on your terminal follow. These involve a mixture of intrinsic IDL and AstUseLib routines:

1. Plot galaxy surface brightness data (in magnitudes) with error bars versus radius to the one-quarter power. Use discrete symbols (not a connected line). On this plot, a galaxy with a standard "de Vaucouleurs" brightness profile will produce a straight line.
   Assume that the vectors flux, rads, and fluxerr already exist, with fluxes in units of ergs/s/cm^2/Angstrom. Assume that you must truncate the plot to eliminate the first 3 entries and those after the 20th.

    
   
   mags=-2.5*alog10(flux(3:19)) -21.1 ; Convert fluxes to magnitudes,
                                      ;    ignoring bad data
                                      ; Assumes all flux entries ge 0 
                                    
   
   r25=rads(3:19)^0.25                ; Compute fourth root of radius vector
   
   magerr=1.086*fluxerr(3:19)/flux(3:19)   ; Convert uncertainties 
                                           ;   in flux to magnitudes
   
   !y.range=[25,18]               ; Set a non-default y-axis range.
                                  ; Note: this magnitude scale has smaller values
                                  ;    higher on the y-axis
   
                                  ; Make the titles
   
   !p.title='Sample Surface Brightness Profile"
   !x.title='Radius(arcsec)^0.25'
   !y.title='Surface Bright (mags/arcsec^2)'
   
   plotsym,4,1.5,/fill            ; Choose filled triangles for plotting symbol,
                                  ;   50% larger than the default
   
   
   ploterror,r25,mags,magerr,psym=8
                                 ; Make plot on terminal screen with error bars; 
                                 ; The keyword psym selects the plotting symbol;
                                 ; Psym=8 specifies a user-created symbol, which
                                 ;    in this case was defined by plotsym
                                 ; Plot will appear in active window, or in 
                                 ;    Window 0 if none have been opened yet.
   
    

2. Make a contour plot of a smoothed image.

    
   
   chan,3                              ; open plotting window
   
   !x.title='X'                        ; make titles
   !y.title='Y'
   !p.title=' Contours for Image'
   
   square                              ; set aspect ratio to make square plot
                                       ; (Note that you must also give this command
                                       ; after the PostScript device is called
                                       ; when making hardcopies.)
   
   smooth_one=smooth(image,5)          ; smooth the image by a 5 pixel boxcar
   
   clev=[10,20,40,80,160]              ; define trial contour levels--assume
                                       ;     these values span range of interest
   
   contour,smooth_one,levels=clev       ; do fast test of contour plot.  Check &
                                        ;   iterate clev for best appearance
    
   contour,smooth_one,levels=clev,/follow  ; do more accurate (slow) plot,
                                           ;  with labels
   
    

3. Read, sort, and plot data from an ASCII file; make & display trial polynomial fits

   Assume x is a vector containing values in the range 0 to 5 and that y is the corresponding dependent variable. Assume that these are to be read from an ASCII file named xy.dat, which contains x and y in separate columns. xy.dat can contain an initial explanatory section and other separator headers, as long as none of these contain only one or two floating point numbers (since readcol will mistake those for data lines). The readcol routine will read in the numerical x,y data ignoring (in this example) any line containing alphabetic characters. No labels are put on the plot in this example.

    
   readcol,'xy.dat',xx,yy         ; Read data from the file.  Note that format 
                                  ;    statements are not required
   
   index=sort(xx)                 ; Sort the arrays in order of increasing x 
   x=xx(index)
   y=yy(index)
   
   chan,1                         ; Open Window 1 for plotting
   
   plot,x,y,psym=5                ; Plot the data with open triangles
   
   quadcoeff=poly_fit(x,y,2)      ; Derive coefficients for best quadratic
                                  ;    polynomial fit
   print,quadcoeff                ; Print these out (optional) [Note: 
                                  ;    quadcoeff is a vector]
   
   tx=findgen(101)/20.            ; Create independent variable vector for fitted
                                  ;    values (uniform interval of 0.05 x units)
   
   quadtesty=poly(tx,quadcoeff)   ; Create the fitted quadratic values
   
   oplot,tx,quadtesty,psym=1      ; Overplot the quadratic fit with plus signs
   
   cubcoeff=poly_fit(x,y,3)       ; Derive coefficients for cubic fit
   cubtesty=poly(tx,cubcoeff)     ; Create the fitted cubic values
   
   oplot,tx,cubtesty,psym=3       ; Overplot the cubic values with small dots
   
   delta=y-poly(x,quadcoeff)      ; Compute the difference between y data and
                                  ;    the best quadratic fit 
   
   nix=where(abs(delta) gt 2.)     ; Locate those y values which are more
                                   ;    than 2 units from the best fit
   
   weight=fltarr(n_elements(x))+1. ; Create a weight vector corresponding to
                                   ;     x with unit entries
   
   weight(nix)=0.0                 ; Give deviant points zero weight
   
   newquadcoeff=polyfitw(x,y,weight,2) ; Derive improved quadratic coeff.
   
   final=poly(tx,newquadcoeff)         ; Create improved fit values
   
   chan,2                         ; Open Window 2 for final, clean plot.
                                  ; (Window 1 is retained for comparison.)
   
   plot,x,y,psym=5,xrange=[1,3.5] ; Plot the data with open triangles in
                                  ;    Window 2.  
                                  ; Assume interest is limited to only 
   		 	       ;    part of data x-range.
   
   oplot,tx,final,psym=0          ; Overplot final fit with solid line
    

13. GRAPHICS HARDCOPIES

[Up to Contents]

The most common method of obtaining hardcopies or permanent storage of graphics output (plots or images) is to use PostScript files, since these can be printed on most laser printers. PostScript files can be later edited and reformatted, though special (non-IDL) programs are needed. IDL also supports output of GIF, JPEG, TIFF, SRF, and other file formats. GIF and JPEG are standard for Internet Web browsers. GIF or TIFF are recommended for transporting files to local vendors to make photographic prints or slides.

You should always experiment on the terminal screen with your plot format before dumping to an output file. It is easy to do this by working out the set of commands you want by plotting to the screen, then typing set_plot,'ps (in the case of PostScript output) and repeating the commands using the command recall buffer.

 
        set_plot,'x  :  Send output to X Windows (default) 
        set_plot,'ps :  Send output to the PostScript file "idl.ps"

The subsequent commands for sending data to the PS file are (mostly) the same as for putting data on your monitor screen, since monitors and PS files are interchangeable output devices for IDL.

You can always check the properties of the current graphics output device by typing help,/dev. You can change these defaults by using the device command. The hardware/software interfaces are sometimes non-trivial, and you will want to plan for a significant learning curve in doing things which are not "vanilla." Before sending large jobs to printers, vendors, etc., be sure to check the files using UNIX ghostview, xv, or other screen display programs.

Here are some graphics output methods for common situations:

• To make a PostScript hardcopy of a plot.
  1. Type set_plot,'ps to send output to "idl.ps"

  2. Optionally, make adjustments to the plot size, aspect ratio, orientation, lettering fonts, etc. using the device command

  3. Give the set of plotting commands here---just as for a screen plot; all system variables will still be in force

  4. Type device,/close to close the file idl.ps. (Note: the PostScript file is not actually written to disk until the close command is given.)

  5. Type $lp idl.ps to print the file on the default printer.

  6. The next plotting command will overwrite idl.ps. If you want to save it, you must change its name. E.g. $mv idl.ps bossplot.ps.

  7. Example (based on continuing Sample Script #1 under Plots above.)

     
     set_plot,'ps                  ; Plot will be sent to PostScript file "idl.ps", 
                                   ;     not to the screen
     
     ploterror,r25,mags,magerr,psym=8
                                   ; Make plot (in PostScript file) with error bars; 
                                   ; The keyword psym selects the plotting symbol;
                                   ; Psym=8 specifies a user-created symbol, which
                                   ;    in this case was defined by plotsym
                                   ; System variables for labels are still in force
                                  
     
     device,/close                 ; Close file 
     
     $lp idl.ps                    ; Send file to printer
     
     $mv idl.ps surbriteplot.ps    ; Rename PS file to save it.
     
     set_plot,'x                   ; Send further output to the terminal
     
     cleanplot                     ; Reset the plotting system variables to defaults
     

  8. The output file will have the expected "black-on-white" sense, unless you make use of the keywords described next.

  9. You can make color PostScript files by setting device,/color and using the background and color keywords (see the Plots section). However, the treatment of color tables differs from the X-windows case. Consult the IDL manuals.

• Making a PostScript hardcopy of a displayed image: use tvlaser. This dumps a bitmap of the current window (as selected by the chan routine) to a PostScript file and prints it on the default PS printer. Various options to add comments, information from the header, change the format, and so forth. If you want to save the PostScript file, answer no to the query about "removing" it.

• Color image output: tvlaser supports PS image output in both greyscale and color. For color output, use the colorps keyword.
  As an example of how to handle IDL image output in color, here are the steps that tvlaser uses to make color PS files:

   
    First create the image as you want it to appear, complete with
    your chosen color table (load with loadct or
    tvlct).  Put it in the current window.
  
    pic = tvrd()   ; copy the (byte) window buffer to a variable
       
    tvlct,r,g,b,/get   ; save the current color tables to vectors
  
    set_plot,'ps   ; put further output in the "idl.ps" file
       
    device,/color,bits_per_pixel=8    ; set pseudo-color output
  
    tvlct,r,g,b    ; write the color tables to idl.ps
  
    tv,pic         ; write the image to idl.ps 
  
    device,/close  ; close the file
  
    $mv idl.ps  colimage.ps     ; rename the file to save it
  
       [Option: check the *.ps file with UNIX ghostview or equivalent.]
  
    $lp -d chroma colimage.ps  ; send the file to a color printer
  
    set_plot,'x          ; return graphics output to your screen 

• GIF file output. For image output in GIF, JPEG, TIFF, and other formats, you do not need to use the set_plot command. Simply send the appropriate picture elements to an output file, as in the following:

    pic = tvrd()   ; copy the (byte) window buffer to a variable
  
    tvlct,r,g,b,/get   ; save the current color tables to vectors
  
    write_gif,'picname.gif',pic,r,g,b  ; write to a GIF file
  

  Tip: when producing PostScript output files of images for publication, it's useful to also make a GIF version, since this can be read back into IDL later if touch-ups are needed. IDL cannot read PS files (though UNIX xv can convert PS's to GIF's).

• Large Images: image output need not be confined to those sizes you can display on your screen, as in the above examples. Larger image arrays can be written directly to files using the write_gif, fits_write, and similar commands. Convert the image to byte format before outputting using the bytscl command, as in:

  
       pic = bytscl(bigim,min=0,max=1835,top=255)
  
  

• Note: some slide-making software assumes that images will be in LANDSCAPE mode---i.e. long axis horizontal. If you are exporting images intended for slides, it is easiest to adopt landscape mode here. If your image is significantly higher than wide, rotate it 90 degrees using one of the IDL utilities before saving it. E.g. picname = rotate(picname,3).

PostScript files are the best way to get high quality line-drawing plots and are generally well treated by publishers. Greyscale or color images are another matter, however, and should be approached in an iterative way. A published PS image may look very different from the one you printed locally. GIF or TIFF files may yield better results than PS.

There can also be difficulties with the finite resolution of screen displays copied using the tvrd routine. This is true for the quality of both the image and any lettering which may have been added to it. On a typical computer screen, you will not get more than about 900x900 resolution. However, a PostScript file at 300 dpi can yield much higher resolution (1800x1800 in a 6" image).

As an alternative to the screen-capture tvlaser method described above, you can write images and labeling directly to a PostScript file using the standard tv, tvscl, xyouts and other routines. The main difficulty is understanding the coordinate system used within the PS file and placing the various elements of an output page in the right positions. People wind up using trial and error (easy by writing the PS file, then giving a $ghostview [filename] command from within IDL).
For more information on the use of PS files with IDL, see http://www.dfanning.com/documents/tips.html#PostScript

If you store copies of your graphics output in GIF or JPG (or several other popular format) files, you can use the UNIX utility xv to manipulate them further: in size, rotation, contrast, color table, and by applying various image enhancements. xv can convert between GIF and PostScript---and also, in more recent releases, vice versa. Especially useful for compressing image sizes for use on the Internet, the arXiv Preprint Server, and so forth. You can also, of course, use PC software such as Photoshop.

14. IDL HINTS AND ANNOYANCES

[Up to Contents]

Not many people have experienced fully interactive computing before they start to use IDL. There are tremendous advantages but also many pitfalls for the unwary. The pitfalls will, of course, mostly seem obvious and trivial in retrospect---i.e. after you have learned to avoid them. A number of tips & warnings for IDL beginners are discussed in this section.

• If a procedure name is unrecognized or gives unexpected error messages, check to be sure your directory path (!path inside IDL) is set properly. The initial value of !path is taken from the shell variable $IDL_PATH. Check the directories in the path for the procedure.

• The notation :+/directoryname in the $IDL_PATH definition expands the path to include all subdirectories of the named directory which contain *.pro files. Use sparingly t