[Previous Routine] [Next Routine] [List of Routines]NAME: SKY PURPOSE: Determine the sky level in an image using the the procedure MMM EXPLANATION: Approximately 4000 uniformly spaced pixels are selected for the computation. Adapted from the DAOPHOT routine of the same name. CALLING SEQUENCE: SKY, image, [ skymode, skysig, CIRCLE = ,/SILENT ] INPUTS: IMAGE - One or two dimensional array OPTIONAL OUTPUT ARRAYS: SKYMODE - Scalar, giving the mode of the sky pixel values of the array IMAGE, as determined by the procedure MMM. SKYSIG - Scalar, giving standard deviation of sky brightness INPUT KEYWORD PARAMETERS: CIRCLERAD - Use the keyword to have SKY only select pixels within the specified pixel radius of the center of the image. If CIRCLERAD = 1, then the radius is set equal to half the image width. Useful when the data is restricted to a circular area of the image. SILENT - If this keyword is supplied and non-zero, then SKY will not display the sky value and sigma at the terminal PROCEDURE: A regular grid of points, not exceeding 4000 in number, is extracted from the image array. The mode of these pixel values is determined by the procedure MMM. PROCEDURE CALLS: MMM REVISION HISTORY: Written, W. Landsman STX Co. September, 1987 Changed INDGEN to LINDGEN January, 1994 Fixed display of # of points used March, 1994 Converted to IDL V5.0 W. Landsman September 1997(See sky.pro)
SKYADJ_CUBE
[Previous Routine] [Next Routine] [List of Routines]NAME: SKYADJ_CUBE PURPOSE: Sky adjust the planes of a datacube. EXPLANATION: When removing cosmic rays from a set of images, it is desirable that all images have the same sky level. This procedure (called by CR_REJECT) removes the sky from each image in a data cube. CALLING SEQUENCE: SKYADJ_CUBE,Datacube, Skyvals,Totsky, [/XMEDSKY, /VERBOSE, /NOEDIT, REGION = ] MODIFIED ARGUMENT: Datacube: 3-D array with one image of same field in each plane. Returned with sky in each plane adjusted to zero. OUTPUT ARGUMENTS: Skyvals: Array of sky values used on each plane of datacube. For a scalar sky, this parameter is a vector containing the sky value for each image plane. For a vector sky, this parameter is a 2-D array where each line corresponds to one image plane. INPUT KEYWORD PARAMETERS: REGION - [X0,X1,Y0,Y1] to restrict area used for computation of sky. Default is 0.1*Xdim, 0.9*Xdim, 0.1*Ydim, 0.9*Ydim VERBOSE - Flag. If set, print information on skyvals. NOEDIT - Flag. If set, return sky values without changing datacube. XMEDSKY - Flag. If set, return vector sky as a function of X. PROCEDURE: Uses astronomy library "sky" routine for scalar sky and column-by-column median for vector sky. PROCEDURE CALLS: SKY, XMEDSKY ;in IDL Astronomy Library MODIFICATION HISTORY: 20 Oct. 1997 - Original Version, Robert Hill, Raytheon STX 9 Apr 1998 - Added calling sequence, Wayne Landsman, Raytheon STX Jun 1998 - Converted to IDL V5.0, Wayne Landsman, Raytheon STX(See skyadj_cube.pro)
SPEC_DIR
[Previous Routine] [Next Routine] [List of Routines]NAME: SPEC_DIR PURPOSE: Complete a file specification by appending the default disk or directory CALLING SEQUENCE: File_spec = SPEC_DIR( filename, [ extension ] ) INPUT: filename - character string giving partial specification of a file name. Examples for different operating systems include the following: VMS: '$1$DUA5:TEST.DAT','[.SUB]TEST' Unix: 'pro/test.dat', '$IDL_HOME/test','~/subpro' MacOS: ':Programs:test' Windows: '\pro\test.dat','d:\pro\test' OPTIONAL INPUT: exten - string giving a default file name extension to be used if filename does not contain one. Do not include the period. OUTPUT: File_spec - Complete file specification using default disk or directory when necessary. EXAMPLE: IDL> a = spec_dir('test','dat') is equivalent to the commands IDL> cd, current=cdir IDL> a = cdir + delim + 'test.dat' where delim is the OS-dependent separator METHOD: SPEC_DIR() decomposes the file name using FDECOMP, and appends the default directory (obtained from the CD command) if necessary. Under VMS, SPEC_DIR() will also try to translate disk and directory logical names. SPEC_DIR() does not check whether the constructed file name actually exists. PROCEDURES CALLED: EXPAND_TILDE(), FDECOMP REVISION HISTORY: Written W. Landsman STX July, 1987 Added Unix compatibility, W. Landsman, STX August 1991 Added Windows and Macintosh compatibility W. Landsman September, 1995 Work for relative Unix directory W. Landsman May, 1997 Expand Unix tilde if necessary W. Landsman September 1997 Converted to IDL V5.0 W. Landsman September 1997(See spec_dir.pro)
SPHDIST
[Previous Routine] [Next Routine] [List of Routines]NAME: SPHDIST PURPOSE: Angular distance between points on a sphere. CATEGORY: CALLING SEQUENCE: d = sphdist(long1, lat1, long2, lat2) INPUTS: long1 = longitude of point 1. in lat1 = latitude of point 1. in long2 = longitude of point 2. in lat2 = latitude of point 2. in KEYWORD PARAMETERS: Keywords: /DEGREES means angles are in degrees, else radians. OUTPUTS: d = angular distance between points. out COMMON BLOCKS: NOTES: Notes: points 1 and 2 may be arrays. MODIFICATION HISTORY: R. Sterner, 5 Feb, 1991 R. Sterner, 26 Feb, 1991 --- Renamed from sphere_dist.pro Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. Converted to IDL V5.0 W. Landsman September 1997(See sphdist.pro)
SPLINE_SMOOTH
[Previous Routine] [Next Routine] [List of Routines]NAME: SPLINE_SMOOTH PURPOSE: Compute a cubic smoothing spline to (weighted) data EXPLANATION: Construct cubic smoothing spline (or give regression solution) to given data with minimum "roughness" (measured by the energy in the second derivatives) while restricting the weighted mean square distance of the approximation from the data. The results may be written to the screen or a file or both and are optionally returned in the parameters. The results may be optionally displayed graphically. CALLING SEQUENCE: SPLINE_SMOOTH,X,Y,Yerr,distance, [coefficients,smoothness,xplot,yplot [ XTITLE= ,YTITLE=, INTERP=, TEXTOUT=,/SILENT,/PLOT,/ERRBAR] INPUT PARAMETERS: X - N_POINT element vector containing the data abcissae Y - N_POINT element vector containing the data ordinates Yerr - estimated uncertainty in ordinates ( positive scalar) distance - upper bound on the weighted mean square distance of the approximation from the data (non-negative scalar) OPTIONAL INPUT PARAMETERS xplot - vector of spline evaluation abcissae OPTIONAL INPUT KEYWORD PARAMETERS: TEXTOUT - Controls print output device, defaults to !TEXTOUT textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout = filename (default extension of .prt) OPTIONAL OUTPUT PARAMETERS: coefficients - N_POINT x 4 element array containing the sequence of spline coefficients including the smoothed ordinates. smoothness - N_POINT element vector containing the energy in second derivatives of approximated function. yplot - vector of evaluated spline ordinates. OPTIONAL OUTPUT KEYWORD PARAMETERS /SILENT - suppress all printing. /PLOT - display smooth curve, data ordinates and error bars /ERRBAR - display error bars XTITLE - optional title for X-axis YTITLE - optional title for Y-axis INTERP - optionally returned interpolated smooth spline NOTES: This procedure constructs a smoothing spline according to the method described in "Fundamentals of Image Processing" by A. Jain [Prentice- Hall : New Jersey 1989]. If the distance parameter is sufficiently large a linear regression is performed, otherwise a cubic smoothing spline is constructed. This procedure assumes regular sampling and independent identically distributed normal errors without missing data. The data are sorted. SPLINE_SMOOTH uses the non-standard system variables !TEXTOUT and !TEXTUNIT. These can be added to one's session using the procedure ASTROLIB. COMMON BLOCKS: None. EXAMPLE: Obtain coefficients of a univariate smoothing spline fitted to data X,Y assuming normally distributed errors Yerr and write the results to a file. IDL> SPLINE_SMOOTH, X, Y, Yerr, distance, coefficients, smoothness, t='spline.dat' Fit a smoothing spline to observational data. Suppress all printing and save the smoothed ordinates in output variables. Display results. IDL> SPLINE_SMOOTH, X, Y, Yerr, distance, coefficients, /SILENT, /PLOT PROCEDURES CALLED: Procedures TEXTOPEN, TEXTCLOSE, PLOT, PLOTERR RESTRCTIONS: This procedure is damn slow and should probably be rewritten using the Cholesky decomposition. AUTHOR: Immanuel Freedman (after A. Jain). December, 1993 REVISIONS January 12, 1994 I. Freedman (HSTX) Adjusted formats March 14, 1994 I. Freedman (HSTX) Improved convergence March 15, 1994 I. Freedman (HSTX) User-specified interpolates Converted to IDL V5.0 W. Landsman September 1997 (See spline_smooth.pro)
SRCOR
[Previous Routine] [Next Routine] [List of Routines]NAME: SRCOR PURPOSE: Correlate the source positions found on two lists. CALLING SEQUENCE: srcor,x1in,ylin,x2in,y2in,dcr,ind1,ind2 INPUTS: x1in,y1in - First set of x and y coordinates. The program marches through this list element by element, looking in list 2 for the closest match. So, the program will run faster if this is the shorter of the two lists. Unless you use the option or magnitude keyword, there is nothing to guarantee unique matches. x2in,y2in - Second set of x and y coordinates. This list is searched in its entirety every time one element of list 1 is processed. dcr - Critical radius outside which correlations are rejected; but see 'option' below. OPTIONAL KEYWORD INPUT: option - Changes behavior of program and description of output lists slightly, as follows: OPTION=0 or left out Same as older versions of SRCOR. The closest match from list2 is found for each element of list 1, but if the distance is greater than DCR, the match is thrown out. Thus the index of that element within list 1 will not appear in the IND1 output array. OPTION=1 Forces the output mapping to be one-to-one. OPTION=0 results, in general, in a many-to-one mapping from list 1 to list 2. Under OPTION=1, a further processing step is performed to keep only the minimum-distance match, whenever an entry from list 1 appears more than once in the initial mapping. OPTION=2 Same as OPTION=1, except the critical distance parameter DCR is ignored. I.e., the closest object is retrieved from list 2 for each object in list 1 WITHOUT a critical-radius criterion, then the clean-up of duplicates is done as under OPTION=1. magnitude An array of stellar magnitudes corresponding to x1in and y1in. If this is supplied, then the brightest star from list 1 within the selected distance of the star in list 2 is taken. The option keyword is ignored in this case. spherical If SPHERICAL=1, it is assumed that the input arrays are in celestial coordinates (RA and Dec), with x1in and x2in in decimal hours and y1in and y2in in decimal degrees. If SPHERICAL=2 then it is assumed that the input arrays are in longitude and latitude with x1in,x2in,y1in,y2in in decimal degrees. In both cases, the critial radius dcr is in *arcseconds*. Calculations of spherical distances are made with the gcirc program. OUTPUTS: ind1 - index of matched stars in first list ind2 - index of matched stars in second list COMMON BLOCKS: none SIDE EFFECTS: none METHOD: See under keyword LEVEL above. REVISON HISTORY: Adapted from UIT procedure J.Wm.Parker, SwRI 29 July 1997 Converted to IDL V5.0 W. Landsman September 1997(See srcor.pro)
STARAST
[Previous Routine] [Next Routine] [List of Routines]NAME: STARAST PURPOSE: Compute astrometric solution using positions of 2 or 3 reference stars EXPLANATION: Computes an exact astrometric solution using the positions and coordinates from 2 or 3 reference stars. If 2 stars are used, then the X and Y plate scales are assumed to be identical, and the axis are assumed to be orthogonal. Use of three stars will allow a unique determination of each element of the CD matrix. CALLING SEQUENCE: starast, ra, dec, x, y, cd INPUTS: RA - 2 or 3 element vector containing the Right Ascension in DEGREES DEC- 2 or 3 element vector containing the Declination in DEGREES X - 2 or 3 element vector giving the X position of reference stars Y - 2 or 3 element vector giving the Y position of reference stars OUTPUTS: CD - CD (Coordinate Description) matrix (DEGREES/PIXEL) determined from stellar positions and coordinates. EXAMPLE: To use STARAST to add astrometry to a FITS header H; IDL> starast,ra,dec,x,y,cd ;Determine CD matrix IDL> crval = [ra(0),dec(0)] ;Use Star 0 as reference star IDL> crpix = [x(0),y(0)] +1 ;FITS is offset 1 pixel from IDL IDL> putast,H,cd,crpix,crval ;Add parameters to header METHOD: The CD parameters are determined by solving the linear set of equations relating position to local coordinates (l,m) REVISION HISTORY: Written, W. Landsman January 1988 Converted to IDL V5.0 W. Landsman September 1997(See starast.pro)
STORE_ARRAY
[Previous Routine] [Next Routine] [List of Routines]NAME: STORE_ARRAY PURPOSE: Insert array INSERT into the array DESTINATION EXPLANATION: The dimensions of the DESTINATION array are adjusted to accomodate the inserted array. CATEGOBY: Utility CALLING SEQUENCE: STORE_ARRAY, DESTINATION, INSERT, INDEX INPUT: DESTINATION = Array to be expanded. INSERT = Array to insert into DESTINATION. INDEX = Index of the final dimension of DESTINATION to insert INSERT into. OUTPUTS: DESTINATION = Expanded output array. If both input arrays have the same number of dimensions, then the DESTINATION will be replaced with INSERT. RESTRICTIONS: DESTINATION and INSERT have to be either both of type string or both of numerical types. INSERT must not have more dimensions than DESTINATION. MODIFICATION HISTOBY: William Thompson, Feb. 1992, from BOOST_ARRAY by D. Zarro and P. Hick. Converted to IDL V5.0 W. Landsman September 1997(See store_array.pro)
STRD
[Previous Routine] [Next Routine] [List of Routines]NAME: STRD PURPOSE: Open an STSDAS file and read into an image array and header. EXPLANATION: Combines the functions of SXREAD and SXOPEN. CALLING SEQUENCE: STRD, im, hdr, [ filename, GROUP = , PAR = ] OPTIONAL INPUT: FILENAME - Character string giving the name of the SDAS file to be read. If omitted, then program will prompt for the file name. If an extension is given, then it must terminate in a 'h'. A default extension of '.hhh' is assumed, if one is not supplied. Under VMS, the version numbers are ignored, and the most recent version is always used. OUTPUTS: IM - array containing image data HDR - string array containing header OPTIONAL INPUT KEYWORD PARAMETER: GROUP - scalar integer specifying group number to read. Default is 0. OPTIONAL OUTPUT KEYWORD PARAMETER: PAR - Parameter block (byte array) read from group formatted data COMMON BLOCKS: STCOMMN - Created by SXOPEN. STRD uses STCOMMN to check for an open unit, and to get image dimensions. SIDE EFFECTS: STSDAS image array and header are read into IM and HDR IF FILENAME is not supplied, then the program will check that the image and header variable do not already contain data. SYSTEM VARIABLES: Set !QUIET = 1 to suppress informational messages. METHOD: Program checks that specified STSDAS file exists before calling SXOPEN and SXREAD to read in data. PROCEDURES CALLED: FDECOMP, PICKFILE(), SPEC_DIR(), SXOPEN, SXREAD() MODIFICATION HISTORY: Written W. Landsman, STI Corporation August 1986 Optional parameter "FILENAME" added November 1986 Correctly print header size when more than 2 dimensions February 1996 Add GROUP, PAR keywords, call PICKFILE W. Landsman March 1996 Converted to IDL V5.0 W. Landsman September 1997(See strd.pro)
STREBCASC
[Previous Routine] [Next Routine] [List of Routines]NAME: STREBCASC PURPOSE: Function to converts an EBCDIC string to its ASCII equivalent EXPLANATION: Similar to the IDL Version 1 routine of the same name. CALLING SEQUENCE: result = STREBCASC( ebcstring ) INPUT PARAMETERS: EBCSTRING - String scalar or array written in EBCDIC OUTPUT: RESULT - the input string converted to ASCII DATA FILES: STREBCASC reads a file EBCASC.DAT containing the EBCDIC-ASCII conversion code. This file must be in the directory specified by the logical name or the environment variable ASTRO_DATA (see the first line of the program) COMMON BLOCKS: The conversion matrix read in from EBCASC.DAT is saved in the common block EBCASC for subsequent use. PROCEDURE: Each EBCDIC character is converted to its ASCII equivalent. NOTES: The conversion of non-printable characters differs somewhat from the Version 1 procedure. MODIFICATION HISTORY: Adapted from the IUE program EBCDIC, Wayne Landsman December, 1990 Converted to IDL V5.0 W. Landsman September 1997(See strebcasc.pro)
STRN
[Previous Routine] [Next Routine] [List of Routines]NAME: STRN PURPOSE: Convert a number to a string and remove padded blanks. EXPLANATION: The main and original purpose of this procedure is to convert a number to an unpadded string (i.e. with no blanks around it.) However, it has been expanded to be a multi-purpose formatting tool. You may specify a length for the output string; the returned string is either set to that length or padded to be that length. You may specify characters to be used in padding and which side to be padded. Finally, you may also specify a format for the number. NOTE that the input "number" need not be a number; it may be a string, or anything. It is converted to string. CALLING SEQEUNCE: tmp = STRN( number, [ LENGTH=, PADTYPE=, PADCHAR=, FORMAT = ] ) INPUT: NUMBER This is the input variable to be operated on. Traditionally, it was a number, but it may be any scalar type. OPTIONAL INPUT: LENGTH This KEYWORD specifies the length of the returned string. If the output would have been longer, it is truncated. If the output would have been shorter, it is padded to the right length. PADTYPE This KEYWORD specifies the type of padding to be used, if any. 0=Padded at End, 1=Padded at front, 2=Centered (pad front/end) IF not specified, PADTYPE=1 PADCHAR This KEYWORD specifies the character to be used when padding. The default is a space (' '). FORMAT This keyword allows the FORTRAN type formatting of the input number (e.g. '(f6.2)') OUTPUT: tmp The formatted string USEFUL EXAMPLES: print,'Used ',strn(stars),' stars.' ==> 'Used 22 stars.' print,'Attempted ',strn(ret,leng=6,padt=1,padch='0'),' retries.' ==> 'Attempted 000043 retries.' print,strn('M81 Star List',length=80,padtype=2) ==> an 80 character line with 'M81 Star List' centered. print,'Error: ',strn(err,format='(f15.2)') ==> 'Error: 3.24' or ==> 'Error: 323535.22' HISTORY: 03-JUL-90 Version 1 written by Eric W. Deutsch 10-JUL-90 Trimming and padding options added (E. Deutsch) 29-JUL-91 Changed to keywords and header spiffed up (E. Deutsch) Ma7 92 Work correctly for byte values (W. Landsman) 19-NOV-92 Added Patch to work around IDL 2.4.0 bug which caused an error when STRN('(123)') was encountered. (E. Deutsch) Converted to IDL V5.0 W. Landsman September 1997(See strn.pro)
STRNUMBER
[Previous Routine] [Next Routine] [List of Routines]NAME: STRNUMBER PURPOSE: Function to determine if a string is a valid numeric value. CALLING SEQUENCE: result = strnumber( st, [val] ) INPUTS: st - any IDL scalar string OUTPUTS: 1 is returned as the function value if the string st has a valid numeric value, otherwise, 0 is returned. OPTIONAL OUTPUT: val - (optional) value of the string. real*8 EXAMPLES: IDL> res = strnumber(' ',val) returns res=0 (not a number) and val is undefined IDL> res = strnumber('0.2d', val) returns res=1 (a valid number), and val = 0.2000d NOTES: STRNUMBER was modified in February 1993 to include a special test for empty or null strings, which now returns a 0 (not a number). Without this special test, it was found that a empty string (' ') could corrupt the stack. HISTORY: version 1 By D. Lindler Aug. 1987 test for empty string, W. Landsman February, 1993 Converted to IDL V5.0 W. Landsman September 1997(See strnumber.pro)
STR_INDEX()
[Previous Routine] [Next Routine] [List of Routines]NAME: STR_INDEX() PURPOSE: Get indices of a substring (SUBSTR) in string. EXPLANATION: The IDL intrinsic function STRPOS returns only the index of the first occurrence of a substring. This routine calls itself recursively to get indices of the remaining occurrences. CALLING SEQUENCE: result= STR_INDEX(str, substr [, offset]) INPUTS: STR -- The string in which the substring is searched for SUBSTR -- The substring to be searched for within STR OPTIONAL INPUTS: OFFSET -- The character position at which the search is begun. If omitted or being negative, the search begins at the first character (character position 0). OUTPUTS: RESULT -- Integer scalar or vector containing the indices of SUBSTR within STR. If no substring is found, it is -1. CALLS: DATATYPE(), DELVARX COMMON BLOCKS: STR_INDEX -- internal common block. The variable save in the block is deleted upon final exit of this routine. CATEGORY: Utility, string MODIFICATION HISTORY: Written January 3, 1995, Liyun Wang, GSFC/ARC Converted to IDL V5.0 W. Landsman September 1997(See str_index.pro)
STSUB
[Previous Routine] [Next Routine] [List of Routines]NAME: STSUB PURPOSE: Subroutine of STSUBIM to read a subset of a SDAS image file. EXPLANATION: User can specify a subimage range or a step size Called by STSUBIM CALLING SEQUENCE: Result = stsub( unit, x1, x2, y1, y2, step) INPUTS: UNIT = Unit number of file, must be from 1 to 9. Unit must have been opened with SXOPEN. x1 = lower x value x2 = upper x value y1 = lower y value y2 = upper y value step = used to extract every nth pixel. If step = 1, a full res. subimage is extracted; step = 2, every other pixel is extracted, etc. Defaults to 1. The minimum value is 1. OUTPUTS: Result of function = array constructed from designated record. COMMON BLOCKS: Uses idl common stcommn to access parameters (see SXOPEN) MODIFICATION HISTORY: Written, M. Greason, STX, July 1990. Remove initialization of array for increased efficiency January, 1991 Removed call to STSUBC.EXE, do it all in IDL - K. Venkatakrishna, STX, April 1992 Converted to IDL V5.0 W. Landsman September 1997(See stsub.pro)
STSUBIM
[Previous Routine] [Next Routine] [List of Routines]NAME: STSUBIM PURPOSE: Open an STSDAS file and read a portion of the file into an array. EXPLANATION: An enhanced version of STRD. Program will prompt for the file name and subimage bounds. CALLING SEQUENCE: STSUBIM, im, hdr, [ filename, x1, x2, y1, y2, step, /SILENT ] OPTIONAL INPUTS: FILENAME - Character string giving the name of the SDAS file to be read. If omitted, then program will prompt for the file name. If an extension is given, then it must terminate in a 'h'. A default extension of '.hhh' is assumed, if one is not supplied. In VMS, version numbers are ignored, and the most recent version is always used. X1 - Starting x value (def=0), integer scalar X2 - Ending x value (def=total record size), integer scalar Y1 - Starting y value (def = 0), integer scalar Y2 - Ending y value (def = total no. of records), integer scalar STEP - The number of pixels between extracted pixels. This allows the user to read every Nth pixel from the image. STEP=1 indicates full resolution, STEP=2 indicates every other pixel, etc. OUTPUTS: IM - array containing image data HDR - string array containing STSDAS header OPTIONAL KEYWORD INPUT: SILENT - If this keyword is present, the size of the image will not be printed. COMMON BLOCKS: STCOMMN - Created by SXOPEN. STSUBIM uses STCOMMN to check for an open unit, and to get image dimensions. SIDE EFFECTS: STSDAS image array and header are read into IM and HD IF FILENAME is not supplied, then the program will check that the image and header variable do not already contain data. RESTRICTIONS: For use only on data without Groups!! For use only on 2 dimensional data files. PROCEDURE: Program checks that STSDAS file exists and that IDL variables do not already contain data, before calling SXOPEN and STSUB to read in data. The header keywords NAXIS* and CRPIX* are updated to account for the actual image size. PROCEDURES CALLED: FDECOMP, ORDINAL(), SPEC_DIR(), STSUB, SXOPEN, SXADDPAR, SXADDHIST MODIFICATION HISTORY: Written B. Pfarr, STX, September 1987 from STRD Modifed to IDL Version 2, M. Greason, STX, May 1990. Prints 1st, 2nd, etc., instead of 1th, 2th... R. S.Hill, STX, Aug 1991 CRPIX transformation corrected. RSH, HSTX, 27-May-1992. Use new astrometry structure W. Landsman Feb 1994 Converted to IDL V5.0 W. Landsman September 1997(See stsubim.pro)
STWRT
[Previous Routine] [Next Routine] [List of Routines]NAME: STWRT PURPOSE: Write a STSDAS header and/or 2-D array to disk (without groups!) CALLING SEQUENCE: STWRT, hdr ;Write image header (.hhh file) only STWRT, im ;Create header to match image array STWRT, im, hdr,[ name, /SDAS, /NOUPDATE ] INPUT PARAMETERS: im - image array to be written to disk. If no header array is supplied, then a simple header appropiate to the image will be constructed. OPTIONAL INPUT PARAMETER: hdr - STSDAS header, string array. name - character string containing the name of output file to which the image is written. If omitted, then the program will prompt for the file name. A file name will have the default extension of '.HHH' OPTIONAL KEYWORD INPUTS: NOUPDATE-- By default, STWRT will modify the input FITS header to create a proper SDAS .hhh file. This includes ensuring that (1) a DATATYPE keyword exists, and (2) that BITPIX is a positive value. SDAS-- The SDAS keyword can be specified to modify the input header to ensure SDAS compatibility. RESTRICTIONS: (1) STWRT is only for 2 dimensional images. For other arrays use SXOPEN,1,NAME,HD,HISTORY,'W' ;HISTORY need not be defined SXWRITE,1,IM CLOSE,1 (2) The type of data written is determined by the DATATYPE keyword in the header. A DATATYPE keyword appropiate to the image array type will be added if does not already exist SIDE EFFECTS: A STSDAS header and/or image array is written to disk. Unit 2 is opened and closed. REVISION HISTORY: Written W. Landsman, STI Corp. August, 1986 Returned old version to not modify header. W. Landsman July 1991. Included call to CHKDType--option to change DATATYPE and BITPIX if they; do not match. J.D.Offenberg Dec 1991. Added call to CHECK_FITS, NOUPDATE keyword, remove autochange keyword W. Landsman May 1992 Converted to IDL V5.0 W. Landsman September 1997(See stwrt.pro)
ST_DISKREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISKREAD PURPOSE: Read HST FITS formatted disk files and reconstruct GEIS (STSDAS) files. CALLING SEQUENCE: ST_DISKREAD, infiles INPUT PARAMETER: infiles - (scalar string) input disk files to be converted into GEIS files. Wildcards are allowed. FILES CREATED: GEIS files: The GEIS file is reconstructed from each input Fits file. The output filename is composed from the rootname of the observation and the appropriate GEIS file extension (i.e. d0h/d, c0h/d, etc.). Tables: If input file is a fits table, the output is an SDAS table. EXAMPLES: a) Reconstruct the GEIS file for disk FITS file z29i020ct*.fits. st_diskread,'z29i020ct*.fits' PROCEDURES CALLED: ST_DISK_DATA, ST_DISK_TABLE, ST_DISK_GEIS FTSIZE,SXPAR(),TAB_CREATE, TAB_WRITE HISTORY: 10/17/94 JKF/ACC - taken from ST_TAPEREAD. 11/02/94 JKF/ACC - added /block on open statement to handle files with 512 bytes/record. 12/6/95 JKF/ACC - include new jitter files...replaces st_read_jitter.pro. 03/5/96 W. Landsman, change FORRD to READU, remove Version 1 type codes, add message facility **************************************************************************** Converted to IDL V5.0 W. Landsman September 1997(See st_diskread.pro)
ST_DISK_DATA
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISK_DATA PURPOSE: Routine to read next header and data array from an HST FITS disk file. This is a subroutine of ST_DISKREAD and not intended for stand alone use. CALLING SEQUENCE: st_disk_data,unit,h,data,name,gcount,dimen,opsize,nbytes,itype INPUTS: unit - logical unit number. OUTPUTS: h - FITS header data - data array name - file name gcount - number of groups dimen - data dimensions opsize - parameter blocks size nbytes - bytes per data group itype - idl data type Notes: This is not a standalone program. Use ST_DISKREAD. PROCEDURES CALLED: GETTOK(), SXPAR() HISTORY: 10/17/94 JKF/ACC - taken from ST_TAPE_DATA. ***************************************************************************(See st_diskread.pro)
ST_DISK_GEIS
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISK_GEIS PURPOSE: Routine to construct GEIS files from ST FITS disk files. CALLING SEQUENCE: ST_DISK_GEIS, h, data, htab, tab, table_available, name, gcount, dimen,opsize, nbytes_g,itype INPUT PARAMETERS: h - header for data data - data array htab - header for the table tab - fits table table_available - logical variable (1 if table was found) name - data set name gcount - number of groups dimen - data dimensions opsize - original parameter block size nbytes_g - number of bytes per group itype - idl integer data type value for the output data groups SIDE EFFECTS: GEIS file updated with group parameters in unit 1 (already open) and header file created NOTES: This is not a standalone program. Use st_diskread. During the creation of the header, this routine performs the following steps: 1) create a basic fits header (7 keywords) 2) adjust basic fits header for the number of axis present (i.e. >1) 3) adjust basic fits header for parameter keywords (i.e. ptype,etc) 4) from this point, sequentially copies keywords until it hits one of the following keywords 'INSTRUME','INSTRUID', or 'CONFG'. 5) append 'END' statement PROCEDURES CALLED: FTSIZE, SXADDPAR, SXHWRITE HISTORY: 10/17/94 JKF/ACC - taken from ST_DISK_GEIS ****************************************************************************(See st_diskread.pro)
ST_DISK_TABLE
[Previous Routine] [Next Routine] [List of Routines]NAME: ST_DISK_TABLE PURPOSE: Routine to read FITS table from an ST fits on disk. This is a subroutine of st_diskread and not intended for stand alone use. CALLING SEQUENCE: st_disk_table,unit,h,data INPUTS PARAMETER: unit - disk unit number OUTPUTS: h - FITS header data - table array NOTES: This is not a standalone program. Use ST_DISKREAD. HISTORY: 10/17/94 JKF/ACC - taken from ST_TAPE_TABLE. 12/7/95 JKF/ACC - handle tables for jitter data. ****************************************************************************(See st_diskread.pro)
SUBSTAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SUBSTAR PURPOSE: Subtract a scaled point spread function at specified star position(s). EXPLANATION: Part of the IDL-DAOPHOT photometry sequence CALLING SEQUENCE: SUBSTAR, image, x, y, mag, [ id, psfname, /VERBOSE] INPUT-OUTPUT: IMAGE - On input, IMAGE is the original image array. A scaled PSF will be subtracted from IMAGE at specified star positions. Make a copy of IMAGE before calling SUBSTAR, if you want to keep a copy of the unsubtracted image array INPUTS: X - REAL Vector of X positions found by NSTAR (or FIND) Y - REAL Vector of Y positions found by NSTAR (or FIND) MAG - REAL Vector of stellar magnitudes found by NSTAR (or APER) Used to scale the PSF to match intensity at star position. Stars with magnitude values of 0.0 are assumed missing and ignored in the subtraction. OPTIONAL INPUTS: ID - Index vector indicating which stars are to be subtracted. If omitted, (or set equal to -1), then stars will be subtracted at all positions specified by the X and Y vectors. PSFNAME - Name of the FITS file containing the PSF residuals, as generated by GETPSF. SUBSTAR will prompt for this parameter if not supplied. OPTIONAL INPUT KEYWORD: VERBOSE - If this keyword is set and nonzero, then SUBSTAR will display the star that it is currently processing COMMON BLOCKS: The RINTER common block is used (see RINTER.PRO) to save time in the PSF calculations PROCEDURES CALLED: DAO_VALUE(), READFITS(), REMOVE, SXOPEN, SXPAR(), SXREAD() REVISION HISTORY: Written, W. Landsman August, 1988 Added VERBOSE keyword January, 1992 Fix star subtraction near edges, W. Landsman May, 1996 Assume the PSF file is in FITS format W. Landsman July, 1997 Converted to IDL V5.0 W. Landsman September 1997(See substar.pro)
SUNPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: SUNPOS PURPOSE: To compute the RA and Dec of the Sun at a given date. CALLING SEQUENCE: SUNPOS, jd, ra, dec, [elong, obliquity, /RADIAN ] INPUTS: jd - The Julian date of the day (and time), scalar or vector usually double precision OUTPUTS: ra - The right ascension of the sun at that date in DEGREES double precision, same number of elements as jd dec - The declination of the sun at that date in DEGREES OPTIONAL OUTPUTS: elong - Ecliptic longitude of the sun at that date in DEGREES. obliquity - the obliquity of the ecliptic, in DEGREES OPTIONAL INPUT KEYWORD: RADIAN - If this keyword is set and non-zero, then all output variables are given in Radians rather than Degrees NOTES: The accuracy in the 20th century should be within 1"; however this has not been extensively tested. The returned RA and Dec are in the given date's equinox. Procedure was extensively revised in May 1996, and the new calling sequence is incompatible with the old one. METHOD: Uses a truncated version of Newcomb's Sun. Adapted from the IDL routine SUN_POS by CD Pike, which was adapted from a FORTRAN routine by B. Emerson (RGO). EXAMPLE: (1) Find the apparent RA and Dec of the Sun on May 1, 1982 IDL> jdcnv, 1982, 5, 1,0 ,jd ;Find Julian date jd = 2445090.5 IDL> sunpos, jd, ra, dec IDL> print,adstring(ra,dec,2) 02 31 32.61 +14 54 34.9 The Astronomical Almanac gives 02 31 32.58 +14 54 34.9 so the error in SUNPOS for this case is < 0.5". (2) Find the apparent RA and Dec of the Sun for every day in 1997 IDL> jdcnv, 1997,1,1,0, jd ;Julian date on Jan 1, 1997 IDL> sunpos, jd+ dindgen(365), ra, dec ;RA and Dec for each day MODIFICATION HISTORY: Written by Michael R. Greason, STX, 28 October 1988. Accept vector arguments, W. Landsman April,1989 Eliminated negative right ascensions. MRG, Hughes STX, 6 May 1992. Rewritten using the 1993 Almanac. Keywords added. MRG, HSTX, 10 February 1994. Major rewrite, improved accuracy, always return values in degrees W. Landsman May, 1996 Added /RADIAN keyword, W. Landsman August, 1997 Converted to IDL V5.0 W. Landsman September 1997(See sunpos.pro)
SUNSYMBOL
[Previous Routine] [Next Routine] [List of Routines]NAME: SUNSYMBOL PURPOSE: Return the Sun symbol as a subscripted postscript character string EXPLANATION: Returns the Sun symbol (circle with a dot in the middle) as a (subscripted) postscript character string. Needed because although the Sun symbol is available using the vector fonts as the string '!9n', it is not in the standard postscript set. CALLING SEQUENCE: result = SUNSYMBOL() INPUTS: None OUTPUTS: result - a scalar string representing the Sun symbol. A different string is output depending (1) the device is postscript and hardware fonts are used (!P.FONT=0), (2) vector fonts are used, or (3) hardware fonts are used on a non-postscript device. For case (3), SUNSYMBOL simply outputs the 3 character string 'Sun' EXAMPLE: To make the X-axis of a plot read M/M_Sun IDL> plot,indgen(10),xtit = 'M / M' + sunsymbol() RESTRICTIONS: (1) The postscript output does not have the dot perfectly centered in the circle (2) SUNSYMBOL() includes subscript output positioning commands in the output string. REVISION HISTORY: Written, W. Landsman, HSTX April, 1997 Converted to IDL V5.0 W. Landsman September 1997(See sunsymbol.pro)
SXADDHIST
[Previous Routine] [Next Routine] [List of Routines]NAME: SXADDHIST PURPOSE: Procedure to add history line(s) to a FITS header CALLING SEQUENCE sxaddhist, history, header, [ /PDU ] INPUTS: history - string or string array containing history line(s) to add to the header header - string array containing the FITS header KEYWORD INPUTS: /PDU - if specified, the history will be added to the primary data unit header, (before the line beginning BEGIN EXTENSION...) Otherwise, it will be added to the end of the header OUTPUTS: header - unpdated header EXAMPLES: sxaddhist, 'I DID THIS', header hist = strarr(3) hist(0) = 'history line number 1' hist(1) = 'the next history line' hist(2) = 'the last history line' sxaddhist, hist, header HISTORY: D. Lindler Feb. 87 April 90 Converted to new idl D. Lindler Put only a single space after HISTORY W. Landsman November 1992 Aug. 95 Added PDU keyword parameters Converted to IDL V5.0 W. Landsman September 1997(See sxaddhist.pro)
SXADDPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXADDPAR PURPOSE: Add or modify a parameter in a FITS header array. CALLING SEQUENCE: sxaddpar, Header, Name, Value, [ Comment, Location, BEFORE =, AFTER = , FORMAT= , /PDU] INPUTS: Header = String array containing FITS or STSDAS header. The length of each element must be 80 characters. If not defined, then SXADDPAR will create an empty FITS header array. Name = Name of parameter. If Name is already in the header the value and possibly comment fields are modified. Otherwise a new record is added to the header. If name = 'HISTORY' then the value will be added to the record without replacement. In this case the comment parameter is ignored. Value = Value for parameter. The value expression must be of the correct type, e.g. integer, floating or string. String values of 'T' or 'F' are considered logical values. OPTIONAL INPUT PARAMETERS: Comment = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '', then the previous comment field is retained (when found) Location = Keyword string name. The parameter will be placed before the location of this keyword. This parameter is identical to the BEFORE keyword and is kept only for consistency with earlier versions of SXADDPAR. OPTIONAL INPUT KEYWORD PARAMETERS: BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A scalar string should be used. For complex numbers the format should be defined so that it can be applied separately to the real and imaginary parts. /PDU = specifies keyword is to be added to the primary data unit header. If it already exists, it's current value is updated in the current position and it is not moved. OUTPUTS: Header = updated FITS header array. RESTRICTIONS: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types. MODIFICATION HISTORY: DMS, RSI, July, 1983. D. Lindler Oct. 86 Added longer string value capability Converted to NEWIDL D. Lindler April 90 Added Format keyword, J. Isensee, July, 1990 Added keywords BEFORE and AFTER. K. Venkatakrishna, May '92 Pad string values to at least 8 characters W. Landsman April 94 Aug 95: added /PDU option and changed routine to update last occurence of an existing keyword (the one SXPAR reads) instead of the first occurence. Comment for string data can start after column 32 W. Landsman June 97 Make sure closing quote supplied with string value W. Landsman June 98 Converted to IDL V5.0 W. Landsman June 98(See sxaddpar.pro)
SXDELPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXDELPAR PURPOSE: Procedure to delete a keyword parameter(s) from a FITS header CALLING SEQUENCE: sxdelpar, h, parname INPUTS: h - FITS or STSDAS header, string array parname - string or string array of keyword name(s) to delete OUTPUTS: h - updated FITS header, If all lines are deleted from the header, then h is returned with a value of 0 EXAMPLE: Delete the astrometry keywords CDn_n from a FITS header, h IDL> sxdelpar, h, ['CD1_1','CD1_2','CD2_1','CD2_2'] NOTES: (1) No message is returned if the keyword to be deleted is not found (2) All appearances of a keyword in the header will be deleted HISTORY: version 1 D. Lindler Feb. 1987 Converted to new IDL April 1990 by D. Lindler Test for case where all keywords are deleted W. Landsman Aug 1995 Converted to IDL V5.0 W. Landsman September 1997(See sxdelpar.pro)
SXGINFO
[Previous Routine] [Next Routine] [List of Routines]NAME: SXGINFO PURPOSE: Return information on all group parameters in an STSDAS header. EXPLANATION: Return datatype, starting byte, and number bytes for all group parameters in an STSDAS file. Obtaining these values greatly speed up execution time in subsequent calls to SXGPAR. CALLING SEQUENCE: sxginfo, h, par, type, sbyte, nbytes INPUTS: h - header returned by SXOPEN par - parameter block returned by SXREAD or multiple parameter blocks stored in array of dimension greater than one. OUTPUT: type - data type (if not supplied or null string, the header is searched for type,sbyte, and nbytes) sbyte - starting byte in parameter block for data nbytes - number of bytes in parameter block for data The number of elements in type,sbyte and nbytes equals the total number of group parameters. METHOD: The parameter type for each parameter is obtained from PDTYPEn keyword. If not found then DATATYPE keyword value is used. If that is not found then BITPIX is used. BITPIX=8, byte; BITPIX=16 integer*2; BITPIX=32 integer*4. NOTES: For an example of the use of SXGINFO, see CONV_STSDAS HISTORY: version 1 W. Landsman Apr. 93 Converted to IDL V5.0 W. Landsman September 1997(See sxginfo.pro)
SXGPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXGPAR PURPOSE: Obtain group parameter value in SDAS/FITS file CALLING SEQUENCE: result = sxgpar( h, par, name, [ type, sbyte, nbytes] ) INPUTS: h - header returned by SXOPEN par - parameter block returned by SXREAD or multiple parameter blocks stored in array of dimension greater than one. name - parameter name (keyword PTYPEn) or integer parameter number. OPTIONAL INPUT/OUTPUT type - data type (if not supplied or null string, the header is searched for type,sbyte, and nbytes) sbyte - starting byte in parameter block for data nbytes - number of bytes in parameter block for data OUTPUT: parameter value or value(s) returned as function value SIDE EFFECTS: If an error occured then !err is set to -1 OPERATIONAL NOTES: Supplying type, sbyte and nbytes greatly decreases execution time. The best way to get the types is on the first call pass undefined variables for the three parameters or set type = ''. The routine will then return their values for use in subsequent calls. METHOD: The parameter type for parameter n is obtained from PDTYPEn keyword. If not found then DATATYPE keyword value is used. If that is not found then BITPIX is used. BITPIX=8, byte; BITPIX=16 integer*2; BITPIX=32 integer*4. HISTORY: version 1 D. Lindler Oct. 86 version 2 D. Lindler Jan. 90 added ability to process multiple parameter blocks in single call version 3 D. Lindler (converted to New vaxidl) Apr 14 1991 JKF/ACC - fixed make_array datatypes(float/double) Converted to IDL V5.0 W. Landsman September 1997(See sxgpar.pro)
SXGREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: SXGREAD PURPOSE: Read group parameters from a Space Telescope STSDAS image file CALLING SEQUENCE: grouppar = sxgread( unit, group ) INPUTS: UNIT = Supply same unit as used in SXOPEN. GROUP = group number to read. if omitted, read first group. The first group is number 0. OUTPUTS: GROUPPAR = parameter values from fits group parameter block. It is a byte array which may contain multiple data types. The function SXGPAR can be used to retrieve values from it. COMMON BLOCKS: Uses IDL Common STCOMMN to access parameters. SIDE EFFECTS: IO is performed. MODIFICATION HISTORY: WRITTEN, Don Lindler, July, 1 1987 MODIFIED, Don Neill, Jan 11, 1991 - derived from sxread.pro Converted to IDL V5.0 W. Landsman September 1997(See sxgread.pro)
SXHCOPY
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHCOPY PURPOSE: Copies selected portions of one header to another CALLING SEQUENCE: sxhcopy, h, keyword1, keyword2, hout INPUTS: h - input header keyword1 - first keyword to copy keyword2 - last keyword to copy INPUT/OUTPUT: hout - header to copy the information to. METHOD: the headers lines from keyword1 to keyword2 are copied to the end of the output header. No check is made to verify that a keyword value already exists in the output header. HISTORY: version 1 D. Lindler Sept. 1989 Converted to IDL V5.0 W. Landsman September 1997(See sxhcopy.pro)
SXHEDIT
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHEDIT PURPOSE: Routine to interactively edit an STSDAS header on disk. EXPLANATION: VMS: uses EDT. Unix: uses whatever your EDITOR environment variable is set to. CALLING SEQUENCE: sxhedit, name, [ h ] INPUTS: name - header file name (default extension is .hhh) OUTPUTS: h - (optional) edited header SIDE EFFECTS: A new version of the file will be created. HISTORY: Version 1 D. Lindler July 1987 Version 2 JAH Dec '88: Converted to Sun IDL. Modified D. Neill Sept, 1990: Now deletes all versions of sxhedit.tmp made compatable with Unix Modified D. Neill Apr, 1991: Ensures 80 char headers and will not create new version if no changes made. Converted to IDL V5.0 W. Landsman September 1997(See sxhedit.pro)
SXHMAKE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHMAKE PURPOSE: Create a basic STSDAS header file from an IDL data array CALLING SEQUENCE: sxhmake, Data, Groups, Header INPUTS: Data = IDL data array of the same type, dimensions and size as are to be written to file. Groups = # of groups to be written. OUTPUTS: Header = String array containing ST header file. PROCEDURE: Call sxhmake to create a header file. Then call sxopen to open output image, followed by sxwrite to write the data. If you do not plan to change the header created by sxhmake before calling sxopen, you might consider using sxmake which does both steps. MODIFICATION HISTORY: Don Lindler Feb 1990 modified from SXMAKE by DMS, July, 1983. D. Lindler April 90 Converted to new VMS IDL M. Greason May 1990 Header creation bugs eliminated. W. Landsman Aug 1997 Use SYSTIME() instead of !STIME for V5.0 Converted to IDL V5.0 W. Landsman September 1997(See sxhmake.pro)
SXHREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHREAD PURPOSE: Procedure to read a STSDAS header from disk. EXPLANATION: This version of SXHREAD can read three types of disk files (1) VMS Fixed record length 80 byte files, or GEIS files with VMS buckets (2) Unix stream files with a CR after every 80 bytes (3) Variable length record files (Unix or VMS) CALLING SEQUENCE: sxhread, name, header INPUT: name - file name, scalar string. An extension of .hhh is appended if not already supplied. (Note STSDAS headers are required to have a 3 letter extension ending in 'h'.) OUTPUT: header - STSDAS header, string array NOTES: SXHREAD does not do any checking to see if the file is a valid STSDAS header. It simply reads the file into a string array with 80 byte elements HISTORY: Version 1 D. Lindler July, 1987 Version 2 M. Greason, August 1990 Use READU for certain ST VAX GEIS files W. Landsman January, 1992 Read variable length Unix files E. Deutsch/W. Landsman November, 1994 Converted to IDL V5.0 W. Landsman September 1997(See sxhread.pro)
SXHWRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXHWRITE PURPOSE: Procedure to write an STSDAS or FITS header to disk as a *.hhh file. CALLING SEQUENCE: sxhwrite,name,h INPUTS: name - file name. If an extension is supplied it must be 3 characters ending in "h". h - FITS header, string array SIDE EFFECTS: File with specified name is written. If qualifier not specified then .hhh is used SXHWRITE will modify the header in the following ways, if necessary (1) If not already present, an END statement is added as the last line. Lines after an existing END statment are deleted. (2) Spaces are appended to force each line to be 80 characters. (3) On Unix machines, a carriage return is appended at the end of each line. This is consistent with STSDAS and allows the file to be directly displayed on a stream device PROCEDURES USED: zparcheck, fdecomp HISTORY: version 1 D. Lindler June 1987 conversion cleaned up. M. Greason, June 1990 Add carriage return at the end of Unix files W. Landsman Oct 1991 Use SYSTIME() instead of !STIME for V5.0 compatibility Aug 1997 Converted to IDL V5.0 W. Landsman September 1997(See sxhwrite.pro)
SXMAKE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXMAKE PURPOSE: Create a basic ST header file from an IDL array prior to writing data. CALLING SEQUENCE: sxmake, Unit, File, Data, Par, Groups, Header INPUTS: Unit = Logical unit number from 1 to 9. File = file name of data and header files to create. The filetype extension must not appear in this name. The header file is created with the extension 'HHH' and the data file has 'HHD'. Data = IDL data array of the same type, dimensions and size as are to be written to file. Par = # of elements in each parameter block for each data record. If = to 0, parameter blocks will not be written. The data type of the parameter blocks must be the same as the data array. Groups = # of groups to write. If 0 then write in basic format without groups. OPTIONAL INPUT PARAMETERS: Header = String array containing ST header file. If this parameter is omitted, a basic header is constructed. If included, the basic parameters are added to the header using sxaddpar. The END keyword must terminate the parameters in Header. OPTIONAL OUTPUT PARAMETERS: Header = ST header array, an 80 by N character array. COMMON BLOCKS: Stcommn - as used in sxwrite, sxopen, etc. SIDE EFFECTS: The header file is created and written and then the data file is opened on the designated unit. RESTRICTIONS: Header files must be named .HHH and data files must be named .HHD. PROCEDURE: Call sxmake to create a header file. Then call sxwrite to output each group. MODIFICATION HISTORY: DMS, July, 1983. converted to new VMS IDL April 90 Use SYSTIME() instead of !STIME W. Landsman Aug 1997 Converted to IDL V5.0 W. Landsman September 1997(See sxmake.pro)
SXOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: SXOPEN PURPOSE: Open a Space Telescope formatted header file. EXPLANATION: Saves the parameters required subsequent SX routines in the common block Stcommn. Optionally save the header in the string array Header, and the history in the string array History. Open the data file associated with this header on the same unit. CALLING SEQUENCE: SXOPEN, Unit, Fname [, Header [,History] [,Access]] INPUTS: Unit = IDL unit used for IO. Must be from 1 to 9. Fname = File name of header file. Default extension is .hhh for header files and .hhd for data files. If an extension is supplied it must have the form .xxH where xx are any to alphanumeric characters. The data file must have extension .xxD No version number is allowed. Most recent versions of the files are used. OPTIONAL INPUT PARAMETER: Access = 'R' to open for read, 'W' to open for write. OUTPUTS: Stcommn = Common block containing ST parameter blocks. (Long arrays.) OPTIONAL OUTPUT PARAMETERS: Header = 80 char by N string array containing the names, values and comments from the FITS header. Use the function SXPAR to obtain individual parameter values. History = String array containing the value of the history parameter. COMMON BLOCKS: STCOMMN - Contains RESULT(20,10) where RESULT(i,LUN) = 0 - 121147 for consistency check, 1 - Unit for consistency, 2 - bitpix, 3 - naxis, 4 - groups (0 or 1), 5 - pcount, 6 - gcount, 7 - psize, 8 - data type as idl type code, 9 - bytes / record, 10 to 10+N-1 - dimension N, 17 = record length of file in bytes. 18 - # of groups written, 19 = gcount. SIDE EFFECTS: The data and header files are accessed. RESTRICTIONS: Works only for disc files. The data file must have must have the extension ".hhd" and the header file must have the extension ".hhh". PROCEDURE: The header file is opened and each line is read. Important parameters are stored in the output parameter. If the last two parameters are specified the parameter names and values are stored. The common block STCOMMN is filled with the type of data, dimensions, etc. for use by SXREAD. If access is for write, each element of the header array, which must be supplied, is written to the header file. The common block is filled with relevant parameters for SXWRITE. A keyword of "END" ends the header. MODIFICATION HISTORY: Written, DMS, May, 1983. D. Lindler Feb. 1990 Modified to allow var. record length header files. D. Lindler April 1990 Conversion to new VMS IDL Added /BLOCK when opening new .hhd file Converted to IDL V5.0 W. Landsman September 1997(See sxopen.pro)
SXPAR
[Previous Routine] [Next Routine] [List of Routines]NAME: SXPAR PURPOSE: Obtain the value of a parameter in a FITS header CALLING SEQUENCE: result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT = ]) INPUTS: Hdr = FITS header array, (e.g. as returned by READFITS) string array, each element should have a length of 80 characters Name = String name of the parameter to return. If Name is of the form 'keyword*' then an array is returned containing values of keywordN where N is an integer. The value of keywordN will be placed in RESULT(N-1). The data type of RESULT will be the type of the first valid match of keywordN found. OPTIONAL INPUTS: ABORT - string specifying that SXPAR should do a RETALL if a parameter is not found. ABORT should contain a string to be printed if the keyword parameter is not found. If not supplied SXPAR will return with a negative !err if a keyword is not found. OPTIONAL OUTPUT KEYWORDS: COUNT - Optional keyword to return a value equal to the number of parameters found by sxpar, integer scalar COMMENT - Array of comments associated with the returned values OUTPUTS: Function value = value of parameter in header. If parameter is double precision, floating, long or string, the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1b is returned for T, and 0b is returned for F. If Name was of form 'keyword*' then a vector of values are returned. SIDE EFFECTS: !ERR is set to -1 if parameter not found, 0 for a scalar value returned. If a vector is returned it is set to the number of keyword matches found. If a keyword occurs more than once in a header, a warning is given, and the first occurence is used. EXAMPLES: Given a FITS header, h, return the values of all the NAXISi values into a vector. Then place the history records into a string vector. IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records PROCEDURE: The first 8 chacters of each element of Hdr are searched for a match to Name. The value from the last 20 characters is returned. An error occurs if there is no parameter with the given name. If a numeric value has no decimal point it is returned as type LONG. If it contains more than 8 numerals, or contains the character 'D', then it is returned as type DOUBLE. Otherwise it is returned as type FLOAT. Very large integer values, outside the range of valid LONG, are returned as DOUBLE. NOTES: The functions SXPAR() and FXPAR() are nearly identical, although FXPAR() has slightly more sophisticated parsing. There is no particular reason for having two nearly identical procedures, but both are too widely used to drop either one. PROCEDURES CALLED: GETTOK(), STRNUMBER() MODIFICATION HISTORY: DMS, May, 1983, STPAR Written. D. Lindler Jan 90 added ABORT input parameter J. Isensee Jul,90 added COUNT keyword W. Thompson, Feb. 1992, added support for FITS complex values. W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank keywords, and complex value error correction. W. Landsman, November 1994, fix case where NAME is an empty string W. Landsman, March 1995, Added COMMENT keyword, ability to read values longer than 20 character W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call T. Beck May 1998, Return logical as type BYTE W. Landsman May 1998, Make sure integer values are within range of LONG Converted to IDL V5.0, May 1998(See sxpar.pro)
SXREAD
[Previous Routine] [Next Routine] [List of Routines]NAME: SXREAD PURPOSE: Read a Space Telescope STSDAS image file CALLING SEQUENCE: result = sxread( Unit, group , [par] ) INPUTS: UNIT = Unit number of file, must be from 1 to 9. Unit must have been opened with SXOPEN. GROUP = group number to read. if omitted, read first record. The first record is number 0. OUTPUTS: Result of function = array constructed from designated record. OPTIONAL OUTPUT: PAR = Variable name into which parameter values from STSDAS group parameter block are read. It is a byte array which may contain multiple data types. The function SXGPAR can be used to retrieve values from it. COMMON BLOCKS: Uses IDL Common STCOMMN to access parameters. NOTES: Use the function SXGREAD to read the group parameter blocks without having to read the group array. If the STSDAS file does not contain groups, then the optional output parameter PAR is returned undefined, but no error message is given. SIDE EFFECTS: IO is performed. MODIFICATION HISTORY: WRITTEN, Don Lindler, July, 1 1987 Converted to IDL V5.0 W. Landsman September 1997(See sxread.pro)
SXWRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: SXWRITE PURPOSE: Write a group of data and parameters in ST format to a STSDAS data file. CALLING SEQUENCE: SXWRITE, Unit, Data,[ Par] INPUTS: Unit = unit number of file. The file must have been previously opened by SXOPEN. Data = Array of data to be written. The dimensions must agree with those supplied to SXOPEN and written into the FITS header. The type is converted if necessary. OPTIONAL INPUT PARAMETERS: Par = parameter block. The size of this array must agree with the Psize parameter in the FITS header. OUTPUTS: None. COMMON BLOCKS: STCOMMN - Contains RESULT(20,10) where RESULT(i,LUN) = 0 - 121147 for consistency check, 1 - Unit for consistency, 2 - bitpix, 3 - naxis, 4 - groups (0 or 1), 5 - pcount, 6 - gcount, 7 - psize, 8 - data type as idl type code, 9 - bytes / record, 10 to 10+N-1 - dimension N, 18 - # of groups written, 19 = gcount. SIDE EFFECTS: The data are written into the next group. RESTRICTIONS: SXOPEN must have been called to initialize the header and the common block. MODIFICATION HISTORY: DMS, July, 1983. D.Lindler July, 1986 - changed block size of file to 512 moved group parameters after the groups data. D.Lindler July, 1987 - modified to allow any size parameter block (in bytes). D. Lindler April, 1990 - converted to new VMS IDL Converted to IDL V5.0 W. Landsman September 1997(See sxwrite.pro)
TABINV
[Previous Routine] [Next Routine] [List of Routines]NAME: TABINV PURPOSE: To find the effective index of a function value in an ordered vector. CALLING SEQUENCE: TABINV, XARR, X, IEFF INPUTS: XARR - the vector array to be searched, must be monotonic increasing or decreasing X - the function value(s) whose effective index is sought (scalar or vector) OUTPUT: IEFF - the effective index or indices of X in XARR real or double precision, same # of elements as X RESTRICTIONS: TABINV will abort if XARR is not monotonic. (Equality of neighboring values in XARR is allowed but results may not be unique.) This requirement may mean that input vectors with padded zeroes could cause routine to abort. PROCEDURE: A binary search is used to find the values XARR(I) and XARR(I+1) where XARR(I) < X < XARR(I+1). IEFF is then computed using linear interpolation between I and I+1. IEFF = I + (X-XARR(I)) / (XARR(I+1)-XARR(I)) Let N = number of elements in XARR if x < XARR(0) then IEFF is set to 0 if x > XARR(N-1) then IEFF is set to N-1 EXAMPLE: Set all flux values of a spectrum (WAVE vs FLUX) to zero for wavelengths less than 1150 Angstroms. IDL> tabinv, wave, 1150.0, I IDL> flux( 0:fix(I) ) = 0. FUNCTIONS CALLED: ISARRAY() REVISION HISTORY: Adapted from the IUE RDAF January, 1988 More elegant code W. Landsman August, 1989 Mod to work on 2 element decreasing vector August, 1992 Converted to IDL V5.0 W. Landsman September 1997(See tabinv.pro)
TABLE_APPEND
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_APPEND PURPOSE: Routine to append STSDAS tables to create a single table. Input tables must all have identical columns. CALLING SEQUENCE: table_append,list,name INPUTS: list - string array listing the file names or a string scalar giving a file name template. name - output file name. SIDE EFFECTS: a new STSDAS table is created with the specified name. OPERATIONAL NOTES: all input tables must have the same number of columns with the same names, datatypes, and column order. Header parameters are taken only from the first table. HISTORY: version 1 D. Lindler April 1989 Removed call to non-standard system variable !DUMP WBL September 1997 Converted to IDL V5.0 W. Landsman September 1997(See table_append.pro)
TABLE_CALC
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_CALC PURPOSE: Adds a new table column from a expression using existing columns CALLING SEQUENCE: table_calc, table, expression, table_out INPUTS: table - input SDAS table table expression - expression for new or updated column values. Any legal IDL expression is valid where existing column names can be used as variables. User functions within the expression are allowed if the function is in an IDL library or previously compiled. OPTIONAL INPUT: table_out - output table name. If not supplied, the input name is used. OUTPUTS: a new SDAS table file is created. EXAMPLES: create a column WAVELENGTH in table TAB which is the average of the WLOW and WHIGH columns of table TAB. table_calc,'tab','WAVELENGTH=(WLOW+WHIGH)/2.0' add a column SINX which is the sin of column X to table JUNK. table_calc,'junk','SINX=sin(X)' add 10.0 to an existing column in table MYTAB. table_calc,'mytab','flux=flux+10.0' HISTORY version 1 D. Lindler November, 1989 Converted to IDL V5.0 W. Landsman September 1997(See table_calc.pro)
TABLE_CONV
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_CONV PURPOSE: Convert STSDAS table(s) to the host format EXPLANATION: If on a BIG_ENDIAN machine (e.g. SparcStation), assumes table came from a little endian machine unless /FROM_VMS keyword is set If on a LITTLE_ENDIAN machine (e.g. OSF, Windows), assumes table came from a big endian machine unless /FROM_VMS keyword is set If on a VMS machine, assumes table came from a big endian machine unless the /FROM_LITTLE keyword is set CALLING SEQUENCE: TABLE_CONV, filespec, [ /FROM_VMS, /FROM_LITTLE ] INPUT PARAMETERS: filespec - file specification for table(s), scalar string. Can include wildcard values, e.g. '*.tab' EXAMPLE: (1) An STSDAS table "calspec.tab" has been FTP'ed from a Sparcstation to a VMS machine. Convert the table to the host VMS format. (The FTP mode should be set to binary when copying STSDAS tables) IDL> table_conv, 'calspec.tab' (2) A set of files '*.tab' have been FTP'ed from VMS machine to a Sparcstation. Convert all the files to the host format IDL> table_conv, '*.tab', /FROM_VMS NOTES: TABLE_CONV does not check whether byte-swapping is actually needed. If this procedure is applied to a file that is already in the host format, then that file will be corrupted. PROCEDURES CALLED: CONV_VAX_UNIX(), CONV_UNIX_VAX, FDECOMP, IS_IEEE_BIG(), SWAP_ENDIAN(), TABLE_HCONV, TAB_PUT, TAB_READ, TAB_SIZE, TAB_WRITE MODIFICATION HISTORY: W. Landsman, Hughes STX/Goddad July 1996 Adapted from GHRS version by Don Lindler, Keith Feggans Converted to IDL V5.0 W. Landsman September 1997(See table_conv.pro)
TABLE_DELETE
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_DELETE PURPOSE: Delete specified rows from an STSDAS table CALLING SEQUENCE: table_delete, name, rows, [ outname ] INPUT: name - table name rows - row (scalar) or rows(vector) to delete from the table OPTIONAL OUTPUT: outname - output table name, if not supplied the input name is used HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See table_delete.pro)
TABLE_EXT
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_EXT PURPOSE: Routine to extract columns from an STSDAS table CALLING SEQUENCE: TABLE_EXT, name, columns, v1, [v2,v3,v4,v5,v6,v7,v8,v9] INPUTS: name - table name, scalar string columns - table columns to extract. Can be either (1) String with names separated by commas (2) Scalar or vector of column numbers OUTPUTS: v1,...,v9 - values for the columns EXAMPLES: Read wavelength and throughput vectors from STSDAS table, wfpc_f725.tab IDL> table_ext,'wfpc_f725.tab','wavelength,throughput',w,t or IDL> table_ext,'wfpc_f725.tab',[1,2],w,t PROCEDURES CALLED: GETTOK(), TAB_READ, TAB_VAL() HISTORY: version 1 D. Lindler May 1989 Accept Column Numbers as well as names, W. Landsman February 1996 Converted to IDL V5.0 W. Landsman September 1997(See table_ext.pro)
TABLE_HELP
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_HELP PURPOSE: Procedure to decribe an SDAS table file. CALLING SEQUENCE: table_help, tcb, header table_help, name INPUTS: tcb - table control block returned by TAB_READ or TAB_CREATE name - the table name OPTIONAL INPUTS: header - header array returned by TAB_READ. If supplied it will be printed, otherwise it won't. SIDE EFFECTS: text output as specified by !textout HISTORY: version 1 D. Lindler JAN 1988 Converted to IDL V5.0 W. Landsman September 1997(See table_help.pro)
TABLE_LIST
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_LIST PURPOSE: List the contents of an STSDAS table. EXPLANATION: Procedure to list contents of an STSDAS table. This does not print the table in tabular form but instead for each row prints the column name followed by its value (one column per output line. CALLING SEQUENCE: table_list, name, row1, row2, [ TEXTOUT=, /HEADER ] INPUTS: name - table name OPTIONAL KEYWORD INPUT: TEXTOUT - Scalar string giving output file name, or integer (1-5) specifying output device. See TEXTOPEN for more info. Default is to display output at the terminal HEADER - if set, the header is printed before the selected row printout OPTIONAL INPUTS: row1 - first row to list (default = first row) row2 - last row to list (default = last row) OUTPUT: text output is written to the output device specified by the TEXTOUT keyword, or the nonstandard system variable !TEXTOUT PROCEDURES USED: TAB_COL, TAB_READ, TAB_SIZE, TAB_VAL(), TEXTOPEN, TEXTCLOSE HISTORY: version 1 D. Lindler May 1989 July 1996, DJL, added /header keyword to optionally print header August 1996, WBL, added TEXTOUT keyword Converted to IDL V5.0 W. Landsman September 1997(See table_list.pro)
TABLE_PRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_PRINT PURPOSE: Routine to print an stsdas table. CALLING SEQUENCE: table_print, name, columns, row1, row2 INPUTS: name - table name OPTIONAL INPUTS: columns - vector of column numbers to be printed or a string with column names separated by commas. If not supplied or set to the null string, all columns are printed. row1 - first row to print. (default=0) row2 - last row to print. (default=last row in table) SIDE EFFECTS: text is printed as directed by !textout HISTORY: version 1, D. Lindler Apr 89 Converted to IDL V5.0 W. Landsman September 1997(See table_print.pro)
TABLE_SORT
[Previous Routine] [Next Routine] [List of Routines]NAME: TABLE_SORT PURPOSE: Procedure to sort an STSDAS table by the specified column CALLING SEQUENCE: table_sort, name, column, [ name_out ] INPUTS: name - table name column - column to sort on OPTIONAL INPUTS: name_out - output table name. If not supplied, input name is used. HISTORY: version 1 D. Lindler MAY 1989 Converted to IDL V5.0 W. Landsman September 1997(See table_sort.pro)
TAB_ADDCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_ADDCOL PURPOSE: Procedure to add a new column to an existing STSDAS table. CALLING SEQUENCE: tab_addcol, name, data, tcb, tab INPUTS: name - column name data - sample data of type to be written to the column. This parameter is only used to determine data type. INPUT/OUTPUTS: tcb - table control block tab - table array HISTORY: version 1 D. Lindler April 89 Converted to IDL V5.0 W. Landsman September 1997(See tab_addcol.pro)
TAB_COL
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_COL PURPOSE: Procedure to extract column information from table control block CALLING SEQUENCE: tab_col, tcb, column, offset, width, datatype, name, units, format INPUTS: tcb - table control block returned by tab_open. column - column name (string) or column number OUTPUTS: offset - column offset bytes width - column width in bytes datatype - column data type: 6 - real*4 7 - real*8 4 - integer*4 1 - boolean 2 - character string name - column name units - column units format - format code SIDE EFFECTS: If the column is not found then !err is set to -1. Otherwise !err is set to the column number (starting at one). HISTORY: version 1 D. Lindler Jan 88 Converted to NEW IDL April 90 Converted to IDL V5.0 W. Landsman September 1997(See tab_col.pro)
TAB_CREATE
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_CREATE PURPOSE: Procedure to create a new table file. CALLING SEQUENCE: tab_create, tcb, tab, maxcol, maxrows, row_len, tb_type OUTPUTS: tcb - table control block for reading from and writing to the file (see tab_open for description) tab - table array OPTIONAL INPUTS: maxcol - maximum allocated number of columns [default=10] maxrows - maximum allocated number of rows [default=100] row_len - row length in 2 byte units [default=2*maxcol] tb_type - table type 'row' or 'column' ordered SIDE EFFECTS: Table file is created and left opened to unit number tcb(0,0) for writing. HISTORY: version 1 D. Lindler Dec. 88 Converted to IDL V5.0 W. Landsman September 1997(See tab_create.pro)
TAB_DEL
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_DEL PURPOSE: Delete specified row(s) from an STSDAS table CALLING SEQUENCE: tab_del, tcb, tab, rows INPUT/OUTPUTS tcb - table control block tab - table array OPTIONAL INPUTS: rows - row (scalar) or rows(vector) to delete from the table If not supplied all rows are deleted. HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_del.pro)
TAB_EXPAND
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_EXPAND PURPOSE: routine to expand the size of an SDAS table file. CALLING SEQUENCE: tab_expand, tcb, tab, maxcol, maxrow, rowlen INPUT/OUTPUT: tcb - table control block returned by routine TAB_READ or TAB_CREATE. tab - table array OPTIONAL INPUTS: maxcol - new maximum number of columns. maxrow - new maximum number of rows. rowlen - new maximum row length in 2 byte units. If maxcol, maxrow, or rowlen are supplied with values less than the previous maximums, the previous maximums are used. All values are defaulted to zero if not supplied. HISTORY: Version 1 D. Lindler Dec. 88 Converted to IDL V5.0 W. Landsman September 1997(See tab_expand.pro)
TAB_FORTOSPP
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_FORTOSPP PURPOSE: Procedure to convert a FORTRAN format to an SPP format specfication. CALLING SEQUENCE: sppformat, format, sppformat INPUTS: format - fortran format specification OUTPUTS: sppformat - sppformat specification HISTORY: version 1 D. Lindler Jan, 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_fortospp.pro)
TAB_MODCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_MODCOL PURPOSE: Modify column description in a STSDAS table CALLING SEQUENCE: tab_modcol, tcb, column, units, format, newname INPUTS: tcb - table control block column - column name or number to be modified OPTIONAL INPUTS: units - string giving physical units for the column. If not supplied or set to the null string the units are not changed. format - print format (either fortran or SPP format) An spp format should be preceeded by a '%'. If not supplied or set to a null string, the print format for the column is not changed. newname - new name for the column. If not supplied or set to a null string, the name is not changed EXAMPLES: change the wavelength column to WAVE with a new format of 'F10.3' and columns units of ANGSTROMS. tab_modcol,tcb,'wavelength','ANGSTROMS','F10.3','WAVE' Change to print format of column 3 to spp format 20.10e tab_modcol,tcb,3,'','%20.10e' HISTORY: version 1 D. Lindler Apr 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_modcol.pro)
TAB_NULL
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_NULL PURPOSE: function to locate null values within a vector of values from an STSDAS table. CALLING SEQUENCE result = tab_null(values) INPUTS: values - data value(s) OUTPUTS: a boolean variable is returned with the same length as values. 1 indicates that the corresponding value was null OPERATIONAL NOTES: Boolean columns in an STSDAS table does not presently have the capability to flag null values. HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_null.pro)
TAB_NULLROW
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_NULLROW PURPOSE: Insert null row(s) into a STSDAS table CALLING SEQUENCE: tab_nullrow, tcb, tab, [ row1, row2 ] INPUTS: tcb - table control block INPUT/OUTPUTS: tab - table array OPTIONAL INPUTS: row1 - first row number to insert nulls (default=0) row2 - last row number to insert nulls (default = last row) HISTORY: version 1, D. Lindler Apr 89 Converted to IDL V5.0 W. Landsman September 1997(See tab_nullrow.pro)
TAB_PRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_PRINT PURPOSE: Routine to print an stsdas table. CALLING SEQUENCE: tab_print, tcb, tab, columns, row1, row2 INPUTS: tcb - table control block returned by TAB_READ tab - table array read by TAB_READ OPTIONAL INPUTS: columns - vector of column numbers to be printed or a string with column names separated by commas. If not supplied or set to the null string, all columns are printed. row1 - first row to print. (default=0) row2 - last row to print. (default=last row in table) SIDE EFFECTS: text is printed as directed by !textout HISTORY: version 1, D. Lindler Apr 89 April 90 Converted to NEW IDL D. Lindler Converted to IDL V5.0 W. Landsman September 1997(See tab_print.pro)
TAB_PUT
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_PUT PURPOSE: Procedure to place new values into a STSDAS table. CALLING SEQUENCE: tab_put, column, values, tcb, tab, row INPUTS: column - column name or number (if it is a new column then a column name must be specified) values - data values to add to the table INPUT/OUTPUTS: tcb - table control block tab - table array OPTIONAL INPUT: row - starting row to insert values HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_put.pro)
TAB_READ
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_READ PURPOSE: Procedure to read an SDAS table file CALLING SEQUENCE: tab_read,name,tcb,table,header INPUTS: name - name of the table file OUTPUTS: tcb - table control block Longword array of size 16 x maxcols+2 where maxcols is the maximum number of columns allocated for the table. tcb(*,0) contains: word 0 SPARE 1 number of user parameters 2 max. number of user par. allowed 3 number of rows in the table 4 number of allocated rows (for col. ordered tab) 5 number of columns defined 6 max number of columns 7 length of row used (in units of 2-bytes) 8 max row length (in units of 2-bytes) relevant only for row ordered tables. 9 table type (11 for row order, 12 for col. order) 15 update flag (0-readonly, 1-update) tcb(*,i) contains description of column i word 0 column number 1 offset for start of row in units of 2-bytes 2 width or column in 2-byte units 3 data type 6 = real*4 7 = real*8 4 = integer*4 1 = boolean*4 2 = character string 4-8 ascii column name up to 19 characters 9-13 column units (up to 19 characters) 14-15 format string tcb(*,max number of columns+1)= file name table - table array, Byte array row length (bytes) x nrows header - header parameters in form usable by sxpar, sxaddhist, sxaddpar, ect. HISTORY: Version 1 D. Lindler Jan 88 Converted to NEW IDL April 90 D. Lindler Converted to IDL V5.0 W. Landsman September 1997(See tab_read.pro)
TAB_SIZE
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_SIZE PURPOSE: Routine to extract the table size from a table control block CALLING SEQUENCE: tab_size, tcb, nrows, ncols, maxrows, maxcols, rowlen, max_rowlen INPUTS: tcb - table control block OUTPUTS: nrows - number of rows in the table ncols - number of columns in the table maxrows - number of rows allocated maxcols - number of columns allocated rowlen - length of the rows in bytes max_rowlen - allocated row length HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_size.pro)
TAB_SORT
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_SORT PURPOSE: Procedure to sort table by the specified column CALLING SEQUENCE: tab_sort, column, tcb, tab INPUTS: column - column name or number to sort on tcb - table control block INPUT/OUTPUTS: tab - table array HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_sort.pro)
TAB_SPPTOFOR
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_SPPTOFOR PURPOSE: This procedure converts an spp format specification to a normal Fortran format specification. CALLING SEQUENCE: tab_spptofor, sppformat, format, width INPUTS: sppformat - spp format specification (without preceeding %) OUTPUTS: forformat - fortran format specification (string) width - field width (integer) HISTORY: version 1 D. Lindler Jan 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_spptofor.pro)
TAB_VAL
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_VAL PURPOSE: Routine to read a column from an SDAS table file CALLING SEQUENCE: values = tab_val( tcb, table, column, [ rows ] ) INPUTS: tcb - table control block returned by tab_val table - table array returned by tab_val column - scalar column name or number OPTIONAL INPUT: rows - scalar giving row number or vector giving rows. If not supplied all rows are returned. OUTPUT: the values for the specified column (and rows) is returned as the function value. If row is specified as a scalar (single row) then the result will be a scalar. HISTORY: version 1 D. Lindler Jan. 1988 Allow for a null column Landsman/Feggans April 1992 Converted to IDL V5.0 W. Landsman September 1997(See tab_val.pro)
TAB_WRITE
[Previous Routine] [Next Routine] [List of Routines]NAME: TAB_WRITE PURPOSE: Routine to write an stsdas table to disk CALLING SEQUENCE: tab_write, name, tcb, tab, header INPUTS: name - file name (default extension = .tab) tcb - table control block tab - table array OPTIONAL INPUT: header - FITS header array HISTORY: version 1 D. Lindler April 1989 Converted to IDL V5.0 W. Landsman September 1997(See tab_write.pro)
TAG_EXIST()
[Previous Routine] [Next Routine] [List of Routines]NAME: TAG_EXIST() PURPOSE: To test whether a tag name exists in a structure. EXPLANATION: Routine obtains a list of tagnames and tests whether the requested one exists or not. The search is recursive so if any tag names in the structure are themselves structures the search drops down to that level. (However, see the keyword TOP_LEVEL). CALLING SEQUENCE: status = TAG_EXIST(str, tag, [ INDEX =, /TOP_LEVEL ] ) INPUT PARAMETERS: str - structure variable to search tag - tag name to search for, scalar string OUTPUTS: Function returns 1b if tag name exists or 0b if it does not. OPTIONAL INPUT KEYWORD: TOP_LEVEL = If set, then only the top level of the structure is searched. OPTIONAL OUTPUT KEYWORD: INDEX = index of matching tag, scalar longward, -1 if tag name does not exist EXAMPLE: Determine if the tag 'THICK' is in the !P system variable IDL> print,tag_exist(!P,'THICK') PROCEDURE CALLS: DATATYPE() MODIFICATION HISTORY: : Written, C D Pike, RAL, 18-May-94 Passed out index of matching tag, D Zarro, ARC/GSFC, 27-Jan-95 William Thompson, GSFC, 6 March 1996 Added keyword TOP_LEVEL Zarro, GSFC, 1 August 1996 Added call to help Converted to IDL V5.0 W. Landsman September 1997(See tag_exist.pro)
TAPRD
[Previous Routine] [Next Routine] [List of Routines]NAME : TAPRD PURPOSE : Emulates VMS TAPRD procedure on UNIX machines. EXPLANATION : Emulates VMS TAPRD procedure on UNIX machines. However, the actions of this routine may differ from the VMS equivalent in nonstandard situations. *** Unix only *** CALLING SEQUENCE: TAPRD, ARRAY, UNIT [, BYTE_REVERSE ] Inputs : ARRAY = Variable into which the data should be read. The datatype and number of values to attempt to read is based on this array. UNIT = Specifies the magnetic tape unit. Not to be confused with logical unit numbers. In UNIX, the number refers to one of the environment variables MT0, MT1, etc., which translate into a physical device name, e.g. setenv MT0 /dev/nrst0 Opt. Inputs : BYTE_REVERSE = If present, then even and odd bytes are swapped. Outputs : The output is read into ARRAY. Also, !ERR is set to the number of bytes actually read. Opt. Outputs: None. Keywords : None. Calls : CHECK_TAPE_DRV Common : None. Restrictions: This routine may not have all the abilities of the VMS equivalent, particularly in regards to the !ERR system variable. The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. Side effects: The device file is opened. Category : Utilities, I/O, Tape. Prev. Hist. : William Thompson, GSFC, June 1991. Written : William Thompson, GSFC, June 1991. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Rewrote to use READU with TRANSFER_COUNT keyword. Version 2, William Thompson, GSFC, 22 December 1993. Added check of ARRAY variable. Version : Version 2, 22 December 1993. Converted to IDL V5.0 W. Landsman September 1997(See taprd.pro)
TAPWRT
[Previous Routine] [Next Routine] [List of Routines]NAME : TAPWRT PURPOSE : Emulates VMS TAPWRT procedure on UNIX machines. EXPLANATION : Emulates VMS TAPWRT procedure on UNIX machines. *** Unix only *** CALLING SEQUENCE: TAPWRT, ARRAY, UNIT [, BYTE_REVERSE ] Inputs : ARRAY = Variable into which the data should be read. UNIT = Specifies the magnetic tape unit. Not to be confused with logical unit numbers. In UNIX, the number refers to one of the environment variables MT0, MT1, etc., which translate into a physical device name, e.g. setenv MT0 /dev/nrst0 Opt. Inputs : BYTE_REVERSE = If present, then even and odd bytes are swapped. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : CHECK_TAPE_DRV Common : None. Restrictions: The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. Side effects: The device file is opened. Category : Utilities, I/O, Tape. Prev. Hist. : William Thompson, GSFC, June 1991. Written : William Thompson, GSFC, June 1991. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Rewrote to use WRITEU. Version : Version 1, 21 December 1993. Converted to IDL V5.0 W. Landsman September 1997(See tapwrt.pro)
TBDELCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: TBDELCOL PURPOSE: Delete a column of data from a FITS binary table CALLING SEQUENCE: tbdelcol, h, tab, name INPUTS-OUPUTS h,tab - FITS binary table header and data array. H and TAB will be updated with the specified column deleted INPUTS: name - Either (1) a string giving the name of the column to delete or (2) a scalar giving the column number to delete EXAMPLE: Delete the column "FLUX" from FITS binary table IDL> TBDELCOL, H, TAB, 'FLUX' PROCEDURES USED: DATATYPE(), TBINFO REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Adapted for IDL Version 2, J. Isensee, July, 1990 Use new structure returned by TBINFO, August, 1997 Converted to IDL V5.0 W. Landsman September 1997(See tbdelcol.pro)
TBDELROW
[Previous Routine] [Next Routine] [List of Routines]NAME: TBDELROW PURPOSE: Delete specified row or rows of data from a FITS binary table CALLING SEQUENCE: TBDELROW, h, tab, rows INPUTS-OUPUTS h,tab - FITS binary table header and data array. H and TAB will be updated on output with the specified row(s) deleted. rows - scalar or vector, specifying the row numbers to delete First row has index 0. If a vector it will be sorted and duplicates removed by TBDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = TBGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes TBDELROW,h,tab,bad ;Delete rows with negative fluxes PROCEDURE: Specified rows are deleted from the data array, TAB. The NAXIS2 keyword in the header is updated. REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Checked for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997(See tbdelrow.pro)
TBGET
[Previous Routine] [Next Routine] [List of Routines]NAME: TBGET PURPOSE: Function to return value(s) from specified column in a FITS binary table CALLING SEQUENCE values = TBGET( h, tab, field, [ rows, nulls, /NOSCALE] ) or values = TBGET( tb_str, tab, field, [ rows, nulls, /NOSCALE] ) INPUTS: h - FITS binary table header, e.g. as returned by FITS_READ or tb_str - IDL structure extracted from FITS header by TBINFO. Use of the IDL structure will improve processing speed tab - FITS binary table array, e.g. as returned by FITS_READ field - field name or number, scalar OPTIONAL INPUTS: rows - scalar or vector giving row number(s) Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned OPTIONAL KEYWORD INPUT: NOSCALE - If this keyword is set and nonzero, then the TSCALn and TZEROn keywords will *not* be used to scale to physical values Default is to perfrom scaling CONTINUE - This keyword does nothing, it is kept for consistency with with earlier versions of TBGET(). OUTPUTS: the values for the row are returned as the function value. Null values are set to 0 or blanks for strings. OPTIONAL OUTPUT: nulls - null value flag of same length as the returned data. Only used for integer data types, B, I, and J It is set to 1 at null value positions and 0 elsewhere. If supplied then the optional input, rows, must also be supplied. EXAMPLE: Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second extension of a FITS file 'spectra.fits' into IDL vectors w and f IDL> fits_read,'spectra.fits',tab,htab,exten=2 ;Read 2nd extension IDL> w = tbget(htab,tab,'wavelength') IDL> f = tbget(htab,tab,'flux') NOTES: (1) If the column is variable length ('P') format, then TBGET() will return the longword array of pointers into the heap area. TBGET() currently lacks the ability to actually extract the data from the heap area. (2) Use the higher-level procedure FTAB_EXT (which calls TBGET()) to extract vectors directly from the FITS file. (3) Use the procedure FITS_HELP to determine which extensions are binary tables, and FTAB_HELP or TBHELP to determine the columns of the table PROCEDURE CALLS: IEEE_TO_HOST, TBINFO, TBSIZE HISTORY: Written W. Landsman February, 1991 Work for string and complex W. Landsman April, 1993 Default scaling by TSCALn, TZEROn, Added /NOSCALE keyword, Fixed nulls output, return longword pointers for variable length binary tables, W. Landsman December 1996 Added a check for zero width column W. Landsman April, 1997 Add TEMPORARY() and REFORM() for speed W. Landsman May, 1997 Use new structure returned by TBINFO W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See tbget.pro)
TBHELP
[Previous Routine] [Next Routine] [List of Routines]NAME: TBHELP PURPOSE: Routine to print a description of a FITS binary table header CALLING SEQUENCE: TBHELP, h, [TEXTOUT = ] INPUTS: h - FITS header for a binary table, string array OPTIONAL INPUT KEYWORD: TEXTOUT - scalar number (0-7) or string (file name) controling output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal METHOD: FITS Binary Table keywords NAXIS*,EXTNAME,TFIELDS,TTYPE*,TFORM*,TUNIT*, are read from the header and displayed at the terminal A FITS header is recognized as bein for a binary table if the keyword XTENSION has the value 'BINTABLE' or 'A3DTABLE' NOTES: Certain fields may be truncated in the display SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) before compilation. !TEXTOUT can be used as an alternate to the TEXTOUT keyword. PROCEDURES USED: GETTOK(), SXPAR(), TEXTCLOSE, TEXTOPEN, ZPARCHECK HISTORY: W. Landsman February, 1991 Parsing of a FITS binary header made more robust May, 1992 Added TEXTOUT keyword August 1997 Converted to IDL V5.0 W. Landsman September 1997(See tbhelp.pro)
TBINFO
[Previous Routine] [Next Routine] [List of Routines]NAME: TBINFO PURPOSE: Procedure to return information on the specified field in a FITS binary table. CALLING SEQUENCE: tbinfo, h, tb_str INPUTS: h - FITS binary table header, e.g. as returned by READFITS() OUTPUTS: tb_str - IDL structure with extracted info from the FITS binary table header. Tags include .tbcol - starting column position in bytes, integer vector .width - width of the field in bytes, integer vector .idltype - idltype of field, byte vector 7 - string, 4- real*4, 3-integer*4, 5-real*8 .numval - repeat count, longword vector .tunit - string unit numbers, string vector .tnull - null value for the field, string vector .tform - format for the field, string vector .ttype - field name, string vector .maxval- maximum number of elements in a variable length array, long vector .tscale - scale factor for converting to physical values, default 1.0 .tzero - additive offset for converting to physical values, default 0.0 .tdisp - recommended output display format All of the output vectors will have same number of elements, equal to the number of columns in the binary table SIDE EFFECTS: If there are difficulties interpreting the table then !ERR is set to -1 PROCEDURES USED: SXPAR() NOTES: For variable length ('P' format) column, TBINFO returns values for reading the 2 element longward array of pointers (numval=2, idltype = 3, width=4) HISTORY: Major rewrite to return a structure W. Landsman August 1997 Release for IDL V5.0 August 1997 Converted to IDL V5.0 W. Landsman September 1997(See tbinfo.pro)
TBPRINT
[Previous Routine] [Next Routine] [List of Routines]NAME: TBPRINT PURPOSE: Procedure to print specified columns & rows of a FITS binary table CALLING SEQUENCE: TBPRINT, h, tab, columns, [ rows, TEXTOUT = ] or TBPRINT,tb_str, tab, columns, [ rows, TEXTOUT = ] INPUTS: h - FITS header for table, string array or tb_str - IDL structure extracted from FITS header by TBINFO tab - table array columns - string giving column names, or vector giving column numbers (beginning with 1). If string supplied then column names should be separated by comma's. rows - (optional) vector of row numbers to print. If not supplied or set to scalar, -1, then all rows are printed. OUTPUTS: None OPTIONAL INPUT KEYWORDS: TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal FMT = Format string for print display. If not supplied, then any formats in the TDISP keyword fields of the table will be used, otherwise IDL default formats. SYSTEM VARIABLES: Uses nonstandard system variables !TEXTOUT and !TEXTOPEN Set !TEXTOUT = 3 to direct output to a disk file. The system variable is overriden by the value of the keyword TEXTOUT EXAMPLES: tab = readfits('test.fits',htab,/ext) ;Read first extension into vars tbprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars tbprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for first 100 stars tbprint,h,tab,text="STARS.DAT" ;Convert entire FITS table to ;an ASCII file named STARS.DAT PROCEDURES USED: DATATYPE(), GETTOK(), TEXTOPEN, TEXTCLOSE, TBINFO RESTRICTIONS: (1) Program does not check whether output length exceeds output device capacity (e.g. 80 or 132). (2) Column heading may be truncated to fit in space defined by the FORMAT specified for the column (3) Program does not check for null values HISTORY: version 1 D. Lindler Feb. 1987 Accept undefined values of rows,columns W. Landsman August 1997 Use new structure returned by TBINFO W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See tbprint.pro)
TBSIZE
[Previous Routine] [Next Routine] [List of Routines]NAME: TBSIZE PURPOSE: Procedure to return the size of a fits table. CALLING SEQUENCE: tbsize, h, tab, ncols, nrows, tfields, ncols_all, nrows_all INPUTS: h - FITS table header tab - fits table array OUTPUTS: ncols - number of characters per row in table nrows - number of rows in table tfields - number of fields per row ncols_all - number of characters/row allocated (size of tab) nrows_all - number of rows allocated HISTORY D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997(See tbsize.pro)
TEN()
[Previous Routine] [Next Routine] [List of Routines]NAME: TEN() PURPOSE: Converts a sexigesimal number to decimal. EXPLANATION: Inverse of the SIXTY() function. CALLING SEQUENCES: X = TEN( [ HOUR_OR_DEG, MIN, SEC ] ) X = TEN( HOUR_OR_DEG, MIN, SEC ) X = TEN( [ HOUR_OR_DEG, MIN ] ) X = TEN( HOUR_OR_DEG, MIN ) X = TEN( [ HOUR_OR_DEG ] ) <-- Trivial cases X = TEN( HOUR_OR_DEG ) <-- INPUTS: HOUR_OR_DEG,MIN,SEC -- Scalars giving sexigesimal quantity in in order from largest to smallest. OUTPUTS: Function value returned = double real scalar, decimal equivalent of input sexigesimal quantity. A minus sign on any element of the input vector causes all the elements to be taken as < 0. PROCEDURE: Mostly involves checking arguments and setting the sign. The procedure TENV can be used when dealing with a vector of sexigesimal quantities. MODIFICATION HISTORY: Written by R. S. Hill, STX, 21 April 87 Modified to allow non-vector arguments. RSH, STX, 19-OCT-87 Converted to IDL V5.0 W. Landsman September 1997(See ten.pro)
TENV()
[Previous Routine] [Next Routine] [List of Routines]NAME: TENV() PURPOSE: Converts sexigesimal number or vector to decimal. EXPLANATION: Like TEN() but allows vector input. CALLING SEQUENCES: Result = TENV( dd, mm ) ; result = dd + mm/60. Result = TENV( dd, mm, ss) ; result = dd + mm/60. + ss/3600. INPUTS: dd - Sexigesimal element(s) corresponding to hours or degrees mm - Sexigesimal element(s) corresponding to minutes ss - Sexigesimal element(s) corresponding to seconds (optional) The input parameters can be scalars or vectors. However, the number of elements in each parameter must be the same. OUTPUTS: Result - double, decimal equivalent of input sexigesimal quantities. Same number of elements as the input parameters. If the nth element in any of the input parameters is negative then the nth element in Result wil also be negative. EXAMPLE: If dd = [60,60,0], and mm = [30,-30,-30], then IDL> Result = TENV(dd,mm) ====> Result = [60.5,-60.5,-0.5] PROCEDURE: Mostly involves checking arguments and setting the sign. MODIFICATION HISTORY: Written by W.B. Landsman April, 1991 Converted to IDL V5.0 W. Landsman September 1997(See tenv.pro)
TEXTCLOSE
[Previous Routine] [Next Routine] [List of Routines]NAME: TEXTCLOSE PURPOSE: Close a text outpu file previously opened with TEXTOPEN EXPLANATION: procedure to close file for text output as specifed by the (non-standard) system variable !TEXTOUT. CALLING SEQUENCE: textclose, [ TEXTOUT = ] KEYWORDS: textout - Indicates output device that was used by TEXTOPEN SIDE EFFECTS: if !textout is not equal to 5 and the textunit is opened. Then unit !textunit is closed and released HISTORY: D. Lindler Dec. 1986 (Replaces PRTOPEN) Test if TEXTOUT is a scalar string W. Landsman August 1993 Can't close unit -1 (Standard Output) I. Freedman April 1994 Converted to IDL V5.0 W. Landsman September 1997(See textclose.pro)
TEXTOPEN
[Previous Routine] [Next Routine] [List of Routines]NAME: TEXTOPEN PURPOSE: Open a device specified by TEXTOUT with unit !TEXTUNIT EXPLANATION: Procedure to open file for text output. The type of output device (disk file or terminal screen) is specified by the TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT. CALLING SEQUENCE: textopen, program, [ TEXTOUT =, /STDOUT ] INPUTS: program - scalar string giving name of program calling textopen OPTIONAL INPUT KEYWORDS: TEXTOUT - Integer scalar (0-7) specifying output file/device to be opened (see below) or scalar string giving name of output file. If TEXTOUT is not supplied, then the (non-standard) system variable !TEXTOUT is used. STDOUT - if this keyword is set and non-zero, then the standard output (unit = -1) is used for TEXTOUT=1 or TEXTOUT=2. The use of STDOUT has 2 possible advantages: (1) the output will appear in a journal file (2) Many Unix machines print spurious control characters when printing to /dev/tty. These characters are eliminated by setting /STDOUT The disavdantage of /STDOUT is that the /MORE option is not available. SIDE EFFECTS: The following dev/file is opened for output. Different effects occur depending whether the standard output is a GUI (Macintosh, Windows, Unix/IDLTool) or a TTY textout=0 Nowhere textout=1 if a TTY then TERMINAL using /more option otherwise standard (Unit=-1) output textout=2 if a TTY then TERMINAL without /more option otherwise standard (Unit=-1) output textout=3.prt textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to .prt file if it already exists. textout = filename (default extension of .prt) The unit to be opened is obtained with the procedure GET_LUN unless !TEXTOUT=5. The unit number is placed in system variable !TEXTUNIT. For !TEXTOUT=5 the user must set !TEXTUNIT to the appropriate unit number. NOTES: When printing to a TTY terminal, the output will *not* appear in an IDL JOURNAL session, unlike text printed with the PRINT command. NON-STANDARD SYSTEM VARIABLES: DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 One way to add these variables is to use the procedure ASTROLIB HISTORY: D. Lindler Dec. 1986 Keyword textout added, J. Isensee, July, 1990 Made transportable, D. Neill, April, 1991 Trim input PROGRAM string W. Landsman Feb 1993 Don't modify TEXTOUT value W. Landsman Aug 1993 Modified for MacOS I. Freedman April 1994 Modified for output terminals without a TTY W. Landsman August 1995 Added /STDOUT keyword W. Landsman April 1996 added textout=7 option, D. Lindler, July, 1996 Converted to IDL V5.0 W. Landsman September 1997 (See textopen.pro)
TICLABELS
[Previous Routine] [Next Routine] [List of Routines]NAME: TICLABELS PURPOSE: Create tic labels for labeling astronomical images. EXPLANATION: Used to display images with right ascension and declination axes. This routine creates labels for already determined tic marks (every other tic mark) CALLING SEQUENCE: ticlabels, minval, numtics, incr, ticlabs, [ RA = ,DELTA = ] INPUTS: minval - minimum value for labels (degrees) numtics - number of tic marks incr - increment in minutes for labels OUTPUTS: ticlabs - array of charater string labels OPTIONAL INPUT KEYWORDS: RA - if this keyword is set then the grid axis is assumed to be a Right Ascension. Otherwise a declination axis is assumed DELTA - Scalar specifying spacing of labels. The default is DELTA = 2 which means that a label is made for every other tic mark. Set DELTA=1 to create a label for every tic mark. PROCEDURES USED: RADEC RESTRICTIONS: Invalid for wide field (> 2 degree) images since it assumes that a fixed interval in Y (or X) corresponds to a fixed interval in Dec (or RA) REVISON HISTORY: written by B. Pfarr, 4/15/87 Added DELTA keywrd for compatibility with IMCONTOUR W. Landsman Nov 1991 Added nicer hms and dms symbols when using native PS fonts Deutsch 11/92 Added Patch for bug in IDL <2.4.0 as explained in NOTES E. Deutsch 11/92 Fix when crossing 0 dec or 24h RA Fix DELTA keyword so that it behaves according to the documentation W. Landsman Hughes STX, Nov 95 Converted to IDL V5.0 W. Landsman September 1997(See ticlabels.pro)
TICPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: TICPOS PURPOSE: Specify distance between tic marks for astronomical coordinate overlays EXPLANATION: User inputs number an approximate distance between tic marks, and the axis length in degrees. TICPOS will return a distance between tic marks such that the separation is a round multiple in arc seconds, arc minutes, or degrees CALLING SEQUENCE: ticpos, deglen, pixlen, ticsize, incr, units INPUTS: deglen - length of axis in DEGREES pixlen - length of axis in plotting units (pixels) ticsize - distance between tic marks (pixels). This value will be adjusted by TICPOS such that the distance corresponds to a round multiple in the astronomical coordinate. OUTPUTS: ticsize - distance between tic marks (pixels), positive scalar incr - incremental value for tic marks in round units given by the UNITS parameter units - string giving units of ticsize, either 'ARC SECONDS', 'ARC MINUTES', or 'DEGREES' EXAMPLE: Suppose a 512 x 512 image array corresponds to 0.2 x 0.2 degrees on the sky. A tic mark is desired in round angular units, approximately every 75 pixels. IDL> ticsize = 75 IDL> TICPOS,0.2,512,ticsize,incr,units ==> ticsize = 85.333, incr = 2. units = 'ARC MINUTES' i.e. a good tic mark spacing is every 2 arc minutes, corresponding to 85.333 pixels. REVISON HISTORY: written by W. Landsman November, 1988 Converted to IDL V5.0 W. Landsman September 1997(See ticpos.pro)
TICS
[Previous Routine] [Next Routine] [List of Routines]NAME: TICS PURPOSE: Compute a nice increment between tic marks for astronomical images. EXPLANATION: For use in labelling a displayed image with right ascension and declination axes. An approximate distance between tic marks is input, and a new value is computed such that the distance between tic marks is in simple increments of the tic label values. CALLING SEQUENCE: tics, min, max, numx, ticsize, incr, [RA = ] INPUTS: min - minimum axis value (degrees) max - maximum axis value (degrees) numx - number of pixels in x direction INPUT/OUTPUT ticsize - distance between tic marks (pixels) OUTPUTS: incr - incremental value for tic labels (in minutes of time for R.A., minutes of arc for dec.) REVISON HISTORY: written by B. Pfarr, 4/14/87 Added some more tick precision (i.e. 1 & 2 seconds in case:) EWD May92 Converted to IDL V5.0 W. Landsman September 1997(See tics.pro)
TIC_ONE
[Previous Routine] [Next Routine] [List of Routines]NAME: TIC_ONE PURPOSE: Determine the position of the first tic mark for astronomical images. EXPLANATION: For use in labelling images with right ascension and declination axes. This routine determines the position in pixels of the first tic. CALLING SEQUENCE: tic_one, zmin, pixx, incr, min2, tic1, [RA = ] INPUTS: zmin - astronomical coordinate value at axis zero point (degrees or hours) pixx - distance in pixels between tic marks (usually obtained from TICS) incr - increment in minutes for labels (usually an even number obtained from the procedure TICS) OUTPUTS: min2 - astronomical coordinate value at first tic mark tic1 - position in pixels of first tic mark EXAMPLE: Suppose a declination axis has a value of 30.2345 degrees at its zero point. A tic mark is desired every 10 arc minutes, which corresponds to 12.74 pixels. Then IDL> TIC_ONE, 30.2345, 1, 12.74, min2, tic1 yields values of min2 = 30.333 and tic1 = 5.74, i.e. the first tic mark should be labeled 30 deg 20 minutes and be placed at pixel value 5.74 REVISION HISTORY: by B. Pfarr, 4/15/87 Converted to IDL V5.0 W. Landsman September 1997(See tic_one.pro)
TINIT
[Previous Routine] [Next Routine] [List of Routines]NAME: TINIT PURPOSE: Position a tape for appending a new file EXPLANATION: To position a tape for append a new file by placing it between the final double EOF marks. (VMS or Unix IDL only) CALLING SEQUENCE: TINIT, UNIT PARAMETERS: UNIT - Integer scalar giving tape drive unit number SYSTEM VARIABLES USED: !ERR PROCEDURE: The SKIPF procedure is used to skip files until a double end of file (EOF) is encountered. The tape is then positioned between the 2 EOF marks. TINIT will also display the number of files skipped. RESTRICTIONS: MODIFICATION HISTORY: W.B. Landsman March 1990 Adapted from IUE RDAF Converted to IDL V5.0 W. Landsman September 1997(See tinit.pro)
TO_HEX
[Previous Routine] [Next Routine] [List of Routines]NAME: TO_HEX PURPOSE: Translate a non-negative decimal integer to a hexadecimal string CALLING SEQUENCE: HEX = TO_HEX( D, [ NCHAR ] ) INPUTS: D - non-negative decimal integer, scalar. All leading blanks are removed. OPTIONAL INPUT: NCHAR - number of characters in the output hexadecimal string. If not supplied, then the hex string will contain no leading zeros. OUTPUT: HEX - hexadecimal translation of input integer, string EXAMPLES: IDL> A = TO_HEX(11) ==> A = 'B' IDL> A = TO_HEX(100,3) ==> A = '064' METHOD: The hexadecimal format code '(Z)' is used to convert. No parameter checking is done. REVISION HISTORY: Written W. Landsman November, 1990 Converted to IDL V5.0 W. Landsman September 1997(See to_hex.pro)
TRAPZD
[Previous Routine] [Next Routine] [List of Routines]NAME TRAPZD PURPOSE: Compute the nth stage of refinement of an extended trapezoidal rule. EXPLANATION: This procedure is called by QSIMP and QTRAP. Algorithm from Numerical Recipes, Section 4.2. TRAPZD is meant to be called iteratively from a higher level procedure. CALLING SEQUENCE: TRAPZD, func, A, B, S, step INPUTS: func - scalar string giving name of function to be integrated. This must be a function of one variable. A,B - scalars giving the limits of the integration INPUT-OUTPUT: S - scalar giving the total sum from the previous interations on input and the refined sum after the current iteration on output. step - LONG scalar giving the number of points at which to compute the function for the current iteration. If step is not defined on input, then S is intialized using the average of the endpoints of limits of integration. NOTES: (1) TRAPZD will check for math errors when computing the function at the endpoints, but not on subsequent iterations. (2) TRAPZD always uses double precision to sum the function values but the call to the user-supplied is double precision only if one of the limits A or B is double precision. REVISION HISTORY: Written W. Landsman August, 1991 Always use double precision for TOTAL March, 1996 Converted to IDL V5.0 W. Landsman September 1997(See trapzd.pro)
TRIM()
[Previous Routine] [Next Routine] [List of Routines]NAME: TRIM() PURPOSE: Converts numbers to strings, without trailing zeros. EXPLANATION: Converts numbers into a string representation, and trims off leading and/or trailing blanks. Differs from STRTRIM in that trailing zeros after the period are also trimmed off, unless NUMBER is already a string, or an explicit format is passed. CALLING SEQUENCE: Result = TRIM( NUMBER [, FORMAT ] [, FLAG ] ) INPUTS: NUMBER = Scalar variable or constant. May be of any ordinary type, including string. However, structures are not allowed. OPTIONAL INPUTS : FORMAT - Format specification for STRING function. Must be a string variable, start with the "(" character, end with the ")" character, and be a valid FORTRAN format specification. If NUMBER is complex, then FORMAT will be applied separately to the real and imaginary parts. FLAG - Flag passed to STRTRIM to control the type of trimming: FLAG = 0 Trim trailing blanks. FLAG = 1 Trim leading blanks. FLAG = 2 Trim both leading and trailing blanks. The default value is 2. If NUMBER is complex, then FORMAT will be applied separately to the real and imaginary parts. OUTPUTS: Function returns as a string variable representing the value NUMBER. RESTRICTIONS: NUMBER must not be an array. NUMBER must not be a structure. FORMAT must be a valid format specification, and must not be passed if NUMBER is of type string. FLAG must not be of string type, or an array. PROCEDURES USED: None REVISION HISTORY: Version 1, William Thompson, GSFC, 9 April 1993, Transferred from Solar Library, W. Landsman September 1997 Updated parentheses to V5.0, W. Landsman September 1997(See trim.pro)
TSUM
[Previous Routine] [Next Routine] [List of Routines]NAME: TSUM PURPOSE: Trapezoidal summation of the area under a curve. CALLING SEQUENCE: Result = TSUM(y) or Result = TSUM( x, y, [ imin, imax ] ) INPUTS: x = array containing independent variable. If omitted, then x is assumed to contain the index of the y variable. x = lindgen( N_elements(y) ). y = array containing dependent variable y = f(x) OPTIONAL INPUTS: imin = index of x array at which to begin the integration, integer scalar. If omitted, then summation starts at x(0). imax = index of x value at which to end the integration, integer scalar. If omitted then the integration ends at x(npts). OUTPUTS: result = area under the curve y=f(x) between x(imin) and x(imax). PROCEDURE: The area is determined of individual trapezoids defined by x(i), x(i+1), y(i) and y(i+1). MODIFICATION HISTORY: Written, W.B. Landsman, STI Corp. May 1986 Modified so X is not altered in a one parameter call Jan 1990 Converted to IDL V5.0 W. Landsman September 1997(See tsum.pro)
TVBOX
[Previous Routine] [Next Routine] [List of Routines]NAME: TVBOX PURPOSE: Draw a box(es) or rectangle(s) of specified width EXPLANATION: Positions can be specified either by the cursor position or by supplying a vector of X,Y positions. CALLING SEQUENCE: TVBOX, width, [ x, y, color, /DATA, COLOR =, _EXTRA = ] INPUTS: WIDTH - either a scalar giving the width of a box, or a 2 element vector giving the length and width of a rectangle. OPTIONAL INPUTS: X - x position for box center, scalar or vector, device coordinates Y - y position for box center, scalar or vector. If vector, then Y must have the same number of elements as X If X and Y are not specified, and device has a cursor, then TVBOX will draw a box at current cursor position COLOR - intensity value(s) (0 - !D.N_COLORS) used to draw the circle(s) If COLORS is a scalar then all circle are drawn with the same color value. Otherwise, the Nth circle is drawn with the Nth value of color. Default = !P.COLOR. OUTPUTS: None OPTIONAL KEYWORD INPUT: COLOR - Scalar or vector, overrides the COLOR input parameter DATA - if this keyword is set and non-zero, then the box width and X,Y position center are interpreted as being in DATA coordinates. Note that data coordinates must be previously defined (e.g. with a PLOT or CONTOUR call). Any keyword recognized by PLOTS (or POLYFILL if /FILL is set) is also recognized by TVBOX. In particular, the color, linestyle, and thickness of the boxes is controlled by the COLOR, LINESTYLE, and THICK keywords. SIDE EFFECTS: A square or rectangle will be drawn on the device For best results WIDTH should be odd. (If WIDTH is even, the actual size of the box will be WIDTH + 1, so that box remains centered.) EXAMPLE: Draw a double thick box of width 13, centered at 221,256 in the currently active window IDL> tvbox, 13, 221, 256, thick=2 RESTRICTIONS: (1) TVBOX does not check whether box is off the edge of the screen (2) Allows use of only device (default) or data (if /DATA is set) coordinates. Normalized coordinates are not allowed REVISON HISTORY: Written, W. Landsman STX Co. 10-6-87 Modified to take vector arguments. Greg Hennessy Mar 1991 Fixed centering of odd width W. Landsman Sep. 1991 Let the user specify COLOR=0, accept vector color, W. Landsman Nov. 1995 Fixed typo in _EXTRA keyword W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See tvbox.pro)
TVCIRCLE
[Previous Routine] [Next Routine] [List of Routines]NAME: TVCIRCLE PURPOSE: Draw circle(s) of specified radius at specified position(s) EXPLANATION: If a position is not specified, and device has a cursor, then a circle is drawn at the curret cursor position. CALLING SEQUENCE: TVCIRCLE, rad, x, y, color, [ /DATA, /FILL, _EXTRA = ] INPUTS: RAD - radius of circle(s) to be drawn, positive numeric scalar OPTIONAL INPUT: X - x position for circle center, vector or scalar Y - y position for circle center, vector or scalar If X and Y are not specified, and the device has a cursor, then program will draw a circle at the current cursor position COLOR - intensity value(s) (0 - !D.N_COLORS) used to draw the circle(s) If COLOR is a scalar then all circles are drawn with the same color value. Otherwise, the Nth circle is drawn with the Nth value of color. Default = !P.COLOR. OPTIONAL KEYWORD INPUTS: DATA - if this keyword is set and non-zero, then the circle width and X,Y position center are interpreted as being in DATA coordinates. Note that data coordinates must be previously defined (with a PLOT or CONTOUR call). TVCIRCLE will internally convert to device coordinates before drawing the circle, in order to maintain optimal smoothness. FILL - If set, fill the circle using POLYFILL Any keyword recognized by PLOTS (or POLYFILL if /FILL is set) is also recognized by TVCIRCLE. In particular, the color, linestyle, and thickness of the circles are controlled by the COLOR, LINESTYLE, and THICK keywords. If POLYFILL is set then available keywords are LINE_FILL and FILL_PATTERN. OUTPUTS: None RESTRICTIONS: (1) TVCIRCLE does not check whether it writes off of the edge of the display (2) Some round-off error may occur when non-integral values are supplied for both the radius and the center coordinates (3) TVCIRCLE does not accept /NORMAL coordinates, only data coordinates (if /DATA is set) or device coordinates (the default) EXAMPLE: (1) Draw circles of radius 9 pixels at the positions specified by X,Y vectors, using double thickness lines IDL> tvcircle, 9, x, y, THICK = 2 Now fill in the circles using the LINE_FILL method IDL> tvcircle, 9, x, y, /FILL, /LINE_FILL METHOD: The method used is that of Michener's, modified to take into account the fact that IDL plots arrays faster than single points. See "Fundamental of Interactive Computer Graphics" by Foley and Van Dam" p. 445 for the algorithm. REVISON HISTORY: Original version written by B. Pfarr STX 10-88 Major rewrite adapted from CIRCLE by Allyn Saroyan LNLL Wayne Landsman STX Sep. 91 Added DATA keyword Wayne Landsman HSTX June 1993 Added FILL keyword. R. S. Hill, HSTX, 4-Nov-1993 Always convert to device coords, add _EXTRA keyword, allow vector colors. Wayne Landsman, HSTX, May 1995 Allow one to set COLOR = 0, W. Landsman, HSTX, November 1995 Check if data axes reversed. P. Mangifico, W. Landsman May 1996 Converted to IDL V5.0 W. Landsman September 1997(See tvcircle.pro)
TVELLIPSE
[Previous Routine] [Next Routine] [List of Routines]NAME: TVELLIPSE PURPOSE: Draw an ellipse on the current graphics device. CALLING SEQUENCE: TVELLIPSE, rmax, rmin, xc, yc, [ pos_ang, color, COLOR= ,/DATA, NPOINTS= LINESTYLE=, THICK = ] NPOINTS =, LINESTYLE = ] INPUTS: RMAX,RMIN - Scalars giving the major and minor axis of the ellipse XC,YC - Scalars giving the position on the TV of the ellipse center OPTIONAL INPUTS: POS_ANG - Position angle of the major axis, measured counter-clockwise from the X axis. Default is 0. COLOR - Scalar giving intensity level to draw ellipse. The color can be specified either with either this parameter or with the COLOR keyword. Default is !P.COLOR OPTIONAL KEYWORD INPUT: DATA - if this keyword is set and non-zero, then the ellipse radii and X,Y position center are interpreted as being in DATA coordinates. Note that the data coordinates must have been previously defined (with a PLOT or CONTOUR call). COLOR - Intensity value used to draw the circle, overrides parameter value. Default = !P.COLOR THICK - Thickness of the drawn ellipse, default = !P.THICK LINESTLYLE - Linestyle used to draw ellipse, default = !P.LINESTYLE NPOINTS - Number of points to connect to draw ellipse, default = 120 RESTRICTIONS: TVELLIPSE does not check whether the ellipse is within the boundaries of the window. The ellipse is evaluated at NPOINTS (default = 120) points and connected by straight lines, rather than using the more sophisticated algorithm used by TVCIRCLE TVELLIPSE does not accept normalized coordinates. TVELLIPSE is not vectorized; it only draws one ellipse at a time EXAMPLE: Draw an ellipse of major axis 50 pixels, minor axis 30 pixels, centered on (250,100), with the major axis inclined 25 degrees from the X axis Use a double thickness line and device coordinates (default) IDL> tvellipse,50,30,250,100,25,thick=2 NOTES: Note that the position angle for TVELLIPSE (counter-clockwise from the X axis) differs from the astronomical position angle (counter-clockwise from the Y axis). REVISION HISTORY: Written W. Landsman STX July, 1989 Converted to use with a workstation. M. Greason, STX, June 1990 LINESTYLE keyword, evaluate at 120 points, W. Landsman HSTX Nov 1995 Added NPOINTS keyword, fixed /DATA keyword W. Landsman HSTX Jan 1996 Check for reversed /DATA coordinates P. Mangiafico, W.Landsman May 1996 Converted to IDL V5.0 W. Landsman September 1997(See tvellipse.pro)
TVLASER
[Previous Routine] [Next Routine] [List of Routines]NAME: TVLASER PURPOSE: Prints screen or image array onto a Postscript file or printer. Information from FITS header is optionally used for labeling. CALLING SEQUENCE: TVLASER, [header, Image, BARPOS = ,CARROWS =, CLABELS = ,/COLOPS, COMMENTS = ,CSIZE = ,CTITLE = , DX = , DY =, /ENCAP, FILENAME = HEADER = ,/HELP, IMAGEOUT = ,/INTERP, /MAGNIFY, /NoCLOSE, /NoDELETE, /NO_PERS_INFO, /NoEIGHT, /NoPRINT, /NoRETAIN, /PORTRAIT, PRINTER = , /REVERSE, /SCALE, TITLE = , /TrueColor, XDIM=, XSTART=, YDIM=, YSTART= ] Note that the calling sequence was changed in May 1997 OPTIONAL INPUTS: HEADER - FITS header string array. Object and astrometric info from the FITS header will be used for labeling, if available IMAGE - if an array is passed through this parameter, then this image will be used rather than reading off the current window. This allows easy use of large images. It is usually preferable to optimally byte scale IMAGE before supplying it to TVLASER OPTIONAL KEYWORD INPUT PARAMETERS: BARPOS - A four- or five-element vector giving the position and orientation of the color bar. The first four elements [X0,Y0,XSize,YSize] indicate the position and size of the color bar in INCHES, relative to origin of the displayed image. (X0,Y0) are the position of the lower left corner and (XSize,YSize) are the width and height. The fifth element is optional, and if present, the color bar will be printed horizontally rather than vertically. If BARPOS is set to anything but a four- or five-element vector, the bar is NOT printed. The default value is BARPOS = [-0.25, 0.0, 0.2, 2.0] CARROWS - The color to print the North-East arrows. Default is dark. Three types of values can be passed: SCALAR: that value's color in the current color table 3-ELEMENT VECTOR: the color will be [R,G,B] STRING: A letter indicating the color. Valid names are: 'W' (white), 'D' (dark/black), 'R' (red), 'G' (green), 'B' (blue), 'T' (turquoise), 'V' (violet), 'Y' (yellow), If the keyword is set to a value of -1, the arrows are NOT printed. COLORPS - If present and non-zero, the idl.ps file is written using color postscript. COMMENTS - A string that will be included in the comment line below the image. For multi-line comments you can either use "!C" in the string as a carriage return {although the vertical spacing might be a little off} or, preferably, make the COMMENTS a string array with each line as a separate element. CLABELS - Color to print the labels, same format as for CARROWS. CSIZE - Color to print the size-scale bar and label, same format as for CARROWS. CTITLE - Color to print the title, same format as for CARROWS. DX,DY - offsets in INCHES added to the position of the figure on the paper. As is the case for the device keywords XOFFSET and YOFFSET, when in landscape mode DX and DY are the same *relative to the paper*, not relative to the plot (e.g., DX is the horizontal offset in portrait mode, but the *vertical* offset in landscape mode). ENCAP - If present and non-zero, the IDL.PS file is written in encapsulated postscript for import into LaTeX documents FILENAME - scalar string giving name of output postscript file. Default is idl.ps. Automatically sets /NODELETE HEADER = FITS header. This is an alternative to supplying the FITS header in the first parameter. HELP - print out the sytax for this procedure. INTERP - If present and non-zero, current color table will be interpolated to fill the full range of the PostScript color table (256 colors). Otherwise, the current color table will be directly copied. You probably will want to use this if you are using IMAGE keyword and a shared color table. MAGNIFY - The net magnification of the entire figure. At this point, the figure is not automatically centered on the paper if the value of MAGNIFY is not equal to 1, but the DX and DY keywords can be used to shift location. For example, to fit a full plot on the printable area (8.5x8.5 inches) of the Tek PhaserIISD color printer use: MAGNIFY=0.8, DX=0.5, DY=0.5.; NoCLOSE - If present and non-zero, then the postscript file is not closed (or printed), the device is set to 'PS', and the data coordinate system is set to match the image size. This allows the user to add additional plotting commands before printing. For example, to include a 15 pixel circle around a source at coordinates (150,160), around an image, im, with FITS header array, h IDL> tvlaser,h,im,/NoClose ;Write image & annotation IDL> tvcircle,15,150,160,/data ;Draw circle IDL> device,/close ;Close postscript file & print NoDELETE - If present and non-zero, the postscript file is kept AND is also sent to the printer NoEIGHT - if set then only four bits sent to printer (saves space) NO_PERS_INFO - if present and non-zero, output notation will NOT include date/user block of information. NoPRINT - If present and non-zero, the output is sent to a file (default name 'idl.ps'), which is NOT deleted and is NOT sent to the printer. NoRETAIN - In order to avoid possible problems when using TVRD with an obscured window, TVLASER will first copy the current window to a temporary RETAIN=2 window. Set /NORETAIN to skip this step and improve performance PORTRAIT - if present and non-zero, the printer results will be in portrait format; otherwise, they will be in landscape format. If labels are requested, image will be in portrait mode, regardless PRINTER - scalar string giving the OS command to send a the postscript file to the printer. Under Unix, the default value of PRINTER is 'lpr ' while for other OS it is 'print ' REVERSE - if present and non-zero, color table will be fliped, so black and white are reversed. SCALE - if present and non-zero, image will be bytscaled before being sent to postscript file. TITLE - if present and non-zero, the string entered here will be the title of the picture. Default is the OBJECT field in the header (if present). TRUECOLOR - if present and non-zero, the postscript file is created using the truecolor switch (i.e. true=3). The colorbar is not displayed in this mode. XDIM,YDIM - Number of pixels. Default is from !d.x_size and !d.y_size, or size of image if passed with IMAGE keyword. XSTART,YSTART - lower left corner (default of (0,0)) OPTIONAL KEYWORD OUTPUT PARAMETER IMAGEOUT = the image byte array actually sent to the postscript file. SIDE EFFECTS: A postscript file is created in the current directory. User must have write privileges in the current directory. The file is named idl.ps unless the FILENAME keyword is given. The file is directed to the printer unless the /ENCAP, /NoCLOSE, or /NOPRINT keywords are given. After printing, the file is deleted unless the /NODELETE or FILENAME keywords are given. PROCEDURE: Read display or take IMAGE and then redisplay into a postscript file. If a header exists, printout header information. If header has astrometry, then print out orientation and scale information. PROCEDURES USED: ARROWS, EXTAST, FDECOMP, GETROT, PIXCOLOR, SXPAR(), XYAD, ZPARCHECK *EXAMPLE: 1) Send a true color image (xsize,ysize,3) to a printer (i.e. print23l), tvlaser,huv,cpic,/colorps,/truecolor,printer="print23l" % TVLASER: Now printing image: $print23l idl.ps MODIFICATION HISTORY: Major rewrite from UIT version W. Landsman Dec 94 Massive rewrite. Added North-East arrows, pixel scale bar, color bar, and keywords DX, DY, MAGNIFY, INTERP, HELP, and COMMENTS. Created ablility to define colors for annotation and text. Repositioned text labels. J.Wm.Parker, HITC, 5/95 Make Header and Image parameters instead of keywords. Add PRINTER keyword. Include alternate FITS keywords. W. Landsman May 97 Copy to a RETAIN=2 window, work without FITS header W. Landsman June 97 Cleaner output when no astrometry in header W. Landsman June 97 Added /INFO to final MESSAGE W. Landsman July 1997 12/4/97 jkf/acc - added TrueColor optional keyword. Converted to IDL V5.0 W. Landsman 10-Dec-1997 Added /NoClose keyword, trim Equinox format W. Landsman 9-Jul-1997(See tvlaser.pro)
TVLIST